Prompt-Driven Development · A field manual
Write the rules down.
Let the agent follow them.
Put requirements, house rules, and acceptance criteria into files your coding agent reads every session, not into chat messages you have to repeat. Here you'll find the method, essays on applying it, and templates to copy.
§01 — DEFINITION
A prompt isn't a spell.
It's a spec.
Prompt-Driven Development (PDD) means writing down what you expect from a coding agent — what to do, what never to do, what counts as done — as versioned rule files, skills, and templates that live in the repo and get reviewed like code.
It isn't a bag of prompt tricks, and it doesn't replace tests, code review, or human judgment. The point is to keep them working when an agent is the one writing the code.
§02 — CONTRAST
Same task, two habits
| Dimension | Ad-hoc prompting | PDD |
|---|---|---|
| Where rules live | Retyped into each chat, gone when the session ends. | Committed rule files the agent loads at the start of every session. |
| Definition of done | Done when the agent says it's done. | A failing test first. Every PR states validation, risk, and rollback. |
| Judgment calls | Buried in a change summary, found after release. | Listed as decisions open to veto: the choice, the alternative, the way back. |
| Follow-ups | A closing line that says "follow up later." | A ledger entry, committed with the code and waiting for a decision. |
§03 — PRINCIPLES
Six principles
Every article and template here unpacks one of these.
Keep the rules file lean
The rules file loads every session. Put only non-negotiables there; move everyday conventions into skills and docs.
Say when, not just what
One job per skill. The description says when to invoke it; a skill that doesn't say when rarely gets picked.
Check five things first
Before a long task, confirm repo and branch, scope, decisions left to humans, hard limits, and how to split PRs. State any defaults you're assuming.
Leave decisions open to veto
User-facing copy, pricing, restricting users, deleting data: the agent may go with the recommended option, but must list the choice, the alternative, and the rollback.
Checks over promises
Write the failing test first. Every PR needs Validation, Risk, and Rollback, and CI fails a PR that skips one or fills it with N/A.
Write for the absent reader
Log follow-ups in a ledger, not in chat. Reports lead with the conclusion and what you need from the reader, then the process.
§04 — LIBRARY
The library
Essays organized by topic. Each covers one practice, with snippets you can adapt. Pieces still in progress are marked "In progress."
- All
- Rules
- Skills
- Decisions
- Workflow
- Quality
- Handoff
- 01RulesYour rules file is too long: what stays, what movesSeparate non-negotiables from conventions, and keep the file short enough that the agent takes it all in every session.In progress
- 02SkillsWriting a skill that gets invoked at the right timeThe agent picks skills by their description. Name the situation and the cues, and say when not to use the skill.In progress
- 03DecisionsThe veto list: the agent decides, a human can overruleWhich calls must be surfaced, how to format the list, and how to write a rollback someone can actually run.In progress
- 04WorkflowThe five-point check before a long agent runRepo and branch, scope, open decisions, hard limits, how to split PRs, plus sane defaults for whatever nobody specified.In progress
- 05QualityMake CI read your PR descriptionA small script that fails PRs with missing sections or placeholder text, and why you should run it locally before you push.In progress
- 06QualityA recurring review checklist for long sessionsHave the agent re-read its diff on a timer, check it for correctness, security, performance, consistency, and maintainability, then report in a fixed format.In progress
- 07HandoffIf it's not in the ledger, it doesn't existCommit follow-ups as files alongside the code. Archive them once resolved; don't delete them.In progress
- 08HandoffWriting the wrap-up for someone who wasn't watchingLead with the outcome and what you need from the reader, then the story. Explain every ID and acronym the first time it appears.In progress
§05 — TEMPLATES
Templates
Copy into your repo and replace anything in [brackets].
CLAUDE.md / AGENTS.md
Project rules file
Non-negotiables only: branching, PRs, decision records, testing. Same content either way; use the filename your agent reads.
SKILL.md
Skill skeleton
Three parts: when to trigger, the steps, the output format.
pull_request_template.md
PR description template
Validation, Risk, and Rollback sections, with guidance for when one doesn't apply.
DECISIONS.md
Decision log
One entry per decision open to veto: the choice, the alternative, the rollback.
ledger/ENTRY.md
Ledger entry
One file per follow-up: source, impact, status, resolution.
HANDOFF.md
Handoff report
Conclusion first, then what the reader needs to do and which decisions are open to veto. Details go last.
§06 — SAMPLE
What a rules file looks like
A generic excerpt. Swap in your own values where you see brackets.
L1–3
Open by saying what belongs here: rules, nothing else.
L9
Write limits as "not without approval," not "be careful."
L17–18
Anything a human must sign off on gets its own list.