# Rolling out coding agents to a team

URL: https://developertoolkit.ai/en/teams/adopt/
Description: For tech leads: the order a team rollout of coding agents runs in, which page covers each step, and the evidence that proves the rollout works.

A team rollout of coding agents succeeds when every engineer works from one shared harness, one measured workflow, and one repository roadmap, not when every engineer has a seat. This section runs in that order: convert the repository, define one workflow, onboard people onto it, climb the roadmap loop by loop, and move review from diffs to evidence.

This hub is for the tech lead who owns the rollout and the CTO who asks whether it worked. Say you bought eight seats: three engineers use agents daily with private setups, two gave up, and review slowed. New to leading a rollout? Start with the [tech lead track](/en/start/tech-lead/).

## Which rollout page do you need?

| Your situation | Start with |
| --- | --- |
| The agent keeps guessing your build, test and style commands | [Project conversion playbook](/en/teams/adopt/project-conversion/) |
| Engineers have access, but few finish a real task with it | [Team onboarding and adoption](/en/teams/adopt/team-adoption/) |
| You need a plan for what the agent may do here, and when | [Adoption roadmap for one repository](/en/teams/adopt/adoption-roadmap/) |
| The team's delivery loop still assumes a human writes every line | [Workflow transformation guide](/en/teams/adopt/workflow-transformation/) |
| Leadership asks "is it working?" and you only have seat counts | [Measure effective workflow use](/en/cto-scorecard-guide/team-adoption-rate/) |
| New hires take days to reach their first safe agent task | [Prove one safe onboarding workflow](/en/cto-scorecard-guide/dev-onboarding-time/) |

## In what order does a team rollout run?

Each step has an exit check that later steps depend on.

1. **Convert one repository.** Commit the instructions file, the exact build and test commands, and the shared settings. Exit check: a fresh clone passes typecheck, lint, and tests with the agent's own commands. See the [project conversion playbook](/en/teams/adopt/project-conversion/) and [agent-ready codebase](/en/workflows/harness/agent-ready-codebase/).

2. **Pick one workflow and write its adoption card.** Choose a task type the team repeats weekly, such as repairing failing tests. The card fixes who is eligible, what counts as done, and which guardrails you watch. Exit check: the card is published before the comparison period starts ([effective workflow use](/en/cto-scorecard-guide/team-adoption-rate/)).

3. **Onboard people onto that workflow.** Pair each engineer with a champion for one real task that ends in a merged pull request. Exit check: each engineer passes the [onboarding fixture](/en/cto-scorecard-guide/dev-onboarding-time/) within one working day and then merges one real task at the workflow's evidence boundary.

4. **Climb the repository roadmap loop by loop.** Promote loops up the [autonomy ladder](/en/ladder/one-map/) only with a rollback rule for each step. Exit check: the loop's gate evidence is visible in Git and CI ([adoption roadmap](/en/teams/adopt/adoption-roadmap/)).

5. **Move review from diffs to evidence.** Once a loop's gates hold, review its [evidence bundle](/en/workflows/ship/evidence-bundle/) instead of the diff. Exit check: the stage entry criteria in [trust transfer](/en/teams/trust-transfer/) are met.

## What does the shared harness look like in each tool?

Only the committed files differ by tool. Full setup: [team collaboration: shared context and rules](/en/teams/adopt/team-collaboration/).

**Claude Code**

    Commit `CLAUDE.md` and `.claude/settings.json` for shared permissions. Claude Code reads `AGENTS.md` when a project has no `CLAUDE.md`, from v2.1.277, on both release channels (v2.1.281 on Bedrock, Google Cloud, Microsoft Foundry and LLM gateways; checked 2026-10-12). If the repository keeps only an `AGENTS.md` (for Codex), also commit a `CLAUDE.md` while part of the team may be on a build older than v2.1.277, because those builds do not read `AGENTS.md`. Once a `CLAUDE.md` exists, Claude Code no longer falls back to `AGENTS.md`, so make the committed `CLAUDE.md` the single line `@AGENTS.md`: it imports the shared file, and the team still maintains one set of conventions. Run the same checks headless in CI with `claude -p --output-format json`.

