CLAUDE CODE AGENTS: FUNDAMENTALS - Chapter 9, Exercise 1
Why a Documentation Agent's Edit Access Stays Scoped
====================================================================================

QUESTION:
Explain why a documentation agent's Edit access is often scoped
specifically to documentation files rather than granted broadly across the
whole codebase.

SOLUTION / EXPLANATION:

This chapter is direct about the specific risk broad Edit access creates
for a documentation agent: a capable model trying to be genuinely helpful
while documenting a piece of code might notice something it thinks could be
improved - a slightly awkward variable name, a small inefficiency, a minor
inconsistency - and "helpfully" fix it while it's already in the file
documenting that exact behavior. If the agent has unrestricted Edit access
across any source file, nothing structurally prevents this from happening,
even though changing actual code behavior was never the documentation
agent's job in the first place.

This mirrors Chapter 6's own reasoning for why a code-review agent is
denied Edit access entirely: keeping "describing" cleanly separate from
"changing" isn't about distrust of the agent's competence - it's a
structural guarantee that the agent's actual output (updated documentation)
doesn't come bundled with an unrequested, unreviewed side effect (a
quiet code change nobody asked for or explicitly reviewed as its own
step).

Scoping Edit access specifically to documentation files and comment/
docstring regions achieves this directly: the agent is structurally unable
to alter real logic, no matter how tempting an "improvement" might seem
while it's reading through the code to document it. Whatever it produces is
guaranteed, by construction, to be documentation only - not documentation
plus an unreviewed drive-by code change.

--------------------------------------------------------------------------
WHY THIS WORKS AS AN ANSWER:
It names the specific temptation broad Edit access creates (a capable model
"helpfully" fixing code while documenting it), connects this to the same
separation-of-concerns reasoning Chapter 6 established for review agents,
and explains what scoped Edit access structurally guarantees rather than
merely discourages.