Buying code assistant seats is not a transformation: building an AI-assisted SDLC step by step

In spring, a forty-person team gets code assistant seats. In autumn, the leadership meeting asks where the productivity went. The release calendar is unchanged, the review queue is longer, test coverage has not moved. The licence dashboard, meanwhile, is green: everyone has opened the tool, suggestions were accepted, lines were written.

Our position: a seat changes how fast an individual developer types. What changes how a team delivers is the set of files that land in the repository and the rules the team agrees on. This article walks through each step of the delivery life cycle and says what we hand to AI, what we keep with a human, and which concrete file makes that repeatable. The running example is a hypothetical retail app repository with iOS, Android and a small BFF service.

Seats were bought, delivery stayed the same

Six months after the purchase, the repository in a large team tends to look roughly like this:

retail-app/
├── CLAUDE.md                        # added by one person, 600 lines, half of it stale
├── .github/
│   └── copilot-instructions.md      # added by someone else, contradicts CLAUDE.md
├── README.md                        # setup steps last worked two Xcode versions ago
├── ios/
├── android/
└── bff/

PR #2147  "Cart screen refactor"
  +1,840  −212   27 files
  Description: "Reworked the cart flow."
  Review: 1 approval, 4 minutes later

The pieces are familiar. Three or four enthusiasts use the tool well, each with private prompts on their own machine. The rest of the team left autocomplete on and touched nothing else. Instruction files were added on personal initiative and nobody owns them. The review process, the test strategy and the release steps are exactly what they were before the purchase.

The outcome is predictable. Code gets written faster, PRs get bigger, and the two senior people who review are the same two people. The bottleneck moves from writing to reading and delivery time does not budge. Since the only metric leadership sees is "accepted suggestions", nobody can point at where the problem is.

A map of the life cycle: what we hand to AI at each step

What we call transformation is the last column of the table below existing in the repository and being used by the whole team. The first two columns show what current tools can reasonably take on and what has to stay with a person.

Do not start on all eight rows. We begin with coding, review and testing, because the output of all three shows up in a PR and can be measured. The requirements and operations rows need wider data access (the ticket system, crash reports, logs), and that brings data classification and permission questions with it. If the answers to those questions are not written down, do the work in AI usage policy first.

Every row follows the same pattern: AI produces the draft, a person makes the decision, and the file keeps that from varying person to person. Without the file, the step stays at the level of "Ayşe writes good prompts".

The foundation most teams skip: a repository an agent can read

An agent is an engineer who joined today and cannot ask anyone a question. It has not read the Slack history and never heard "set this environment variable before you run that script". If something is not written in the repository, it does not exist for the agent. Cloud-hosted agents make this more visible: every task starts on a clean virtual machine with a clean checkout. GitHub's Copilot cloud agent, for example, prepares its environment from a .github/workflows/copilot-setup-steps.yml file containing a job named copilot-setup-steps; if your build needs steps nobody wrote down, that file is where you find out.

A build your agent cannot run is a build your new hire cannot run on day one either.

The first job is a verification script that runs with one command and asks for nothing:

#!/usr/bin/env bash
# scripts/verify.sh: runs from a clean checkout and never prompts.
set -euo pipefail

target="${1:-all}"

case "$target" in
  ios)
    xcodebuild test \
      -workspace ios/Retail.xcworkspace \
      -scheme RetailApp \
      -destination 'platform=iOS Simulator,name=iPhone 17' \
      -quiet
    ;;
  android)
    (cd android && ./gradlew --no-daemon lint testDebugUnitTest)
    ;;
  bff)
    (cd bff && npm ci && npm test)
    ;;
  all)
    "$0" ios && "$0" android && "$0" bff
    ;;
  *)
    echo "usage: verify.sh [ios|android|bff|all]" >&2
    exit 2
    ;;
esac

The value of this script is that the agent can check its own work. An agent that cannot run tests hands you code without knowing whether it compiles, and you find out in review or in CI. The check is simple: clone the repository into an empty directory and run the script without looking at the README. If it fails for you, it fails for the agent.

