Day 5 · Lesson 2 — Spec-Driven Production Development

Where Instructions Live & Execution Modes

Instructions live in a hierarchy, not one prompt box, and turning a spec into code takes five different hats.

A good spec is worthless if it's dumped into a chat window: you'll blow the context budget and fragment the instructions. Spec-driven development needs to know where each kind of instruction lives, and that turning a spec into code isn't one act but five distinct modes, each demanding a different mindset.

Recall first (spacing — from Day 1)

From Day 1 L4: instructions/rule files that load on every call are —

Dynamic context
Static context
A transient tool result

Static context, the system-prompt layer. This lesson maps all the places instructions live, static and dynamic, into a working hierarchy.

The instruction hierarchy

Dumping a 100-page design into chat exhausts the context budget and fragments the plot. Instead, instructions live in four places, each with a job:¹

Where	Lifetime	For
Chat interface	Ephemeral, session	High-level orchestration + instant feedback ("run Scenario 3's tests")
`specs/` folder	Task-specific, version-controlled	Technical design, BDD scenarios, API contracts, YAML schemas
Agent Skills (`.agent/`)	Reusable, trigger-based	Repeatable habits (auto-maintain a CHANGELOG on code change)
System prompts	Global, identity	The engineering "DNA": persona, principles, house rules

System prompts layer hierarchically, global → local: a global profile (~/.gemini/GEMINI.md), a shared cross-tool AGENTS.md (so multiple AI clients don't fragment), and a project GEMINI.md that takes highest priority.¹ This is Day 1's harness (instructions/rule files) and Day 3's static context, given a filing system.

Five execution modes, five mindsets

Turning a spec into code isn't one act. Each mode needs a different posture:¹

Project Generation, the Architect. Scaffolding from scratch. No YOLO mode: make the agent propose folder structure + tech stack for confirmation first; require tests, docs, and logging; pin every version (or it defaults to its stale knowledge cutoff).
Feature Generation, the Builder. Building on an existing codebase. Match the existing style and error handling; confirm the diff before multi-file edits land.
Bug Fixing, the Forensic Specialist. Root-cause, surgical. Shift from symptom prompting ("the button doesn't work") to evidence prompting (logs, a 403, the request flow). Reproduce with a failing test first; fix only the root cause; don't "clean up" unrelated code.
Documentation, the Author. Docs are the source of truth; if docs and code drift, the AI hallucinates. Skills should keep README/CHANGELOG in sync.
Data Engineering, the Librarian. Always make the agent show the exact SQL/command it used.

The governance layer, on where instructions live

Governance overlay · Day 5 Lesson 2

The system-prompt hierarchy is where policy is declared

The instruction hierarchy is a governance layering: AGENTS.md / project GEMINI.md are exactly Day 2's BIND, where an agent's identity, rules, and forbidden actions are declared, version-controlled, and reviewed like code. Skills package procedural policy that triggers on task match. "No YOLO mode" in the Architect posture is a V Validation checkpoint (confirm structure before generation); confirming diffs is a R human-in-the-loop control on what actually changes.

Ladder read: intent scattered across chat history is L1 Unseen; instructions filed into a reviewed, hierarchical, version-controlled structure is the L3 Controlled posture: you can point to where every rule lives and who approved it.

Through your three lenses

Individual (IC)

Name your mode before you prompt: are you the Architect, Builder, or Forensic Specialist right now? Each has different rules (no-YOLO scaffolding, confirm diffs, evidence-not-symptom). Stop free-styling.

Team

Adopt a shared AGENTS.md so multiple AI clients don't fragment your conventions, and keep a skills library for repeatable habits. The hierarchy is a team asset, versioned like code.

Organisation

Standardise the instruction hierarchy (global profile → shared AGENTS.md → project spec) so intent is auditable and reproducible across teams, not lodged in individual chat sessions.

Check the reflex

Recall, don't re-read.

Reusable, trigger-based engineering habits belong in —

The chat interface
Agent Skills
A one-off prompt

Skills (in .agent/), repeatable workflows like auto-maintaining a CHANGELOG. Chat is for ephemeral orchestration; the spec folder holds the design.

Fixing a bug well means shifting from symptom prompting to —

YOLO auto-approve mode
Renaming variables first
Evidence prompting

The Forensic Specialist gives logs and the request flow, reproduces with a failing test first, and fixes only the root cause, not "the button doesn't work."

In "Architect" (project generation) mode, the agent should first —

Propose structure and stack for confirmation
Immediately write all the code
Skip tests to move faster

No YOLO: confirm folder structure and tech stack before coding, and require tests, docs, logging, and pinned versions. Scaffolding is where wrong assumptions are cheapest to catch.

Carry this into the week

Audit where your agent's instructions actually live. Is there a project AGENTS.md/ GEMINI.md, or does the agent relearn your conventions every session from chat? Move one recurring instruction from chat into the hierarchy. That's spec-driven development starting.

Go deeper (primary source)

Spec-Driven Production Grade Development (Day 5), "Where do the instructions live?" & "Different Prompts for Different Use Cases" pp.11–14.

Notes

Boonstra, Spec-Driven Production Grade Development (Day 5), pp.11–14 (the instruction hierarchy; the five execution modes).

Up next → Day 5 · Lesson 3: Code Review at Scale. When agents ship PRs faster than humans can review, the process breaks. Bundled summaries, the Conditional LGTM, and the three-tier spectrum of continuous review agents.