Specification-Driven Development (SDD) for production agentic engineering: living Markdown
blueprints, SKILL.md 3-level progressive disclosure,
GCPSkillRegistry, deterministic hooks, and agents-cli
spec-to-eval CI pipelines.
Most developers using AI coding assistants today work in an ad-hoc, reactive mode: they open a chat, type a prompt like "build me a login page," accept the output, and move to the next thing. This works for simple tasks but breaks down for anything complex, team-based, or production-grade.
The result? Inconsistent outputs, lost context between sessions, no reproducibility, and code that works in isolation but fails when integrated. IDD solves this by treating AI interaction as a structured engineering process, not a casual conversation.
The same prompt produces different results across sessions, models, or team members. No deterministic outputs.
AI forgets previous decisions. Each session starts from zero. Architectural coherence degrades over time.
Prompts live in one developer's head. No shared understanding, no review process, no handoff protocol.
Without structure, each AI interaction accumulates subtle inconsistencies. By the time you notice, your codebase is a patchwork of individually-correct but collectively-incoherent components. This is the "death by a thousand prompts" anti-pattern.
Instruction-Driven Development (IDD) — also called Specification-Driven Development (SDD) — is a methodology where you write detailed, structured instructions before engaging the AI. These instructions serve as the contract between human intent and AI execution.
Think of it as TDD (Test-Driven Development) but for prompts: instead of writing tests first then code, you write specifications first then let AI generate the implementation. The spec is the single source of truth — versioned, reviewed, and shared across the team.
The community uses both terms interchangeably. IDD (Instruction-Driven Development) emphasizes the instructional nature of prompts. SDD (Specification-Driven Development) emphasizes the formal specification. In practice, they describe the identical workflow.
IDD follows a disciplined, phased workflow. Each phase has clear inputs, outputs, and quality gates. The methodology can be applied to a single feature or an entire project.
Write the instruction document with requirements, constraints, and success criteria
Peer review the spec for clarity, completeness, and feasibility
Feed the instruction to the AI and generate the implementation
Compare output against spec. Run tests, review code, check constraints
Update spec based on learnings, iterate until output meets all criteria
Version the spec alongside code. Document patterns for reuse
If your instruction is ambiguous, the AI's output will be unpredictable. The quality of your specification directly determines the quality of the generated code. Invest time in the spec, save time in debugging.
The instruction document is the heart of IDD. It's not just a prompt — it's a structured specification that gives the AI everything it needs to produce consistent, high-quality output. Here's the anatomy of a well-crafted IDD instruction.
# Instruction: [Feature Name] ## Version: 1.0 | Date: 2025-07-15 | Author: [Name] ## 1. Context Project: [Project name and brief description] Current State: [What exists, what's the starting point] Goal: [What this instruction should produce] ## 2. Functional Requirements - FR-01: [User can register with email and password] - FR-02: [System sends verification email on registration] - FR-03: [User can login and receive a JWT token] ## 3. Non-Functional Requirements - NFR-01: Response time < 200ms for auth endpoints - NFR-02: Passwords hashed with bcrypt (cost factor 12) - NFR-03: Rate limiting: 5 login attempts per minute per IP ## 4. Technical Constraints - Language: Python 3.12 - Framework: FastAPI - Database: PostgreSQL via SQLAlchemy - Auth: JWT with PyJWT - Testing: pytest with >80% coverage ## 5. File Structure src/ auth/ router.py # API endpoints service.py # Business logic models.py # SQLAlchemy models schemas.py # Pydantic schemas tests/ test_auth.py # Unit + integration tests ## 6. Acceptance Criteria - [ ] All FR items implemented and tested - [ ] All NFR constraints verified - [ ] No security vulnerabilities (no hardcoded secrets) - [ ] Code passes ruff linting with zero warnings - [ ] README updated with setup instructions
| Dimension | Traditional Dev | Vibe Coding | IDD / SDD |
|---|---|---|---|
| Planning | Requirements doc / tickets | Mental model + ad-hoc prompts | Structured instruction document |
| Implementation | Human writes all code | AI generates, human reviews | AI generates from spec, human validates |
| Reproducibility | High (deterministic) | Low (prompt-dependent) | High (spec is the contract) |
| Team Scalability | High (established processes) | Low (tribal knowledge) | High (shared specs) |
| Speed | Slow (manual coding) | Very fast (but fragile) | Fast (after initial spec investment) |
| Quality Control | Code review + CI | Varies (often minimal) | Spec review + output validation + CI |
| Best For | Critical systems, large teams | Prototypes, solo exploration | Production AI-assisted development |
IDD doesn't replace vibe coding — it matures it. Many teams start with vibe coding to explore ideas, then formalize their prompts into IDD specs once they decide to build for production. Think of it as: Vibe Coding = Prototyping → IDD = Engineering.
Break complex projects into layers of instructions that reference each other:
Combine IDD with TDD for maximum confidence:
Use the instruction document as the pull request description:
Build a reusable library of proven instruction templates:
AGENTS.md, GEMINI.md, .agents/rules/, /plan, /grill-me): Agent-first IDE & CLI with executable Plan Artifacts, interactive design interviews, scoped rules, and native SKILL.md discoveryCLAUDE.md, .claude/rules/, Plan Mode): Project documentation files read automatically, path-scoped rules, deterministic lifecycle hooks, and Shift+Tab Plan Modegoogle-agents-cli (agents-cli): Unified Google Cloud CLI for installing official agent skills, scaffolding ADK agents, running CI eval gates, and publishing to Gemini Enterprise.github/copilot-instructions.md files that constrain Copilot's behavior.aider.conf.yml and convention files that encode project standards/specs or /docs/idd directoryIDD-{module}-{feature}-v{version}.mdSPEC_INDEX.md listing all active specsThere's a balance between thorough and excessive. If your spec is 10 pages for a 50-line function, you've gone too far. The spec should be proportional to complexity. For simple tasks, a few bullet points suffice. Reserve detailed specs for complex, team-critical, or security-sensitive features.
SKILL.md), Progressive Disclosure & GCPSkillRegistry
Cramming 40 procedural runbooks or dozens of verbose MCP tool schemas directly into
AGENTS.md or CLAUDE.md triggers context & tool bloat:
attention degrades, latency spikes, and every trivial prompt pays for thousands of irrelevant tokens.
The open Agent Skills standard (agentskills.io) packages domain expertise
into modular folders (.agents/skills/<name>/SKILL.md or .claude/skills/)
loaded through 3-Level Progressive Disclosure.
description is mandatory: At startup the model sees only YAML frontmatter — vague descriptions prevent Level 2 activation.SKILL.md < 5,000 tokens: Offload large API tables to references/ so Level 2 stays sharp.scripts/: Expose --help flags and exit codes; never block on interactive TTY prompts.GCPSkillRegistry: Centralizes versioned enterprise skills (Skill, SkillRevision, Publisher) across teams instead of copy-pasting folders.agents-cli Spec-to-Eval Workflows
Mature IDD teams separate persistent workspace conventions (Rules),
on-demand procedural playbooks (Skills), 100% deterministic lifecycle
guardrails (Hooks), and automated CI evaluation gates (agents-cli).
| Layer | Google Antigravity | Claude Code | Enforcement & Exam Rule |
|---|---|---|---|
| Persistent / Scoped Rules | AGENTS.md / GEMINI.md + .agents/rules/*.md with snake_case trigger: (always_on, model_decision, glob, manual; ~24 KB/file, ~20k-token cap) |
CLAUDE.md, .claude/CLAUDE.md, ~/.claude/CLAUDE.md (@path imports) + .claude/rules/*.md YAML paths: globs |
Advisory LLM guidance for style & architecture. Gotcha: camelCase alwaysOn in Antigravity YAML is silently discarded! |
| Modular Skills | .agents/skills/<name>/SKILL.md + GCPSkillRegistry |
.claude/skills/<name>/SKILL.md + ~/.claude/skills/ |
Progressive disclosure (~100t → <5kt → 0t scripts) for repeatable multi-step tasks without context bloat. |
| Deterministic Hooks | hooks.json lifecycle command hooks |
settings.json (PreToolUse, PostToolUse, Stop) |
Zero-exception OS enforcement: PreToolUse exit code 2 blocks forbidden commands/.env edits; PostToolUse runs formatters/linters. |
| Spec Alignment | /plan (Plan Artifact) & /grill-me (design interview) |
Plan Mode (Shift+Tab read-only planning) |
Pre-code alignment during IDD Phases 1–2 (Define → Review) before touching source files. |
# 1. Bootstrap official Google Cloud skills into Antigravity, Claude Code & Gemini CLI uvx google-agents-cli setup # 2. Headless scaffold from approved IDD spec (pass --prototype --yes) agents-cli create billing-dispute-agent --prototype --yes agents-cli install # 3. Execute trajectory & rubric acceptance criteria in CI before merge agents-cli eval run --config tests/eval/eval_config.json # 4. Deploy & register in Gemini Enterprise once eval gates pass agents-cli deploy --deployment-target agent_runtime --no-confirm-project agents-cli publish gemini-enterprise --agent-runtime-id <RUNTIME_ID>
/plan and /grill-me).
SKILL.md) cure context/tool bloat via 3-Level Progressive Disclosure (~100-token YAML description → <5,000-token SKILL.md body → on-demand non-interactive scripts/ & references/), distributed centrally via GCPSkillRegistry.
PreToolUse / PostToolUse hooks (exit code 2 blocks deterministically) rather than advisory rules (remember snake_case trigger: in Antigravity .agents/rules/*.md), and gate releases headlessly via agents-cli (--yes + eval run).
Listen to the 56-minute Spec-Driven Development (IDD) audio deep dive, open the study guide PDF and sketchnote infographic in the Hub Viewer, or drill scenario-based questions on the 6-phase IDD lifecycle, SKILL.md 3-level progressive disclosure, GCPSkillRegistry, deterministic PreToolUse / PostToolUse hooks, and headless agents-cli evaluation gates.
Q1. What are the three main problems with ad-hoc AI prompting that IDD solves?
Q2. Name the 6 sections that make up a well-structured IDD instruction document.
Q3. Explain the "Spec-Test-Code Loop" pattern and why it's effective.
Q4. How does IDD relate to Vibe Coding? Are they opposites?
Q5. How does SKILL.md 3-Level Progressive Disclosure prevent context bloat?
description) at startup; Level 2 loads the <5,000-token SKILL.md body only when the task matches description; Level 3 executes non-interactive scripts/ or reads references/ strictly on demand.
Q6. Why use PreToolUse hooks instead of AGENTS.md / CLAUDE.md rules for blocking destructive commands, and why pass --yes to agents-cli?
PreToolUse hook returning exit code 2 deterministically blocks tool execution at the harness level. Passing --yes with explicit flags prevents headless coding agents and CI runners from hanging on interactive TTY prompts.
Drill scenario-based questions on ad-hoc prompting failures, the six IDD phases, spec anatomy, SKILL.md 3-level progressive disclosure, GCPSkillRegistry, Antigravity/Claude rules & hooks, and agents-cli CI gates.