Prompt engineering para agentes de desarrollo: guia practica

Hay una diferencia sustancial entre usar un agente de IA para desarrollo y usar un agente de IA de forma efectiva. La diferencia no esta en el modelo (Claude, GPT, Gemini usan arquitecturas similares), sino en cómo le comunicas lo que necesitas.

El prompt engineering para agentes de desarrollo no es el mismo prompt engineering que se enseña para chatbots o generación de contenido. Un agente de desarrollo necesita entender tu codebase, tus convenciones, tus restricciones técnicas y tu forma de trabajar. Y necesita esa información estructurada de una forma que el modelo pueda procesar de manera eficiente.

Esta guía cubre los cinco pilares del prompt engineering para agentes de desarrollo: system prompts, gestión de contexto, chain-of-thought, few-shot examples y evaluación. No teoría abstracta: técnicas concretas con ejemplos que puedes aplicar directamente.

System prompts: la personalidad técnica de tu agente

Qué es un system prompt y por qué importa

El system prompt es la instrucción inicial que define cómo se comporta el agente. En el contexto de desarrollo de software, es el equivalente a la sesión de onboarding que le darías a un nuevo desarrollador: le explicas las normas del equipo, las convenciones del proyecto, las herramientas que se usan y las decisiones de arquitectura ya tomadas.

Un análisis reciente sobre cómo los system prompts definen el comportamiento de los agentes muestra que el system prompt tiene mas influencia en el output que el propio modelo. El mismo modelo con dos system prompts diferentes puede producir resultados radicalmente distintos en términos de calidad, estilo y utilidad del código generado.

Anatomía de un system prompt efectivo para desarrollo

Un system prompt para un agente de desarrollo debería contener:

1. Rol y expertise:

You are a senior backend developer with expertise in Python,
FastAPI, and PostgreSQL. You follow clean architecture principles
and prioritize readability over cleverness.

Definir el rol no es cosmético. Activa diferentes patrones de conocimiento en el modelo. Un agente con rol de “senior backend developer” produce código diferente al de “full-stack developer junior.”

2. Convenciones del proyecto:

Code conventions:
- Use snake_case for functions and variables
- Use PascalCase for classes
- All functions must have type hints
- Maximum line length: 100 characters
- Use f-strings, never .format() or % formatting

Las convenciones deben ser explícitas y no ambiguas. Si dices “sigue buenas prácticas” el agente interpretará según su entrenamiento. Si dices “usa snake_case” no hay margen de interpretación.

3. Restricciones técnicas:

Technical constraints:
- Target Python 3.12+
- Database: PostgreSQL 16 via SQLAlchemy 2.0 async
- Never use raw SQL queries, always use ORM
- All API endpoints must return Pydantic models
- No external dependencies without explicit approval

Las restricciones evitan que el agente tome decisiones que entren en conflicto con tu arquitectura. Sin ellas, un agente puede perfectamente sugerir una solución técnicamente correcta pero incompatible con tu stack.

4. Patrones preferidos y anti-patrones:

Preferred patterns:
- Repository pattern for database access
- Dependency injection via FastAPI's Depends()
- Structured logging with structlog

Anti-patterns to avoid:
- God classes or functions longer than 50 lines
- Nested try/except blocks
- Global state or module-level variables

5. Proceso de trabajo:

Workflow:
1. Before writing code, explain your approach in 2-3 sentences
2. Write the implementation
3. Add inline comments only for non-obvious logic
4. Suggest tests for the new code
5. Flag any architectural concerns

El archivo CLAUDE.md como system prompt persistente

Claude Code introdujo el concepto de CLAUDE.md: un archivo de configuración que el agente lee automáticamente al iniciar cada sesión. Funciona como un system prompt persistente que vive en tu repositorio.

El valor de este enfoque es que el system prompt evoluciona con el proyecto. Cuando el equipo decide una nueva convención o restricción, se actualiza el CLAUDE.md y todos los agentes del equipo la adoptan inmediatamente.

