AI Coding Agents Should Take an Issue to a Reviewable PR—Not Build the Feature

“Build the feature” is a bad assignment for an engineer and a worse assignment for an AI coding agent.

The agent does not know which ambiguity is intentional. It does not know which architectural compromise the team already rejected. It does not know that the apparently unused validation branch protects the one customer who sends malformed data every Friday. Give it a broad feature request and it will resolve those unknowns by making assumptions, then bury the assumptions inside a large diff.

You may get working code. You also get a pull request nobody can review with confidence.

The useful unit of AI-assisted development is not a feature. It is a small, reviewable change with an explicit contract. The agent can inspect the repository, propose a plan, implement the change, run the checks, and prepare a pull request. A human still owns the decision to merge it.

That boundary is not timid. It is how I would make coding agents useful in a real software company without turning every reviewer into a forensic investigator.

Optimize for Reviewable Work, Not Generated Code

The sales pitch for coding agents is usually about how much code they can produce. That is the least interesting number in the system.

Code generation has become cheap. Understanding a change, proving that it meets the requirement, and accepting responsibility for it are still expensive. If an agent writes 1,500 lines in eight minutes and a senior engineer spends half a day reconstructing its decisions, the company did not gain eight hours. It moved work from implementation to review and made the work harder to see.

I would optimize the workflow for four properties:

• The task is bounded. The expected outcome and the work that is out of scope are written down.
• The diff is small. A reviewer can understand the behavior change without reverse-engineering a redesign.
• The evidence travels with the PR. Tests, commands, assumptions, and limitations are visible.
• The merge remains accountable. An engineer reviews the result and owns what enters the codebase.

This means the agent is not “another engineer.” It is a fast implementation worker operating inside a narrow contract.

Start With the Work Agents Are Actually Good At

Do not begin with the feature your board is waiting for. Begin with work where the desired result is clear and the failure is easy to detect.

Good first tasks include:

• Add validation for one documented input rule.
• Fix a reproducible bug with an existing failing test or clear reproduction.
• Replace a deprecated internal API in one package.
• Add a missing unit or integration test around known behavior.
• Update documentation after an already-approved product change.
• Perform a mechanical refactor with unchanged behavior and strong test coverage.
• Add observability to an existing code path using the repository's established pattern.

Bad first tasks include:

• “Build team permissions.”
• “Improve onboarding.”
• “Modernize the billing service.”
• A new authentication or authorization design.
• A cross-service migration without an agreed sequence and rollback plan.
• Work where product behavior is still being negotiated.
• Anything a qualified engineer cannot explain how to verify.

The distinction is not task size alone. It is decision completeness. A twenty-line change can hide a product decision. A 300-line mechanical migration can be extremely well specified.

If the agent must invent policy, architecture, or acceptance criteria to proceed, the task is not ready for implementation. Send it back to a person.

Give the Agent a Task Contract, Not a Prompt

A one-paragraph issue is usually written to start a conversation. An agent needs an execution contract.

The contract should be short enough that engineers will maintain it and strict enough that the agent knows when to stop. I would require these fields:

task: Reject expired password-reset tokens

outcome:
  Expired reset tokens return the existing TOKEN_EXPIRED error and do not
  change the user's password.

acceptance_criteria:
  - A token older than 30 minutes is rejected.
  - A valid token continues to work.
  - The error is mapped to HTTP 400 by the existing API layer.
  - Existing reset-token behavior remains unchanged otherwise.

out_of_scope:
  - Changing token storage or format
  - Changing the 30-minute policy
  - Editing customer-facing copy