The rest is writing things down. Take the rules that live in the team's heads (which layer may import which, how errors travel, how tests are named) and write them as short bullets. Keep the architecture note to one page: modules, dependency direction, places not to touch. The fourth item is the expensive one: small modules. An agent, like a person, makes mistakes when it has to read ten thousand lines to understand one feature; the difference is that it does not tell you, it writes a plausible guess. In a repository with clear module boundaries, a task can be described as "in this module, behind this interface", and the agent can verify itself by running only that module's tests.

The same rules in every tool: shared instruction files

All of today's tools read an instruction file from the repository at the start of every session. The file names differ, the idea is the same. We keep the rules in one tool-neutral file, AGENTS.md. It is plain Markdown with no required fields and lives at the repository root; in a monorepo it can also sit in subdirectories, and the nearest file wins. The format is stewarded by the Agentic AI Foundation under the Linux Foundation, and both the Copilot and Cursor documentation state that they read it.

# Retail App: agent instructions

## Verification
- After every change run the relevant target: `./scripts/verify.sh ios|android|bff`
- The work is not done until the script passes. If you cannot make it pass, say why. Do not delete or disable tests.

## Architecture
- Module map and dependency direction: docs/architecture.md
- Feature modules do not import each other. Shared needs go into `Core*` modules.
- Network calls are made only in the repository layer.

## Rules
- Do not add dependencies (SPM packages, Gradle libraries, npm packages); propose them in the PR description.
- Any change to public API also updates the matching page under docs/.
- Do not touch files outside the task description. List other problems you notice in the PR description.

## Off limits
- Do not push to `main` or `release/*`.
- Do not read `.env`, `secrets/` or signing files; do not modify anything under `.github/workflows/`.
- Do not run commands that send requests to production.

Claude Code does not need a separate copy. According to its documentation, Claude Code reads AGENTS.md directly when there is no CLAUDE.md in the working directory or above it (v2.1.277 and later). If you have tool-specific additions, a CLAUDE.md pulls the same file in with the import syntax:

@AGENTS.md

## Claude Code
- For changes under `ios/Payments/`, produce a plan first and wait for approval.

The same documentation recommends staying under 200 lines per file; longer files eat context and reduce adherence. For rules that apply only to certain files, all three tools offer path-scoped rule files. Here is one rule written for each (the first line of each section is a label showing the file path and is not part of the file):

# .claude/rules/ios-tests.md  (Claude Code)
---
paths:
  - "ios/**/*Tests.swift"
---
- Write new tests with Swift Testing; do not convert existing XCTest files.
- No tests that hit the network. Use the JSON files under `Fixtures/`.

# .github/instructions/ios-tests.instructions.md  (GitHub Copilot)
---
applyTo: "ios/**/*Tests.swift"
---
- Write new tests with Swift Testing; do not convert existing XCTest files.
- No tests that hit the network. Use the JSON files under `Fixtures/`.

# .cursor/rules/ios-tests.mdc  (Cursor)
---
description: iOS test rules
globs: ios/**/*Tests.swift
alwaysApply: false
---
- Write new tests with Swift Testing; do not convert existing XCTest files.
- No tests that hit the network. Use the JSON files under `Fixtures/`.

On the Copilot side, repository-wide instructions live in .github/copilot-instructions.md. Which Copilot feature reads which file varies by product (GitHub notes that on GitHub.com, path-specific instructions are used only by the cloud agent and code review), so check the support table in the documentation for the surface you use. With two tools in one team, some duplication of rules is unavoidable; keep the copies short and give them all to the same owner.

Know what these files are not. The Claude Code documentation says it plainly: instruction files are context, they are not enforced configuration. Writing "do not push to main" in AGENTS.md is a request. The mechanisms that enforce come in the next sections.

The command library lives in the repo

Good prompts on an enthusiast's machine do not scale until they belong to the team. We put recurring jobs (preparing a PR, examining a ticket, release notes) into the repository as named commands. In Claude Code the place for this is .claude/skills/<name>/SKILL.md; older .claude/commands/*.md files keep working.

---
name: prepare-pr
description: Prepares a PR description for the current branch using the team template.
disable-model-invocation: true
---

## Changes

!`git diff origin/main...HEAD --stat`

## Steps

