The domain knowledge base that builds itself — your next hire’s shortcut
On a large codebase, the “why” lives in people’s heads — the ubiquitous language, the rules, the decisions. SpecShip captures it as you work, links it to the specs and code it governs, and keeps it honest with drift. New team members read the domain, not the tribe.
SE
Selva E.
Jun 26, 2026 · 9 min read
Open a million-line codebase you didn't write and the hard part isn't reading the code. It's the thousand small "why"s the code can't tell you: why captures have to be idempotent, what "settlement" means here specifically, why payments go through an outbox instead of a direct call, which fields are PII and must never be logged. That knowledge is real, load-bearing, and almost entirely undocumented — it lives in the heads of the people who've been here longest.
For a new team member, absorbing it is the whole onboarding. For an AI agent, not having it is why a perfectly reasonable change quietly violates a rule nobody wrote down. SpecShip's answer is a domain knowledge layer: the why, captured as you work, wired into the code it governs, and kept honest over time.
What a domain fact is
The structure layer (the graph) tells you what the code is. The spec layer tells you what it must do. The domain layer captures what it means and why — as small, typed facts, one of four kinds:
Term — a word in your ubiquitous language, defined once. "Capture", "settlement", "chargeback".
Rule — an invariant that must hold. "A repeated capture of the same charge must not double-bill."
Decision — an ADR-style record: the call, why, and what was rejected.
Constraint — a regulatory, security, or performance bound. "PII is never written to logs."
specs/domain/captures-idempotent.md
---
id: DOM-PAY-001
type: rule
depends_on: REQ-PAY-004
---# Captures are idempotent
A repeated capture of the same charge MUST NOT double-bill.
That depends_on is the whole point. A domain fact isn't a wiki page off to the side — it attaches to the requirement specs it governs, and through them to the code that implements them. The why is wired into the what.
It builds itself as you work
Nobody sits down and writes a domain knowledge base — that's why teams don't have one. SpecShip builds it from the work you're already doing, by running the loop automatically and asking only for the part a human has to provide: confirmation.
It finds what's undocumented
SpecShip already has the whole graph, so it knows what exists. A gap pass lists the entities and specs that no domain fact covers — "the Payment class is referenced across twelve files and has no stated rules" — and turns that into a coverage number: documented versus gaps. The system generates the questions; you don't have to know what's missing.
4
fact types: term · rule · decision · constraint
→ spec → code
every fact links down to what it governs
drift
keeps it honest as the code moves
It captures through interaction, not a blank page
The /specship:spec domain command grounds in the real repo and interviews you with targeted, per-type questions about the actual undocumented things — not a generic "describe your domain." You answer in a sentence; it writes a well-formed fact under specs/domain/. Crucially, it writes only on your explicit confirmation. The knowledge accretes from the specs you author, the functional definitions you give, and the answers you confirm — not from a model guessing.
Propose, never auto-apply. The model can detect gaps and draft a fact, but nothing reaches disk until a human confirms it. A domain base full of plausible-but-wrong "knowledge" is worse than none — so the trustworthy facts are the only ones that land.
It stays honest by itself
Because each fact rides its spec's links to code, drift comes for free: rename or move the code a rule governs and the fact's chain flips to drifted, landing in the review queue. A domain wiki rots the day after it's written; this one tells you the moment reality diverges from what it claims.
A domain wiki is a snapshot that's wrong by next week. A linked domain layer is a live index on the why — and it raises its hand when the code moves out from under it.
The enterprise edge: onboarding at scale
On a small project you can carry the domain in your head. On a large one, the implicit domain knowledge is the moat — and it's also the bottleneck. Every new hire spends their first months reconstructing it by reading code, asking questions, and slowly building the mental model the senior engineers already have.
A heavily-scoped domain layer collapses that. A new team member reads the terms, rules, decisions, and constraints — grouped, searchable, each linked to the exact code it governs — and absorbs in hours the context that used to take months. They read the domain, not the tribe. And the coverage number turns an invisible asset into a measurable one: you can see how much of your domain is captured, and where the gaps are.
The same payoff lands on the agent. Because facts are surfaced inline — specship_spec on a requirement lists the domain facts that govern it, and naming a documented term in specship_explore returns its confirmed meaning — your AI coding agent writes code with the same domain context a senior engineer carries. It follows the idempotency rule and the no-PII-in-logs constraint not because you re-pasted them into a prompt, but because they're part of the project's indexed knowledge. New hire or new agent, the shortcut is the same.
Code tells you how the system is built. Specs tell you what it has to do. The domain layer tells you what any of it means — and on a large team, that's the knowledge that's hardest to transfer and most expensive to lose. SpecShip's job is to make sure it isn't only in someone's head.