allowed_paths:
  - src/auth/reset/**
  - test/auth/reset/**

forbidden_actions:
  - Adding dependencies
  - Changing the database schema
  - Calling external services

required_checks:
  - pnpm test test/auth/reset
  - pnpm lint
  - pnpm typecheck

stop_when:
  - The current code contradicts the acceptance criteria
  - The change requires a file outside allowed_paths
  - A required check cannot run in the provided environment

This contract does three useful things.

First, it separates the business outcome from the proposed implementation. The agent can find a simpler implementation without changing the requirement.

Second, it makes scope violations visible. If the change needs a schema migration, the correct response is not to quietly edit the migration folder. It is to stop and report why the contract is insufficient.

Third, it gives review a reference point. The reviewer is not asking whether the code “looks reasonable.” They are checking the diff against written acceptance criteria.

Do not turn the contract into a 40-field form. If preparing the task costs more than implementing it, nobody will use the workflow. Most low-risk changes need one outcome, three to five acceptance criteria, explicit exclusions, a path boundary, required checks, and stop conditions.

The Workflow I Would Ship

The agent should move through a fixed sequence. Do not let it bounce indefinitely between coding and self-correction.

1. Create an Isolated Workspace

Run every task in its own branch, worktree, container, or ephemeral environment. The agent should not edit a developer's working copy or inherit whatever credentials happen to be present on a laptop.

The starting permission set should be deliberately boring:

• Read the assigned repository and approved internal documentation.
• Write only inside the isolated checkout.
• Run an allowlist of build, test, lint, and static-analysis commands.
• Create commits and a draft pull request.
• Read issue and pull-request context relevant to the task.

It should not have production credentials, deployment permission, a generic cloud shell, unrestricted secret access, or the ability to merge its own PR. Dependency installation and network access should require explicit approval because both can change what code runs in the environment.

2. Read Before Editing

The first agent action should be repository inspection, not code generation.

Ask it to find:

• The local instructions for the repository and relevant package.
• The implementation closest to the requested behavior.
• Existing tests for that behavior.
• Similar patterns elsewhere in the codebase.
• The commands needed to validate the change.
• Any conflict between the issue and the current code.

Do not dump the whole repository into a context window. Let the agent search, open relevant files, and show which evidence informed its plan. Repository-wide context sounds comprehensive; in practice it adds stale, irrelevant code and makes the important constraints harder to see.

3. Require a Plan Before Code

For the first phase of adoption, the agent should return a short plan and wait.

The plan needs only four sections:

{
  "understanding": "What behavior changes and what stays unchanged",
  "files": ["Files expected to change and why"],
  "verification": ["Tests and commands that will prove the result"],
  "risks_or_questions": ["Unknowns that may require a stop"]
}

An engineer approves or corrects the plan. This review should take minutes. If it takes an hour, the task is too broad or the repository is too difficult to navigate.

Once a team has evidence that a class of task is predictable—documentation updates, for example—it can skip human plan approval for that class. Do not remove the planning step itself. The plan remains useful evidence in the PR.

4. Implement Within a Change Budget

The task contract defines the hard path boundary. I would also set a soft change budget: expected files, approximate diff size, and maximum repair loops.

A line limit is not a quality metric. Some safe changes are large and mechanical. It is still a useful tripwire. If a bug fix expected to touch two files suddenly changes twelve, the agent should stop and explain the expansion before continuing.

My starting defaults for a low-risk pilot would be:

• No more than five changed files unless the task declares a mechanical migration.
• No unrelated cleanup.
• No new dependency without approval.
• No public API or schema change unless explicitly included.
• At most two implementation-and-test repair loops before escalating.

The “no unrelated cleanup” rule matters. Agents are eager to fix nearby naming, formatting, typing, and abstractions. Those changes may be individually defensible and collectively poisonous to review. One PR should answer one question.

5. Let Deterministic Tools Judge Deterministic Things

The agent can run tests, but it does not decide that the tests are sufficient.

Use the same checks the team already trusts:

• Unit and integration tests
• Type checking
• Linting and formatting
• Static security analysis
• Dependency and license checks
• Generated-file validation
• Repository-specific architecture checks

The agent should not summarize a failed command as “probably unrelated” and move on. It should record the exact command, exit status, and relevant output. If a pre-existing failure blocks validation, the PR must say so explicitly.

An LLM review can be an additional pass for suspicious logic, missed acceptance criteria, or inconsistent patterns. It is not a substitute for CI, and the same agent that wrote the change should not be treated as an independent approver.

6. Open a Draft PR With an Evidence Contract

The pull request is the product of the workflow. Code is only part of it.

Require the agent to produce a fixed description:

## Outcome
What behavior changed, in user or system terms.

## Acceptance criteria
- [x] Criterion one — evidence: test name or code reference
- [x] Criterion two — evidence: test name or code reference

## Files changed
- `path/file.ts` — why it changed

## Decisions and assumptions
- Decisions made inside the contract
- Assumptions the reviewer should verify

## Verification
- `pnpm test ...` — passed
- `pnpm lint` — passed

## Risk and rollback
- Likely failure mode
- How to disable or revert the change

## Not done
- Anything deliberately left out

This format forces the agent to connect claims to evidence. It also makes weak work obvious. Empty “risk” and “not done” sections on a non-trivial change are reasons to inspect more closely, not signs that the change is perfect.

What the Human Reviewer Still Owns

Human review should not repeat work the machine already performed. There is little value in manually checking formatting after CI passed. The reviewer should focus on judgment:

1. Requirement: Does the change satisfy the acceptance criteria without quietly changing the product decision?
2. Scope: Is every changed file necessary? Did the agent smuggle in cleanup or redesign?
3. Architecture: Does the solution follow the system's boundaries and established patterns?
4. Safety: Could this expose data, weaken authorization, corrupt state, or make rollback difficult?
5. Tests: Do the tests prove behavior, or merely reproduce the implementation?
6. Operability: Will the team be able to observe, diagnose, and reverse the change in production?

The reviewer must be able to explain the change after reading it. “The tests are green and the agent says it is safe” is not review. If the diff cannot be understood within a normal review session, split it or return it.

Keep the normal branch protection rules. The agent does not approve, merge, deploy, or grant itself additional permissions. A human uses the same merge button and accepts the same ownership they would for a human-authored PR.

Evaluate the Workflow Before Pointing It at Live Work

Do not judge a coding agent using a polished demo task. Build a replay set from work your team actually completed.

I would start with 30–50 historical issues across five categories:

• Documentation or configuration maintenance
• Small bug fixes with a known reproduction
• Test additions around existing behavior
• Mechanical refactors
• Small product changes with clear acceptance criteria

Remove the original implementation commit from the agent's view, provide the repository at the point where the issue was picked up, and compare the agent's result with what the team shipped.

Score each task on:

• Acceptance criteria met
• Unauthorized files or actions
• Test quality and check results
• Material correctness or security problems
• Diff size and unrelated changes
• Reviewer time to understand and correct it
• Whether a reasonable reviewer would merge, request changes, or reject it

The important comparison is not agent code versus perfect code. It is the complete agent workflow versus the team's current path from ready issue to reviewed PR.

For an initial low-risk rollout, my launch gates would be:

• Zero secret exposure, permission bypass, or changes outside the declared path boundary
• At least 90% of acceptance criteria satisfied across the locked replay set
• No worse defect or revert rate than comparable human-authored work
• Median review time no higher than the team's current median for the same task class
• Every failed or incomplete task stops visibly instead of presenting itself as finished

The exact percentages should change with the risk of the work. The non-negotiable part is agreeing on the gates before everyone sees the best demo.

A 30-Day Rollout That Can Be Reversed

Week 1: Baseline and Replay

Choose two task classes and record the current lead time, review time, change-request rate, and post-merge defect rate. Run the agent on historical work only. Fix repository instructions, missing tests, and environment access before tuning prompts endlessly.

Week 2: Draft PRs for Experienced Engineers

Let three to five experienced engineers assign low-risk tasks. Keep plan approval on. Every PR starts as a draft and carries a visible “AI-assisted” label so reviewers know which workflow produced it.

Record why work is rejected: wrong requirement, scope expansion, weak test, architectural mismatch, unsafe action, or too much review effort. “Did not like it” is not useful failure data.

Week 3: Expand the Task Mix, Not the Permissions

Add a second task class such as reproducible bug fixes. Do not simultaneously add network access, dependency changes, schema edits, and auto-merge. Change one boundary at a time so you know what caused the outcome.

Week 4: Keep, Change, or Stop

Compare the pilot with the baseline. Keep a task class only if lead time improves without shifting the saved time into review or rework. Tighten the contract where failures cluster. Stop using the agent for task classes that repeatedly require hidden product or architecture decisions.

The goal after 30 days is not company-wide adoption. It is a list of task classes the workflow can handle predictably and a list it cannot.

What Changes by Company Size

The issue-to-PR boundary remains the same. The surrounding control system changes.

Company	What I would implement
Small, 5–30 engineers	Use a managed coding agent, one repository instruction file, branch protection, a lightweight task template, and direct human merge approval. Do not build an internal agent platform.
Medium, 30–200 engineers	Standardize task and PR schemas, sandbox defaults, approved models, secrets handling, logs, and evaluation. Let each team define eligible task classes and own the outcomes.
Large, 200+ engineers	Provide centrally managed ephemeral workers, identity and policy enforcement, risk tiers, immutable audit logs, cost attribution, and kill switches. Domain teams still own acceptance criteria, review, and production outcomes.

A small company can often learn more in a week than a large enterprise can approve in a quarter. That is not an excuse for the enterprise to skip controls, or for the startup to skip boundaries. It means each should spend complexity where it has a real problem.

Measure the Delivery System, Not Agent Activity

Do not report lines generated, prompts sent, agent sessions, or percentage of code written by AI. Those are activity measures. They can rise while delivery gets slower and quality gets worse.

Track the workflow:

• Issue-ready to draft-PR time: Did implementation waiting time fall?
• Review time: Is the diff easier or harder to understand?
• Change-request rate: How often does the PR need material correction?
• Reopened work: How often was the issue declared complete too early?
• Change fail and revert rate: Did production quality move?
• Escaped defects: Are acceptance gaps reaching customers?
• Cost per merged PR: Include model cost and the human time spent preparing, reviewing, and repairing the result.

Read these metrics together. Faster PR creation with slower review is not a win. More merged work with a higher revert rate is not a win. Lower implementation time with no change in total lead time means the constraint was somewhere else.

The DORA metrics guide explains why delivery signals have to be balanced. The same principle applies here: speed without instability measures will reward the wrong behavior.

The Copyable Review Checklist

Use this at the bottom of every agent-authored draft PR:

### Task contract
- [ ] Outcome and acceptance criteria are explicit
- [ ] Out-of-scope work is named
- [ ] Changed files stay inside the allowed boundary
- [ ] The agent stopped or asked when the contract was insufficient

### Change
- [ ] The diff does one thing
- [ ] No unrelated cleanup or new dependency slipped in
- [ ] Architecture and authorization boundaries are preserved
- [ ] Failure behavior and rollback are understood

### Evidence
- [ ] Tests prove the required behavior, not just the implementation
- [ ] Required commands ran and exact failures are disclosed
- [ ] Assumptions and limitations are visible
- [ ] A reviewer can explain the change before merging it

If teams routinely cannot check these boxes, do not solve the problem with a longer prompt. Improve the task definition, repository instructions, testability, or code boundaries. Coding agents amplify the development system they enter. A navigable repository with fast tests becomes easier to change. A tangled repository with ambiguous ownership produces tangled changes faster.

The Bottom Line

Do not hire an AI coding agent to “build features.” Build a workflow that converts a ready issue into a small, tested, evidence-rich draft pull request.

Give the agent a task contract. Let it inspect before it edits. Approve the plan. Isolate its workspace. Restrict its tools. Put deterministic checks in charge of deterministic claims. Make the PR explain exactly what changed, why, and how it was verified. Then require a human to understand and merge it.

That version sounds less autonomous than the demos. It is also the version I would trust to produce more software without quietly producing more risk.

I help software companies redesign engineering workflows so AI improves delivery without weakening ownership or production safety. If you want an independent review of your coding-agent workflow and rollout gates, request a consultation.