The Documentation Agent

A documentation agent's job is to describe what code actually does — in a README, in docstrings, in a changelog entry — accurately, for a human reader. Its job is never to change what the code does. This chapter covers designing one, keeping it honest against the single biggest risk documentation faces, and knowing where its responsibility actually ends.

What a Documentation Agent Actually Does

This covers a range of related tasks: writing or updating a README, generating docstrings or comments, keeping a changelog current (recall Chapter 2's own changelog-writer example — a small, specialized version of exactly this agent type), or writing a longer-form guide. What unifies all of these is describing existing or newly-added behavior for a reader, not altering that behavior.

Designing a Documentation Agent's Definition

"Use this agent to write or update documentation — README sections, docstrings, changelog entries, guides — describing what code does. Not for changing code behavior itself; use a coding agent for that." Tool access needs care here: broad Edit access across any source file risks the agent "helpfully" adjusting actual logic while documenting it — a genuine temptation for a capable model trying to be useful. A tighter design scopes Edit to documentation files and comment/docstring regions specifically, keeping the same separation of concerns Chapter 6's review agent relies on: this agent describes, it doesn't modify behavior.

Writing the System Prompt for a Documentation Agent

A documentation agent's system prompt should instruct it to describe what the code actually does — verified by reading the real, current implementation — not what it was originally intended to do, or what older documentation claims it does. It's worth drawing one honest distinction here: a README or API doc legitimately explains what something does, for a reader who's never seen it before — that's the whole point of documentation. Inline code comments are a different context entirely, and should stay minimal, focused only on non-obvious why (a hidden constraint, a subtle workaround) rather than restating what well-named code already makes clear. A good documentation agent should know which context it's writing in and match its style accordingly.

Keeping Documentation Honest and Current

The single biggest risk with any documentation is drift — docs describing behavior that used to be true but no longer is, since nothing forces documentation to update automatically when code changes. A documentation agent's system prompt should explicitly instruct it to treat the actual current code as the source of truth, verifying behavior by reading the real implementation rather than trusting existing documentation, which may itself already be stale.

Briefing a Documentation Agent Well

A good brief states what needs documenting (a specific module, feature, or changelog entry), the intended audience (an end user reading a README versus a fellow developer reading an API reference), and whether the task is updating existing documentation or writing something fresh.

A Worked Example

"Update the README's API section to document the new /users/:id/preferences endpoint added in src/routes/users.ts. Follow the existing README's format for documenting other endpoints exactly — same structure, same level of detail." This names the specific addition to document, points at the actual source of truth (the real route file), and asks for consistency with the existing documentation's own established format.

Hands-On Exercises