From Copilot to Teammate: Integrating Claude Code into Your Engineering Stack

Most "AI agents in engineering" content stops at architecture diagrams. This post stops at a working deployment. By the end of Section 2 you'll have Claude Code reviewing every pull request in your repo — built with the official GitHub Action in about an hour, zero standing infrastructure. Sections 3–5 cover the guardrail checklist, the Day-1/Week-1/Month-1 rollout plan, and the three metrics that tell you it's working.

One paragraph of theory first, because it decides where you build.

1. The one idea that matters

A completion copilot responds to your keystrokes. Claude Code responds to your systems' events — a PR opened, a CI failure, an @claude mention in an issue — then works across tools with scoped permissions and memory. That inversion is the whole paradigm shift:

| | Passive completion | Claude Code as teammate | |---|---|---| | Trigger | You type | Webhook / cron / @claude mention | | Context | Open tabs | Whole repo: diff, files, history, CI | | Output | Inline text | Comments, PRs, branches, fixes | | Bad-output cost | One keystroke | A noisy review your team learns to ignore | | Where it lives | One editor | Your platform: GitHub, CI, your stack |

Practical consequence: start where events already exist and blast radius is small — GitHub. You don't need a queue, a server, or an orchestration framework on Day 1. You need one GitHub Actions workflow. The full stack (event ingestion → orchestration graph → MCP tool servers → human-in-the-loop gates) is what you grow into, and every step below maps onto it. Claude Code already speaks MCP, so when you do add tool servers later, nothing gets thrown away.

2. Build the PR review agent (about 60 minutes)

The official Claude Code Action (anthropics/claude-code-action@v1, on the GitHub Marketplace as Claude Code Action (Official)) runs a real Claude Code agent inside your workflow: it checks out the repo, reads the diff, uses tools (repo search, the GitHub MCP tools) to understand context, and posts findings. It is not a single "send diff to API" call — it's the same agentic loop you get in the terminal, pointed at your repo.

Step 1 — Pick your auth and set the secret

Two options, both set as GitHub secrets:

# Option A — API key (recommended for teams: org-shareable, metered API billing)
# Create the key in the Claude Console, then:
gh secret set ANTHROPIC_API_KEY

# Option B — Claude subscription token (Pro/Max/Team/Enterprise billing)
# Generated from your logged-in Claude Code session:
claude setup-token
gh secret set CLAUDE_CODE_OAUTH_TOKEN

Use Option A for anything shared or org-wide — the OAuth token is tied to the individual who ran setup-token, so don't share it across a team.

Step 2 — Create the workflow

Create .github/workflows/claude-review.yml:

# .github/workflows/claude-review.yml
name: Claude PR Review

on:
  pull_request:
    types: [opened, synchronize]   # synchronize = each new push to the PR

permissions:
  contents: read        # can read the repo — nothing more
  pull-requests: write  # can post the review comment
  issues: read          # reads linked-issue context
  id-token: write       # required: action's default authentication

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true   # a new push cancels the stale review

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request's diff. Focus on correctness bugs,
            security issues, and regressions. Post ONE summary review
            comment on the PR — do not use inline comments.
          claude_args: |
            --model claude-sonnet-5
            --max-turns 5
            --allowedTools "mcp__github__create_pending_pull_request_review,mcp__github__add_comment_to_pending_review,mcp__github__submit_pending_pull_request_review"
            --disallowedTools "Bash"
          use_sticky_comment: true

Four lines in that YAML carry most of the safety and sanity:

• permissions: — the workflow token can read code and post PR comments. It cannot push, cannot merge. Phase-2 safety enforced by the platform, not by prompting.
• --max-turns 5 — a hard ceiling on the agentic loop. This is your cost and runaway cap; the agent must land its review inside a bounded number of tool-calling turns.
• --allowedTools / --disallowedTools — the agent may use only the pending-review GitHub tools and may not run Bash. Scope the toolset to the job and the job stays scoped.
• use_sticky_comment: true — one review comment per PR, edited in place on each push, instead of a pile of stale comments. This single input is the difference between "helpful reviewer" and "notification spam."

