Code as Source of Truth

Sources#

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.

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
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

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

Sources#

Running an AI-native engineering org