Code as Source of Truth

Sources#

• How the Open Knowledge Format can improve data sharing
• Running an AI-native engineering org
• The State of Agent Wikis

Summary#

Fiona Fung's knowledge-sharing rewrite for an AI-native org: when coding bandwidth is high, documentation goes stale faster than anyone can maintain it — so the codebase becomes the source of truth, and anything you want to stay true gets checked into the codebase. Specs become skills committed to the repo; onboarding happens by asking Claude to teach you the surface area rather than by pulling engineers into tech deep-dives. "Our code is our source of truth."

Why docs decay in an AI-native org#

The mechanism is a direct consequence of Verification as the New Bottleneck: higher coding throughput means code changes faster, so any documentation outside the update loop drifts out of date almost immediately. Fung's prescription: "whatever is your source of truth — whether it's a spec — change that into a skill you check into the codebase, so you can keep it up to date." The repo is the one artifact that stays current because it's the thing being changed.

Specs-in-repo enable spec-drift verification#

Checking the spec into the codebase isn't just freshness hygiene — it's what makes mechanical verification possible: "Claude is very good about verifying against spec drift." A committed spec is both human-readable intent and a machine-checkable reference the review agent compares the diff against. (This is the same move as Symphony's WORKFLOW.md and Claude Code's CLAUDE.md — repo-versioned plaintext as control plane; see Symphony, Claude Code Best Practices.)

Docs as build artifact: regenerate instead of maintain (Factory AutoWiki)#

Fung keeps docs true by checking truth into the repo; Factory's AutoWiki (via mem0's July 2026 agent-wiki survey, practitioner-opinion) closes the same staleness gap from the other end — make the documentation a derived function of the repo: a build artifact regenerated in CI on every push to the default branch (/install-wiki writes the workflow), not a separate project anyone maintains. The survey's phrasing: Factory "keeps the wiki correct with infrastructure, and not with discipline," and across the four agent-wiki systems it calls the CI-vs-on-command difference "the maturity tell" — every non-CI wiki "is exactly as current as the last time someone ran the command."

The two prescriptions compose rather than compete: what can be derived from code gets regenerated (AutoWiki); what cannot — intent, specs, conventions — gets committed so the change loop keeps it current (Fung). Either way, nothing load-bearing lives in an artifact outside the update loop. Full landscape on LLM-as-Compiler Knowledge Base.

The same rule written into a format spec (June 2026)#

Fung states check-it-into-the-repo as a workflow prescription. Google Cloud's Open Knowledge Format (2026-06-12, vendor-claim) makes it a format requirement: of the five properties it says a knowledge representation must have, one is that it "lives in version control alongside the code it describes" — which is why the format is "just files" and not a service with an API. The reasoning is this page's, arrived at from the interoperability side: a knowledge store reachable only through a vendor's catalog API is outside the change loop by construction, no matter how current its contents. What the spec does not inherit is the second half of Fung's argument — a committed spec is machine-checkable against drift, and OKF standardizes no field a checker could key on. See LLM-as-Compiler Knowledge Base for what else the format leaves to the producer.

The migration rule this page never states: name one source of truth per artifact (August 2026)#

Both statements above assume a greenfield choice. Anthropic's Applied AI AI-Native SDLC playbook (vendor-claim, 2026-08-21) is the first source in the corpus to address the case that actually blocks adoption — the record already lives somewhere auditors accept. Its sidebar is blunt about why Jira, ServiceNow, a regulated requirements tool or Figma cannot simply be deleted: they are "hard to displace because auditors and regulators already accept them and other teams depend on them."

Its rule is per-artifact, not per-organization: name exactly one system as the source of truth for each artifact, and let everything else hold a copy or a link. Three configurations, in decreasing cleanliness:

• Repo authoritative — the markdown is the record, the legacy system references files within commits. Named the cleanest for engineering-led orgs, and for this page's exact reason: one tool, one timestamp authority.
• Legacy authoritative — the requirements tool holds the record; Claude reads it at session start and writes the outcome back through an MCP connector in the same session that produced the spec or plan, with the markdown demoted to a working copy. This preserves the agent-readability half of this page's argument while conceding the version-control half.
• Linkage only — every artifact notes the record ID, every legacy record carries the commit SHA. Recommended as the starting point, with the cost stated plainly: two sources of truth.

The failure this taxonomy is written against is the un-chosen middle — two systems, neither declared authoritative, drifting. See The Committed-Artifact Chain for the chain of artifacts this rule governs.

Onboarding via Claude, not via colleagues#