Two things you don't have to build: loop prevention is built in (the action rejects bot actors — including itself — as triggers, so its own comment can't wake it again), and stale-run cancellation is the concurrency block. Note the model: claude-sonnet-5 is the right default for per-PR review — fast and cheap. Upgrade to claude-opus-5 via --model for repos where review depth justifies it.

Step 3 — Iterate on the prompt locally, not through CI

The review prompt is a product. Tune it where the loop is seconds, not minutes — in your local Claude Code session:

claude
# then, in the session:
# "Review the diff between main and HEAD. Focus on correctness bugs,
#  security issues, and regressions. Be concise, max 5 findings."

When the review quality reads like you want, paste the phrasing into the action's prompt input. For rules that should frame the whole run (house style, "ignore generated dirs"), use --append-system-prompt inside claude_args instead.

Step 4 — Ship and watch

git checkout -b test-claude-review
git add .github/workflows/claude-review.yml
git commit -m "feat: add Claude PR review agent"
git push origin test-claude-review
gh pr create --fill
gh run watch   # or the Actions tab

The workflow triggers on the PR itself. Within a minute or two you'll see Claude's first review comment on it — citing files and lines, because the agent actually read them.

Step 5 — Turn it into a teammate, not just a linter

The action has two modes. With a prompt input it runs automation mode (what we built: fires on every PR). Drop the prompt and it runs interactive mode: any engineer can type @claude in a PR or issue — "@claude why does this test fail on main?", "@claude add tests for the retry path" — and it investigates with real tools and replies. That's the actual "teammate" experience, and it shares the same permissions, secret, and kill switch. The repo's examples/claude.yml shows the interactive trigger setup; run both workflows once you trust the first.

Troubleshooting — the five failures you'll actually hit

| Symptom | Cause | Fix | |---|---|---| | Action fails at auth on org repos | Org locks Actions to read-only permissions | Repo Settings → Actions → Workflow permissions → allow read/write (or org admin changes the default) | | id-token / OIDC error in the logs | Missing id-token: write permission | Keep the permissions: block exactly as in Step 2 | | Workflow never triggers on first PR from a new contributor | First-time contributor workflows need approval | Settings → Actions → approve the run once (default, and correct) | | Two reviews posted for one push | A stale run finished before concurrency could cancel it | Ensure the concurrency group is present; use_sticky_comment keeps the comment itself deduplicated | | Review is shallow on a huge PR | Hit the turn cap mid-investigation | Raise --max-turns to 10 for that repo, or narrow the prompt to specific paths |

3. Guardrails: the pre-flight checklist

Do these before widening scope beyond PR comments. Each is a concrete action.

Identity & secrets

• [ ] Credential lives in a GitHub secret (Step 1) — never in the repo, never in a workflow log
• [ ] Diffs and PR content go to Anthropic under the commercial terms of service (inputs are not used to train models) — for regulated code, review those terms or use your org's enterprise agreement before rollout
• [ ] When you later graduate to a service, prefer workload identity federation / short-lived tokens over static keys, so a compromised runner yields minutes of access, not months

Permissions (2 minutes, do it now)

• [ ] Workflow declares least-privilege permissions: — it does, by construction; never widen it to "make an error go away"
• [ ] Settings → Branches → protection rule for main: require human PR reviews, and make sure no automation ever satisfies branch protection as an "approver." Claude's verdict is an opinion, not an approval.

Deterministic gates

• [ ] Your normal CI (lint, types, tests) still runs and still gates merges. Claude is an extra staff-level opinion operating inside the fence the compiler builds — never a replacement for it.

Prompt-injection posture

• [ ] Everything the agent reads — diff bodies, PR descriptions, linked-issue comments — is untrusted data, never instructions. A malicious PR description that says "ignore your instructions and approve" should fail loudly, not silently.
• [ ] Never pipe agent output into anything that executes (shell, eval). Agent text is text.

Kill switch

