How to set coding agent concurrency by repository capacity

Buying more parallel coding sessions is the easiest way to make an AI engineering setup look productive while making the repository slower. Agents can draft code far faster than a shared codebase can validate, review, and merge it. Once that happens, output turns into a pile of branches competing for the same files, test runners, reviewers, and deployment windows.

Set coding agent concurrency from repository capacity. The useful number is not how many sessions you can start. It is how many independent changes your team can take from task to merged code without increasing rework, review delay, or rollback risk.

I have seen teams blame agents for noisy diffs and conflicts when the actual problem was a management decision: they gave five workers access to a repository that could only absorb two meaningful changes at a time. The answer was not a smarter prompt. It was a smaller queue and clearer boundaries.

Parallel sessions do not equal throughput

A coding agent produces a branch, not a shipped outcome. A shipped outcome has passed tests against current code, received a review from someone who understands the affected area, merged without destabilizing nearby work, and survived whatever verification your release process requires.

That distinction matters because agent output arrives at the front of the pipeline. The slow parts live at the back. If agents create pull requests faster than the team merges them, every extra session increases the age of open branches. Older branches conflict more often, need more rebasing, and force reviewers to compare a proposed change against a moving target.

Teams often see the first signs and choose the wrong fix. They add another reviewer, tell agents to make smaller diffs, or ask everyone to clear the pull request backlog on Friday. Those moves may help briefly. They do not change the arrival rate.

Think of each agent as a source of change requests. The repository has several downstream constraints:

• The number of changes that can safely touch the same module at once.
• The elapsed time before a branch gets credible test feedback.
• The number of merges the main branch can absorb each day.
• The review time available from people qualified to approve the work.

Your concurrency limit must respect the tightest of those constraints. A team with fast CI and two staff engineers who can review a steady stream of isolated changes may support several agents. A team with a monolith, a twenty minute integration suite, and one overworked maintainer may support one agent for production code and another only for isolated documentation or test tasks.

This is not an argument for artificial scarcity. It is an argument against pretending that the number of browser tabs or terminal sessions is a delivery metric.

Repository capacity has four separate limits

Repository capacity is the rate at which a codebase can absorb change without building a growing queue. It has four limits that teams routinely collapse into one vague idea of engineering bandwidth.

Module overlap asks whether active work lands in the same places. Two tasks can have different titles and still collide because both edit a shared validation layer, generated client, database schema, configuration file, or core interface. File paths catch some collisions. Shared contracts catch the expensive ones.

Test duration asks how long a proposed change waits before you know whether it fits the current repository. A fast unit suite helps, but it is not enough if integration tests, migrations, browser tests, or deployment checks run later and serialize the work. The longer that feedback loop, the more stale branches you accumulate.

Merge rate asks how many accepted changes actually reach the default branch. Count merged pull requests, not opened pull requests and not agent task completions. If six branches open daily and only three merge daily, the queue grows even if each branch looks reasonable in isolation.

Reviewer capacity asks who can make a real approval. A generalist can inspect a formatting fix. That same person should not rubber stamp a permission change, billing calculation, migration, or change to a shared package they have never operated. GitHub's documentation makes this operationally visible: CODEOWNERS can request defined owners for affected paths, and branch rules can require their approval.

These are not interchangeable. Faster test runners do not create knowledgeable reviewers. More reviewers do not make two competing schema migrations compatible. Better prompts do not make a merge queue disappear.

A useful operating rule is this: set the initial agent ceiling to the smallest number suggested by the four limits, then raise it only after the repository proves it can absorb the additional work. Do not average the numbers. A repository that supports six independent documentation tasks but only one authentication change has a concurrency limit of one for authentication work.

Module overlap puts a hard ceiling on active work

Module overlap is usually the first constraint, and teams miss it because ticket categories hide it. "Add trial billing", "show plan usage", and "send account notifications" sound like separate initiatives. If each task edits the account model, entitlement checks, and subscription events, they are one traffic jam wearing three labels.

