1. Introducción al Módulo — Prompts para Código ≠ Chatbots

Descripción

Este módulo cambia tu forma de pensar sobre el prompting. Si vienes de usar ChatGPT, Claude web, o cualquier chatbot para pedir código, traes hábitos que no funcionan con un agente de código. La diferencia no es de grado — es de naturaleza. Un chatbot genera texto basado en tu input; Claude Code lee tus archivos, ejecuta comandos en tu terminal, modifica tu código, y hace commits en tu repositorio. Las consecuencias de un prompt mal escrito en un chatbot son inocuas — texto que ignoras. Las consecuencias en un agente de código son reales — archivos modificados que no debían tocarse, dependencias instaladas que no pediste, commits con código roto.

Por qué importa: La mayoría de developers escribe prompts como si hablara con un chatbot genérico. "Haz una función que valide emails" o "crea un endpoint REST para usuarios." Eso produce resultados inconsistentes con un agente que tiene acceso a tu filesystem, terminal, y git. Developers con methodology de prompting obtienen resultados consistentemente superiores — código más limpio, menos iteraciones, menos bugs. La diferencia no es talento — es método.

Este es el primer módulo de la guía "Prompt Engineering with Claude Code" y el punto de partida de tu transformación como developer que dirige agentes de código en vez de pedirle cosas a chatbots. Aquí descubrirás por qué tus prompts actuales producen resultados inconsistentes, y por qué invertir en aprender a promptear un agente te devuelve el tiempo exponencialmente.

¿Dónde Estamos en la Guía?

Contexto en el Path

Esta es la Guía #3 del Claude Code Agentic Development Path. En la Guía #2 (Claude Code Foundations) aprendiste a operar Claude Code: instalación, CLAUDE.md, hooks, skills, subagents, SDK. Sabes cómo funciona la herramienta. Ahora necesitas aprender a dirigirla con precisión.

Guía #1: Fundamentos de Claude Code ← completada
Guía #2: Claude Code Foundations     ← completada (operar la herramienta)
▶ Guía #3: Prompt Engineering       ← ESTÁS AQUÍ (dirigir la herramienta)
Guía #4: AI Coding Tools Landscape  ← siguiente

Hay una diferencia enorme entre saber operar un martillo y saber construir una casa. Las Guías #1 y #2 te enseñaron el martillo. Esta guía te enseña a construir.

Contexto en la Guía

Esta guía tiene 8 módulos organizados en 3 phases:

Phase 1: Fundamentos del Prompting (Módulos 1-3)
├── Módulo 1: Prompts para Código ≠ Chatbots          ← ESTÁS AQUÍ
├── Módulo 2: Anatomía de un Prompt Efectivo
└── Módulo 3: Zero-shot, One-shot, N-shot

Phase 2: Workflows y Técnicas (Módulos 4-6)
├── Módulo 4: PRD → Plan → Todo → Code
├── Módulo 5: Spec-first y Context Management
└── Módulo 6: Iteration Patterns y /effort

Phase 3: Mastery (Módulos 7-8)
├── Módulo 7: Templates Reutilizables
└── Módulo 8: Proyecto Integrador — Prompt Library Personal

Duración total estimada: 8-10 horas (self-paced).

¿Hacia dónde vamos?

Este módulo abre Phase 1 estableciendo la mentalidad correcta. La progresión de la guía es deliberada:

1. Primero entiendes por qué el prompting para agentes es diferente (este módulo) — sin esto, todo lo demás es una receta sin fundamento
2. Luego aprendes cómo estructurar un prompt (módulo 2) — la anatomía de 4 partes
3. Después dominas cuándo y cómo usar ejemplos (módulo 3) — zero/one/N-shot
4. Aplicas todo en un workflow profesional (módulo 4) — PRD → Plan → Todo → Code
5. Complementas con spec-first y context management (módulo 5) — verificar y gestionar contexto
6. Calibras iteración y esfuerzo (módulo 6) — loops de verificación y /effort
7. Sistematizas en templates reutilizables (módulo 7) — templates por tipo de tarea
8. Construyes tu prompt library personal (módulo 8) — el entregable final de la guía

El Problema: Prompts de Chatbot para Agentes de Código

Un escenario que has vivido

Imagina esta situación: abres Claude Code en un proyecto Python y escribes:

Mejora el código

