DDD Practice

What this is

This repo describes a specific way to practice docs-driven development: how to adopt it in an existing project, and how to use and develop with it when AI agents write the code.

Docs vs implementation

Everything else in the repo is the implementation of that description. The idea's rules apply here by reference; where the implementation contradicts this document or the idea, the implementation is wrong.

Adopting where ./docs already exists

When adopting in a project that already has a ./docs, the existing docs are not kept as they were: they are reworked into the standard structure, and content that does not belong in the docs moves elsewhere in the repo, described abstractly in the docs where needed.

The agent skill

The repo ships an installable skill for AI agents, at skill/: it describes how to practice this (adopting and operating per this repo) consistently with this document, and installs by copying the folder into an agent's skills directory. Everything else about the skill is its implementation.

The human-readable HTML

The docs must be as easy for a human to understand as possible while staying complete: HTML document(s) generated inside the repo render them visually, so the human reads the HTML, not ./docs. The rendering is produced deterministically, with no model in the generation path: a model would embellish and break "nothing hallucinated", and a non-deterministic rendering cannot be checked against the docs. The generator is the repo's own, personalized to how its docs are best understood and evolved as they grow, so the effort goes into authoring it rather than re-deriving the output by hand each time. The HTML covers ./docs and nothing else: it is purely the human-readable representation of the docs, complete and correct; it does not describe the implementation or anything beyond the docs. Nothing hallucinated on top, nothing missing. Its point is to minimize the time a human needs to understand and navigate whatever they want from the docs: it may use everything HTML/CSS documents allow (structure, navigation, emphasis, any trick that makes understanding faster) as long as the content stays exactly the docs'. It does not use em dashes unless necessary. The docs themselves may be whatever format best represents the information: markdown is the base, but HTML, images (e.g. .png), or even video belong in ./docs when they represent it better. The human-readable rendering lives outside ./docs, properly organized.

Doc quality

The docs are documentation, not whatever their consumer finds convenient. A governing doc is written declaratively, for any implementer (human or model) that must satisfy it: it specifies, it does not narrate, address, or motivate. Records (what happened, what was verified, what broke and when) are not specification: however useful, they live outside ./docs and are referenced where needed, and this holds down to the granularity of a single sentence, not just whole files. Tests are derived artifacts, not docs: the behavioral guarantee a test enforces is specification and belongs in the docs, but the test itself (the script, its steps and expected results, and any harness that runs it) lives outside ./docs like any code, and a runner that reads its cases from ./docs also breaks the meta rule below. Where behavior is owned by another document or repo, a doc references the original instead of restating it. Structure is part of correctness: ./docs reads as a designed hierarchy, not a bag of files, and a doc that satisfies every placement rule while being disordered or unreadable is still wrong.

The docs are meta: nothing in the codebase consumes ./docs at run time. Code, prompts, and running systems never read a governing doc to decide behavior. Where a runtime needs instruction text, the docs specify a derived document that carries it: generated from the docs, living outside ./docs, regenerated in the same commit as any doc change like every derived artifact, and the runtime consumes only that document. Code may state that something exists to satisfy a doc; it never reads one as input.

Copies and forks

A repo created by copying a practicing repo (a fork, a template instantiation) inherits the source's derived artifacts: the copied README, mirror, and any generated summary describe the source, not the new repo, and are wrong from the moment the copy exists. Creating the copy is therefore a doc event: every derived artifact is regenerated against the new repo's own ./docs before anything else builds on it, and any doc elsewhere that governs the new repo's existence (a parent's member list, a registry) changes in the same stroke.

The README footer

Every repo using this practice states at the bottom of its README that it uses this practice (linked), describes how its ./docs is structured, and says where the human-readable representation lives. Beyond that footer the README does not mention the practice: to a newcomer the repo looks like any repo with docs, and that it is docs-driven shows only on deeper inspection, unless the repo's own docs specify otherwise.

Contributing

When adopting this practice in a repo, its ./docs must describe how to develop and contribute there: anyone developing or contributing follows this practice (linked), docs first, everything else conforms.