Según un análisis de Arize AI sobre optimización de Claude Code con prompt learning, los equipos que mantienen un CLAUDE.md detallado con comandos bash comunes, archivos core, guías de estilo y instrucciones de testing reportan mejoras significativas en la calidad del output.

Estructura recomendada para CLAUDE.md:

Comandos de build y test: Para que el agente pueda ejecutar y verificar su propio código
Estructura del proyecto: Para que entienda la organización del codebase
Convenciones de código: Para que genere código consistente con el equipo
Decisiones de arquitectura: Para que no contradiga elecciones ya tomadas
Restricciones explícitas: Para evitar sugerencias incompatibles

Gestión de contexto: el factor limitante

Por qué el contexto importa mas que el prompt

Un agente de desarrollo puede tener el system prompt perfecto, pero si no tiene acceso a la información correcta cuando la necesita, el output será mediocre. El contexto es la información que el agente necesita para tomar decisiones informadas sobre tu código específico.

El reto es que los modelos tienen ventanas de contexto limitadas. Aunque los modelos de 2026 manejan ventanas de 128K a 200K tokens, eso no significa que debas enviar todo tu codebase. La calidad del output degrada cuando el contexto contiene demasiada información irrelevante.

Estrategias de gestión de contexto

Contexto jerárquico:

Organiza la información en niveles de relevancia:

Siempre presente: System prompt, convenciones del proyecto, estructura de archivos
Relevante a la tarea: Los archivos que el agente va a modificar, sus dependencias directas, tests existentes
Referencia: Documentación de APIs externas, decisiones de arquitectura, patrones del proyecto
Disponible bajo demanda: Código de otros módulos, historial de git, documentación general

Contexto just-in-time:

En lugar de cargar todo al inicio, proporciónale al agente las herramientas para obtener contexto cuando lo necesite:

Acceso al filesystem para leer archivos relevantes
Capacidad de ejecutar comandos (grep, find, git log) para buscar información
Acceso a documentación online cuando necesita referencia de APIs

Cursor implementa esto leyendo el codebase completo e indexándolo para búsqueda semántica. Cuando el agente necesita contexto sobre un módulo, busca en el índice en lugar de cargar archivos manualmente.

Contexto negativo (qué no incluir):

Archivos generados (node_modules, dist, build)
Archivos binarios
Documentación no técnica (marketing, legal)
Código de dependencias externas (a menos que estés debuggeando una)

Patrones de contexto por tipo de tarea

Bug fix: Archivo con el bug, stack trace, test que falla, archivos relacionados

Nueva feature: Especificación de la feature, archivos donde se implementará, tests existentes de módulos similares, convenciones de naming

Refactoring: Código actual, tests existentes, target architecture, restricciones de backwards compatibility

Code review: Diff del PR, tests nuevos, convenciones del proyecto, checklist de review

Chain-of-thought: razonamiento paso a paso

Por qué los agentes de desarrollo necesitan “pensar en voz alta”

Chain-of-thought (CoT) es una técnica donde instruyes al modelo para que explique su razonamiento paso a paso antes de producir el output final. En desarrollo de software, esto tiene un impacto directo en la calidad del código generado.

La investigación muestra que CoT mejora significativamente la capacidad de razonamiento de los LLMs al inducir al modelo a resolver problemas multi-paso con pasos intermedios que replican un proceso de pensamiento lógico.

Aplicaciones prácticas de CoT en desarrollo

Diseño antes de implementación:

Before writing any code:
1. Identify the core problem this code needs to solve
2. List the components/modules involved
3. Define the interface (inputs/outputs) for each function
4. Consider edge cases and error scenarios
5. Then write the implementation

Este patrón evita el problema mas común de los agentes: generar código que resuelve el caso happy path pero falla en edge cases.

Debugging sistemático:

When debugging:
1. Read the error message carefully and identify the type of error
2. Trace the execution flow to find where the error originates
3. Identify potential causes (list at least 3)
4. For each cause, explain why it could or could not be the issue
5. Propose the most likely fix with explanation
6. Suggest a test to verify the fix

Evaluación de trade-offs:

When choosing between approaches:
1. List all viable approaches (minimum 2)
2. For each approach, list pros and cons
3. Evaluate against project constraints
4. Recommend one approach with clear justification
5. Note any risks or technical debt introduced

Tree of Thought: CoT avanzado

Tree of Thought extiende el chain-of-thought generando y explorando múltiples caminos de razonamiento simultáneamente. Cada nodo representa un paso intermedio y las ramas exploran enfoques alternativos.

En la práctica, esto se traduce en pedir al agente que explore múltiples soluciones antes de elegir una:

Explore 3 different approaches to implement this feature:
- Approach A: [description]
- Approach B: [description]
- Approach C: [description]

For each, write a brief pseudocode sketch, evaluate
complexity, and identify risks. Then recommend the best one.

Few-shot examples: mostrar en lugar de explicar

Cuándo usar few-shot vs instrucciones

Las instrucciones textuales funcionan bien para reglas simples (“usa snake_case”). Pero para patrones complejos, mostrar un ejemplo es mas efectivo que describir el patrón.

Anthropic recomienda 3-5 ejemplos diversos y relevantes para tareas complejas. El few-shot prompting proporciona al modelo inputs y outputs de ejemplo que demuestran el comportamiento deseado.

Tipos de few-shot para desarrollo

Pattern examples (cómo estructurar código):

Example of how we write API endpoints in this project:

@router.post("/users", response_model=UserResponse, status_code=201)
async def create_user(
    user_data: UserCreate,
    service: UserService = Depends(get_user_service),
) -> UserResponse:
    """Create a new user."""
    user = await service.create(user_data)
    return UserResponse.from_orm(user)

Now write an endpoint for creating a product following
the same pattern.

Error handling examples:

Example of how we handle errors:

class UserNotFoundError(AppException):
    status_code = 404
    detail = "User not found"

@router.get("/users/{user_id}")
async def get_user(user_id: UUID) -> UserResponse:
    user = await service.get(user_id)
    if not user:
        raise UserNotFoundError()
    return UserResponse.from_orm(user)

Follow this pattern for all new endpoints.

Test examples:

Example of how we write tests:

@pytest.mark.asyncio
async def test_create_user_success(
    client: AsyncClient,
    mock_user_service: MockUserService,
):
    mock_user_service.create.return_value = sample_user()

    response = await client.post("/users", json={
        "name": "Test User",
        "email": "test@example.com",
    })

    assert response.status_code == 201
    assert response.json()["name"] == "Test User"

Write tests for the product endpoint following this pattern.

Anti-patrones de few-shot

Demasiados ejemplos: Mas de 5 ejemplos satura el contexto sin mejorar la calidad
Ejemplos contradictorios: Si tus ejemplos no son consistentes entre sí, el agente producirá output inconsistente
Ejemplos de baja calidad: Los agentes replican lo que ven, incluyendo malas prácticas. Solo muestra código que quieras ver replicado.
Ejemplos irrelevantes: Un ejemplo de frontend no ayuda en una tarea de backend. La relevancia importa mas que la cantidad.

Evaluación: medir lo que funciona

Por qué necesitas evaluar tus prompts

El prompt engineering no es un proceso de “configura y olvida.” Los modelos se actualizan, los proyectos evolucionan y lo que funcionaba hace tres meses puede no funcionar hoy.

SWE-bench es el benchmark mas utilizado para evaluar agentes de código. Consiste en 300 issues reales de repositorios open source de Python, y mide si los agentes pueden resolverlos. Claude Code domina los rankings de SWE-bench, pero lo que importa para tu equipo no es el benchmark genérico, sino cómo el agente performa en tu contexto específico.

Framework de evaluación práctico

Nivel 1: Correctitud funcional

El código generado compila sin errores
Los tests pasan
El comportamiento es el esperado

Nivel 2: Adherencia a convenciones

Sigue las convenciones de naming del proyecto
Usa los patrones y anti-patrones definidos
Respeta las restricciones técnicas

Nivel 3: Calidad de ingeniería

El código es legible y mantenible
Maneja edge cases apropiadamente
Los tests son relevantes y no triviales

