version 1 · March 2026The system has since been rewritten: five agents became four roles, parallelism was dropped, and everything project-specific moved into a profile. This page is kept as it was — the new article links back to it.

// multi-agent-qa

A multi-agent QA system on Claude Code

One /qa command runs the full test cycle: from task analysis to a finished autotest, a TMS test case, and a final report. No questions, no pauses, no manual intervention.

1

command in

5

agents in the system

15–30

minutes per cycle

1–2

questions up front

// architecture

Architecture: one coordinator, four executors

The core idea is separation of concerns. Each agent does one thing well. The user types /qa <link or description>, and the pipeline takes it from there.

/qa <task link or description>

↓

👔QA Manager — accepts the task, thinks, delegates

↓ parallel launch

🌐Web TesterUI in the browser

🔌API Testercurl, scripts

⚙️QA AutomatorJava autotest

🏃Test Runnerruns, logs

↑ by results

All results flow back to the manager → final report.

// agents

What each agent does

Every agent is a separate context, a separate toolbox, and a separate area of responsibility.

👔QA Manager

Coordinates, does NOT execute. Accepts the task, builds a plan, delegates, gathers results, writes the report.→ Agent tool, file system

🔌API Tester

Manual API testing. Hits endpoints, checks status codes, response bodies, and business logic.→ curl, bash, scripts

🌐Web Tester

UI testing in a real browser. Walks through scenarios, catches regressions, takes screenshots.→ browser automation (MCP)

⚙️QA Automator

Writes a Java autotest based on the real manual run. Compiles, runs, fixes.→ code read/edit, mvn

🏃Test Runner

Runs tests, fetches logs, analyzes failures. Hands the manager facts, not guesses.→ mvn, Grafana Loki

// why

Why the coordinator does nothing itself

This is a critical architectural decision. QA Manager is forbidden to run curl, open the browser, or write code. Its job is to think, delegate, and aggregate results.

01The context window is finite. If the manager starts running curl itself, it quickly forgets the big picture.

02Parallelism. The manager launches Web Tester and API Tester simultaneously — each in its own context.

03Decision quality. The manager focuses on business logic: what to test, why, which scenarios matter most.

«It's like a CEO going down to the warehouse to carry boxes. Helpful in a way — but who's running the company?»

// technical

How it works under the hood

Five mechanisms hold the whole system together.

Slash commands as entry points

Claude Code supports slash commands — markdown files in .claude/commands/ that become commands. The user types /qa <link>, and Claude Code loads the instruction.A slash command is a prompt that launches the coordinator. $ARGUMENTS inserts whatever the user typed after /qa.

.claude/commands/ # entry points qa.md # /qa — launch QA Manager test.md # /test — run tests qase.md # /qase — work with TMS .claude/agents/ # agent instructions qa-manager.md # coordinator api-tester.md # API web-tester.md # UI qa-automator.md # automation

Agent instructions are markdown files

Each agent receives a detailed instruction from its own .md file. This isn't a hint — it's a full behavioral spec.A good agent file contains: a workflow (numbered steps), I/O formats (which files to read, which to create), autonomy rules (what to do without asking, when to stop), error handling (404, 500, timeouts), and examples (concrete commands, file templates).The more detailed the instruction, the more autonomous the agent. Don't rely on LLM common sense — describe the behavior explicitly. Otherwise the agent will go off the rails with a clean conscience.

File-based exchange between agents

Agents run in separate contexts and don't see each other directly. Communication goes through the file system — a shared session folder.Task files (task-*.md) are created by the manager. Result files (result-*.md) are created by the executors. The manager reads them and assembles the final report.The file system is the data bus between agents. Markdown is the contract format. Simple and reliable.

.claude/test-sessions/2026-03-11_feature-name/ manager-plan.md # manager's plan task-api.md # task for API Tester task-web.md # task for Web Tester task-automator.md # task for QA Automator discoveries.md # real-time finding exchange result-api.md # API results result-web.md # UI results result-automator.md # automation results agent-api-completed # flag: API Tester finished agent-web-completed # flag: Web Tester finished report.md # final report

Parallelism and synchronization

