Back to Catalog
Agentic AI
Planning & Control Flow
Spec-First Agent
Drive the agent loop from a human-authored specification document rather than free-form prompts.
Intent & Description
🎯 Intent
Drive the agent loop from a human-authored specification document rather than free-form prompts.
📋 Context
A team runs an agent on a task that is well-defined enough to write down — a recurring report, a bug-fix list, a migration plan, a multi-step automation. The team wants the agent’s instructions to live in a file that humans can read, review, and edit alongside the code, rather than in a chat history or someone’s head. Reviewers should be able to diff changes to the agent’s intent the same way they diff changes to source code.
💡 Solution
- Write the specification as a markdown file (PROMPT.md, fix_plan.md, or similar). - The agent reads the spec at each iteration, executes against it, and may update it under controlled conditions. - The spec is the single source of truth for what “done” means.
Real-world Use Case
- The task is well-defined enough to write down as a spec.
- The spec needs to be inspectable, audited, or shared across engineers.
- The agent benefits from a stable target rather than free-form prompts.
Source
Advantages
- Inspectable target; reviewable diffs over time via standard VCS tooling.
- Pairs naturally with iterative loops (Spec-Driven Loop).
Disadvantages
- Spec quality bounds agent quality; a poor spec produces poor runs.
- Spec mutation introduces drift if updates are uncontrolled.