Fung's own onboarding to Claude Code: instead of (only) tech deep-dives with engineers, she did her first deep-dive with Claude — "before I dive into this bug fix, can you teach me about the surface area and the areas around this bug?" Effects she reports: onboarding ramp-up time falls, and the cost to other team members falls — new joiners stop taxing senior engineers' time for context. As a manager, this is also what lets her get back into the codebase without guilt ("I don't feel like I'm wasting anybody's time"). The codebase + Claude is the onboarding doc. (See Managers as ICs.)

Relationship to CLAUDE.md and agentic debt#

Code-as-source-of-truth is the positive program; Agentic Technical Debt is the failure mode it guards against. Persistent, committed context (CLAUDE.md, checked-in skills/specs) is what stops each agentic session from re-deriving architectural decisions. The wiki's own LLM-as-Compiler Knowledge Base is a higher-order instance: a compiled, current artifact rather than re-derived knowledge.

Connections#

• Building Is Cheap, Arguing Is Expensive — if code wins debates, the repo (not docs) is the source of truth
• Fiona Fung — "our code is our source of truth"
• Verification as the New Bottleneck — the cause: high throughput stales docs; spec-in-repo enables spec-drift checks
• Agentic Technical Debt — the debt that compounds when context isn't persisted in the repo; this is the antidote
• Claude Code Best Practices — CLAUDE.md is the canonical repo-versioned-context pattern
• Symphony — WORKFLOW.md / SPEC.md as repo-versioned control plane at the orchestration layer
• Managers as ICs — Claude-as-onboarding-doc is what makes manager-into-codebase re-entry cheap
• LLM-as-Compiler Knowledge Base — compile-and-keep-current vs. re-derive; the knowledge-management principle one level up
• Claude's Constitution / Model Spec — spec-as-load-bearing-document, at the alignment layer
• Prototype Over PRD — the same rationale-capture gap from the other end: this page deletes the doc because code is truth, Carey deletes it because the prototype is the spec; both leave the "why" homeless
• The Committed-Artifact Chain — this page extended two stages upstream: Anthropic's playbook adds intent.md and spec.md to the committed set, so the artifacts a product owner owns join the ones engineers already commit, and it supplies the legacy-migration rule above. It is also the first source to give the "why" a specified home — intent.md carries "what is wanted, why, and under which constraints" — which is this page's first open question answered as a prescription rather than as evidence
• Dynamic Workflows: An Algebra for Agents — the same move applied to failures rather than specs: serialize compiler errors, stacktraces, and failing tests to a file, then let the file be the work queue agents fan out over
• The Code-Quality Payoff Is Token-Indexed — the alternative place to put the same information: persist the spec in the repo, or encode it in the architecture; both exist to stop agents re-deriving context, and DHH prices that cost in tokens
• Spec-Driven Development as the New Waterfall — the direct refusal of this page's spec-in-repo rule: Martin keeps no specification in the repo because the finished artifact is the specification, and puts the durable statement of intent into checkers (CRAP score, mutation tests, dependency rules) rather than a document. Both sides unmeasured; the spec-drift check this page proposes is the instrument that could adjudicate

Open Questions#

• What knowledge genuinely can't live in the codebase (org strategy, the "why," cross-team context) and therefore still needs a durable doc — and how do you keep that small slice current? Partially answered: Where Does the Why Live? — the "why" is the clearest such slice, and every candidate home fails or only partly works; a compiled knowledge base outside the staling code is the least-bad option. The "keep it current" half is untouched.
• If onboarding is "ask Claude," what happens to the tacit knowledge that was previously transferred socially in deep-dives — is it captured anywhere, or quietly lost?

Derived#

• Where Does the Why Live? — takes up this page's first open question; the "why" this page excludes from the codebase has no clean home, only the richer-artifact and compiled-knowledge-base partial patches
• When Knowledge Layers Disagree: Context Files vs Memory, and Conflicting Sources at Compile Time — uses this page as the fact-layer arbiter: when context file and memory disagree about the world, the repo/live state wins and both caches get repaired
• Is Persistence the Line Between Prompting and Spec-Driven Development? — reads this page's two rules as the strong form of the authority line: the payoff of committing a spec is the drift check rather than the storage, and "name exactly one source of truth per artifact" is a rule about which durable copy binds, unintelligible on a persistence reading

Sources#

• Running an AI-native engineering org
• How the Open Knowledge Format can improve data sharing — Sam McVeety & Amir Hormati, Google Cloud, 2026-06-12 (vendor-claim): "What's missing is a format, not another service" — the five format requirements, including version-control residence alongside the code being described. No measurement; no producer or consumer outside Google. Full source treatment on LLM-as-Compiler Knowledge Base