A methodology for product teams building complex systems — where structured specifications are the source of truth and code is derivable.
You invest enormous effort writing code, but the knowledge justifying it lives scattered and decaying.
Critical decisions live in Jira tickets, Slack threads, wikis nobody reads, and engineers' heads. There is no single place to understand why the system works the way it does.
Docs are written once and forgotten. Within weeks, they diverge from reality. Nobody trusts them, so nobody reads them, so nobody updates them.
When people leave, they take the why with them. Onboarding becomes oral tradition. Each departure is an institutional memory loss.
A practice where domain knowledge is more valuable and durable than any implementation. Technologies change, frameworks die, architectures evolve — but specifications endure.
Each concept, rule, and decision has one canonical place. The specification defines what the system should do; code implements the specification. If they diverge, one is wrong.
"The code is a cache of the specification."
Documentation is not dead text. It's a living, navigable knowledge graph — consultable by humans for onboarding and by AI agents for reasoning, search, and code generation.
"Living knowledge for humans and machines."
Specifications follow the same rigor as code: versioned in Git, linted, tested, and deployed. A full pipeline — edit, lint, test, deploy — ensures they stay accurate.
"Same rigor as code: version, lint, test, deploy."
Each layer answers a fundamental question about your system, building progressively from business context to technical implementation.
Dependency rule: each layer only references layers below it. Domain stays pure, capabilities stay generic, UI is replaceable.
KDD is designed for teams where the cost of losing knowledge exceeds the cost of capturing it.
Product teams building systems where business rules, entities, and processes are too intricate to live only in code.
Organizations needing traceability from every feature back to a business requirement — healthcare, finance, legal.
Teams where the knowledge must outlive any specific technology choice, framework version, or team composition.
Cross-functional teams that need a shared language and shared source of truth to stay aligned as they grow.
Every concept has one canonical place. Code, tests, and docs all derive from the same specification. No more conflicting versions.
Gherkin acceptance criteria become automated tests. Your documentation can't go out of sync because it is the test suite.
Bidirectional links form a knowledge graph. Ask "if we change Rule X, what breaks?" and get a precise answer.
Layers 1–5 are technology-free. Swap frameworks, rewrite the backend, redesign the UI — your specifications survive.
New developers read the domain, not tribal lore. Self-service onboarding replaces weeks of "ask the senior engineer."
Atomic Markdown files with semantic metadata are ideal for RAG, embeddings, and AI agents that reason about your system.
The methodology, templates, and full documentation are open source. Clone the repo and start structuring your domain today.
Get started on GitHub