New engineers joining a typical backend team can get productive fast: read the schema, trace a request through the code, run the test suite, ship a small fix. Joining a team that owns an AI feature is slower in a specific, under-discussed way — not because the code is more complex, but because a meaningful share of how the system actually behaves lives outside the code entirely.
It's in the shape of the prompt: why a particular instruction is phrased awkwardly, because the natural phrasing caused a regression three months ago and nobody wrote that down anywhere but a closed pull request. It's in which failure modes get silently retried versus escalated, a distinction usually encoded as a magic number in a config file with no comment explaining the incident that produced it. It's in which eval failures the team has decided to tolerate because fixing them would regress something else, a tradeoff that exists only in someone's memory of a meeting.
None of this fits neatly into a README, because it isn't a description of the system — it's a description of the system's history, and most documentation formats are bad at capturing history. The fix isn't more documentation effort in the abstract; it's treating "why does this look like this" as a first-class artifact. A short comment linking a prompt line to the incident or eval case that shaped it costs a sentence and saves a new engineer from re-litigating a decision that was already made, often the hard way, once.
If your onboarding doc explains what the system does but not why it stopped doing something else, the next person to touch it will rediscover the reason by breaking it again.