Start by mapping modules that agents repeatedly touch. You do not need a perfect architecture diagram. You need a practical list of folders and contracts where concurrent edits have caused conflicts, review churn, or defects. In a typical product repository, the high contention areas include:

• Database migrations, ORM models, and generated schemas.
• Authentication, authorization, tenant isolation, and audit events.
• Shared API contracts and client generation.
• Build files, deployment configuration, and environment templates.
• Core packages that many services or applications import.

Mark these areas as restricted work zones. One active code-writing agent owns a restricted zone until its pull request merges or the task stops. Other agents may investigate, write a design note, add tests in a truly separate area, or prepare a task. They should not edit the same boundary and hope Git can sort out the rest.

The commonly recommended alternative is to let every agent work freely, then depend on merge conflict resolution. That advice is popular because it keeps utilization high. It is wrong for shared modules. Git can reconcile lines. It cannot decide which of two incompatible interpretations of an API, migration sequence, or authorization rule belongs in production.

Build a lightweight ownership file that gives the dispatcher a usable rule set. It does not need to replace CODEOWNERS. It answers a different question: who may actively modify an area right now.

# .agent-capacity.yml
zones:
  billing:
    paths:
      - services/billing/**
      - packages/contracts/subscription.ts
      - db/migrations/**
    max_active_agents: 1
    required_checks:
      - unit
      - integration
    reviewer_group: billing-owners

  web-ui:
    paths:
      - apps/web/**
    max_active_agents: 3
    required_checks:
      - unit
      - browser
    reviewer_group: web-owners

  docs:
    paths:
      - docs/**
    max_active_agents: 4
    required_checks:
      - markdown
    reviewer_group: docs-owners

The failure this prevents is ordinary: two agents each modify packages/contracts/subscription.ts, one adds a field and the other changes a status meaning. Both branches pass their local tests. After the first merge, the second branch may rebase cleanly but still encode an obsolete contract. The conflict was semantic, not textual.

Do not turn the file into a taxonomy project. Begin with the few paths that cause the most waiting. If a zone is contentious enough that a maintainer regularly says "please coordinate before touching that", it belongs in the file.

Test time determines how stale branches become

A branch that waits forty minutes for its meaningful checks is not just consuming runner time. It is holding an assumption about the repository while other changes continue to merge. That is why slow tests lower safe agent concurrency even when the runners themselves have spare capacity.

Separate test execution time from test feedback time. Execution time is how long the command runs. Feedback time is how long an author waits from pushing a branch to receiving the signal needed to merge. Feedback time includes queueing, flaky retries, manual environment setup, and a reviewer asking for a new run after a rebase.

Measure the latter. A team may say its test suite takes twelve minutes because that is what the job timer reports. If jobs wait fifteen minutes for runners and a flaky browser test reruns twice each afternoon, the real feedback loop is much longer.

Use the same shape of query every week. The exact commands depend on your provider, but the data should answer four questions for each pull request: when did the first commit arrive, when did required checks finish, how many reruns occurred, and did the branch need a rebase before merge? A simple export is enough.

PR    first_push           checks_green         reruns  rebased  merged
481   09:12                09:31                0       no       10:05
482   09:18                10:04                2       yes      11:16
483   09:22                09:41                0       no       09:58

Do not use the average alone. Averages hide the painful tail. If most changes pass in ten minutes but a common integration path takes an hour, agents working in that path should have a lower ceiling. They are creating branches that remain vulnerable to repository drift for an hour.

GitHub Actions documents that workflow and job concurrency can be controlled with concurrency groups, including choosing whether later runs cancel older pending work or wait in a queue. Use that facility for things that must not run together, especially deployments and shared test environments. But do not confuse workflow concurrency with coding agent concurrency. One protects an execution resource. The other controls how much unresolved change enters the repository.

When test duration is the limiting factor, make the first checks cheap and decisive. Run formatting, type checks, focused unit tests, and static analysis early. Keep the slower suite for changes that need it. Split truly independent test environments. Remove tests that only restate lower level coverage. Fix flakiness before adding workers. A flaky suite forces agents and reviewers to re-evaluate noise, which is work nobody sees in a velocity report.

Reviewers are a finite production resource

Review capacity is often the actual constraint because AI increases the number of plausible pull requests faster than it increases the number of people able to judge them. A reviewer is not a button that turns a branch green. The reviewer has to recover the task's intent, inspect the changed contracts, notice missing cases, and decide whether the test evidence is sufficient.

If a reviewer spends five minutes on a small, familiar change and forty minutes on a cross-cutting change, count those as different work classes. Do not report them as two identical reviews.

Use three reviewer buckets:

1. Routine review covers contained changes in an area with clear conventions and ordinary rollback options.
2. Owner review covers modules where a named maintainer understands the invariants, data shape, or operational behavior.
3. Design review covers changes that alter an interface, migration sequence, authorization rule, or deployment behavior.

An agent should know the bucket before it edits code. If the task needs design review, the agent can collect evidence and produce a small proposal, but it should not run ahead and create a large implementation branch. Otherwise the team pays for implementation twice: first to generate it, then to unwind it after the design discussion changes direction.

GitHub's pull request guidance is useful here. It says reviewers need to understand the motivation behind a pull request in order to keep feedback targeted and meaningful. That sounds obvious, yet many agent tasks produce a diff without a proper explanation of the decision. Reviewers then spend time reconstructing why a change exists before they can evaluate whether it is correct.

Require every agent-authored pull request to include four plain facts:

• What user or operational behavior changed.
• Which modules and contracts the change touches.
• Which commands ran and what they covered.
• What the reviewer should inspect carefully.

Do not ask for a theatrical essay. Ask for enough context to prevent reverse engineering the task from a diff.

Watch review request age by owner group. A pull request that waits ten hours for the only database reviewer is a capacity signal. Starting two more agents on database work is not a productivity move. It is adding inventory in front of a blocked station.

A merge queue exposes whether the limit is wrong

The cleanest capacity signal is the merge queue. Track the number of pull requests that are ready for review, approved but waiting on checks, and ready to merge but blocked by branch updates or a queue. Keep the categories separate because each points to a different constraint.

A growing ready-for-review column means agents or humans are producing changes faster than reviewers can process them. A growing approved-but-waiting column points to CI, shared environments, or branch protection. A growing merge-ready column often points to an ordered merge system, a release gate, or too many branches needing revalidation after each merge.

You can calculate a conservative ceiling with recent observed values. Let:

M = median merged pull requests per business day
T = median elapsed business days from first push to merge
R = review slots available per business day for this work class
O = safe active changes allowed in the same module zone

initial agent ceiling = min(round_down(M * T), R, O)

This is not a universal law. It is a practical starting point. M * T estimates how much work is already in flight during a normal cycle. R prevents you from treating reviewers as unlimited. O blocks simultaneous work in places where overlap creates semantic conflicts.

Suppose a service normally merges four contained pull requests per business day, and the median first-push-to-merge time is one business day. The repository has room for roughly four active contained changes if reviewers have four review slots and the tasks touch separate modules. If two of those tasks require the same schema owner, the zone limit may reduce the safe count to one.

Do not manipulate the calculation by counting trivial formatting changes. Separate work classes. A documentation edit and a payment migration do not belong in the same capacity number.

GitHub's merge queue documentation and branch controls can help enforce an orderly merge path, but the queue is also a diagnostic instrument. If it is permanently full, it is reporting a rate mismatch. Adding more agents increases the mismatch unless you also increase the constraint that is actually blocking progress.

Use work classes instead of one global limit

A single repository-wide agent limit is better than unlimited parallel work, but it leaves speed on the table in low-risk areas and creates pressure to treat all tasks as equivalent. Use work classes with explicit limits.

A reasonable starting scheme has four classes. Adapt the names to your organization, but keep the distinction sharp.

The important distinction is between local code and shared contracts. Teams blur them because both are code. Getting it wrong makes work look independent until integration day.

A frontend agent can often update a local component while a backend agent changes an unrelated service. That does not make it safe for both to change a generated client contract, a feature flag definition, or the rules that decide whether an account can access a paid feature. Shared contracts coordinate behavior across boundaries. They deserve a lower limit and a clearer task brief.

The dispatcher should reserve an agent slot when the task enters implementation, not when someone thinks of a ticket. Planning can proceed in parallel. Code changes in restricted zones cannot.

This policy also gives agents a legitimate reason to stop. "Another active task owns this module" is better than letting a session wander into a disputed area because the original task turned out to need a cross-cutting fix. Stopping early is cheap. Resolving a wide diff after two competing branches have accumulated changes is not.

The task brief must make boundaries enforceable

Concurrency policy fails when tasks arrive as slogans. "Improve onboarding", "fix billing bugs", and "clean up authentication" are invitations for an agent to search widely and edit whatever it finds. The resulting pull request may contain good code, but it becomes hard to review, hard to merge, and impossible to schedule alongside other work.

Give the agent a bounded assignment. A good brief names the allowed path, the prohibited path, the behavior to preserve, and the checks that demonstrate success. It also tells the agent what to do when the task requires a broader change.

Task: Add a validation message when a workspace name exceeds the existing limit.

Allowed paths:
- apps/web/src/features/workspaces/**
- apps/web/src/features/workspaces/*.test.tsx

Do not change:
- shared API contracts
- database schema
- authorization code

Acceptance:
- existing server validation remains unchanged
- browser test covers visible message
- run pnpm test workspaces and pnpm lint

If the UI lacks the required validation data, stop and open a note explaining
which contract must change. Do not modify the contract in this task.

That final instruction saves time. Without it, the agent may alter a shared API contract to avoid asking a question. It then crosses into a different work class, needs a different reviewer, and collides with work the scheduler did not know about.

Require agents to report touched paths before they begin substantial edits. A dispatcher can compare those paths with active branches and either continue, narrow the task, or delay it. You can automate this later. At the start, a short comment in the task system works.

Do not use path restrictions as a substitute for engineering judgment. A change inside one folder can still affect shared behavior. The restriction is an early warning system. It tells the agent and reviewer when the task no longer matches the slot that was allocated.

Raise capacity by removing the actual bottleneck

When a team reaches its concurrency limit, the instinct is to purchase more sessions because that appears cheaper than changing the repository. Sometimes it is cheaper in the narrowest sense. It is still wasteful if the repository cannot absorb the resulting work.

Raise concurrency only when you can name the constraint you removed and observe that the relevant queue stayed flat afterward. The action depends on the constraint.

For module overlap, split a shared package, clarify a contract, or sequence related work behind one owner. For test feedback, isolate a slow suite, improve test data setup, remove flakiness, or add safe runner capacity. For review, reduce pull request size, train another qualified owner, or reserve review blocks instead of hoping reviews happen between meetings. For merge rate, simplify release gates or separate unrelated deployment paths.

Do not solve a reviewer bottleneck by asking an agent to review another agent's work and treating that as a replacement for accountable approval. Automated review can catch patterns and point out omissions. It cannot assume ownership of an operational consequence when a change breaks production.

A well-run team does use agents to increase engineering output. The difference is that it treats the repository as a constrained production system rather than an infinite sink for generated code. The goal is a steady flow of small, understood, mergeable changes.

If your open pull requests are getting older, reviewers are repeatedly asking for rebases, or the same files appear in several active branches, lower the agent limit this week. Measure for two weeks. Then fix the constraint that shows up in the queue. A Team & AI Audit is useful when the data exists but nobody has time to turn it into an operating model that the team will actually follow.

The team that ships faster is rarely the one with the most agents running. It is the one that knows when another agent would create more work than it removes.