# Spec-First Agent

> Drive the agent loop from a human-authored specification document rather than free-form prompts.

- **Category**: Agentic AI
- **Subcategory**: Planning & Control Flow
- **Canonical URL**: https://designpattern.fyi/patterns/spec_first_agent/

---

## 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.


## Use Cases
- 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.





## Trade-offs


### Advantages

- Inspectable target; reviewable diffs over time via standard VCS tooling.

- Pairs naturally with iterative loops (Spec-Driven Loop).




### Considerations & Drawbacks

- Spec quality bounds agent quality; a poor spec produces poor runs.

- Spec mutation introduces drift if updates are uncontrolled.







---
**Reference**: [Original Source](https://www.agentpatternscatalog.org/patterns/spec-first-agent/)