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

## Veille

Addy Osmani - writing specs for AI agents, 5 principles, Plan Mode, structured PRD, modularity

## Titre Article

How to write a good spec for AI agents

## Date

2026-01-13

## URL

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

## Keywords

spec, specifications, AI agents, Claude Code, Plan Mode, PRD, modularity, context window, sub-agents, testing, vibe coding, prompt engineering, SPEC.md

## Authors

Addy Osmani

## Ton

Profile: Technical blog article, pedagogical and prescriptive register, engineering-leader perspective (Google Chrome).
Style: Structured around 5 numbered principles with detailed subsections. Uses concrete code examples and comparison tables. Balances theory and practice. References GitHub studies (2,500+ agents analyzed). Warnings against common pitfalls. Target audience: developers using AI coding agents, tech leads, architects.

## Pense-betes

- **Core problem**: Massive specs cause context overload and degraded model performance
- **5 principles** for effective specs: 1. **High-level vision first**: concise brief, let the AI work out the details 2. **Professional PRD structure**: 6 essential areas 3. **Modular division**: avoid monolithic prompts 4. **Built-in self-verification**: constraints and domain expertise 5. **Test, iterate, evolve**: specs as living documents
- **Plan Mode** (Shift+Tab Claude Code): read-only exploration before code generation
- **SPEC.md**: persistent file for cross-session consistency
- **6 PRD areas**: Commands, Testing, Project structure, Code style, Git workflow, Boundaries
- **3-tier system**: ✅ Always do, ⚠️ Ask first, 🚫 Never do
- **"Curse of instructions"**: degraded AI performance with too many simultaneous instructions
- **Modularity solution**: separate SPEC_backend.md, SPEC_frontend.md
- **Sub-agents/skills**: domain-specialized agents
- **LLM-as-a-Judge**: second agent review for style/architecture
- **Conformance testing**: YAML suites as contracts
- **Common pitfalls**: overly vague specs (dominant), skipping human review, confusing vibe coding with production
- **"Lethal trifecta"**: speed (hard to review) + non-determinism + cost (encourages shortcuts)
- **Metaphor**: Treat agents as "competent interns" - clear instructions, relevant context, actionable feedback
- **Tools mentioned**: Claude Code, GitHub Spec Kit, Cursor, LangGraph, OpenAI Swarm, Chroma, Context7, MCP

## RésuméDe400mots

Addy Osmani publishes a comprehensive guide on writing effective specifications for AI coding agents, addressing the core problem that massive specs cause context overload and degrade model performance.

The first principle advocates starting with a high-level vision rather than over-engineering from the outset. Using Plan Mode (Shift+Tab in Claude Code) enables read-only exploration before code generation. The agent then elaborates the details in a persistent SPEC.md file for consistency across sessions.

The second principle structures specs as professional PRDs covering six essential areas: executable commands with flags, testing procedures, explicit project structure, code style examples, git workflow, and clear boundaries. Osmani proposes a three-tier constraint system: "Always do" (safe actions), "Ask first" (high-impact changes), "Never do" (hard stops such as committing secrets).

The third principle divides work into modular tasks. Research reveals a "curse of instructions" where too many simultaneous instructions significantly reduce model adherence. Solutions include separate spec files (SPEC_backend.md, SPEC_frontend.md), specialized sub-agents, and parallel agents for non-overlapping work.

The fourth principle integrates self-verification. The "LLM-as-a-Judge" pattern uses a second agent to verify adherence to style and architecture. YAML conformance tests serve as language-independent contracts. Domain expertise must be explicitly included: preferences, library-specific pitfalls, expected formats.

The fifth principle treats specs as living documents versioned alongside the code. The continuous cycle tests after each milestone, feeds failures back into the next prompt, and updates the document when assumptions prove incomplete.

Osmani warns against common pitfalls: overly vague specs (the dominant failure mode according to the GitHub study), skipping human review because tests pass, and confusing fast "vibe coding" with production engineering. He identifies a "lethal trifecta": speed (hard to review), non-determinism (inconsistent outputs), and cost (encourages shortcuts).

The central metaphor compares AI agents to "competent interns" requiring clear instructions, relevant context, and actionable feedback. Success depends on balancing complete specs with focused context windows.

## 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/en/fiches/osmani-how-write-good-spec-ai-agents-2026-01-13/