Claude Code tiene acceso a todo tu codebase. ¿Qué archivos "mejora"? ¿Qué significa "mejorar"? ¿Refactorizar? ¿Optimizar rendimiento? ¿Añadir types? ¿Mejorar nombres de variables? Sin constraints, Claude Code toma decisiones por ti. Puede modificar 15 archivos, cambiar interfaces públicas, instalar una dependencia nueva, y reorganizar tu estructura de carpetas. ¿Eso querías? Probablemente no.

Con un chatbot, ese prompt produce un texto que miras y descartas. Con un agente, produce cambios reales en tu codebase que necesitas revertir.

La diferencia en consecuencias

Prompt vago a un chatbot:
→ "Mejora este código"
→ Resultado: Texto con sugerencias. Lo lees o lo ignoras.
→ Consecuencia: Ninguna. Tu código no cambió.

Prompt vago a Claude Code:
→ "Mejora el código"
→ Resultado: 12 archivos modificados, 3 dependencias nuevas,
   interfaz pública cambiada, tests que ya no pasan.
→ Consecuencia: 30 minutos revertiendo cambios con git checkout.

Esta diferencia en consecuencias es la razón por la que necesitas este módulo. Un agente de código con acceso a tu filesystem, terminal, y git no es un chatbot con esteroides — es una herramienta fundamentalmente diferente que requiere instrucciones fundamentalmente diferentes.

El costo de no aprender

Sin methodology de prompting, el workflow con Claude Code se ve así:

Prompt vago → output impredecible → "eso no es lo que quería"
→ prompt de corrección vago → output parcialmente mejor
→ "todavía no" → otro prompt → frustración
→ git checkout . → empezar de nuevo
→ 45 minutos perdidos

Con methodology de prompting, el workflow es:

Prompt estructurado → output predecible → verificar
→ ajuste puntual (si necesario) → listo
→ 5 minutos total

La diferencia no es exagerada. Developers con método producen en 5 minutos lo que developers sin método producen en 45 — o no producen. El tiempo invertido en aprender prompt engineering se recupera en la primera semana de uso.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

• ✅ Articular la diferencia fundamental: un chatbot genera texto basado en tu prompt; un agente de código lee archivos, ejecuta comandos shell, modifica código, y hace commits — las consecuencias de un prompt mal escrito son reales
• ✅ Identificar al menos 5 anti-patterns comunes en tus prompts actuales: prompts vagos, falta de contexto técnico, ausencia de constraints, ambigüedad en scope, falta de especificación de output
• ✅ Aplicar el mental model de "developer junior con superpoderes y amnesia" para calibrar tus instrucciones
• ✅ Comparar el output de un mismo prompt escrito en estilo chatbot vs estilo agente, midiendo diferencias en calidad, precisión, e iteraciones necesarias
• ✅ Entender que el tiempo invertido en un buen prompt se recupera exponencialmente en menos iteraciones y menos bugs

Objetivo profesional

Cuando abras Claude Code mañana, no escribirás "haz un endpoint para usuarios." Escribirás un prompt que especifica contexto, tarea concreta, constraints ("no modifiques los tests existentes"), y formato de output esperado. Esa diferencia marcará toda tu productividad con agentes de código — no solo con Claude Code, sino con cualquier herramienta agentic que uses en el futuro.

Roadmap del Módulo

Mapa de cápsulas

Flujo de aprendizaje

Primero entenderás por qué el prompting para agentes de código es fundamentalmente diferente (cápsula 02). Esa base te prepara para reconocer qué estás haciendo mal — los anti-patterns que producen resultados inconsistentes (cápsula 03). Con los problemas identificados, necesitas un framework mental para pensar diferente: los mental models que anclan tu nueva forma de promptear (cápsula 04). Finalmente, aplicas todo en un autodiagnóstico de tus propios prompts, los reescribes, y mides la diferencia (cápsula 05).

La progresión es: entender la diferencia → identificar errores → cambiar mentalidad → aplicar y medir.

Cada cápsula construye directamente sobre la anterior. No saltes a la cápsula 04 sin haber pasado por la 02 y 03 — los mental models cobran sentido cuando ya entiendes la diferencia chatbot vs agente y has identificado tus anti-patterns.

Duración estimada del módulo: 3-4 horas (lecturas + proyecto).

Conexión con el Proyecto

Mini-proyecto de este módulo: Diagnóstico de Prompts

En la cápsula 05 harás un autodiagnóstico de tus propios prompts. Vas a:

1. Recopilar 3-5 prompts que has usado con Claude Code en tu trabajo real
2. Clasificar cada uno como "estilo chatbot" o "estilo agente" usando los criterios de las cápsulas 02-04
3. Reescribir los prompts de estilo chatbot aplicando los mental models aprendidos
4. Comparar los outputs de ambas versiones con Claude Code
5. Documentar las diferencias: calidad del código, iteraciones necesarias, bugs introducidos

Ejemplo de lo que descubrirás:

Prompt original (estilo chatbot):
"Agrega autenticación al proyecto"

Prompt reescrito (estilo agente):
"Agrega autenticación JWT al endpoint POST /api/login en
src/routes/auth.py. Usa PyJWT. El token debe expirar en 24h.
No modifiques los endpoints existentes en src/routes/users.py.
Agrega los tests correspondientes en tests/test_auth.py."

Diferencia medible:
- Original: 8 archivos modificados, 2 no deseados, 3 iteraciones
- Reescrito: 3 archivos modificados, 0 no deseados, 1 iteración

Es un ejercicio de autoconocimiento. Descubrirás patrones en cómo prompteas que explican por qué a veces obtienes resultados excelentes y a veces resultados frustrantes. Esos patrones son tu punto de partida para mejorar.

Conexión con el proyecto final (Módulo 8)

La Prompt Library Personalizada que construirás en el Módulo 8 solo tiene valor si cada template está escrito con la mentalidad correcta — estilo agente, no estilo chatbot. Este módulo establece esa mentalidad. Sin él, tus templates serían versiones decoradas de prompts de chatbot — bonitos pero inefectivos.

Módulo 1: Mentalidad correcta (estilo agente, no chatbot)
    ↓
Módulos 2-7: Técnicas, workflows, y templates
    ↓
Módulo 8: Prompt Library Personal → integra TODO con mentalidad correcta

Prerequisitos

Conocimientos necesarios

• ✅ Claude Code instalado y configurado — Guía #2 del path completada
• ✅ CLAUDE.md básico creado — Al menos un proyecto con CLAUDE.md
• ✅ Programación básica — Cualquier lenguaje (Python preferido para los ejemplos)
• ✅ Familiaridad con terminal y Git — Navegación, comandos básicos, commits

Verificación rápida

Si puedes responder "sí" a estas preguntas, estás listo:

1. ¿Puedes abrir Claude Code en tu terminal y ejecutar una instrucción básica?
2. ¿Tienes un archivo CLAUDE.md en algún proyecto?
3. ¿Has usado Claude Code para modificar código al menos una vez?
4. ¿Sabes qué es un commit y cómo revertir cambios con git checkout?

# En tu terminal, dentro de un proyecto
claude

# Busca CLAUDE.md en tu proyecto
ls CLAUDE.md

# CLAUDE.md
Este proyecto usa Python 3.11+ y FastAPI.

# Verifica que sabes hacer un commit
git status
git add .
git commit -m "test"

Si no tienes los prerequisitos

No necesitas

• ❌ Experiencia previa con prompt engineering — empezamos desde la mentalidad
• ❌ Conocimiento de NLP o machine learning — esto no es sobre cómo funcionan los LLMs
• ❌ Experiencia con otras herramientas AI (Cursor, Copilot) — todo es Claude Code-specific
• ❌ Un proyecto grande — los ejercicios funcionan con cualquier codebase, incluso uno de 3 archivos

Setup para el Módulo

Lo que necesitas tener listo

Para sacar el máximo de este módulo, prepara lo siguiente:

1. Un proyecto con Claude Code configurado:

No necesita ser complejo. Un proyecto Python con 3-5 archivos funciona. Si no tienes uno a mano, puedes crear uno rápido:

mkdir prompt-eng-practice
cd prompt-eng-practice
git init

# Crea un archivo Python simple
cat > app.py << 'EOF'
"""Simple task manager API."""

tasks = []

def add_task(title: str, priority: str = "medium") -> dict:
    task = {"id": len(tasks) + 1, "title": title, "priority": priority, "done": False}
    tasks.append(task)
    return task

def list_tasks() -> list:
    return tasks

def complete_task(task_id: int) -> dict | None:
    for task in tasks:
        if task["id"] == task_id:
            task["done"] = True
            return task
    return None

if __name__ == "__main__":
    add_task("Learn prompt engineering", "high")
    add_task("Practice with Claude Code", "high")
    add_task("Build prompt library", "medium")
    print(list_tasks())