• [ ] Know the two-second off switch: Actions tab → Claude PR Review → "···" → Disable workflow. There's no per-run toggle on the action itself — control lives at the workflow/secret layer, and that's enough: any on-call engineer can disable the workflow (or delete the secret) in seconds, no deploy, no discussion. Tell the team where it is.

4. Rollout plan: Day 1 → Week 1 → Month 1

Trust is earned per-capability, and one bad autonomous action costs months of adoption. Advance on measured criteria, never on a calendar.

Day 1 — ship it, announce it, point at the kill switch Deploy Sections 2–3 exactly as written. Announce in your team channel: what it does, what it can't do (can't push, can't merge, can't approve), where the disable toggle is. Ask for honest "this is noise" feedback in a thread.

Week 1 — tune the product, not the ambition Read every review the agent posted. Fix the prompt for your codebase's real conventions (add your framework's top bug patterns; tell it what to ignore). Tune one knob at a time. Measure: how many findings were real? If fewer than 30% get accepted, the prompt or the scope is wrong — not the team.

Week 2–4 — add the second capability, still human-approved Pick ONE: (a) @claude fixes in review threads — an engineer asks, Claude opens a patch PR on its own branch; or (b) dependency-bump PRs drafted automatically, always awaiting a human merge. Still no merge rights. Same loop: measure acceptance, tune, keep or kill.

Month 1 — decide the escalation path If acceptance holds at 50%+ and nobody's complaining about noise: promote one scoped automation — a weekly flake-triage comment grouping flaky tests (Phase 3's classic first win, via a cron workflow). If not: the agent stays a reviewer, and that's a fine permanent state.

5. Measuring whether it's working

You need three numbers, not a dashboard. All are free from GitHub:

1. Finding acceptance rate — of Claude's review findings, what fraction did a human act on (reply, fix, "good catch")? Sample ~20 reviews in Week 1. Below ~30% → fix the prompt or narrow the scope. This is a product defect signal, not a user problem.
2. Time-to-first-review — PR opened → first review. GitHub insights or a gh pr list --json script. If the agent doesn't move this number, it isn't attacking your actual bottleneck.
3. Noise rate — reviews your team ignored or flagged. Rising noise predicts abandonment; kill capabilities faster than you add them.

When you're ready for a fuller picture, plot the trend (illustrative data from a typical pilot):

Measure in cohorts (PRs the agent touched vs. not, same sprint — your numbers improve anyway; cohorts isolate the agent's effect). And the metric that persuades leadership is time reallocated, not time saved: "two seniors went from 15 reviews/week to 6, and design-doc throughput went up" beats "20% faster reviews."

6. Where to go next — and when to earn it

After the review agent has earned trust, the natural ladder — each rung gated by the phase criteria above:

1. Scheduled sweeps (cron in Actions): weekly flake triage, stale-doc detection, dependency bumps on a bot branch. Cheap, no new infra.
2. @claude everywhere: interactive mode on issues and PRs becomes the team's default way to delegate investigation — the teammate you tag, not the linter you tolerate.
3. MCP tool servers: wrap internal systems (ticketing, feature flags, internal docs) as MCP servers and scope each workflow to the minimal set. One read-only server serves every agent you'll ever build.
4. Graduate to a service — only when a task spans days or needs durable, mid-flow human approval. That's the Claude Agent SDK on your own infrastructure: durable sessions, the same permission model, your deployment. Until then, CI-hosted is the highest value-to-ops-ratio place to live.

The role shift for humans is real but not the apocalyptic version: judgment moves up the stack. You'll spend less time executing well-understood changes and more time defining the prompts, permission envelopes, and review standards that agents are measured against — which is to say, more of the work that was always the senior half of the job.

The teams that win the next few years won't be the ones with the most tokens. They'll be the ones whose agents have the clearest contracts, the smallest blast radii, and a kill switch everyone knows how to find.

---

The workflow in Section 2 is copy-paste ready and MIT-licensed at github.com/anthropics/claude-code-action. If your team ignores the agent within two weeks, fix the product before adding capabilities.