Claude for dev teams: a practical playbookClaude for dev teams: a practical playbook

By Dhashin Reddy, White Wolf Studio. Version 1.1, updated 1 November 2026.

#The loop

Every change goes through the same five steps. The agents do the first four. A person does the last one, every time.

Step	The agent does	The human checks
Plan	Reads the brief and the code, writes a step-by-step plan	Is this the right problem, at the right size?
Build	Implements the plan on a branch, in small commits	Architecture calls, and steering when the plan meets reality
Test	Writes tests, runs them with types and lint, fixes failures	Do the tests prove the behaviour, or only that the code runs?
AI review	A second agent reads the diff cold and leaves advisory notes; the first agent fixes what matters	Which notes matter
Approval	Waits, with CI green	Reads every line, then approves or sends it back

The rest of this playbook is about making each step work in a real team.

The agents make you faster. They do not make you accountable. A person approves every change that ships, and that person can explain it.

#Start small on purpose

Pick one team, one repository and one kind of task for the first few weeks. Good first tasks are well-understood and easy to verify:

• Adding tests around existing behaviour
• Small, well-specified features behind an existing pattern
• Bug fixes with a clear reproduction
• Mechanical changes: renames, dependency bumps, deprecation fixes

Avoid starting with your gnarliest legacy module or a greenfield architecture decision. You want early wins that teach the team how the agent behaves, not a heroic rescue that teaches nothing.

#Give the agent the context a new hire would need

An agent knows a great deal about programming and nothing about your codebase. Write the onboarding notes you wish every new developer read, and put them in the repo where the agent will find them: CLAUDE.md for Claude Code, AGENTS.md for Codex.

#What goes in the context file

Keep it short and specific. A page is plenty to start with.

# Project notes

- Laravel 12 + Inertia + React. Run `composer test` for PHP tests,
  `npm run types` and `npm run lint` for the front end.
- Money is stored in cents as integers. Never use floats for amounts.
- Controllers stay thin; business rules live in app/Actions.
- Never edit migrations that have shipped. Add a new one.
- Ask before adding a dependency.

#What does not go in it

• Secrets, tokens or connection strings
• Generic advice the model already knows ("write clean code")
• Long essays nobody maintains

Treat the file like code: review changes to it in pull requests, and update it every time the agent gets something wrong that a sentence would have prevented.

#Write the brief, not the implementation

The agent can read your repo. The person writing the task usually hasn't read all of it. So when a task spells out file paths, class names, schemas or libraries that were guessed, the agent either follows the wrong guess or stops to say "that isn't how this codebase works".

Split every task into two parts:

• Fixed (the brief owns it): the problem, the goal, who it's for, business rules, decisions already made, what "done" looks like, and the safety rules.
• Flexible (the agent owns it): file paths, names, schema shape, libraries, patterns and how the work splits into pull requests. It takes these from the repo and the context file.

When you do include a specific you haven't checked, label it as a hint: "probably X, confirm against the repo". Then give the agent four instructions every time:

1. Ground first. Read the context files, the conventions and the code this task touches before planning anything.
2. Check the brief against reality. List any assumption in it that is wrong or impossible, with evidence.
3. Take the nearest approach that still meets the goal, instead of forcing the brief's shape or stopping at "not possible". Stop only if the difference changes the goal, money, data or security.
4. Report what was wrong. Every stop report includes "assumptions in this brief that turned out wrong, and what you did instead".

A shape that works:

## The problem
What's wrong or missing, and for whom.

## The goal
What done looks like for the user, not the implementation.

## Decided (don't reopen)
Business rules and choices already made.

## Ground first
Read the context files and the code this touches. Check this brief's
hints against what you find; list anything wrong, with evidence.

## Acceptance
Behaviour, written as tests: "a second run on the same day returns
the existing run", not "add a unique index on column X".

## Stop and report
PR link, test count, and assumptions in this brief that were wrong.

From our own work. We wrote a detailed brief for pack-runner, our internal agent runtime, and got six specifics wrong: two repository names, a character the API doesn't allow in tool names, a feature one model didn't support, an error code, and a severity value another system spells differently. Because the brief said "ground first and report what was wrong", the agent found all six, worked round them and listed them. A brief that dictated the how would have produced six failures instead.

#Plan before code

The cheapest place to catch a bad change is before it exists. Ask the agent for a plan first: the files it will touch, the approach, the tests it will add, and what it is unsure about. Claude Code's plan mode exists for exactly this.

Read the plan the way you would read a junior developer's proposal:

• Is it solving the problem in the brief, or a different one?
• Is the scope right, or has it quietly grown?
• Does it follow the patterns already in the codebase?
• Has it named the risky parts?

Approve the plan, change it, or throw it away. Five minutes here saves an hour of reviewing the wrong diff.

For larger work, split it into sessions with a stop point at the end of each: the agent stops, reports, and waits for a person before the next session starts.

#Tests are the contract

An agent will happily write code that looks right. Tests are how you find out whether it is right, so make them part of the definition of done:

1. The agent writes or updates tests for every behaviour change. Every bug fix gets a test that fails without the fix.
2. It runs them, with types and lint, locally before asking for review, and again after every round of review fixes.
3. CI runs them on the pull request once the reviews are done, and again only if a fix is pushed after that. Green CI is the minimum bar for a human approval.

Then review the tests as carefully as the code. Watch for tests that assert on implementation details, tests that mock away the thing they claim to test, and tests that were edited until they passed.

#AI review is a first pass, not an approval

A second agent reviewing the diff cold is one of the highest-value, lowest-effort steps you can add. A typical pull request goes through a few rounds: the reviewer leaves notes, the building agent fixes the ones that matter, and the reviewer looks again.

Make the boundaries explicit:

• Label it advisory. The AI review comments; it never approves or blocks a merge.
• Keep the review instructions in the repo, so the team can tune what it looks for.
• Run it automatically on every pull request, on an account your organisation controls.
• Don't let it review its own work. Use a different agent, or a fresh session with no memory of writing the code.

#What it actually catches

It isn't only null checks and naming. Our setup is Claude Code building and Codex reviewing. While we built pack-runner, Codex caught:

• A budget guard that under-counted cost. It priced prompt tokens at the normal rate when they were billed at the higher cache-write rate, so a spending cap could be overshot.
• A size limit that could be bypassed. The cap on response size didn't apply to chunked responses, which have no length header.
• Secrets that could reach the error tracker. Error events weren't scrubbed before being sent.
• A retry that looked like a recovery. A pending re-run was treated as if the original failure had been fixed.

Each was a real bug, cheap to fix at review and expensive to find in production.

#The human approval rules

This is the step that makes the rest safe. Write the rules down so they do not erode under deadline pressure:

• Every change gets a human approval. No exceptions for "small" changes.
• The approver reads the whole diff, not just the summary the agent wrote about it.
• The approver can explain the change. If you could not defend it in a review meeting, it is not approved.
• Sending it back is normal. Rejecting an agent's work costs minutes, not feelings.
• Ownership does not transfer to the tool. The person who approved the change owns it in production.

Keep pull requests small enough that reading every line is realistic. If the agent produces a diff too large to review properly, the fix is a smaller task, not a faster skim.

#Guardrails: permissions, secrets and data

Agents run commands on real machines. Decide what they may do before they do it, and enforce it in configuration rather than asking nicely. An instruction in a context file is a request. A permission rule or a hook is a wall.

• Least privilege, in committed settings. Allow the commands the work needs (running tests, linting) and require confirmation for everything else. Claude Code reads permission rules from a settings file you can commit to the repo, so the whole team gets the same limits, not just the person who set them up.
• Block the dangerous commands outright. Use hooks or deny rules for things that should never happen in an agent session: force-pushing, rewriting history, wiping the database, running migrations against anything but the test database.
• No production access. Agents work on branches and pull requests. They do not merge or deploy, and they never hold production credentials.
• Keep secrets out of reach. Nothing secret in context files, prompts or committed config. Use your normal secret management, and have agents report a file path and line, never a value.
• Know where your code goes. Check your provider's data-retention and training terms, and use organisation accounts rather than personal ones.
• Watch for prompt injection. Content the agent reads (issues, pull request text, web pages, dependency READMEs, error messages) can contain instructions. Treat it as data, label it as data when you pass it on, and keep a human in the loop for anything with side effects.

#Watch the cost

Agents change where your money goes. Two bills grow quickly if nobody looks at them.

#CI minutes

Every push to a pull request normally re-runs CI. With agents, a pull request can get five or ten pushes during review rounds, and each one pays for a full CI run that nobody needs yet.

The fix is to run CI on pull requests only when reviews are done. We use a label: adding ready-for-ci starts CI, and later pushes re-run it as normal. Review rounds before the label cost nothing.

on:
  pull_request:
    types: [opened, labeled, synchronize, reopened]
  push:
    branches: [main]

