developmentL1 Ad-hocContext Engineering

Tribal knowledge in people's heads

At L1, the rules governing your codebase live in developers' memories - invisible to AI agents, fragile under turnover, and impossible to scale.

·Agent sees only the currently open file (no project-wide context)
·No structured context files (CLAUDE.md, AGENTS.md) exist in the repository

·README.md exists but may be outdated
·Developers manually paste context into AI chat when needed

Evidence

·Absence of agent instruction files in repository
·README.md with last-modified date older than 6 months

What It Is

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.

Why It Matters

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.

Tip

Run a "Why is this code like this?" session with your senior engineers. For every non-obvious pattern, write down the reason in one sentence. This list is the core of your CLAUDE.md file's conventions section.

Getting Started

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

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has a senior engineer, Tom, who is the only person who fully understands the payment processing integration. Every time that system needs changes, Tom reviews every PR. Tom is a bottleneck - and also a flight risk. Bob knows this is a problem but hasn't acted on it because "Tom is not going anywhere."

What Bob should do: The tribal knowledge problem is a continuity risk whether or not Tom leaves. Bob should treat the knowledge transfer as a business continuity exercise, not an HR risk mitigation. The action: block 4 hours of Tom's time over two weeks to produce three artifacts - a CLAUDE.md section for the payment integration, an ADR for the key architectural decisions, and a "danger zones" document for the parts of the code that require unusual care. This investment pays off for AI tooling, for new developer onboarding, and for the org's resilience.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah notices that AI tool acceptance rates are significantly lower in teams working on legacy systems compared to greenfield services. She surveys developers and gets a consistent answer: "The AI doesn't know our constraints." Developers in those teams spend more time correcting AI suggestions than they save accepting them.

What Sarah should do: The root cause is tribal knowledge density. Legacy systems have accumulated more undocumented constraints over more years, and the gap between what the agent knows and what it needs to know is correspondingly larger. Sarah should propose a "context engineering sprint" for each legacy system - a two-week investment in capturing the most important tribal knowledge into CLAUDE.md files. She can frame this as infrastructure investment: the sprint unlocks AI productivity gains that compound for the lifetime of the system.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor is the keeper of significant tribal knowledge about the event sourcing implementation. He fields questions about it weekly. When he tries to use Claude Code on that codebase, he spends the first 10 minutes of every session re-explaining the same constraints before he can trust the agent's suggestions.

What Victor should do: Victor is manually providing the same context every session - that's a sign the context should be written down once. His action: write a AGENT.md (or append to CLAUDE.md) that captures the event sourcing invariants, the patterns that are forbidden, and the common mistakes agents tend to make in this domain. Then test: start a fresh agent session, let it read the file, and compare suggestion quality to his current manual-context workflow. The improvement should be immediate and demonstrable.

What Victor should do - role-specific action plan