When an AI coding agent adds plus-ones to a dinner-club app, the change gets buried in a JavaScript ternary expression like const status = taken + need <= dinner.seats ? 'going' : 'waitlist'. It is correct, but figuring out what actually changed for your users requires decoding implementation details. According to Fabio Giolito in Doc-driven development for AI Agents (ddd skill), the fix is to stop reading code diffs and start reading natural language docs before any code is written.
The Generic Default: Silent Code Generation
Most developers using AI agents today let them touch code files immediately. The agent writes functions, updates database tables, and juggles API routes in one opaque turn. If you want to know what changed, you have to parse git diffs or test the live app manually. Framework choices and technical debt get tangled up with core product rules. Non-coding team members cannot review the logic, and minor edge cases slip past unnoticed.
The Fix: Behavior Over Implementation
Doc-driven development (the /ddd skill) reverses that order. Every change that alters how the app behaves must land in a markdown document inside a docs/ folder before touching code. For example, a feature file for replying to an invite defines who can access it, rules for waitlists, and exact acceptance criteria like Given a dinner with seats left, when a guest replies going, then they appear on the guest list.
The agent never rebuilds silently. It shows what changed in the docs, explains the impact on users, flags contradictions, and waits for confirmation. The history of the docs becomes a clean history of the app in plain language.
Structuring the Knowledge Base
Organizing files by purpose rather than technology keeps things obvious. The docs/ folder uses specific subdirectories:
app.mdfor what the app is and who uses itroadmap.mdfor upcoming milestonesdata/for what the app remembersfeatures/for what the app doespages/for what people seeintegrations/for email, sign-in, and payments.tech/for technical decisions that non-coders can ignore
Each feature document includes frontmatter listing its dependencies, such as uses: [data/rsvp, integrations/email]. When a dependency changes, the agent knows precisely which other documents require review.
Planning and Roadmap Commands
Instead of letting an agent freestyle a full-stack application from scratch, you can run /ddd plan <your idea> to outline features and phases without generating code. Finalized plans live in plan/, while experimental ideas stay in plan/ideas/. When you are ready to build, calling /ddd next prompts the agent to address open questions, execute the next item, run the associated tests, and move the documentation into the active features/, pages/, or data/ folders.
If you want to try it, you can install the skill via npx skills add fabiogiolito/ddd and use commands like /ddd to inspect recent doc changes or /ddd <request> to start a new feature. How do you currently verify that your AI coding assistant implemented the exact business rules you asked for?