Knowledge and Epistemology
A seventeen-year-old project that moves fast and has no policy requiring documentation updates when architecture changes accumulates a particular kind of debt: design documents that accurately described the system at the time of writing but no longer match the codebase. The Chromium docs/ directory is full of them. A reader who consults a stale document receives an accurate historical description and an inaccurate current description, and there is no automated mechanism for telling the two apart. Senior contributors recognize the staleness; new contributors and AI coding agents trained on stale documents do not.
The concepts and antipatterns in this section name that condition and its consequences. Design Document Staleness names the condition itself — endemic, predictable, and corrosive in ways that are easy to underestimate until an AI coding agent hallucinates an architectural approach from a 2019 document. Tribal Knowledge names the body of architectural constraints, historical rationale, and unwritten conventions that lives in the heads of senior contributors and is transmitted through code review comments, Slack messages, conference talks, and mentoring. The Formal-Informal Channel Split names the structural division between formal channels (blink-dev, Gerrit, crbug.com, design documents at chromium.googlesource.com) that are indexed and archived, and informal channels (chromium.slack.com, direct messages, hallway conversations) that are ephemeral. Chromium policy is that formal decisions must be recorded in formal channels; the practical consequence is that the most useful operational knowledge often lives only in the informal channels and is lost when threads scroll away.
This section is meta. It names the conditions that motivate every other section’s existence: the catalog itself is an attempt to transfer informal-channel knowledge into a persistent, indexed, dated artifact that does not go stale silently. A reader who has just landed in the project, an executive wondering why a senior engineer “knows things no one wrote down,” or an AI agent operator trying to figure out why the agent keeps hallucinating an obsolete design uses this section to understand what they are working against.