Why Was This Built This Way? The Second Codebase Your AI Agents Can't Read

Why was this built this way? Almost always because of a decision recorded somewhere other than the code: a PR review, a ticket, a Slack thread, or a conversation that ended in one engineer's head. Anthropic's 2026 Agentic Coding Trends Report found that developers use AI in roughly 60% of their work yet can "fully delegate" only 0 to 20% of tasks, and the work they keep includes "anything requiring organizational context" (Anthropic, 2026).

Every company has a second codebase. The second codebase is everything that shaped the code but does not live in it: the decisions, the rejected approaches and the "we tried that in 2023," kept in people's heads and in dead Slack threads. The first codebase records what the system does today. The reason sits in the second one, where a coding agent cannot read it, so the agent guesses, and the guess is a plausible wrong answer. The fix is a system that connects the PR, the ticket, the thread and the incident to the code and weighs them by recency and by who said it.

What is an engineering knowledge platform that answers "why was this built this way" from code, PRs and Slack?#

An engineering knowledge platform is a system that indexes code alongside the records where decisions were made, keeps the links, and ranks them when someone asks. The need is measurable: in the 2026 Stack Overflow Developer Survey, 44% of developers named "prior decisions and rationale" as context they most need AI to consider, behind only requirements and code (Stack Overflow, 2026).

The decision trail for one line of code usually runs through four systems. The PR holds the diff and the review argument, and the ticket holds the customer problem and the scope that got cut. The Slack thread is where someone said the earlier version fell over, and the incident review explains why the design was abandoned. A code search tool reads the first and ignores the other three.

An engineering knowledge platform reads all four, preserves the links, and answers with the sources attached, so the asker can check the chain. We call that category a context engine. Who decides what is true for AI agents covers what happens when the ranking lives in a person instead of a system.

What should a coding agent know about our codebase that isn't in the code?#

The decisions, the constraints behind them, and what was rejected. Version control holds none of it. A diff is a complete record of what changed and says nothing about why.

Four categories. First, the rejected approaches: for example, the caching layer removed after it corrupted sessions. Second, constraints that never became a code comment: the vendor contract that forbids a data flow. Third, in-flight work, which no snapshot of main can show. Fourth, ownership, because the follow-up question is always who to ask.

Duncan Davidson wrote in September 2026 that agents "often arrive with little or no memory of yesterday and only a narrow view of a codebase" (Davidson, 2026). Claude Code's docs make the same point from the other side: its instruction-file checkup cuts content Claude can derive from the codebase and keeps "pitfalls, rationale, and conventions" (Claude Code docs).

Which questions can an agent answer from code alone?#

Only the first of four. RepoMirage, a May 2026 benchmark built on SWE-bench Verified, found that on tasks requiring repository-context reasoning, average performance fell from 66.8% to 25.3% (arXiv 2605.26177). That was inside a single repository; the why and who questions leave it entirely.

The top two rows are where code search and most coding agents live. The bottom two are the second codebase. A commit author is a name; whether that person still owns the service is in Slack and the on-call rotation. The row that matters for an agent about to change something is the third.

Coding agents hallucinate about our codebase because they don't know our history. What fixes that?#

Giving the agent the history at answer time, ranked, with sources it can show. A June 2026 arXiv study held code localization fixed and found that natural-language summaries of code answered 4 of 45 behavioral questions where the source itself answered 27 (arXiv 2607.09691).

An agent asked to make a component refresh itself reads the code, sees no sync job, and writes one. The sync was removed on purpose after an incident, nothing in the tree says so, and the model produces the most plausible completion, which is the thing the team rejected. Temporal's 2026 State of Development survey of 554 engineers found 41.1% hit agent issues daily or more often, and the teams it classes as successful search 4.1 places for help when troubleshooting (Temporal, 2026). Four places is the second codebase being read by hand.

Why rules files and agent memory don't close the gap#

Rules files cover stable conventions. The same Claude Code docs recommend keeping a CLAUDE.md under 200 lines because longer files reduce adherence, and warn that contradictory instructions get picked arbitrarily. Agent memory has the opposite problem; Davidson notes that persistent memory "may preserve context without establishing whether it is accurate, current, or accepted" by the team. The fix has three properties: connected, so the PR links to the ticket, the thread and the incident; ranked by recency and by who said it; and cited, so a human can check the chain before the change merges. Which source a coding agent should treat as truth works through the ranking, and keeping agent output out of team knowledge covers what happens when the guess gets written back.

