Keep a person accountable for the system model

An agent can produce a plausible implementation and an equally plausible explanation. Acceptance still requires someone to connect the change to the product’s constraints, architecture, operating history, and maintenance obligations. Those connections are part of engineering judgment.

The required depth depends on consequence. A disposable script may need a clear input contract and a contained failure impact. Core product logic needs an explanation of invariants, state transitions, tradeoffs, and recovery. Passing tests provide evidence about selected behavior; they do not remove this responsibility.

Frame changes around behavior and boundaries

Give the agent a concrete problem, the relevant behavior, and the constraints it must preserve. Identify the canonical implementation and documentation. Explain which nearby patterns are current and which exist for compatibility. This reduces the chance that a generic solution or a legacy example becomes an accidental architectural decision.

Keep the initial scope reviewable. A request to fix duplicate submission should expose the relevant transaction and retry behavior before inviting a broad workflow redesign. If investigation reveals a larger problem, make the proposed scope and reasoning visible before additional complexity accumulates.

text
Change: prevent duplicate purchase requests after retry
Behavior: repeating one confirmed request creates one record
Boundary: preserve existing approval and permission rules
Source of truth: request service and persistence contract
Evidence: retry integration case plus independent diff review
Owner review: explain identity, transaction, and recovery paths

Use repository instructions as orientation

A short repository instruction file can establish local commands, sources of truth, generated-file boundaries, and decisions that require escalation. Route detailed knowledge to maintained documents that can be loaded when relevant. Avoid duplicating the same rule across several places with slightly different wording.

Choose instructions because they correct observed local mistakes. “Run this validation command” or “edit this source rather than the generated file” can change behavior. General requests to write good code add little guidance. Where a rule is mechanical, prefer an executable check and point the agent toward it.

Review what the change makes possible

Read the resulting diff alongside the behavior it is supposed to implement. Follow new branches, dependencies, state, and failure paths. Ask whether an added abstraction solves the current problem, which callers depend on it, and what the next maintainer must understand to change it safely.

Use the agent’s explanation as a contribution to investigation. Check material claims against source code, tests, and actual execution. For important behavior, use evidence that can challenge the proposed implementation rather than tests that simply reproduce its internal structure.

  • Explain the important invariant without relying on the agent’s prose.
  • Inspect a failure or retry path, not only the successful example.
  • Identify what changed outside the requested behavior and why.
  • Resolve material comprehension gaps before accepting dependent work.

Watch the review queue for comprehension debt

A team can lose understanding gradually: one unfamiliar helper, one unexplained state machine, one accepted change that nobody has traced. Later changes build on those gaps. High implementation throughput can make the resulting complexity look like progress until maintainers can no longer judge the next proposal.

Reduce scope, investigate the unclear part, or simplify the design when review capacity becomes the constraint. Measuring accepted changes together with preparation, intervention, review, and correction effort gives a more useful picture than counting generated code or completed agent sessions.

Improve the environment after recurring mistakes

Repeated failures are evidence about the repository workflow. A missing validation command may need a script. A misunderstood boundary may need a contract test or a clearer module interface. Stale guidance needs an owner and a canonical replacement.

Observe whether the improvement changes later work and what it costs to maintain. Add instructions, documentation, and checks where they resolve a demonstrated problem. The objective is an environment in which agents can contribute useful work and people can continue to explain, operate, and evolve the result.