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 recommends 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 domains: 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 directives 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 per the GitHub study), skipping human review because tests pass, and confusing rapid "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.