Inside the Agentic Coding Loop
This chapter examines the operating loop behind organizational agentic coding: what context an agent receives, how it forms and executes a plan, how tests return evidence, and where human authority must stop delegation. The practical goal is to distinguish a context problem from a model problem and to show why a small, testable task is easier to govern than an open-ended request.
The useful unit is not “a prompt in, code out.” It is a bounded state transition. A developer starts with an intended change and a definition of success. The agent inspects the available context, proposes or follows a plan, changes some part of the repository, and invokes tools that produce evidence. Tests, logs, and review then determine whether the new state is acceptable, needs another iteration, or should be discarded. Each participant owns a different part of that transition. When those ownership boundaries are unclear, the agent can appear autonomous while the team remains responsible for every hidden consequence.
Context comes before action
An agent cannot make a repository-specific decision from the task sentence alone. “Add authentication,” “fix the failing button,” or “modernize this service” leaves too many questions open. Which behavior is required? Which existing pattern should be followed? What versions and dependencies are in use? Which edge cases are known? What must remain compatible? What tests define the current contract? A useful request supplies enough of that surrounding information for the agent to reason about the actual system rather than generate a plausible answer to an abstract problem.
The necessary context has several layers. The first is the task boundary: the desired outcome, the parts of the system in scope, constraints, and conditions under which the work should stop. The second is repository context: relevant code, tests, interfaces, configuration, documentation, and conventions. The third is environment context: the language and framework versions, commands available to run, data shape, and the difference between a local development setup and a production-like one. The fourth is organizational context: security policies, review expectations, compatibility commitments, and patterns the team has already approved.
These layers also have different freshness and authority. A task description may be current while a setup document is stale. A repository may contain a newer interface than a copied example. A policy may prohibit an action even when the codebase contains an older exception. The agent should not be expected to resolve those conflicts by confidence or recency alone. The workflow needs a way to surface the conflict, identify the owner of the decision, and pause when the available evidence does not establish which state is authoritative.
This is why “put more context in the prompt” is an incomplete remedy. More text can increase the amount of material available while making it harder to identify which constraint controls the decision. Context preparation is useful when it improves relevance and traceability: the agent can point to the test, policy, interface, or example that led to a proposed action. It is less useful when it becomes an unranked archive. The team’s job is not to maximize context indiscriminately, but to make the important boundaries legible.
These layers do not have equal authority. The task defines intent. The repository is the current system of record, although its code and documentation may disagree. A shared instruction file can expose conventions and warnings, but it is still guidance that should be checked against the repository and its tests. A generated explanation can suggest a possibility, but it does not become a fact merely because it sounds confident. A verifiable workflow keeps these distinctions visible instead of merging every piece of text into one undifferentiated prompt.
Anthropic’s guide recommends project-level CLAUDE.md files as a way to carry repository etiquette, environment setup, architectural notes, security requirements, and unexpected behavior across sessions and team members. The practice addresses a genuine systems problem. Experienced maintainers often possess tacit knowledge that is not obvious from a file’s local syntax: an apparently obsolete compatibility branch may protect a customer, a helper may be preferred because it preserves an invariant, or an external API may fail in a way that ordinary tests do not model. Making such knowledge explicit can improve the agent’s starting point.
But explicit context is not the same as complete context. The guide offers the file as a team knowledge layer; it does not show that the file eliminates misunderstanding or creates a measured productivity gain. The METR study supplies a useful caution from a different setting. Developers working in mature repositories reported that AI often behaved like a new contributor, missed implicit assumptions, chose the wrong edit location, or failed to understand data and backwards-compatibility requirements. The implication is not that a shared instruction file is futile. It is that context transfer is a design intervention whose effectiveness must be checked against real failures.
Once the initial context is assembled, the agent’s first useful act should often be explanation rather than modification. It can identify likely files, describe the existing flow, list assumptions, propose a sequence, and name the checks it intends to run. This planning step makes hidden interpretation visible while the cost of correction is still low. A developer who sees the agent aiming at the wrong subsystem can narrow the request before unrelated files are changed. Planning does not guarantee correctness, but it creates an inspectable artifact between intent and action. It also gives the developer a chance to ask whether the proposed sequence has the right initial conditions. If the plan assumes a migration has already run, a service is available, or a test fixture represents production behavior, those assumptions should be named before the agent proceeds. If the plan has no clear stopping point, it is not yet a bounded plan; it is a request for the agent to discover the scope while changing the system.
A plan can be useful even when it is rejected. Rejection is evidence that the task description, repository context, or agent interpretation is misaligned. The organization can learn whether the missing ingredient was a project rule, a test, an interface contract, or a human design decision. That learning is more valuable than silently accepting a plausible patch and discovering the mismatch during a later review.
The boundary is especially important when a tool can search, edit, run commands, or consult external integrations. Tool access turns a language response into an interaction with state. The agent may discover information, mutate files, generate artifacts, or trigger a process. The repository remains the durable system of record; the agent’s plan and intermediate reasoning are temporary working state. A team should know which actions are read-only, which are reversible, which require approval, and which must never occur in a production environment without an independent gate.
The sequence shows why the developer is not simply “waiting for the AI.” The developer owns the intent and the authority to widen or narrow the task. The agent owns a bounded attempt to transform the repository. The test system owns a set of observable checks, not the complete meaning of the change. The reviewer owns the decision to accept the result under the project’s quality and security standards. Those roles can be assisted by automation, but they should not silently collapse into one actor.
Verification makes agency controllable
The most reliable way to control a broad agentic request is to reduce it to a sequence of observable decisions. Anthropic’s guide recommends test-driven development for exactly this reason. Rather than ask an agent to “build a user authentication system,” a team can define registration, login, password reset, token behavior, invalid input, and failure handling as testable requirements. The agent can then implement enough for one coherent behavior, run the checks, inspect the result, and proceed only when the current checkpoint is understood.
This is not a claim that tests are complete specifications. A test suite can omit a security property, encode an accidental behavior, or pass while the architecture is becoming harder to maintain. The guide itself presents testing as a guardrail, not as a replacement for review. Its value is that it supplies fast, repeatable evidence about selected behaviors and prevents an unverified interpretation from expanding unchecked. The human still has to decide whether the tested behavior is the right behavior.
Small scope improves control in three ways. First, it limits the number of assumptions an agent must hold at once. A request to add a database schema, an API, a user interface, and deployment configuration in one pass creates many opportunities for a locally reasonable but globally incompatible choice. Separate, coherent tasks make the agent’s context more relevant and make failures easier to localize. Second, small scope makes review possible. A reviewer can understand a focused change and compare it with the stated acceptance criteria; the same reviewer may only skim a sweeping generated diff. Third, it creates a natural rollback point. If the new step is wrong, the team can revert or revise it before later work depends on it.
Acceptance criteria should cover more than the happy path. For a change to an authentication flow, for example, a team may need to distinguish valid credentials, malformed input, expired credentials, duplicate registration, and failure responses that do not reveal sensitive information. The point is not to turn every request into an exhaustive checklist. It is to identify the few negative paths and invariants that make the change safe to accept. An agent can implement the visible success case quickly while still violating a boundary that only appears when the input is invalid or the dependency is unavailable.
Precise feedback is the other half of the loop. “This is not working” describes frustration but not state. A useful report includes the expected behavior, the observed behavior, the full error, the action that triggered it, relevant environment details, and any constraints that must remain intact. The agent can then update its hypothesis rather than guessing what the developer meant. Visual defects benefit from the same discipline: a measured discrepancy or a clear before-and-after condition is more actionable than a general statement that an interface looks strange. This feedback also preserves a record of why the next attempt changed. Without that record, repeated prompting can look like progress while the team is merely cycling through unexamined guesses.
The sequence also explains why the agent’s ability to run commands is not the same as permission to decide what success means. A test command can report that an assertion passed, but it cannot decide whether the assertion covers a newly exposed threat. A linter can enforce a style rule, but it cannot choose between a backward-compatible workaround and a cleaner breaking change. A security review command can identify a likely injection path or insecure cookie setting, but the organization should retain its established security tools and review process. The guide explicitly recommends using agentic assistance alongside, rather than instead of, existing security controls.
Human judgment should remain decisive at boundaries where the evidence is incomplete or the consequences are asymmetric. Those boundaries include changing the task’s scope, accepting a migration that may affect unknown consumers, permitting access to sensitive data or external systems, overriding a failing check, approving a security exception, and merging a change that has not been reviewed under the repository’s normal standards. Delegating the mechanical steps around those decisions can make the process faster. Delegating the decisions without preserving ownership makes it difficult to explain or undo an outcome.
A good loop also has explicit termination conditions. It may terminate successfully when the required behavior is implemented, relevant tests pass, the change has been reviewed, and security or policy checks are satisfied. It may terminate by escalation when the agent cannot resolve a failure, the task reveals an architectural choice, or required context is missing. It may terminate by rejection or rollback when the proposed change is unreliable, over-scoped, or more expensive to verify than to implement directly. “The agent stopped producing text” is not a meaningful completion condition; a verified state or an accountable handoff is.
That distinction matters for the economics of agentic coding. Generation can be quick while the path to acceptance is slow. An output that requires extensive review, cleanup, or repeated prompting may shift effort rather than remove it. This is why the workflow must measure the full path to a mergeable result rather than treating the first generated patch as completion. If an organization counts only the moment an agent produces a patch, it will systematically miss the cost of deciding whether that patch is safe to keep.
The task-level loop is therefore a control system. Context establishes the initial state. Planning exposes assumptions. Tool use changes state. Tests and other checks provide feedback. Human review interprets evidence and owns the transition to an accepted state. When a check fails, the correct response is not automatically to ask for a larger prompt or grant broader access. The team may need better context, a smaller task, a different test, a human design decision, or a decision to stop using the agent for that work.
Once this loop is repeatable, the problem changes shape. The question is no longer whether one skilled developer can make an agent useful in a favorable session. It is how a team captures the useful patterns, teaches them to others, and maintains the context and boundaries as repositories evolve. That is the adoption problem: turning a task-level control loop into shared organizational capability without allowing local experimentation to become uncontrolled variation.