# osmani-how-write-good-spec-ai-agents-2026-01-13

## Veille

Addy Osmani - escribir especificaciones para agentes de IA, 5 principios, Plan Mode, PRD estructurado, modularidad

## Titre Article

How to write a good spec for AI agents

## Date

2026-01-13

## URL

https://addyosmani.com/blog/good-spec/

## Keywords

spec, especificaciones, agentes de IA, Claude Code, Plan Mode, PRD, modularidad, ventana de contexto, subagentes, pruebas, vibe coding, prompt engineering, SPEC.md

## Authors

Addy Osmani

## Ton

Perfil: Artículo de blog técnico, registro pedagógico y prescriptivo, perspectiva de líder de ingeniería (Google Chrome).
Estilo: Estructurado en torno a 5 principios numerados con subsecciones detalladas. Usa ejemplos de código concretos y tablas comparativas. Equilibra teoría y práctica. Cita estudios de GitHub (más de 2500 agentes analizados). Advertencias sobre errores frecuentes. Público objetivo: desarrolladores que usan agentes de codificación de IA, tech leads, arquitectos.

## Pense-betes

- **Problema central**: Las especificaciones masivas provocan sobrecarga de contexto y degradación del rendimiento del modelo
- **5 principios** para especificaciones eficaces: 1. **Visión de alto nivel primero**: resumen conciso, dejar que la IA resuelva los detalles 2. **Estructura de PRD profesional**: 6 áreas esenciales 3. **División modular**: evitar prompts monolíticos 4. **Autoverificación integrada**: restricciones y experiencia de dominio 5. **Probar, iterar, evolucionar**: especificaciones como documentos vivos
- **Plan Mode** (Shift+Tab Claude Code): exploración de solo lectura antes de la generación de código
- **SPEC.md**: archivo persistente para la coherencia entre sesiones
- **6 áreas del PRD**: Comandos, Pruebas, Estructura del proyecto, Estilo de código, Flujo de trabajo Git, Límites
- **Sistema de 3 niveles**: ✅ Always do, ⚠️ Ask first, 🚫 Never do
- **"Maldición de las instrucciones"**: rendimiento degradado de la IA con demasiadas instrucciones simultáneas
- **Solución de modularidad**: archivos separados SPEC_backend.md, SPEC_frontend.md
- **Subagentes/skills**: agentes especializados por dominio
- **LLM-as-a-Judge**: revisión por un segundo agente para estilo/arquitectura
- **Pruebas de conformidad**: suites YAML como contratos
- **Errores frecuentes**: especificaciones demasiado vagas (dominante), omitir la revisión humana, confundir vibe coding con producción
- **"Trifecta letal"**: velocidad (difícil de revisar) + no determinismo + coste (fomenta atajos)
- **Metáfora**: Tratar a los agentes como "pasantes competentes" - instrucciones claras, contexto relevante, retroalimentación accionable
- **Herramientas mencionadas**: Claude Code, GitHub Spec Kit, Cursor, LangGraph, OpenAI Swarm, Chroma, Context7, MCP

## RésuméDe400mots

Addy Osmani publica una guía exhaustiva sobre cómo redactar especificaciones eficaces para agentes de codificación de IA, abordando el problema central de que las especificaciones masivas provocan sobrecarga de contexto y degradan el rendimiento del modelo.

El primer principio aboga por partir de una visión de alto nivel en lugar de sobreingeniería desde el inicio. El uso de Plan Mode (Shift+Tab en Claude Code) permite una exploración de solo lectura antes de la generación de código. El agente elabora después los detalles en un archivo SPEC.md persistente para mantener la coherencia entre sesiones.

El segundo principio estructura las especificaciones como PRD profesionales que cubren seis áreas esenciales: comandos ejecutables con flags, procedimientos de prueba, estructura explícita del proyecto, ejemplos de estilo de código, flujo de trabajo git y límites claros. Osmani propone un sistema de restricciones de tres niveles: "Always do" (acciones seguras), "Ask first" (cambios de alto impacto), "Never do" (bloqueos absolutos, como confirmar secretos en un commit).

El tercer principio divide el trabajo en tareas modulares. La investigación revela una "maldición de las instrucciones" en la que demasiadas instrucciones simultáneas reducen significativamente la adherencia del modelo. Las soluciones incluyen archivos de especificación separados (SPEC_backend.md, SPEC_frontend.md), subagentes especializados y agentes en paralelo para trabajo sin solapamiento.

El cuarto principio integra la autoverificación. El patrón "LLM-as-a-Judge" utiliza un segundo agente para verificar la adherencia al estilo y a la arquitectura. Las pruebas de conformidad YAML sirven como contratos independientes del lenguaje. La experiencia de dominio debe incluirse explícitamente: preferencias, trampas específicas de bibliotecas, formatos esperados.

El quinto principio trata las especificaciones como documentos vivos versionados junto con el código. El ciclo continuo prueba tras cada hito, retroalimenta los fallos en el siguiente prompt y actualiza el documento cuando los supuestos resultan incompletos.

Osmani advierte sobre errores frecuentes: especificaciones demasiado vagas (el modo de fallo dominante según el estudio de GitHub), omitir la revisión humana porque las pruebas pasan, y confundir el rápido "vibe coding" con la ingeniería de producción. Identifica una "trifecta letal": velocidad (difícil de revisar), no determinismo (resultados inconsistentes) y coste (fomenta atajos).

La metáfora central compara a los agentes de IA con "pasantes competentes" que requieren instrucciones claras, contexto relevante y retroalimentación accionable. El éxito depende de equilibrar especificaciones completas con ventanas de contexto enfocadas.

## GrapheDeConnaissance

- Addy Osmani —publie→ guide specs agents IA (DOCUMENT, 0.98)
- Addy Osmani —travaille_chez→ Google (ORGANISATION, 0.95)
- specs massives —réduit→ performance du modèle (surcharge de contexte) (CONCEPT, 0.95)
- Plan Mode —permet→ exploration read-only avant code (CONCEPT, 0.93)
- spec.md —permet→ cohérence cross-sessions (CONCEPT, 0.9)
- malédiction des instructions —réduit→ adhérence modèle (CONCEPT, 0.92)
- modularité specs —résout→ surcharge contexte (CONCEPT, 0.9)
- LLM-as-a-Judge —permet→ vérification de l'adhérence style et architecture (CONCEPT, 0.88)
- vitesse, non-déterminisme et coût —fait_partie_de→ triade létale (CONCEPT, 0.85)
- vibe coding —s_oppose_à→ ingénierie production (METHODOLOGIE, 0.83)
- Addy Osmani —recommande→ traiter les agents IA comme des stagiaires compétents (AFFIRMATION, 0.88)

---
Canonical: https://www.thekb.eu/es/fiches/osmani-how-write-good-spec-ai-agents-2026-01-13/