A method for document-driven agentic development
There is a fundamental tradeoff in LLM-based development: automation vs. design. The more we qualify what we want to create, the less we can automate its creation. "Create a reddit clone" is four words because every design decision is answered by example; any fundamental (non-modular) innovation requires to express how it affects every part of the program. Design must be expressed; intention cannot be inferred.
Document-driven development is an answer to that tradeoff where the user/team meet the automated system halfway.
Four principles hold the method together:
- Documents carry structured context — they hold the project's organized knowledge.
- Documents are part of the repository — committed, tracked, and updated from version to version, just like code.
- Documents have relations amongst them (dependency, supersession etc.) expressed in metadata
- Documents hold both a prescriptive role and a descriptive role — what has been done, what is to be done
- Documents use a familiar hierarchy with explicit semantics — project plan → task plans (roadmaps) → specs, a shape many project-management methodologies use under various naming schemes.
- Document meaning is explicit — not a "find the most relevant context" retrieval or memory system.
- A spec states the intent for one piece of work.
- A roadmap describes a capability or otherwise grouped functionality expressed in ordered specs.
- A project plan imposes global order and connects to global constraints
- Horizontal rules (approaches) hold invariants that apply globally.
- Project vocabulary is used both as a human-readable glossary as well as a constraint to vocabulary drift (the tendency of agents to explode their vocabulary into many different synonyms and keywords.)
- A VISION.md holding the project vision and scope as well as some guiding principles
Hyperlinking and file metadata do the quiet work of holding the structure together, letting each spec point to another spec it refines, a roadmap it helps advance, an approach that it applies. Rich grep-able metadata names status and place in a glanceable form, so state is visible without opening every file.
Two situations call for this method:
- You need a document trail. Your project must be audited, handed over, or reconstructed later. Committing project documentation to git provides that trail for free. Every decision is dated, tracked, and updated from version to version — with no external service to adopt or maintain.
- You want code and design in one history. Code and design traditionally evolve in separate tracks, kept in sync by manual or semi-automatic effort. LLM-based development forces the two together with the design committed besides the code it produces. What was decided, what is done, and what remains are readable in one place, at one version.
If either describes your project, the method asks for little: documents you would write anyway, kept in the version control you already use.
- User sovereignty: the end user remains the final judge. Agents research, propose, and execute, but only the user decides.
- Horizontal-vertical separation: shared rules stay apart from project detail, so principles stay stable while the work itself changes.
- Use-what-you-need: adopt only what the task requires, from just using specs to the full-fledged methodology, at your own pace.
Together these ideas keep authority with the person, stability with shared rules, and effort proportional to the task at hand. The most opinionated idea is that documents, not chat history should drive the work. This is the differentiating factor between DDD methods and any method that tries to automatically create context. Context is created in an explicit manner, via user decisions. We are balancing ease of use, with state observability and capacity for communication.
This project is an applied exploration, being worked on in the open. The project itself is bootstrapped and developed using the Docent Method.
The method's document discipline should be real, intuitive, and eased into at your own pace, a structure to grow into, not a wall to climb first; the user's attention should stay on the task at hand and the method should only enhance their experience.