Web Tester and API Tester run at the same time. It's not pseudo-parallelism — they're literally launched in one message: Web Tester in the background (run_in_background), API Tester in the main thread.But parallelism creates a problem: what if one agent is stuck while the other has the answer? The fix is discoveries.md. Every agent periodically reads it and appends its findings.If an agent is blocked (404, 403), it enters a wait mode and checks discoveries every minute for new info from the parallel agent. Completion flags (agent-*-completed) are empty files. The blocked agent sees the flag and knows there's nothing more to wait for.

🌐 Web Tester: Frontend hits /api/v2/endpoint, not /api/v1 🔌 API Tester: Got it, switching to v2. Endpoint needs X-Custom-Header — check the frontend. 🌐 Web Tester: Header is being sent. Confirmed.

Pipeline: API Tester → QA Automator

After manual testing, API Tester creates an automation task with verified endpoints, request/response samples, and the main business scenario.QA Automator gets the task and: writes a test method into the existing class, compiles and runs it, fixes failures (up to 5 retries), and on success marks it @Disabled("WIP").Key principle: the autotest is written from a real manual run, not from documentation. The automator knows the endpoint actually works and what response to expect. None of the "well, I assumed it should be 200" stuff.

// principles

Principles we ended up with

Five rules, without which the pipeline falls apart.

01Full executor autonomy

Executors never ask the user questions. They act, fail, recover — but they don't stop. Only the coordinator asks questions, and only at the very start.→ Every question is a pause of minutes or hours. One question from an agent = the whole pipeline freezes.

02The coordinator doesn't execute

The manager thinks and delegates. Period.→ Context is finite. The manager's context should be about the big picture, not curl commands.

03Test the effect, not CRUD

Checking "create-read-delete" isn't enough. The autotest must check business impact: after action X, did result Y actually change.→ This rule is baked into every agent's instruction — otherwise they generate trivial CRUD tests and call it done.

04Write results incrementally

Web Tester works in a browser — every screenshot eats context. Buffering results until the end runs out of context first. Solution: write each result immediately.→ Even if the agent gets cut off, results are already on disk.

05The autotest mirrors reality

If the feature is broken (500, DB error), the autotest must fail rather than paper over the problem with soft assertions. Once infra is fixed, the test will pass.→ It's an honest signal, not a green check for self-soothing.

// how-to

How to do this yourself

Six steps to assemble a similar system on any project.

01Define the agentsWhich roles participate in your process? Who analyzes? Who tests the API? UI? Who writes autotests? Each role is a separate agent.

02Write the instructionsFor each agent: .claude/agents/{role}.md with a workflow, I/O format, error handling, and examples.

03Create a slash command.claude/commands/qa.md as the entry point into the pipeline. One prompt launches the whole system.

04Define the file protocolWhich files the coordinator creates, which the executors create, how they exchange findings. Markdown as the contract format.

05Set up CLAUDE.mdShared knowledge: project structure, environments, auth, scripts. So every agent doesn't start from zero.

06Move boilerplate into scripts.claude/scripts/. Agents shouldn't memorize long commands. A script is a contract: call it with simple args, get the result.

// outcome

What we ended up with

One /qa command runs the whole pipeline:

✓Task analysis and scope clarification

✓Parallel API + UI testing

✓Real-time finding exchange between agents

✓Writing and debugging the autotest

✓Creating a test case in the TMS

✓Updating the project knowledge base

✓Final report

The whole cycle — 15–30 minutes. Manual involvement — answering 1–2 questions at the start.

// 4 months later

Numbers, evolution, what surprised me

Above — how the system works. Below — four months of real data from docs/test-sessions/, no spin. Where it grew, where it got harder.

10×

growth in 2 months

~2,900

lines of instructions

85%

sessions with discoveries.md

0.55

open questions per report

// metrics

Month-by-month dynamics

All numbers are real /qa sessions with a manager plan and at least one executor.

Session volume grew 10×

Not because there's more work — the launch threshold dropped. /qa moved from "when I have energy to figure it out" to a routine: copy the link, hit enter, read the report 30 minutes later.

January

2 sessions

February

2 sessions

March

14 sessions

April

20 sessions

Sessions became more complex

Average files per session folder — a proxy for complexity. From "check this endpoint" to "run a full E2E with artifacts on every step so you can compare on retest".