# A run the gate skips gets a group of its own, so it can't cancel a real run.
concurrency:
  group: ${{ github.workflow }}-${{ (github.event_name != 'pull_request' || (github.event.action == 'labeled' && github.event.label.name == 'ready-for-ci') || (github.event.action != 'labeled' && contains(github.event.pull_request.labels.*.name, 'ready-for-ci'))) && (github.event.pull_request.number || github.ref) || github.run_id }}
  cancel-in-progress: true

jobs:
  test:
    if: >-
      github.event_name != 'pull_request' ||
      (github.event.action == 'labeled' && github.event.label.name == 'ready-for-ci') ||
      (github.event.action != 'labeled' && contains(github.event.pull_request.labels.*.name, 'ready-for-ci'))

The long concurrency line matters. With a plain per-PR group, adding any other label while CI is running starts a run the gate skips, and that skipped run cancels the real one.

Three things to know:

• A skipped job counts as passing. If your main branch requires status checks, a pull request without the label can look mergeable without CI having run. Keep "green CI before approval" as a human rule, or add a check that fails when the label is missing.
• Each job is billed rounded up to a whole minute. Several tiny parallel jobs can cost more than one combined job.
• Skip what the change didn't touch, but default to running everything. A backend-only change can skip the frontend checks. A file nobody thought to classify should cost a few extra minutes, never a silent gap in CI.

#API spend

Subscriptions for coding agents are predictable. API usage, for agents you run yourself (scheduled jobs, review bots, internal tools), is metered and can surprise you.

• Give each agent a budget, per run and per month, and stop the run before it goes over.
• Compute cost from the token usage the API returns, against a dated price table. Never estimate it from text length.
• Put agent API keys in their own workspace with a hard spend limit, as a backstop if your own budget code has a bug.
• Use the smallest model that does the job, and escalate to a larger one only when needed.

#Rolling it out across a team

1. Run a pilot. One or two volunteers, one repository, a few weeks. Keep notes on what worked and what went wrong.
2. Write the conventions down. The context file, the brief template, the review instructions, the approval rules and the permission settings. Commit them.
3. Pair before you scale. Have pilot members pair with colleagues on real tickets. Watching someone brief, steer and reject is how the habits spread.
4. Expand one team at a time, keeping the same loop. Resist adding a second, different workflow alongside it.
5. Revisit monthly. Update the context files, prune the rules that don't help, add the ones you keep wishing you had, and check the CI and API bills.

Expect the role of senior developers to shift towards briefing, reviewing and teaching. That is the point, and it is worth saying out loud early.

#What to watch

Look at signals, not targets. Turning any of these into a target is the fastest way to make them meaningless.

• Review load. Are approvers getting diffs they can actually read, or drowning?
• Send-back rate. How often does a change go back? Rising can mean vaguer briefs or a context file that needs work.
• Wrong assumptions reported. If the same kind keeps coming up, the context file is missing a sentence.
• Escaped defects. Bugs found after merge, and which step should have caught them.
• Time from ticket to merged. Useful as a trend for one team, useless as a comparison between teams.
• Cost per merged change. CI minutes and API spend, as a trend.
• How the team feels. If people feel like rubber stamps, the loop is broken, whatever the numbers say.

Never rank individual developers by agent output.

#Anti-patterns

• Approving the summary instead of the diff. The agent's description of its change is not the change.
• Letting the AI review stand in for the human one. Two agents agreeing is still zero people agreeing.
• Giant pull requests. If it cannot be read in one sitting, it cannot be approved.
• Prompting around failing tests. "Make the tests pass" invites the agent to change the tests.
• Skipping the plan for "quick" changes. Quick changes are where scope creep hides.
• Dictating the how from memory. A brief full of guessed file names gets you either the wrong code or an argument.
• Guardrails that only live in a prompt. If it must never happen, block it in configuration.
• One person's private setup. Prompts, settings and context that live on one laptop leave with that laptop.

#The checklist

Pin this to the pull request template.

• There is a brief, and the agent's plan was approved before code was written
• The agent reported any wrong assumptions, and they were dealt with
• The change is small enough to read in one sitting
• Tests cover the behaviour change, and CI is green
• The AI review ran, and its notes were read and resolved or dismissed with a reason
• A person read every line of the diff
• That person can explain the change and owns it in production
• No secrets, credentials or production access were involved

#What changed

• 1.1 (1 November 2026): Added "Write the brief, not the implementation", "Watch the cost" and "What it actually catches". CI now runs once reviews are done rather than on every push. Guardrails are enforced in configuration. Updated the rollout, signals, anti-patterns and checklist to match.
• 1.0 (October 2026): First version.

---

Want help putting this loop into your team? The Engineering Reset installs it in two weeks: PR process, green CI, AI first-pass review, and a human on approval.