← All guides AI Release
RU Subscribe to @ai_release1

Claude Code Agent Teams: running a team of coding agents

Updated: 30.10.2026 · AI Release · @ai_release1
Claude Code Agent Teams: running a team of coding agents

TL;DR

Requirements and setup

Illustration: Requirements and setup
Illustration: Requirements and setup

What to do: create the directory skeleton and confirm the toolchain.

Why: every later step reads or writes into these three folders. Creating them first means a missing path shows up now, not in the middle of a run.

How to check:

cd ~/projects/billing-service       # replace with your repo
git status --short                  # expected: no output (clean tree)
mkdir -p roles tasks releases
command -v claude git

Expected output (paths will differ):

/usr/local/bin/claude
/usr/bin/git

An empty git status --short is the important line — it proves no uncommitted work will be mixed into the agent diff.

Step 1. Define 12 model-agnostic roles

Illustration: Step 1. Define 12 model-agnostic roles
Illustration: Step 1. Define 12 model-agnostic roles

What to do: create one markdown file per role in roles/, each with a short frontmatter block describing what it reads, what it writes, and when it is done. Do not put a model name in the file.

Why: this is the single design decision behind the "8 model versions, zero role rewrites" result. A role describes *responsibility and output format*; the model is a per-run setting. When a model is replaced, you change one line in the run config, not 12 files.

Example: roles/implementer.md

---
id: implementer
reads:  [tasks/TASK-014.md, roles/architect.md, src/**]
writes: [src/**, tests/**]
done_when:
  - "npm test exits 0"
  - "no file created outside src/ and tests/"
output_format: "unified diff + one-line summary"
---
Write the smallest change that satisfies every acceptance criterion
in the task file. Do not refactor unrelated code. Do not edit RELEASES.md.

The post reports 12 roles but does not publish the list, so use the grouping below as a template and map your own names onto it. Keep the count at 12 or adjust it — what matters is that every role has disjoint write paths.

Role groupExample roleReadsWrites
Planning`architect``tasks/*.md``plan.md`
Implementation`implementer``plan.md`, `src/**``src/**`, `tests/**`
Verification`reviewer`, `tester``src/**`, `tests/**``review.md`
Coordination`lead``tasks/*.md`, all role filesrouting decisions only
Release`release-manager``review.md`, `RELEASES.md``RELEASES.md`, git tag

Two roles writing to the same path is the most common reason a run produces a diff you cannot review. Keep the writes lists disjoint.

Before you hand file access to agents, read AI agent security: protecting your data during automation — the permission scoping there applies directly to src/** write access.

How to check:

ls roles | wc -l
head -6 roles/implementer.md

Expected: 12 on the first line, then the frontmatter block starting with --- and id: implementer. If the count is not 12, ls roles shows which file is missing or duplicated.

Step 2. Write the task contract and run the team

What to do: turn one piece of work into a file in tasks/ with three sections — scope, acceptance criteria, and touched paths. Then start a run from the repo root.

Why: in this workflow the human only does two things: sets the task and accepts the result. The task file is therefore the entire interface between you and the 12 agents. Vague criteria produce a diff you have to rewrite by hand.

Example: tasks/TASK-014.md

# TASK-014 — Retry failed billing webhook deliveries

## Scope
- src/webhooks/billing.ts
- tests/webhooks/billing.test.ts

## Acceptance criteria
- [ ] a failed delivery is retried 3 times with exponential backoff
- [ ] retry attempts are logged with the delivery id
- [ ] existing test suite still passes
- [ ] no new runtime dependency added

Start the run. First confirm which non-interactive flags your build exposes:

claude --help | grep -i -E 'print|agent|task'

Expected: one or more lines naming the flags for your version. If nothing matches, open a normal interactive session from the repo root and paste the task file — the rest of this guide is unchanged.

cd ~/projects/billing-service
git switch -c task/TASK-014
claude --print "$(cat tasks/TASK-014.md)" 2>&1 | tee releases/TASK-014.log

How to check:

git status --short
tail -20 releases/TASK-014.log

Expected: only paths listed under Scope appear in git status, and the log ends with the implementer's one-line summary plus a test result. Any file outside the declared scope means a role's writes list is too wide — fix it before the next run.

Step 3. Gate the release and tag it

Illustration: Step 3. Gate the release and tag it
Illustration: Step 3. Gate the release and tag it

What to do: run the verification gate, review the diff, then write the release row and tag the commit.

Why: the source workflow logged 44 releases in six months. At that cadence a manual checklist gets skipped within a week, so the gate has to be a command you can run in one line and a checklist you can scan in five seconds.

Example — the gate:

npm test --silent
git diff --stat main

Expected screen output (your test counts will differ):

# tests 42
# pass 42
# fail 0

The git diff --stat line should list only files from the task's Scope section.

Release checklist:

- [ ] `npm test` exits 0
- [ ] `git status --short` shows changes only in declared paths
- [ ] reviewer output contains the acceptance-criteria block, all boxes ticked
- [ ] `RELEASES.md` has a new row: task ID, date, short commit hash
- [ ] `git tag` created and pushed
git commit -am "TASK-014: retry billing webhook deliveries"
git tag -a v1.14.0 -m "TASK-014 billing webhook retry"
git push origin main v1.14.0

If your releases also ship a mobile build, the store submission half of this step is covered in How to Automate App Publishing to App Store and Google Play with AI Agents.

How to check:

git tag --list 'v*' | tail -3
git log --oneline -1

Expected: your new tag on top of the list, and the commit subject starting with TASK-014. If the tag is missing, the git tag line exited non-zero — usually because the message contained a character the shell expanded.

Troubleshooting

Problem. The CLI is not found after installation

Problem. The run starts but the agents refuse to touch the project

Problem. A role file is missing mid-run

Summary and next steps

You now have a 12-role team defined by write-scoped contracts, a task file format that a single run can consume, and a release gate that produces a tag and a RELEASES.md row. The next improvements are tightening the writes lists until git status is predictable, and automating the checklist as a pre-push hook.

FAQ

How many agents should a Claude Code Agent Team have?

The workflow described here runs 12 roles. That number is a design choice, not a limit — what matters is that each role has a distinct, non-overlapping set of files it may write.

Does the team need one specific model?

No. The roles are deliberately model-agnostic: the model is set per run, not per role file. That is how the same 12 roles survived 8 model versions without being rewritten.

How much does this cost?

The source material does not publish pricing or token figures. Check the official Claude Code pricing documentation for your plan before running long unattended sessions.

Can one developer really ship at this cadence?

In the described setup, yes: 44 releases over six months, with one person setting tasks and accepting results while the agents write the code. The constraint is review discipline, not headcount.

🤖 AI summary

Related posts

Related guides

ChatGPT, Claude, Gemini, DeepSeek: AI assistant comparison

Прямое сравнение популярных ИИ-ассистентов: качество ответов, цена, лимиты и для кого что лучше.

AI agent security: protecting your data during automation

Разбираем риски использования ИИ-агентов и даём практические советы по безопасной автоматизации задач.

How to Automate App Publishing to App Store and Google Play with AI Agents

Настраиваем MCP-сервер shipstores, чтобы ИИ-агент сам собирал, загружал и публиковал ваши iOS и Android приложения в сто