Most README files for an AI-backed feature look like documentation for any other service: how to call it, what the request and response shapes look like, maybe a rate limit. What they almost never answer is the question a new engineer actually needs the first time something goes wrong in production: what does this feature do when the model is wrong, slow, or unavailable?
That's not a gap in effort — it's a gap in convention. Traditional software documentation grew up assuming failure is binary and rare enough to handle with a status code and a retry. AI features fail in shades: a confidently wrong answer, a technically valid response that ignores half the prompt, a timeout that leaves a partial tool call in flight. None of those show up in an API reference, and none are obvious from reading the code, because the failure lives in the model's behavior, not the code around it.
A README worth trusting for an AI feature should say, explicitly: what the fallback is when the model call fails outright, what the feature does when the output fails validation, what a human reviewer should do when they disagree with the model, and which failure modes are known and accepted versus actively being fixed. That's the section a new engineer will actually search for at 2 a.m. — and it's usually the one missing.
If your team already writes a runbook for on-call, this is the same document. It's just written down before the incident instead of reconstructed during one.