1. Run `./scripts/verify.sh` for the targets that changed and note the result.
2. Fill in the template at `.github/pull_request_template.md`.
3. In the "AI use" section, state which files were produced by the agent
   and which steps still need to be verified by hand.
4. If the diff exceeds 400 lines, propose a sensible split and do not open the PR.

disable-model-invocation: true means the command runs only when someone types /prepare-pr. The Copilot equivalent is *.prompt.md files under .github/prompts/; GitHub still marks these as public preview and supports them only in VS Code, Visual Studio and JetBrains IDEs. Whichever tool you use, the principle holds: the command lives in the repo, changes through a PR, and gets reviewed.

Working agreements: who is accountable, what the agent may not touch

The files describe how the team does things. Working agreements describe who answers for what. We do not start a pilot until these fit on one page and the team has accepted them.

Whoever or whatever wrote the code, the person who opens the PR owns every line.

"The agent wrote that" is not accepted as a review answer. The person who opens the PR has read the whole diff, has run it and can explain it. Code they cannot explain does not get merged. We treat AI output the way we treat the work of an engineer who has just started: fast, usually useful, and always reviewed.

The second agreement is disclosure. A reviewer should know where to look harder:

## What changed and why

## How it was verified
- [ ] `./scripts/verify.sh` passed locally (target: ...)
- [ ] Tried by hand: (device, scenario)

## AI use
- Parts produced by an agent: (files, or "none")
- Parts I read line by line:
- Where I am not sure and want the reviewer to look closely:

## Risk
- [ ] Touches payments, authentication, personal data or a migration

This template goes into the repository as .github/pull_request_template.md. The "AI use" section directs the reviewer's attention, and three months later it shows you which kinds of work the agent handles well. Nobody is blamed for what they write in it.

The third agreement is the agent's limits, and it is not left to a request. In Claude Code, permission rules live in .claude/settings.json, checked into the repository:

{
  "permissions": {
    "allow": [
      "Bash(./scripts/verify.sh *)",
      "Bash(git commit *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Edit(/.github/workflows/**)",
      "Bash(fastlane *)"
    ]
  }
}

Rules are evaluated in the order deny, ask, allow, and the first match wins. Take the documentation's own warning seriously, though: Bash rules match the command text the agent writes, they do not catch the same program invoked another way (inside sh -c, or by full path), and they are not a security boundary. The real fence is on the server: branch protection for main and release/*, required status checks, CODEOWNERS approval. The token the agent uses should be narrowly scoped too. Signing certificates, store keys and production credentials are simply absent from the environment the agent runs in; what is not there cannot leak.

The fourth agreement is review depth. Since nobody can give every PR the same attention, we define risk classes: changes touching payments, authentication, personal data or migrations get two human approvals and a line-by-line read; low-risk mechanical changes get the AI first pass plus one human approval. The review side is covered in detail in AI code review.

A first-pass review in CI

The way to ease the review bottleneck is for a PR to reach the human reviewer already cleared of obvious problems. The workflow below sets up Claude Code's GitHub Action following the example in its documentation: when a PR is opened or updated it runs the review plugin and leaves its findings as inline comments on the PR.

name: AI first-pass review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Three details matter. With contents: read, this job cannot change code, it can only comment. The review reads the instruction file in the repository, so "feature modules do not import each other" applies here as well; you write the rule once and use it in two places. On public repositories GitHub withholds secrets from fork PRs, so the job runs only for branches in the same repository. For teams on Copilot the equivalent is Copilot code review, which reads .github/copilot-instructions.md and the path-specific instruction files.

Do not make this job a required status check. The findings of an AI review are a list of suggestions; it produces false positives and it misses things. What is required is the job that runs verify.sh, and a human approval. Enforcing architecture rules with lint or compile-time checks is separate work and more reliable than an AI review.

Rolling out in phases: what to do, what to measure

We move in four phases. Each has an exit condition, and we do not move on until it is met.

Phase 0: baseline

Record the current state before changing anything, or in six months the only answer to "did it improve" will be a feeling. Measures you can pull from git and CI history are enough: time from PR open to merge, wait until first review, lines changed per PR, share of PRs reverted, how often CI passes on the first attempt. On the delivery side, DORA's five metrics (change lead time, deployment frequency, failed deployment recovery time, change fail rate, deployment rework rate) are a good frame. Take at least two or three months of history. The details are in measuring AI productivity.