EOF

# Crea un CLAUDE.md básico
cat > CLAUDE.md << 'EOF'
# Project: Prompt Engineering Practice

- Python 3.11+
- Simple task manager for practicing prompts
- Follow PEP 8 conventions
EOF

git add . && git commit -m "Initial setup for prompt engineering practice"

2. Claude Code funcionando:

# Verifica que Claude Code está operativo
claude --version

# Abre Claude Code en tu proyecto
cd prompt-eng-practice
claude

3. Un documento para notas:

Crea un archivo donde documentarás tus observaciones durante el módulo:

touch prompt-diagnosis-notes.md

Vas a usarlo en la cápsula 05 para documentar tus prompts, clasificaciones, y comparaciones.

Límites: Qué NO Se Cubre en Este Módulo

• ❌ Estructura de prompts (anatomía) — Se cubre en el Módulo 2. Aquí entiendes el "por qué" de la diferencia; allá aprendes el "cómo" estructurar
• ❌ Técnicas de few-shot prompting — Se cubre en el Módulo 3. Primero necesitas la mentalidad correcta
• ❌ Workflows profesionales (PRD, spec-first) — Se cubren en Módulos 4-5, Phase 2
• ❌ Templates y prompt libraries — Se cubren en Módulos 7-8, Phase 3
• ❌ Prompt engineering genérico para LLMs — Todo en esta guía es específico para agentes de código. Si buscas prompting para chatbots, hay otros recursos
• ❌ Configuración de Claude Code — Se cubrió en la Guía #2 (Claude Code Foundations). Aquí asumimos que ya está configurado

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

• ✅ Puedes explicar en una frase por qué un prompt para Claude Code necesita ser diferente a un prompt para ChatGPT
• ✅ Puedes tomar un prompt tuyo y detectar al menos 2 anti-patterns en él
• ✅ Usas el mental model "developer junior con superpoderes y amnesia" para calibrar tus instrucciones antes de enviarlas
• ✅ Comparaste al menos 3 prompts (chatbot vs agente) y documentaste las diferencias en output
• ✅ Sientes que el tiempo invertido en construir un buen prompt es una inversión, no un overhead
• ✅ Puedes explicar a un colega por qué "mejora el código" es un prompt peligroso en un agente

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar el módulo, vas por buen camino:

1. ¿Cuál es la diferencia fundamental entre un chatbot y un agente de código?
2. ¿Por qué "crea un endpoint para usuarios" es un prompt insuficiente para Claude Code?
3. ¿Qué significa que Claude Code es un "developer junior con superpoderes y amnesia"?
4. ¿Cuáles son los 3 anti-patterns más comunes en tus prompts actuales?
5. ¿Qué cambio concreto harías a tu próximo prompt basado en lo aprendido?

Resumen

• Este módulo establece la mentalidad fundamental para todo lo que sigue en la guía
• La diferencia clave: un chatbot genera texto; un agente de código ejecuta acciones reales en tu codebase con consecuencias tangibles
• Aprenderás a identificar anti-patterns en tus prompts actuales — los hábitos de chatbot que producen resultados inconsistentes
• El mental model "developer junior con superpoderes y amnesia" será tu ancla para calibrar instrucciones en cada prompt que escribas
• El mini-proyecto es un autodiagnóstico que te muestra exactamente dónde están tus gaps
• Todo lo aprendido aquí fundamenta los módulos 2-8 de la guía — sin la mentalidad correcta, las técnicas no sirven

Recursos Adicionales

1. Claude Code Best Practices — Documentación oficial de Anthropic con best practices para prompting en Claude Code
2. Prompt Engineering Overview (Anthropic) — Fundamentos de prompt engineering según Anthropic
3. Claude Code Overview — Qué es Claude Code y cómo funciona como agente de código
4. Tweag: AI-assisted Coding — Spec-first methodology para desarrollo con AI (preview del Módulo 5)
5. Agentic Coding Best Practices — Research sobre el workflow Research → Plan → Execute → Validate
6. Anthropic Cookbook — Ejemplos prácticos de uso de Claude para desarrollo

Siguiente cápsula: En la cápsula 02 verás la diferencia fundamental entre chatbots y agentes de código — con ejemplos concretos y outputs reales que te mostrarán por qué el mismo prompt produce resultados radicalmente diferentes en cada contexto.