Tribal knowledge in people's heads

Every mature codebase has a shadow architecture - a body of unwritten rules, hard-won decisions, and institutional memory that explains why the code is the way it is. Why do we never use the EventBus for cross-domain communication? Because two years ago it caused a cascade failure during a peak traffic event, and we moved to direct service calls for anything user-facing. Why does the OrderService have that unusual retry loop? Because the payment processor we use returns 500 during peak load, and this was cheaper than switching providers.

At L1, this knowledge lives exclusively in the heads of the developers who were there. It's never been written down in a place where an AI agent could read it. When a new developer (or an AI agent) touches that code without knowing the history, they make locally reasonable decisions that violate invisible constraints.

Tribal knowledge is not just a documentation debt problem - it's a context engineering problem. The difference matters: framing it as documentation debt suggests the fix is writing docs. Framing it as a context engineering problem points to the real solution: making that knowledge available to the agents and developers who need it, in a form they can act on.

At L1, the organization accepts this condition as normal. Senior engineers are the "context lookup service" - junior developers and AI agents alike come to them with questions that could be answered by a well-maintained CLAUDE.md file. This is expensive, doesn't scale, and creates a bottleneck that gets worse as the team grows.

Tribal knowledge is a compounding liability. Every L1 organization has it; organizations that stay at L1 accumulate it faster than they dissipate it. The cost shows up in several ways:

• AI agents hallucinate plausible alternatives - without knowing why a constraint exists, the agent removes it or works around it
• Bus-factor risk - the departure of a single senior engineer can make large sections of the codebase effectively unmodifiable
• Onboarding friction - new developers spend weeks asking questions that could be answered by documentation
• Inconsistent code review - reviewers apply different invisible rules; what gets approved depends on who reviews it
• Regressions at the architecture layer - not logic bugs, but violation of invariants no test covers because no one thought to write the test

For AI tooling specifically, tribal knowledge in people's heads means agents make suggestions that are technically valid but organizationally wrong. The agent can't distinguish "this is a good pattern" from "this is a pattern we tried and explicitly rejected." The result is that AI-assisted code requires heavier review than hand-written code - which defeats much of the productivity benefit.

1. Identify your knowledge holders - Map which engineers have unique knowledge about which system areas. Who gets the most "why does this code do X?" questions? They are your knowledge bottlenecks.
2. Run a "five whys" documentation sprint - Pick the 10 most common questions new developers ask senior engineers. For each one, write a 2-3 sentence answer. These are your highest-value documentation targets.
3. Capture decisions in ADRs - Architecture Decision Records (ADRs) are a lightweight format for documenting why a decision was made. A single ADR per major decision, committed to the repository, starts to formalize tribal knowledge.
4. Annotate code with intent, not mechanics - Comments that say "validates the order state machine before processing" are tribal knowledge made explicit. Comments that say "checks if state equals PENDING" are redundant with the code.
5. Build CLAUDE.md from what you've captured - Once you have even a partial inventory of unwritten rules, consolidate them into a CLAUDE.md file in the repository root. This is the transition from L1 to L2.
6. Create a "fragile zones" map - Document which parts of the codebase have the highest implicit complexity. This helps new developers and AI agents know where to slow down and ask questions.

Treating documentation as a one-time project. Tribal knowledge accumulates continuously. A documentation sprint captures the current state but doesn't prevent new undocumented decisions from accumulating. The fix is process: every significant architectural decision should produce an ADR or CLAUDE.md update as part of the work.

Documenting mechanics instead of decisions. "We use PostgreSQL for persistent storage" is not tribal knowledge - it's visible from the codebase. "We chose PostgreSQL over MongoDB in 2021 because our data has highly relational structure and our team has deep SQL expertise - we explicitly don't want to adopt NoSQL patterns" is tribal knowledge worth capturing.

Assuming senior engineers will voluntarily write things down. Senior engineers with deep tribal knowledge are typically also the most busy people on the team. Without explicit time allocation and leadership support, knowledge transfer competes with feature work and loses. Make documentation a first-class deliverable.

Letting the CLAUDE.md file become stale. Worse than no documentation is incorrect documentation. If the CLAUDE.md file says "we use Express.js for HTTP servers" but the team migrated to Fastify six months ago, agents following that guidance will generate wrong code confidently. Build documentation updates into your definition of done.