Code as Source of Truth

Sources#

• Running an AI-native engineering org

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

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#

• 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

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

Sources#

• Running an AI-native engineering org