Phase 1: one team, one or two steps

Pick a volunteer team and a narrow scope. Our preference is writing tests for existing code plus the first-pass review in CI: both are low risk and their output is visible in the PR. verify.sh, AGENTS.md and the PR template get written in this phase. What you measure: the same baseline metrics for this team only, how many AI review comments turned out useful (counting those marked "resolved" versus "not applicable" on the PR is enough), and a short weekly note from the team on where the agent saved time and where it went the wrong way. Exit condition: the team uses the files daily and the instruction file has been updated through PRs at least a few times.

Phase 2: rules and templates

What the pilot taught becomes permanent: the working agreements are written, the permission file and branch protection go live, the command library moves into the repository, the instruction files get an owner. Adoption rate tells you little at this point; look at where rule violations get caught. When an agent breaks a rule that is written in the instructions, did the AI review catch it, did the human reviewer, or did production? If the catch point is moving left, the system works.

Phase 3: expansion

Other teams adapt the same files to their repositories. We watch two things. First, the baseline metrics per team: review wait time and PR size are the two indicators that degrade earliest. Second, the senior engineers' calendars: if the time they spend reviewing is going up, the bottleneck has moved there, and you need to slow the expansion and tighten the first-pass review and the PR size limit.

The failure modes we see most

Tool sprawl comes first. Four assistants, each with its own instruction file, means four copies of the rules that nobody updates. Pick two tools at most, gather the rules in AGENTS.md, keep the tool-specific files thin.

Second is "vibe coding" into main: a developer gives the agent a broad task and opens a PR without reading the diff, and the reviewer looks at the size and approves. The symptom is the PR at the top of this article: 27 files, a one-line description, approved in four minutes. The remedy is a PR size limit, the disclosure section and the rule that you do not merge code you cannot explain.

Third, the review bottleneck moves to the seniors. Code production speeds up, reading capacity stays where it was. You see it in review wait time and in the share of reviews done by the top two or three reviewers.

Fourth, security blind spots. Every file the agent reads goes to the model provider along with the prompt. How it is stored depends on your plan. As an example, the Claude Code documentation states that on commercial plans (Team, Enterprise, API) code and prompts are not used for model training by default and the standard retention period is 30 days, while on consumer plans training use depends on the user's setting; session transcripts are also kept in plain text on the developer's machine. The practical consequence: no personal accounts on company code, and files like .env stay outside read permission. Read your own provider's terms in the contract. The other blind spot is invented dependencies: an agent can suggest a package that does not exist or has a slightly different name. That is why the instruction file makes a new dependency a human decision.

Fifth, counting lines. Lines produced, accepted suggestions and "percentage of code written with AI" are output measures, and agents are generous with lines. Make those metrics a target and you get bigger PRs and more review load.

Where to stop

For a five-person team with one repository the full structure is too much: verify.sh, a short AGENTS.md and the disclosure section in the PR template will do. Turn off the AI review in CI, or narrow its scope, if most of its comments turn out to be wrong; a noisy bot trains the team to ignore every bot comment. Agents with production access, automatic merge and store submission are jobs we do not give to an agent today; the four phases above need to have settled before those are opened up.

Monday checklist

• I cloned the repository into an empty directory; build and tests run with one command (./scripts/verify.sh).
• There is an AGENTS.md under 200 lines at the repository root with the verification command, an architecture summary, rules and off-limits items.
• Every tool the team uses reads that file (directly, or through an import in CLAUDE.md); tool-specific copies have a named owner.
• .github/pull_request_template.md has "How it was verified" and "AI use" sections.
• main and release branches are protected; the token the agent uses cannot push to them.
• Secrets, signing files and production credentials are absent from the environment the agent runs in; the permission file denies reading them.
• No personal accounts are used on company code, and the provider's data retention terms have been confirmed.
• Baseline metrics for the last two or three months (PR time, wait for first review, PR size, revert rate) are written down.
• The pilot team and the one or two steps the pilot covers are chosen; the exit condition is written.
• The rule "the person who opens the PR owns every line" has been discussed with the team and written down.
• Line counts and accepted suggestions do not appear as a target in any report.