Code as Source of Truth

資料來源#

• Running an AI-native engineering org

摘要#

Fiona Fung 對 AI-native org 的知識分享重寫是：當 coding bandwidth 很高時，documentation 會比任何人能維護的速度更快過期，所以 codebase 變成 source of truth，而任何你想保持真實的東西都要 check into codebase。 Specs 會變成 committed to repo 的 skills；onboarding 不是把工程師拉進 tech deep-dives，而是請 Claude 教你 surface area。「Our code is our source of truth.」

為什麼 docs 會在 AI-native org 中腐壞#

這個機制是 Verification as the New Bottleneck 的直接後果：更高的 coding throughput 意味著 code 變動更快，所以任何在 update loop outside 的 documentation 幾乎立刻就會 drift 過期。Fung 的處方是：「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.」repo 是唯一會保持 current 的 artifact，因為它就是正在被改動的東西。

Specs-in-repo enable spec-drift verification#

把 spec check into codebase 不只是 freshness hygiene，更是讓 mechanical verification 成為可能的東西：「Claude is very good about verifying against spec drift.」一份 committed spec 同時是 human-readable intent，也是 review agent 用來對照 diff 的 machine-checkable reference。（這和 Symphony 的 WORKFLOW.md 以及 Claude Code 的 CLAUDE.md 是同一招：repo-versioned plaintext 作為 control plane；見 Symphony、Claude Code Best Practices。）

透過 Claude onboarding，而不是透過同事#

Fung 自己 onboarding 到 Claude Code 的方式是：不是（只）和工程師做 tech deep-dives，而是第一次 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?」她回報的效果是：onboarding ramp-up time 下降，對 other team members 的成本也下降，new joiners 不再為了 context 消耗 senior engineers 的時間。作為 manager，這也讓她能無負罪感地重新進入 codebase（「I don't feel like I'm wasting anybody's time」）。codebase + Claude 就是 onboarding doc。（見 Managers as ICs。）

與 CLAUDE.md 和 agentic debt 的關係#

Code-as-source-of-truth 是正面的 program；Agentic Technical Debt 是它防範的 failure mode。Persistent、committed context（CLAUDE.md、checked-in skills/specs）會阻止每一次 agentic session 重新推導 architectural decisions。這個 wiki 自己的 LLM-as-Compiler Knowledge Base 是更高階的實例：它是 compiled, current artifact，而不是重新推導出來的 knowledge。

相關連結#

• Building Is Cheap, Arguing Is Expensive — 如果 code 贏得 debates，那麼 repo（不是 docs）就是 source of truth
• Fiona Fung —「our code is our source of truth」
• Verification as the New Bottleneck — 原因：high throughput 讓 docs 變 stale；spec-in-repo 啟用 spec-drift checks
• Agentic Technical Debt — 當 context isn't persisted in repo 時會 compound 的 debt；這就是 antidote
• Claude Code Best Practices — CLAUDE.md 是 canonical repo-versioned-context pattern
• Symphony — WORKFLOW.md / SPEC.md 作為 orchestration layer 的 repo-versioned control plane
• Managers as ICs — Claude-as-onboarding-doc 讓 manager-into-codebase re-entry 變便宜
• LLM-as-Compiler Knowledge Base — compile-and-keep-current vs. re-derive；knowledge-management principle 往上一層
• Claude's Constitution / Model Spec — spec-as-load-bearing-document，位於 alignment layer

待解決的問題#

• 什麼 knowledge 真的 can't live in codebase（org strategy、「why」、cross-team context），因此仍然需要 durable doc？又該如何讓那一小塊保持 current？
• 如果 onboarding 是「ask Claude」，那些過去在 deep-dives 中透過社交方式傳遞的 tacit knowledge 會發生什麼事？它有被 capture 在任何地方嗎，還是安靜地 lost？

衍生內容#

• Where Does the Why Live? — 接續本頁第一個 open question；本頁排除在 codebase 外的「why」沒有乾淨的 home，只有 richer-artifact 和 compiled-knowledge-base 這些 partial patches

資料來源#

• Running an AI-native engineering org