Spec-writing framework for AI coding agents — five principles for keeping agents focused¶
Insight: Effective AI agent specs follow five principles: (1) start with a high-level vision and let the AI draft details into a spec.md, (2) break large tasks into smaller scoped specs rather than one massive prompt, (3) use Plan Mode (read-only) first to iterate on the plan before execution, (4) include structure, style, testing, and boundary constraints, and (5) treat the spec as a living artifact that evolves with the project. Simply throwing massive specs at agents doesn't work — context windows and attention budgets degrade.
Detail: Osmani recommends "spec-driven development" where specs become shared source of truth between human and agent. Claude Code's Plan Mode (Shift+Tab) enforces planning-first by restricting to read-only operations. The key insight is that planning in advance matters even more with agents than with human developers. The spec becomes the first artifact built collaboratively before any code is written.
Sources
Related: existing entry "Prompt engineering for coding is a systematic skill" in external/claude-code.md — COMPLEMENTS