迭代审查
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第一阶段:计划
如果`.claude/state/plan-<branch>.md`不存在,或者`--plan-only`已通过:从对话上下文中读取票证/用户意图生成`architect`代理,并提示:“为当前任务制定实施计划。识别更改的表面、风险和最小连贯范围。以Markdown格式输出,其中包含以下部分:目标、更改、风险、超出范围。”将架构师的输出写入`.claude/state/plan-<branch>.md`
第 2 阶段:实施
根据计划进行更改。此阶段作为主代理(您)运行,而不是子代理——用户在代码落地时看到代码。自动应用`.claude/rules/`中的项目规则。边运行边运行`{{TEST_COMMAND}}`和`{{FORMAT_COMMAND}}`。如果`--review-only`,则跳过此阶段。
第 3 阶段:审核(协调员)
生成`review-coordinator`代理:协调器处理所有子代理编排 - 不要通过此技能生成单独的审阅者。
第四阶段:表面结论和下一步行动
阅读协调员的报告。向用户显示:使用的层和代理(以便他们知道检查了什么) 按严重性分组的结果(针对尼特折叠) 判决(批准/批准_WITH_NOTES/请求更改/需要讨论) 建议的下一步操作:
第五阶段:迭代
当用户进行更改后再次运行`/iterative-review`时:协调器读取之前的`review-state-<branch>.json`不再重现的结果→标记为`fixed`,显示在“已解决”部分结果仍然存在→结转修复引入的新问题→标记为新问题
# Iterative Review — The Feedback Loop
A sustained plan/code/review/re-code cycle on the current branch. Each pass:
1. Plans (or replans) the change
2. Implements the plan
3. Spawns `review-coordinator` to synthesize parallel reviewer findings
4. Persists findings to `.claude/state/review-state-<branch>.json` (append-only)
5. On the next pass, the coordinator sees prior findings and tracks fixed/unfixed/won't-fix
This is the framework's primary inner loop for non-trivial work. Use `/team review` for one-shot reviews; use `/iterative-review` when you expect multiple iterations.
## Usage
```
/iterative-review — start or continue the loop on the current branch
/iterative-review --plan-only — produce/refresh the plan; do not implement or review
/iterative-review --review-only — skip planning + coding; just spawn coordinator
/iterative-review --reset — discard state for this branch and start fresh
/iterative-review --override [reason] — break glass; force APPROVE without review (tracked)
```
**Break-glass override.** For hotfixes when a real review would block a critical merge, `--override` tells `review-coordinator` to skip Steps 2–6, write a single APPROVE iteration to state with `"override": "break-glass"`, and exit. The override is tracked in `review-state-<branch>.json` for retrospective analysis. The next iteration without `--override` runs the full review normally.
Equivalent: a comment containing `break glass` in the user's prompt to the skill triggers the same path. Use sparingly; review-coordinator's verdict rubric already biases toward APPROVE for legitimate cases.
## State Files
All state lives in `.claude/state/` (gitignored). Per branch:
| File | Purpose | Lifecycle |
|------|---------|-----------|
| `plan-<branch>.md` | The current implementation plan | Rewritten on `--plan-only` |
| `review-context-<branch>.md` | Shared context every sub-reviewer reads | Rewritten by coordinator each iteration |
| `review-state-<branch>.json` | Append-only findings history | Coordinator appends, never rewrites |
Branch names with `/` are sanitized to `-` for filenames (e.g., `feature/auth` → `feature-auth`).
## Process
### Phase 1: Plan
If `.claude/state/plan-<branch>.md` doesn't exist, or `--plan-only` was passed:
1. Read the ticket / user intent from the conversation context
2. Spawn the `architect` agent with prompt: "Produce an implementation plan for the current task. Identify changed surfaces, risks, and the minimum coherent scope. Output in markdown with sections: Goal, Changes, Risks, Out-of-scope."
3. Write architect's output to `.claude/state/plan-<branch>.md`
4. Show the plan to the user. If `--plan-only`, exit here.
If the plan exists and `--plan-only` was not passed, read and reuse it. The plan stays stable across iterations unless the user explicitly refreshes.
### Phase 2: Implement
Make the changes per the plan. This phase runs as the main agent (you), not a sub-agent — the user sees code as it lands.
Apply project rules from `.claude/rules/` automatically. Run `{{TEST_COMMAND}}` and `{{FORMAT_COMMAND}}` as you go.
If `--review-only`, skip this phase.
### Phase 3: Review (Coordinator)
Spawn the `review-coordinator` agent:
```
Spawn review-coordinator on the current branch. It will:
- classify the diff into trivial/lite/full
- select sub-reviewers
- spawn them in parallel
- read prior state from .claude/state/review-state-<branch>.json
- merge, dedup, filter their findings
- append to state and render the consolidated report
```
The coordinator handles all sub-agent orchestration — do not spawn individual reviewers from this skill.
### Phase 4: Surface Verdict and Next Action
Read the coordinator's report. Show the user:
- **Tier and agents used** (so they know what was checked)
- **Findings grouped by severity** (collapsed for nits)
- **Verdict** (APPROVE / APPROVE_WITH_NOTES / REQUEST_CHANGES / NEEDS_DISCUSSION)
- **Suggested next action:**
- `REQUEST_CHANGES` → "Run `/iterative-review` again after addressing critical findings"
- `APPROVE_WITH_NOTES` → "Optional improvements remain; run `/iterative-review` again or proceed to commit"
- `APPROVE` → "Ready to commit"
- `NEEDS_DISCUSSION` → list the disputed findings with developer pushback
### Phase 5: Iterate
When the user runs `/iterative-review` again after making changes:
- Coordinator reads prior `review-state-<branch>.json`
- Findings that no longer reproduce → marked `fixed`, shown in "Resolved" section
- Findings still present → carried forward
- New issues introduced by the fixes → flagged as new
The state file is append-only, so iteration history is preserved (useful for PR retrospectives).
## Caching-Friendly Prompt Shape
Sub-reviewers and the coordinator are given prompts that follow this order to maximize prompt cache hit rate:
1. System rules (stable across all runs)
2. `CLAUDE.md` / `AGENTS.md` excerpts (stable across iterations on this repo)
3. `review-context-<branch>.md` (stable across all sub-agents within one iteration)
4. Prior findings state (stable per iteration)
5. Current diff or specific question (most volatile, last)
Volatile data (timestamps, current SHA, random IDs) is always at the end. Never embed `Date.now()` or similar in the static prefix.
## Marking a Finding "Won't Fix"
When the user disagrees with a finding, two ways to record it:
**Option A — In the state file** (recommended, machine-readable):
Edit `.claude/state/review-state-<branch>.json` and add to the top-level `user_decisions` map:
```json
"user_decisions": {
"src/auth.ts:42:auth-security:fail-open": {
"status": "wont_fix",
"reason": "Behind feature flag, not yet enabled in any environment"
}
}
```
**Option B — Tell the assistant in conversation**, and ask it to update the state file. The coordinator respects these on the next iteration and does not re-raise unless severity is `critical`.
## Edge Cases
| Scenario | Behavior |
|----------|----------|
| No diff against base branch | "Nothing to review" — exit without spawning agents |
| Coordinator fails | Show the partial output; user can retry |
| `.claude/state/` is in gitignore but doesn't exist | Create it; warn if `.gitignore` doesn't list `.claude/state/` |
| User switches branches mid-loop | New branch gets its own state file; old state stays put |
| Plan in `plan-<branch>.md` is stale (e.g., user pivoted) | User runs `--plan-only` to regenerate |
| State file grows large (many iterations) | Coordinator only loads the most recent iteration's findings + `user_decisions` for matching; full history is preserved but not parsed every time |
## Related
- `review-coordinator` agent — the synthesizer this skill orchestrates (`templates/agents/review-coordinator.md`)
- `docs/finding-schema.md` — finding schema every sub-reviewer emits
- `/team review` — one-shot multi-agent review without state
- `/develop` — the broader dev cycle (fetch ticket → implement → validate → PR); use `/iterative-review` *within* `/develop` for tight loops
- `/factory` — end-to-end pipeline; calls `/iterative-review` automatically when more than one review pass is expected
---
> Source: [BostonOrange/claude-code-framework](https://github.com/BostonOrange/claude-code-framework) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
用途
状态文件
第一阶段:计划
第 2 阶段:实施
第 3 阶段:审核(协调员)
文件/命令 -> review-coordinator · .claude/state/review-state-<branch>.json · /team review · /iterative-review · --override · "override": "break-glass" · review-state-<branch>.json · break glass
内容校验值 -> 574f28b50c11
当前原文的自动摘译,尚未人工审校。
用途
打破玻璃覆盖。对于修补程序,当真正的审查会阻止关键合并时,
--override告诉review-coordinator跳过步骤2-6,编写一个批准迭代来用"override": "break-glass"声明,然后退出。覆盖在review-state-<branch>.json中进行跟踪以进行回顾性分析。没有--override的下一次迭代将正常运行完整审核。等效:用户技能提示中包含break glass的注释会触发相同的路径。谨慎使用;审查协调员的裁决标题已经偏向于批准合法案件。状态文件
所有状态都位于
.claude/state/(gitignored)。每个分支:文件 · 目的 · 生命周期plan-<branch>.md· 当前实施计划 · 重写于--plan-onlyreview-context-<branch>.md· 每个子审阅者读取的共享上下文 · 由协调员每次迭代重写review-state-<branch>.json· 仅追加发现历史记录 · 协调员追加,从不重写第 2 阶段:实施
根据计划进行更改。此阶段作为主代理(您)运行,而不是子代理——用户在代码落地时看到代码。自动应用
.claude/rules/中的项目规则。边运行边运行{{TEST_COMMAND}}和{{FORMAT_COMMAND}}。如果是--review-only,则跳过此阶段。