Stop reading code. Start reading what your app does.
AI writes the code now, and most of us have stopped reading it. What still matters is what the app does, and that is best said in plain natural language.
/ddd (doc-driven development) is a skill for AI coding agents to write documentation for features, changes and plans so humans can follow along.
You continue working exactly the same way you do today. The difference is now you can follow a record of what's decided and planned, what changed and needs testing. Without needing to decipher code diffs.
Docs first, then code
Every change that affects how the app behaves lands in the docs before it lands in code. "Let guests bring a plus-one" becomes a few new sentences in the RSVP doc, then code.
Plan, then apply.
The agent never rebuilds silently. It shows what changed in the docs, explains what that means for the people using the app, flags anything that contradicts another doc, and asks before touching code.
Behavior, not implementation.
The docs say what the app does, in words you'd use in a meeting. Frameworks, database tables and other technical choices go in a separate .tech/ folder that non-coders can ignore.
Every feature doc ends with a few acceptance criteria and the agent turns each one into a test. If the code and the doc disagree, a test fails.
You can still edit a doc yourself when that's quicker. At the start of every turn the agent checks what changed in the docs since the last build, so an edit you forgot to mention never slips through.
What the docs look like
Everything lives in a docs/ folder, and each subfolder answers one question, so there's always one obvious place to look:
docs/
├── app.md what the app is, who uses it
├── roadmap.md what gets built next
├── data/ what the app remembers
├── features/ what the app does
├── pages/ what people see
├── components/ pieces reused across pages
├── integrations/ email, sign-in, payments
├── plan/ work that isn't built yet
└── .tech/ technical decisions
A feature doc for a small dinner-club app reads like this:
---
type: feature
uses: [data/rsvp, data/dinner, integrations/email]
shown-on: [pages/dinner]
---
# Reply to an invite
A guest opens their invite and says
whether they're coming.
## Who
- Anyone with the invite link.
- Guests don't need an account. They give
their name and email once.
## Rules
- Replies close when the dinner starts.
- Each invite is for one person.
- If the dinner is full, new "going"
replies join a waitlist.
## After
- Host gets [[integrations/email#new-reply]]
## Acceptance criteria
- Given a dinner with seats left, when a
guest replies "going", then they appear
on the guest list.
- Given a full dinner, when a guest
replies "going", then they join the
waitlist.
## Open questions
- Should guests see who said maybe?
No function names, no tables, no endpoints. Docs link to each other, and a short header records what each one depends on, so when one changes the agent knows which others to check.
Reviewing a change in sentences
This is where ddd pays off for a team. Take adding plus-ones to the dinner club. As a code diff, it touches five files. The new rule is buried in a line like this:
const status = taken + need <= dinner.seats ? 'going' : 'waitlist';
It's correct, but to know what changed for guests you have to work it out, and one consequence is easy to miss.
The same change as a doc diff:
- Each invite is for one person.
+ Guests who are going can bring one plus-one.
+ A plus-one takes a seat. If there's room for the guest
+ but not the plus-one, both join the waitlist.
The rule is the diff. A product manager, a designer or the person who asked for the feature can read it, check it's what they meant, and comment on a sentence. The history of the docs becomes a history of the app in plain language.
Plan the whole app, build it one piece at a time
The docs can also describe what the app will do. Use /ddd plan <your idea> to describe what you have in mind, and the agent writes it up a plan without building anything.
Where a doc lives tells you its stage.
Anything in features/, pages/ or data/ is built and live, so you can trust every rule in it.
Finalized plans live in plan/. While loose ideas still evolving go in plan/ideas/. You can see what exists and what's coming from the folder tree alone.
Roadmap
A roadmap.md groups the plans into phases, with phase 1 as the smallest version someone would actually use. From there, saying /ddd next to your agent takes one item at a time:
- It asks about anything the plan left open.
- It builds the item and runs its tests.
- It moves the doc to where it now belongs and checks the item off.
- It stops and reports what was done.
Changes to existing features get their own plan too, so the live docs are never mixed with work in progress. The frontmatter header on the file specifies what is a change or new feature.
Try it and give feedback
ddd works with Claude Code, Cursor, Codex and most other coding agents. Install it from your project folder:
npx skills add fabiogiolito/ddd
Then talk to your agent as usual, or use the commands:
• /ddd shows what changed in the docs since the last build
• /ddd plan <idea> plans features and phases, without building
• /ddd next builds the next item on the roadmap
• /ddd <request> starts a new app or makes a change, docs first
Use it on your next project and you may find you understand your own app better than you ever did from the code.
Project page: more details and a full example.
Github repo: skill source.
Top comments (0)