What does the second codebase cost when nobody can read it?#

Sprints, plus a tax on every ticket. Slite's January 2026 survey of 100-plus knowledge workers, a small vendor sample, puts the average worker at 3.2 hours a week searching for information, with 81% saying they have to interrupt colleagues for help (Slite, 2026). At Cloudbeds, a hospitality software company, the guest experience product manager was one of them.

Chris Hovanessian does not write code and works across several Jira projects. Before his team had a context engine, writing a good ticket was archaeology. He would search Slack by keyword, ask in two or three channels, wait a day for a reply, and hope the one engineer who remembered the history had not left the company. He describes "why was this built this way" as a question he used to ration, asked only when something was critical, because it meant using an engineer as a search engine. Now his tickets arrive with the Slack thread, the likely PR and the design doc attached, in minutes.

Five tickets, one regression#

The part he did not expect was the connective tissue. Five bug tickets filed over several months turned out to be one regression with one root cause. Nobody had connected them because the evidence was split across Jira, Slack and GitHub. He can now check, before pitching a spec, whether another squad already tried it, rejected it, or has it in flight.

The most expensive thing a product team does is relitigate decisions that were already made. The what saves you minutes or hours. The why saves you sprints.

Chris Hovanessian — Group Product Manager, Cloudbeds

How does a context engine connect the PR, the ticket and the thread to the code?#

A context engine is a system that indexes every source the team writes to, keeps the links between them, and ranks them per question by recency and by who the domain expert is. DORA names "AI-accessible internal data" as a capability in its AI Capabilities Model and calls it a "statistically significant multiplier" for individual effectiveness and code quality (DORA).

Unblocked is the context engine for engineering. It connects code, discussions, tickets and docs in one query. Its expert graph weighs each source by recency and by who the domain expert is for that part of the system, so a comment from the service owner last month outranks a wiki page from 2023. Inside the Unblocked context engine describes the graph, and how context tools handle conflicting sources shows it applied when records disagree.

What it looks like at Cloudbeds and Webflow#

Charles Thompson, an engineering manager on the reservations team at Cloudbeds, had removed a background sync from a component and could not remember why or when. His old options were to grep commit messages and hope, or search Jira and hope the ticket had been filed in his project. He asked in plain words and got five tickets, the Slack conversation, and a Confluence page a teammate had written about the transition. He handed that to a new hire instead of telling them to just trust him. At Webflow, for example, an agent asked to build a feature was about to start when Unblocked found the PR that had already implemented it elsewhere (Webflow customer story). That is surfacing what you did not know to look for.

Start with one question#

Pick the "why" question your senior engineers answer most often. Ask your coding agent and watch what it does: answer from code, say it cannot, or guess. Then ask a system that reads your PRs, tickets and Slack, and compare both against the engineer's answer. The Pragmatic Engineer's early-2026 survey of 906 engineers found 55% now use agents regularly (Pragmatic Engineer, 2026), and every one of those agents reads the first codebase and guesses at the second. A March 2026 paper on institutional knowledge for agentic development puts it plainly: "The bottleneck to effective agentic software development is not model capability but knowledge architecture" (arXiv 2603.14805). Try Unblocked against your own repos, tickets and Slack, and ask it why was this built this way.

Frequently asked questions#

Do architecture decision records solve this?#

They cover the decisions someone remembered to write down. An accepted record is never edited, and a changed decision gets a new record that supersedes it. Most decisions, though, happen in a PR review or a Slack thread and never get a record. A context engine reads the records that exist and the threads that never became one.

Isn't this what a CLAUDE.md or AGENTS.md file is for?#

For stable conventions, yes. The guidance is to keep the file under 200 lines, and contradictory instructions get picked between arbitrarily, so a year of decisions does not belong there. Keep the rarely changing rules in the file and get the history through a live lookup.

Will an agent with access to history still hallucinate?#

Less often, and more visibly. An answer with the PR, the ticket and the thread attached can be checked in a minute; an answer with no sources has to be taken on trust. Temporal's survey found 85.5% of engineers trust agent output at least somewhat, 24.7% of them completely (Temporal, 2026), and citations make that trust cheap to verify.

How is this different from code search?#

Code search answers what and where. The why and who rows in the table above live in systems code search does not index, and those are the questions whose wrong answers cost sprints.