January

6.5 files

February

9.0 files

March

10.6 files

April

19.6 files

Multi-round retests appeared

Share of sessions with round 2/3+. Not a drop in first-pass quality — the system learned to follow through: discoveries.md → wait for the fix → new manager plan → compare with the previous round.

January

0 %

February

0 %

March

7 %

April

20 %

Cross-agent communication scaled an order of magnitude

Average lines in discoveries.md per session. Web Tester and API Tester run in parallel and don't see each other directly — the shared file compensates.

January

0 lines

February

68 lines

March

17 lines

April

76 lines

// April: peak session

162 files, 5 rounds, 5 MB of artifacts

Fix verification on a complex financial task. Each round after deploy we re-captured state, reports, logs — and compared with the previous one. Manually, it would've been three full work days. With agents — six iterations in a week, in the background, with a detailed audit of every pass.

// discoveries.md in action«Web Tester, digging through frontend JS, noticed the frontend was sending a parameter in a format that didn't match the docs. Wrote it to discoveries. API Tester, reading the file every minute, saw the entry, switched format — and discovered the backend was ignoring that format. Without discoveries.md, API Tester would've gone into a dead end with the right endpoint and the wrong parameter.»

// prompts

Prompts evolve: 2,900+ lines of instructions

Every edit is the story of an error that shouldn't happen again. Last month — about +15% growth, mostly rephrasings and clarifications, not new sections. The skeleton has stabilized.

filerolelinessize

qa-manager.mdcoordinator66756 KB

qa-automator.mdautomation94143 KB

api-tester.mdAPI67630 KB

web-tester.mdUI60530 KB

Total: ~2,900 lines, 159 KB

// reports

Report quality: barely any open questions

April's final reports averaged 0.55 "open questions" each. Agents follow through: instead of "couldn't check, no data" — they go and create data via curl. Instead of "UI didn't open" — they debug the MCP browser to victory or open the file via JS. In parallel, detail grew: a typical April report is 170+ rows of scenario tables (January was 120 lines of general prose with severity tagged on each bug).

// time

How long one /qa session actually takes

Median active phase by file timestamps: March — 13 minutes, April — 50 minutes. A paradox: April is slower than March. Simple explanation — in March /qa was launched mostly on simple single-round tasks, in April — on complex multi-round scenarios. The hardest April sessions are 2–3 work days of QA in manual mode. With agents — 167 hours in the background (6 rounds, one calendar week), with about an hour of human time total. Just to read the report and say "ship it".

// surprises

What surprised me

Agents don't ask questions

We pinned the rule in the prompt — and agents listened. Across April: zero cases where an executor sent a question to chat. Only the coordinator asks, only at the very start, and even then rarely.

discoveries.md emerged on its own

I didn't design this pattern from day one — it appeared after two agents wasted time in parallel twice in a row. Now it's a central piece.

Prompt size ≠ quality

The biggest prompt belongs to the automator — and it screws up more than the others. Lighter tester prompts are more stable. It's not size, it's clarity of responsibility boundaries.

The manager still wants to do it itself

Despite five repetitions in the prompt that it can't run curl. It's the human-like behavior of the model — wanting to help directly instead of delegating. The cure is repeating the rules.

If you want to try this yourself

The first two months will look bad on paper. Sessions will fall apart, agents will ask questions, reports will come out incomplete. That's normal — every such error is a line in the prompt that wasn't there before. After a month or two the numbers start to right themselves, and you'll realize you've moved into a different mode of working.And the main thing — don't try to build one super-agent with one mega-prompt. I tried. It doesn't work on hard tasks. What works is separation of responsibility and contracts between agents through files. Boring architecture. But the numbers are higher.

// takeaway

Architecture beats one clever prompt

The main lesson: an agent system is not a single clever prompt — it's an architecture of specialized agents with clear contracts between them. The file system as a data bus, markdown as the contract format, slash commands as the entry points.And yes — agents mess up. So do humans. But unlike humans, you can rewrite their brain in 10 minutes and restart.

// discuss a rolloutHappy to help design or embed a multi-agent QA pipeline into your process — from picking agents to file protocols and CI/CD.

Message on Telegram