Nivel 4: Eficiencia de contexto

El agente solicita la información correcta (no de mas, no de menos)
Las iteraciones necesarias para llegar al resultado son razonables
El coste en tokens es proporcional a la complejidad de la tarea

Prompt Learning: optimización basada en datos

El prompt learning es un enfoque de optimización que busca mejorar el rendimiento de un agente optimizando su prompt basándose en cómo performa sobre un dataset de tareas.

En la práctica, esto significa:

Define un dataset de evaluación: 20-30 tareas representativas de tu trabajo diario
Ejecuta cada tarea con tu prompt actual y registra los resultados
Identifica patrones de fallo: Tareas donde el agente falla consistentemente
Ajusta el prompt para abordar esos patrones
Re-evalúa para verificar que la mejora no introduce regresiones

Métricas que importan

First-attempt success rate: Porcentaje de tareas resueltas correctamente sin iteración
Iteration count: Número medio de iteraciones hasta un resultado aceptable
Convention adherence: Porcentaje de output que cumple con las convenciones del proyecto
Token efficiency: Tokens consumidos por tarea completada exitosamente

De prompt engineering a agent engineering

La evolución del rol en 2026

Un análisis de CIO sobre cómo la IA agéntica redefinirá los workflows de ingeniería en 2026 describe un cambio decisivo: el prompt engineering como disciplina individual está evolucionando hacia la orquestación de múltiples agentes especializados.

El desafío principal ya no es escribir el prompt perfecto para una tarea individual. Es diseñar workflows complejos y protocolos de interacción entre múltiples agentes especializados:

Un agente que analiza requisitos
Otro que diseña la arquitectura
Otro que implementa el código
Otro que escribe tests
Otro que hace code review

Cada uno necesita su propio system prompt, sus propios examples y su propio contexto. La ingeniería de prompts se convierte en ingeniería de sistemas de agentes.

Recomendaciones para mantenerse al día

Documenta tus prompts: Trátalos como código. Versiónalos, revísalos, testéalos.
Comparte con tu equipo: Un buen system prompt no debería ser conocimiento individual. Vive en el repo.
Evalúa regularmente: Cada actualización del modelo puede cambiar cómo responde a tus prompts.
Empieza simple: Un prompt de 10 líneas bien pensado supera a uno de 200 líneas confuso.
Itera basándote en datos: No cambies el prompt por intuición. Cambialo porque los datos muestran que algo no funciona.

Conclusión

El prompt engineering para agentes de desarrollo no es un skill esotérico. Es la habilidad de comunicar requisitos técnicos de forma clara y estructurada, algo que ya deberías hacer con los humanos de tu equipo.

Los cinco pilares (system prompts, gestión de contexto, chain-of-thought, few-shot examples y evaluación) son complementarios. Un system prompt define las reglas. El contexto proporciona la información. CoT guía el razonamiento. Few-shot muestra los patrones. Y la evaluación mide si todo funciona.

La diferencia entre un equipo que usa agentes de IA de forma superficial y uno que los usa de forma efectiva suele estar en la calidad de sus prompts. Y la calidad se consigue con el mismo enfoque que se aplica a cualquier artefacto de ingeniería: iteración disciplinada basada en datos.

¿Quieres maximizar la efectividad de los agentes de IA en tu equipo?

En NERVICO ayudamos a equipos técnicos a implementar prompt engineering profesional:

Diseño de system prompts: Creamos prompts optimizados para tu stack, convenciones y workflows
Frameworks de evaluación: Configuramos pipelines de evaluación para medir y mejorar la calidad del output
Formación práctica: Workshops de prompt engineering enfocados en desarrollo de software, no en chatbots
CLAUDE.md y configuración de agentes: Preparamos tu repositorio para que los agentes trabajen de forma efectiva

Sin hype. Sin técnicas mágicas. Solo ingeniería de comunicación con modelos de lenguaje.

Solicitar auditoría técnica gratuita — Evaluaremos cómo usas agentes de IA actualmente y te mostraremos dónde el prompt engineering puede mejorar tu productividad.