**Codex**

    Commit `AGENTS.md`; Codex reads it before it starts work. Since Codex CLI 0.150.0, an untrusted project does not supply its `AGENTS.md`, so each engineer trusts the repository once. In CI, `codex exec --json` emits machine-readable events.

**Cursor**

    Commit project Rules with the repository so that every engineer's agent loads them. Keep one core of conventions and generate the per-tool files from it, as [shared agent rules](/en/cto-scorecard-guide/shared-agent-rules/) describes. In CI, run the Cursor CLI in print mode (`-p`); Cursor documents a GitHub Actions setup.

**Copy-paste prompt: rollout readiness check for this repository**

```text
Audit this repository for a team rollout of coding agents. Do not change any files.
Report, as a table with columns item / status (pass, fail, missing) / evidence (file path or command output):
1. Is there a committed instructions file (CLAUDE.md, AGENTS.md, or project rules)? Does it list the exact install, build, typecheck, lint, and test commands?
2. Run each of those commands. Which pass on the default branch?
3. Are there committed shared agent settings (permissions, hooks, MCP servers)? Do any of them contain secrets?
4. Is the default branch protected with required status checks?
5. Which recurring change types appear most often in the last 50 merged pull requests? Name the one best suited as a first agent workflow and explain why.
End with the three fixes that would unblock a rollout, in priority order.
```

**Copy-paste prompt: draft the adoption card for the first workflow**

```text
Using the last 12 weeks of merged pull requests in this repository (list them with `gh pr list --state merged --search "merged:>=YYYY-MM-DD" --limit 1000 --json number,title,labels,mergedAt`, replacing YYYY-MM-DD with the date 12 weeks ago, then read the changed files only for the pull requests you use as evidence with `gh pr view <number> --json files`), draft an adoption card for the workflow "repair a failing test with an agent".
Fill in: workflow owner (leave as TBD), decision owner (leave as TBD), approved tools, eligible people, eligible tasks, excluded tasks (name risky directories you find), evidence boundary (merged PR, required checks green, not reverted or fixed within 14 days), what does not count as completion, guardrail metrics, and the baseline numbers for this task type from the data.
Show the command output you used for each baseline number. Mark any number you could not compute as UNKNOWN instead of estimating it.
```

## How do you know the rollout works without reading every diff?

Measure the workflow, not the seats. Effective adoption is the share of eligible engineers who completed the workflow at its evidence boundary in the period: a merged pull request with required checks green that was not reverted or fixed within 14 days.

Pair it with guardrails: the 14-day follow-up fix rate, the change failure rate, and review load against the pre-rollout baseline. [Metrics frameworks](/en/org/metrics-frameworks/) holds the canonical definitions. The tech lead signs off each loop's promotion on the roadmap, and the decision owner named on the adoption card signs off on the rollout.

## What stalls a team rollout?

- **Seats without a workflow.** Usage rises; nothing else moves. Recover by narrowing to one workflow with a published adoption card.
- **A private setup per engineer.** Results vary by person. Recover by committing one instructions file and shared settings, then deleting private copies.
- **Review becomes the bottleneck.** Agents open more pull requests than people read. Recover with the [review queue](/en/teams/review-queue/) limits, and do not raise autonomy until evidence gates exist.
- **Senior engineers opt out.** Recover by giving them the gate design, not a training course ([skeptics and seniors](/en/teams/skeptics-and-seniors/)).
- **A pilot that proves nothing.** Without a baseline and a decision rule, results are anecdotes. Use [pilot design](/en/org/pilot-design/) before you scale.

## Where to go next with your team rollout

Switching tools is a separate decision: see the [tool comparison](/en/comparison/) and guides for moving from [GitHub Copilot](/en/teams/adopt/from-copilot/), [Devin Desktop (formerly Windsurf)](/en/teams/adopt/from-windsurf/), [Codex, Cursor or Claude Code](/en/teams/adopt/from-codex/) and a [traditional IDE](/en/teams/adopt/from-traditional-ide/).

- [Adoption roadmap for one repository](/en/teams/adopt/adoption-roadmap/) — The next step: move one repository's loops up the ladder with gate evidence.
- [Team: leading a team that ships with agents](/en/teams/) — The parent hub: rollout, shared harness, review and flow, and people.
- [The organization-wide roadmap](/en/strategy/transformation-roadmap/) — For the CTO: scale this rollout from one team to the organization.