ddadmin
2d88edcf52
- Зачем:
- Скилл был привязан к Claude Code Agent Teams, в Codex приходилось
вручную комбинировать /receiving-code-review и /claude-team-review.
В реальной L4-сессии lead применял findings без верификации, что
привело к большой структурной правке на основе неверной цитаты
из upstream-issue.
- Что:
- SKILL.md: platform-agnostic спавн (Claude Code Task/Agent Teams,
Codex native subagents). Новые шаги Evaluate findings (matrix +
verification-by-type, REQUIRED SUB-SKILL на receiving-code-review)
и Apply/push-back (three-section response — applied / re-scoped /
rejected-with-reasoning). Fresh-spawn теперь operator-gated на
любой платформе. Добавлена Red Flags table.
- reviewer-prompt.md: новый briefing template с placeholders,
заменяет Claude Code-specific agent definition.
- README.md: пути установки исправлены на ~/.claude/skills/ и
~/.codex/skills/, формулировка cross-platform смягчена, секция
эксперимента переведена в английский для единого языка.
- adversarial-reviewer.md: удалён (содержимое переехало в
reviewer-prompt.md).
- .gitignore: tmp/ для локальных рабочих заметок.
- Проверка:
- Прогнать /claude-team-review на этих же изменениях в отдельной
ветке для self-review.
236 lines
8.8 KiB
Markdown
236 lines
8.8 KiB
Markdown
# Claude Team Review
|
|
|
|
Adversarial code and plan review through a peer-reviewer subagent.
|
|
|
|
One subagent reviews. The lead evaluates findings, fixes what holds up,
|
|
pushes back on what doesn't, and asks for re-review. Up to 5 rounds.
|
|
|
|
**Designed for Claude Code and Codex.** The skill is platform-agnostic
|
|
in its instructions, so it can potentially work on other hosts that
|
|
support subagents — but Claude Code and Codex are the verified targets.
|
|
|
|
## What is this
|
|
|
|
A skill that spawns an adversarial reviewer as a subagent on the host
|
|
of your choice. The reviewer reads your project, runs tests, checks
|
|
documentation, and delivers findings with a skeptical stance.
|
|
|
|
The lead (your main session) **does not blindly apply findings**. It
|
|
builds an evaluation matrix, verifies the technical claims, and replies
|
|
with applied / re-scoped / rejected-with-reasoning sections. The reviewer
|
|
gets a chance to contest the rejections in the next round.
|
|
|
|
### How it differs from [adversarial-review](https://github.com/dementev-dev/adversarial-review)
|
|
|
|
**adversarial-review** uses two different models (Claude writes, Codex
|
|
reviews) — you get cross-model blind-spot coverage and cheap re-review
|
|
via `codex exec resume`. It requires Codex CLI and an OpenAI API key.
|
|
|
|
**claude-team-review** stays inside whichever host you're using. No
|
|
external dependencies. The reviewer is a subagent with its own context
|
|
window, MCP access, and the ability to run commands. For re-review, the
|
|
lead tries continuation when the host supports it (e.g. Claude Code
|
|
Agent Teams), and otherwise spawns a fresh subagent with the previous-
|
|
rounds context block.
|
|
|
|
Use **adversarial-review** when you want maximum review quality through
|
|
model diversity. Use **claude-team-review** when you want zero external
|
|
dependencies and a richer reviewer (tests, docs, web search) running on
|
|
the same host as the lead.
|
|
|
|
## How it works
|
|
|
|
```
|
|
┌──────────┐ spawn ┌────────────┐
|
|
│ Lead │ ───────────────> │ Reviewer │
|
|
│ (code) │ │ (subagent) │
|
|
└──────────┘ └────────────┘
|
|
^ │
|
|
│ findings │
|
|
│ <────────────────────────────┘
|
|
│
|
|
│ evaluate (matrix, verify)
|
|
│ apply / re-scope / reject
|
|
v
|
|
┌──────────┐ re-review ┌────────────┐
|
|
│ Lead │ ───────────────> │ Reviewer │
|
|
│ (fixed) │ "applied A, │(same / new)│
|
|
│ │ rejected B └────────────┘
|
|
│ │ with reason" │
|
|
└──────────┘ │
|
|
VERDICT: APPROVED
|
|
```
|
|
|
|
The lead tries to **continue the same reviewer** for re-review when the
|
|
host supports it (cheaper — context is preserved). When continuation is
|
|
unavailable (Codex, or Claude Code without Agent Teams), or when the
|
|
previous reviewer is no longer reachable, the lead asks the operator
|
|
before spawning a fresh subagent — full project re-read is expensive,
|
|
and the operator may prefer to conclude the review unverified. Headless
|
|
runs without operator access conclude unverified.
|
|
|
|
### Three modes
|
|
|
|
| Mode | What it reviews | When to use |
|
|
|----------------|------------------------------------|--------------------------|
|
|
| `plan` | Implementation plan | Before writing code |
|
|
| `code` | Git diff (unstaged, staged, branch)| After writing code |
|
|
| `code-vs-plan` | Code changes against the plan | Verify implementation |
|
|
|
|
Mode is auto-detected from context, or you can force it with an argument.
|
|
|
|
### What the reviewer can do
|
|
|
|
- **Read** any file in the repository
|
|
- **Run commands** — tests, linters, type checkers, build scripts
|
|
- **Search the web** and **query documentation** via MCP (Context7)
|
|
- **Inspect git history** — blame, log, diff
|
|
|
|
The reviewer **must not** create, edit, or delete project files. The
|
|
briefing forbids it. If your host supports an enforced read-only sandbox
|
|
(Claude Code `disallowedTools`, Codex `sandbox_mode = "read-only"`), the
|
|
skill recommends applying it on top.
|
|
|
|
### What the lead does (and does NOT do)
|
|
|
|
**Does:** evaluates each finding through a verification matrix, classifies
|
|
by type (architectural / tool-mechanic / style / security), verifies its
|
|
own technical claims before publishing them, replies in a structured
|
|
applied/re-scoped/rejected-with-reasoning format.
|
|
|
|
**Does NOT:** apply findings blindly, trust cited upstream issues by
|
|
number, make confident tool-mechanic claims without empirical testing,
|
|
stay silent about rejections.
|
|
|
|
The skill explicitly invokes `superpowers:receiving-code-review` for the
|
|
evaluation step (and inlines its key principles for portability).
|
|
|
|
## Requirements
|
|
|
|
- A host that supports subagents — Claude Code or Codex
|
|
- Optional: Claude Code with Agent Teams enabled, for cheaper re-review
|
|
via continuation
|
|
|
|
No external API keys.
|
|
|
|
## Installation
|
|
|
|
### Claude Code
|
|
|
|
```bash
|
|
git clone https://github.com/dementev-dev/claude-team-review.git
|
|
cd claude-team-review
|
|
|
|
# Symlink the skill into the personal skills directory
|
|
mkdir -p ~/.claude/skills
|
|
ln -s "$(pwd)" ~/.claude/skills/claude-team-review
|
|
```
|
|
|
|
Claude Code watches `~/.claude/skills/` for changes and will pick the
|
|
skill up without a restart.
|
|
|
|
**Optional — enable Agent Teams for cheaper re-review** (continuation
|
|
between rounds instead of fresh-spawn). Add to your Claude Code settings:
|
|
|
|
```json
|
|
{
|
|
"env": {
|
|
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
|
}
|
|
}
|
|
```
|
|
|
|
The skill works fine without Agent Teams — it falls back to a fresh
|
|
subagent each round, with the previous-rounds context block packed into
|
|
the briefing.
|
|
|
|
### Codex
|
|
|
|
```bash
|
|
git clone https://github.com/dementev-dev/claude-team-review.git
|
|
cd claude-team-review
|
|
|
|
# Place the skill in the standard Codex skills directory
|
|
mkdir -p ~/.codex/skills
|
|
ln -s "$(pwd)" ~/.codex/skills/claude-team-review
|
|
```
|
|
|
|
Codex spawns subagents without context continuation across spawns. The
|
|
skill treats every re-review on Codex as an operator-gated decision —
|
|
the lead asks whether to spawn a fresh subagent (full project re-read,
|
|
expensive) or conclude without verification. Continuation can be added
|
|
later if Codex grows that feature.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Auto-detect what to review
|
|
/claude-team-review
|
|
|
|
# Review a plan
|
|
/claude-team-review plan
|
|
|
|
# Review code changes
|
|
/claude-team-review code
|
|
|
|
# Review a specific file
|
|
/claude-team-review path/to/plan.md
|
|
|
|
# Use maximum reasoning effort for the reviewer
|
|
/claude-team-review xhigh
|
|
```
|
|
|
|
## Files in this skill
|
|
|
|
- `SKILL.md` — workflow and rules
|
|
- `reviewer-prompt.md` — briefing template with placeholders (filled and
|
|
passed as the subagent's prompt at spawn time)
|
|
- `README.md` — this file
|
|
- `EXPERIMENT.md` — comparative experiment notes (Opus vs GPT reviewer)
|
|
|
|
## Reviewer behavior
|
|
|
|
The reviewer uses an adversarial stance — it defaults to skepticism and
|
|
tries to break confidence in the change. Each finding must answer:
|
|
|
|
1. **What can go wrong?** — concrete scenario
|
|
2. **Why vulnerable?** — cite specific location
|
|
3. **Impact** — what breaks and how badly
|
|
4. **Recommendation** — specific fix
|
|
|
|
The reviewer verifies findings by running tests, checking documentation,
|
|
and inspecting related code before reporting.
|
|
|
|
## Roadmap
|
|
|
|
- [ ] Real-world testing of the cross-platform spawn path on Codex
|
|
- [ ] Parallel multi-reviewer mode (security + performance + correctness)
|
|
— Codex has a native pattern for this; the skill is ready to adopt
|
|
- [ ] Persistent reviewer memory across sessions
|
|
- [ ] Integration with CI (GitHub Actions)
|
|
- [ ] Comparison benchmarks: Codex backend vs Team backend
|
|
|
|
## Experiment: comparing reviewers
|
|
|
|
We ran both reviewers (Opus and GPT-5.4) on the same plan and compared
|
|
their findings. The key takeaway: the two models review from
|
|
fundamentally different paradigms — Opus as an architect ("will this
|
|
design work?"), Codex as a security/ops engineer ("what will break in
|
|
production?"). Zero complete overlaps, roughly 30% partial overlaps.
|
|
|
|
Details (in Russian): [EXPERIMENT.md](EXPERIMENT.md) — full experiment
|
|
write-up, all findings, overlap analysis, conclusions.
|
|
|
|
## Related
|
|
|
|
- [adversarial-review](https://github.com/dementev-dev/adversarial-review) —
|
|
cross-model variant using Codex CLI as the reviewer backend
|
|
- [Claude Code Agent Teams docs](https://code.claude.com/docs/en/agent-teams) —
|
|
official documentation on Agent Teams
|
|
- [Codex Subagents docs](https://developers.openai.com/codex/subagents) —
|
|
official documentation on Codex subagents
|
|
|
|
## License
|
|
|
|
Apache-2.0 — see [LICENSE](LICENSE).
|