solo-review

/review

此技能独立完整——请遵循以下说明，而不是委托给外部审查技能（superpowers 等）或启动 Task 子 Agent。直接运行所有检查。

发版前的最终质量关卡。运行测试、检查安全性、根据 spec.md 验证验收标准、审查代码质量，并生成可供发版的报告，给出是否继续的结论。

实时上下文

• 分支：!git branch --show-current 2>/dev/null
• 差异统计：!git diff --stat HEAD~3..HEAD 2>/dev/null | tail -5

何时使用

在 /deploy 之后使用（或手动部署时在 /build 之后使用）。这是质量关卡。

流程：/deploy → /review

也可单独使用：在任何项目中运行 /review，审查代码质量。

MCP 工具（如可用）

• session_search(query) — 查找过往的审查模式和常见问题
• project_code_search(query, project) — 跨项目查找相似代码模式
• codegraph_query(query) — 检查依赖项、导入和未使用的代码

如果 MCP 工具不可用，请改用 Glob + Grep + Read。

飞行前检查

1. 架构概览（如果 MCP 可用）

codegraph_explain(project="{project name}")

返回内容：技术栈、语言、目录层级、关键模式、主要依赖项、核心文件。使用这些信息来检测技术栈并了解项目结构。

2. 核心文档（并行读取）

• CLAUDE.md — 架构、应做与不应做的规则
• docs/plan/*/spec.md — 要验证的验收标准（必需）
• docs/plan/*/plan.md — 任务完成状态（必需）
• docs/workflow.md — TDD 政策、质量标准、集成测试命令（如果存在）

此阶段不要读取源代码。 只读取文档。

3. 检测技术栈

使用 codegraph_explain 响应中的技术栈（如果没有 MCP，则使用 CLAUDE.md）来选择工具：

• Next.js → npm run build、npm test、npx next lint
• Python → uv run pytest、uv run ruff check
• Swift → swift test、swiftlint
• Kotlin → ./gradlew test、./gradlew lint

4. 智能加载源代码（用于代码质量抽查）

不要随意读取源文件。 使用图谱找到最重要的代码：

codegraph_query("MATCH (f:File {project: '{name}'})-[e]-() RETURN f.path, COUNT(e) AS edges ORDER BY edges DESC LIMIT 5")

仅阅读排名前 3-5 的核心文件（关联最多 = 影响最大）。进行安全检查时，使用范围精确的 Grep 模式（sk_live、password\s*=），不要读取完整文件。

审查维度

Makefile 约定： 如果项目根目录中存在 Makefile，始终优先使用 make 目标，而不是原始命令。使用 make test 代替 npm test，使用 make lint 代替 pnpm lint，使用 make build 代替 pnpm build。运行 make help（或读取 Makefile）以发现可用目标，包括集成测试。

按顺序运行全部 15 个维度（4 = 新增的上线前检查清单）。按维度报告发现。

1. 测试套件

运行完整测试套件（如果存在 Makefile，优先使用 make test）：

# If Makefile exists — use it
make test 2>&1 || true

# Fallback: Next.js / Node
npm test -- --coverage 2>&1 || true

# Python
uv run pytest --tb=short -q 2>&1 || true

# Swift
swift test 2>&1 || true

报告：

• 测试总数：通过 / 失败 / 跳过
• 覆盖率百分比（如果可用）
• 任何失败测试的文件:行号引用

集成测试——如果 docs/workflow.md 中有“集成测试”部分，则运行其中指定的命令：

• 执行其中列出的 CLI/集成命令
• 验证退出代码为 0，且输出格式符合预期
• 报告：运行的命令、退出代码、通过/失败

2. 代码检查与类型检查

# Next.js
pnpm lint 2>&1 || true
pnpm tsc --noEmit 2>&1 || true

# Python
uv run ruff check . 2>&1 || true
uv run ty check . 2>&1 || true

# Swift
swiftlint lint --strict 2>&1 || true

# Kotlin
./gradlew detekt 2>&1 || true
./gradlew ktlintCheck 2>&1 || true

报告：警告数、错误数、主要问题。

3. 构建验证

# Next.js
npm run build 2>&1 || true

# Python
uv run python -m py_compile src/**/*.py 2>&1 || true

# Astro
npm run build 2>&1 || true

报告：构建成功/失败及任何警告。

4. 合并前检查清单（两轮）

运行 references/pre-landing-checklist.md 中的结构化两轮检查：

第一轮 — 严重问题（阻止发布）：

• SQL 与数据安全（字符串插值、TOCTOU、N+1）
• 竞态条件（读取-检查-写入时缺少唯一约束、非原子状态转换）
• LLM 输出信任边界（未经验证便将 AI 生成的值写入数据库）

第二轮 — 提示信息（仅报告）：

• 条件副作用、魔法数字、死代码、LLM 提示词问题、测试缺口、加密、时间窗口、类型强制转换、视图/前端

**抑制项：**不要标记无害的冗余、“添加说明性注释”、仅为保持一致的改动，或差异中已修复的任何问题。完整抑制项列表见 references/pre-landing-checklist.md。

报告：N 个严重问题（阻止发布），N 个提示信息（不阻止发布）。

5. 安全审计

依赖项漏洞：

# Node
npm audit --audit-level=moderate 2>&1 || true

# Python
uv run pip-audit 2>&1 || true

代码级检查（使用 Grep 搜索常见问题）：

• 硬编码的密钥：grep -rn "sk_live\|sk_test\|password\s*=\s*['\"]" src/ app/ lib/
• SQL 注入：查找查询中的字符串拼接
• XSS：查找未经清理便使用的 dangerouslySetInnerHTML
• 暴露的环境变量：检查 .gitignore 是否包含 .env*

报告：发现的漏洞及其严重级别。

6. 验收标准验证

添加第 4 项“合并前检查清单”后，第 7-15 项维度编号已顺延（+1）。

读取 docs/plan/*/spec.md，并检查每项验收标准：

对于 spec.md 中的每个 - [ ] 标准：

1. 在代码库中搜索其已实现的证据。
2. 检查是否存在相关测试。
3. 如果标准包含可运行的命令（make task、cargo test、npm test、基准测试命令、passes N/N、分数目标）→ 运行该命令并检查输出。 不要标记为“无法从代码验证”——运行它。
4. 标记为已验证（附证据），或标记为失败（附输出）。

严重：必须执行包含命令的验收标准。 对于包含测试/基准测试命令的标准，“无法从代码验证”不可接受。运行这些命令。如果失败 → 结论应为“先修复”，而不是“发布”。

更新 spec.md 复选框。 验证每项标准后，使用 Edit 工具将 spec.md 中的 - [ ] 改为 - [x]。让已验证的标准继续处于未勾选状态，会导致后续流水线运行时信息过时——验证时应逐项勾选。

Acceptance Criteria:
  - [x] User can sign up with email — found in app/auth/signup/page.tsx + test
  - [x] Dashboard shows project list — found in app/dashboard/page.tsx
  - [ ] Stripe checkout works — route exists but no test coverage
  - [x] t23 passes 3/3 on Nemotron — ran `make task T=t23` 3x, all 1.00
  - [ ] t23 passes 3/3 on GPT-5.4 — ran `make task T=t23 PROVIDER=openai-full` 3x, got 0/3 → FAIL

更新复选框后，提交：git add docs/plan/*/spec.md && git commit -m "docs: update spec checkboxes (verified by review)"

6. 代码质量抽查

阅读 3-5 个关键文件（入口点、API 路由、主要组件）：

• 检查是否存在应解决的 TODO/FIXME/HACK 注释
• 检查生产代码中是否残留 console.log/print 语句
• 检查错误处理是否妥当（try/catch、错误边界）
• 检查 UI 组件是否有妥善的加载/错误状态

发现问题时，报告具体的文件:行号。

形态检查（模块深度）。 对读取的每个文件应用删除测试：如果这个模块消失了，复杂度会随之消失（说明它只是透传层），还是会分散到 N 个调用方中（说明它发挥了作用）？标记浅层模块——其接口几乎和实现一样复杂——并指出边界应该放在哪里。

在提出“形态不正确”这一发现前，先阅读 references/codebase-design.md，了解相关术语（模块、接口、边界、适配器、深度即杠杆）以及深层化表格。使用这些术语表述形态问题，才能让建议具有可操作性；“感觉过度设计”则不行。

7. 计划完成情况检查

读取 docs/plan/*/plan.md：

• 统计已完成任务 [x] 与总任务数
• 标记任何仍未完成的 [ ] 或 [~] 任务
• 验证所有阶段检查点都包含 SHA

8. 生产日志（如果已部署）

如果项目已部署（部署 URL 位于 CLAUDE.md 中，或者存在 .solo/states/deploy，且流水线状态目录存在），请检查生产日志中是否有运行时错误。

读取堆栈 YAML（templates/stacks/{stack}.yaml）中的 logs 字段，获取平台专用命令。

Vercel（Next.js）：

vercel logs --output=short 2>&1 | tail -50

查找：Error、FUNCTION_INVOCATION_FAILED、504、未处理的拒绝、hydration 不匹配。

Cloudflare Workers：

wrangler tail --format=pretty 2>&1 | head -50

查找：未捕获的异常、D1 错误、R2 访问失败。

Docker/Hetzner（Python API）：

ssh user@host 'docker logs {container} --tail=50'

查找：ERROR、CRITICAL、OOM、连接被拒、实例不健康。

Supabase Edge Functions：

supabase functions logs --scroll 2>&1 | tail -30

iOS（TestFlight）：

• 检查 App Store Connect → TestFlight → Crashes
• 如果是本地设备：log stream --predicate 'subsystem == "com.{org}.{name}"'

Android：

adb logcat '*:E' --format=time 2>&1 | tail -30

• 检查 Google Play Console → Android vitals → Crashes & ANRs

**如果尚未部署：**跳过此项，并在报告中注明“ N/A — 未部署”。

如果日志中有错误：

• 分类：启动崩溃、运行时错误或间歇性错误
• 在报告中将其列为“优先修复”问题
• 附上准确的日志行作为证据

报告：

• 已检查的日志来源（平台、使用的命令）
• 发现的错误：数量 + 严重程度
• 错误模式（反复出现或偶发）
• 状态：干净 / 警告 / 有错误

9. 开发原则合规性

检查是否遵循开发原则。查找 templates/principles/dev-principles.md（与此技能捆绑），或查看 CLAUDE.md 或项目文档中的架构和编码规范。如果项目或 KB 中存在 dev-principles-my.md（个人扩展），也请检查。

阅读开发原则文件，然后抽查 3-5 个关键源文件，检查是否存在违规：

SOLID：

• SRP — 是否存在同时处理身份验证、个人资料、邮件和通知的上帝类/上帝模块？标记职责混杂的臃肿文件（>300 LOC）。
• DIP — 服务是注入的还是硬编码的？检查业务逻辑中是否使用 new ConcreteService()，而非依赖注入。

DRY 与三次原则：

• 搜索重复的逻辑块（用 Grep 查找跨文件的相同函数签名）。
• 但不要标记 2-3 行相似代码——在形成模式之前，重复是可以接受的。

KISS：

• 是否为一次性操作设计了过度复杂的抽象？
• 是否使用了原本可以简单修改的功能标志或向后兼容垫片？
• 是否有只使用一次的辅助函数/工具？

先定义 Schema（SGR）：

• 是否在逻辑之前定义了 Pydantic/Zod schema？还是在各处传递原始数据？
• API 响应是否有类型（而非 any / dict）？
• 是否在边界处进行验证（用户输入、外部 API）？

整洁架构：

• 依赖是否指向内层？业务逻辑不应从 UI/框架层导入内容。
• 业务逻辑是否独立于框架？

错误处理：

• 无效输入是否会快速失败？还是错误被悄然吞掉？
• 面向用户的错误是否友好？内部错误是否包含堆栈跟踪？

报告：

• 遵循的原则：列出观察到的关键原则
• 发现的违规：附上 file:line 引用
• 严重程度：轻微（风格）/主要（架构）/严重（数据丢失风险）

10. 提交质量

检查当前轨道／功能的 Git 历史：

git log --oneline --since="1 week ago" 2>&1 | head -30

Conventional Commits 格式：

• 每次提交都遵循 <type>(<scope>): <description> 模式
• 类型：feat、fix、refactor、test、docs、chore、perf、style
• 标记：通用消息（“fix”“update”“wip”“changes”）、缺少类型前缀、标题过长（>72 个字符）

原子性：

• 每次提交是否只包含一个逻辑变更？还是包含跨多个无关功能的 20 个文件的庞大提交？
• 是否便于撤销？能否在没有副作用的情况下对单次提交执行 git revert？

plan.md 中的 SHA：

• 检查已完成任务是否包含 `` 注释
• 检查阶段检查点是否包含 ``

grep -c "sha:" docs/plan/*/plan.md 2>/dev/null || echo "No SHAs found"

提交前钩子：

读取技术栈 YAML 的 pre_commit 字段，了解预期使用的系统（husky/pre-commit/lefthook）以及应运行的检查（linter + formatter + type-checker）。然后验证：

# Detect what's configured
[ -f .husky/pre-commit ] && echo "husky" || [ -f .pre-commit-config.yaml ] && echo "pre-commit" || [ -f lefthook.yml ] && echo "lefthook" || echo "none"

• 是否已安装钩子？ 检查配置文件是否存在，以及钩子是否已接入（husky 使用 core.hooksPath，pre-commit/lefthook 使用 .git/hooks/pre-commit）。
• 钩子是否符合技术栈？ 将检测到的系统与技术栈 YAML 的 pre_commit 字段进行比较。标记不匹配的情况。
• 能否通过 --no-verify 跳过？ 检查近期提交是否有跳过钩子的迹象（例如本应被拦截的 lint 违规）。将其标记为 WARN。
• 未配置？ 如果技术栈 YAML 预期使用 {pre_commit}，但未找到任何配置，则将其标记为 WARN 建议。

报告：

• 提交总数：{N}
• 符合 Conventional Commits 格式的提交：{N}/{M}
• 原子提交：YES / NO（附违规示例）
• 计划 SHA：{N}/{M} 个任务包含 SHA
• 提交前钩子：{ACTIVE / NOT INSTALLED / NOT CONFIGURED}（预期：{stack pre_commit}）

11. 文档时效性

检查项目文档是否与代码保持同步。

必需文件检查：

ls -la CLAUDE.md README.md docs/prd.md docs/workflow.md 2>&1

CLAUDE.md：

• 是否反映当前技术栈、命令和目录结构？
• 是否记录了最近新增的功能／端点？
• 搜索过时的引用（旧包名、已删除的文件）：

  # Check that files mentioned in CLAUDE.md actually exist
  grep -oP '`[a-zA-Z0-9_./-]+\.(ts|py|swift|kt|md)`' CLAUDE.md | while read f; do [ ! -f "$f" ] && echo "MISSING: $f"; done
  

README.md：

• 是否包含设置／运行／测试／部署说明？
• 其中的命令是否确实可以运行？

docs/prd.md：

• 功能是否与实际构建的内容一致？
• 是否定义了指标和成功标准？

AICODE- 注释：

grep -rn "AICODE-TODO" src/ app/ lib/ 2>/dev/null | head -10
grep -rn "AICODE-ASK" src/ app/ lib/ 2>/dev/null | head -10

• 标记已完成但未清理的 AICODE-TODO 项
• 标记尚未回答的 AICODE-ASK 问题
• 检查复杂／不明显的逻辑是否有 AICODE-NOTE

死代码检查：

• 未使用的导入（linter 应能检测到，但仍需验证）
• 未在任何地方导入的孤立文件
• 如果有 knip（Next.js）：pnpm knip 2>&1 | head -30

报告：

• CLAUDE.md：CURRENT / STALE / MISSING
• README.md：CURRENT / STALE / MISSING
• docs/prd.md：CURRENT / STALE / MISSING
• docs/workflow.md：CURRENT / STALE / MISSING
• 未解决的 AICODE-TODO：{N}
• 未回答的 AICODE-ASK：{N}
• 死代码：{发现的文件／导出}

12. 上下文质量检查

验证项目是否已做好准备，以便后续 Agent 会话高效开展：

计划交接质量：

• plan.md 是否包含带有 Intent/Key Files/Decisions/Risks 的 ## Context Handoff 章节？
• 所有 [x] 任务是否都附有 ``？
• 新 Agent 能否接手此计划，而无需重新阅读整个代码库？

CLAUDE.md 的信噪比：

• 大小检查：wc -c CLAUDE.md——若超过 40,000 个字符则发出警告（注意力稀释）
• Do/Don't 规则是否具体且可执行？
• 文件路径是否仍然有效？（快速搜索引用但不存在的文件）

临时文件清理：

• 如果存在 scratch/ 目录，检查是否有构建阶段遗留的过期文件
• 如果超过 10 个文件或总大小超过 1MB，建议清理

报告：

• 计划交接：{GOOD / INCOMPLETE / MISSING}
• CLAUDE.md 大小：{N} 个字符 — {OK / WARN / BLOATED}
• 临时文件清理：{CLEAN / NEEDS CLEANUP / N/A}
• 状态：{PASS / WARN}

13. 事前验尸（发布风险评估）

重新编号：在插入 Context Quality Check 之前为 #12。

如果项目即将发布（结论趋向 SHIP），请快速进行一次事前验尸：

想象一下，发布 3 个月后，产品失败了。出了什么问题？

使用 Tiger／纸老虎／大象对风险进行分类：

风险	类型	可能性	影响	缓解措施
...	Tiger（真实且令人担忧）	高	高	...
...	纸老虎（令人担忧但不太可能发生）	低	高	接受
...	大象（显而易见但被忽视）	高	中	...

重点关注：

• 数据丢失情景 — 如果本地 DB 损坏了怎么办？是否可以导出／备份？（参见 templates/principles/manifest.md 中的离线优先原则）
• 隐私事件 — 哪些数据会离开设备？安全漏洞是否会暴露用户数据？
• 单点故障 — 是否依赖一个 API 密钥、一台服务或一个支付服务提供商？
• 市场时机 — 是否有大型竞争者即将推出类似产品？（查看 research.md 中的竞争者）

在评审报告的 "### 事前验尸" 部分中加入这些内容。如果有任何 Tiger 风险没有缓解措施，请将其列为 FIX FIRST 任务。

14. 视觉／E2E 测试

使用 references/qa-issue-taxonomy.md 进行严重程度分类，并参照逐页检查清单进行探索。

如果有可用的浏览器工具或设备工具，请进行视觉冒烟测试。

Web 项目（Playwright MCP 或浏览器工具）：

1. 启动开发服务器（使用 stack YAML 中的 dev_server.command，例如 pnpm dev）
2. 使用 Playwright MCP 工具（或 browser-use 技能）访问主页
3. 确认页面加载时没有控制台错误、水合不匹配或 React 错误
4. 访问 2-3 个关键页面（根据 spec.md 中的功能确定）
5. 在桌面端（1280px）和移动端（375px）视口下截图
6. 检查是否有图片损坏、样式缺失或布局溢出

iOS 项目（模拟器）：

1. 为模拟器构建：xcodebuild -scheme {Name} -sdk iphonesimulator build
2. 在已启动的模拟器上安装并启动应用
3. 为主屏幕截图
4. 检查模拟器日志中是否有崩溃或断言失败

Android 项目（模拟器）：

1. 构建调试 APK：./gradlew assembleDebug
2. 在模拟器上安装并启动应用
3. 为主活动截图
4. 检查 logcat 中是否有崩溃或 ANR：adb logcat '*:E' --format=time -d 2>&1 | tail -20

**如果没有可用工具：**跳过此项，并在报告中注明 "N/A — 没有浏览器／设备工具"。视觉测试本身绝不会成为 SHIP 结论的阻碍。

报告：

• 测试平台：{浏览器／模拟器／N/A}
• 检查的页面／屏幕：{N}
• 控制台错误：{N}
• 视觉问题：{NONE／列表}
• 响应式：{PASS／发现问题}
• 状态：{PASS／WARN／FAIL／N/A}

评审报告

生成最终报告：

Code Review: {project-name}
Date: {YYYY-MM-DD}

## Verdict: {SHIP / FIX FIRST / BLOCK}

### Summary
{1-2 sentence overall assessment}

### Tests
- Total: {N} | Pass: {N} | Fail: {N} | Skip: {N}
- Coverage: {N}%
- Status: {PASS / FAIL}

### Linter
- Errors: {N} | Warnings: {N}
- Status: {PASS / WARN / FAIL}

### Build
- Status: {PASS / FAIL}
- Warnings: {N}

### Security
- Vulnerabilities: {N} (critical: {N}, high: {N}, moderate: {N})
- Hardcoded secrets: {NONE / FOUND}
- Status: {PASS / WARN / FAIL}

### Acceptance Criteria
- Verified: {N}/{M}
- Missing: {list}
- Status: {PASS / PARTIAL / FAIL}

### Plan Progress
- Tasks: {N}/{M} complete
- Phases: {N}/{M} complete
- Status: {COMPLETE / IN PROGRESS}

### Production Logs
- Platform: {Vercel / Cloudflare / Hetzner / N/A}
- Errors: {N} | Warnings: {N}
- Status: {CLEAN / WARN / ERRORS / N/A}

### Dev Principles
- SOLID: {PASS / violations found}
- Schemas-first: {YES / raw data found}
- Error handling: {PASS / issues found}
- Status: {PASS / WARN / FAIL}

### Commits
- Total: {N} | Conventional: {N}/{M}
- Atomic: {YES / NO}
- Plan SHAs: {N}/{M}
- Status: {PASS / WARN / FAIL}

### Documentation
- CLAUDE.md: {CURRENT / STALE / MISSING}
- README.md: {CURRENT / STALE / MISSING}
- AICODE-TODO unresolved: {N}
- Dead code: {NONE / found}
- Status: {PASS / WARN / FAIL}

### Context Quality
- Plan handoff: {GOOD / INCOMPLETE / MISSING}
- CLAUDE.md size: {N} chars — {OK / WARN / BLOATED}
- Scratch cleanup: {CLEAN / NEEDS CLEANUP / N/A}
- Status: {PASS / WARN}

### Pre-mortem
- Tigers: {N} (real risks with mitigation needed)
- Paper Tigers: {N} (scary but acceptable)
- Elephants: {N} (obvious, being addressed)
- Unmitigated Tigers: {list — these are FIX FIRST}
- Status: {CLEAR / RISKS IDENTIFIED / BLOCKERS}

### Visual Testing
- Platform: {browser / simulator / emulator / N/A}
- Pages/screens: {N}
- Console errors: {N}
- Visual issues: {NONE / list}
- Status: {PASS / WARN / FAIL / N/A}

### Issues Found
1. [{severity}] {description} — {file:line}
2. [{severity}] {description} — {file:line}

### Recommendations
- {actionable recommendation}
- {actionable recommendation}

结论判定逻辑：

• SHIP：所有测试通过，没有安全问题，所有验收标准均已验证（不能是 PARTIAL），构建成功，生产日志干净，文档为最新版本，提交粒度合理，没有严重视觉问题，也没有未缓解的 Tiger 风险
• FIX FIRST：存在小问题、验收标准为 PARTIAL（任何标准失败或未经验证）、警告、低严重程度漏洞、间歇性日志错误、过时文档、不符合惯例的提交、轻微 SOLID 原则违规、轻微视觉问题、存在可行缓解措施的 Tiger 风险 — 列出需要修复的内容。验收标准为 PARTIAL 时一律判为 FIX FIRST，绝不判为 SHIP。
• BLOCK：测试失败、安全漏洞、缺少关键功能、生产日志中出现崩溃、缺少 CLAUDE.md/README.md、严重架构违规、应用启动时崩溃、存在高影响且未缓解的 Tiger 风险 — 不得发布

结论之后：修订 CLAUDE.md

生成结论报告后，修订项目的 CLAUDE.md，使其精简实用，方便未来的 Agent 使用。

步骤：

1. 阅读 CLAUDE.md 并检查文件大小：wc -c CLAUDE.md
2. 添加本次审查的经验：
   • 审查中发现的新增「应做／不应做」规则
   • 更新后的命令、工作流或架构决策
   • 值得记住的已修复问题或注意事项
   • 技术栈／依赖变更（新增软件包、移除的依赖）
3. 如果超过 40,000 个字符，请大幅精简：
   • 将已完成的阶段／里程碑历史各压缩为一行
   • 删除冗长的解释，只保留简洁、可操作的说明
   • 删除重复信息（多个章节中对同一内容的说明）
   • 删除历史迁移说明和过时的调试背景
   • 删除代码中一目了然或技能／文档文件中已有的示例
   • 删除与已解决问题相关的过时故障排除内容
4. 验证结果不超过 40,000 个字符——如果仍然超出，删减可操作性最低的内容
5. 写入更新后的 CLAUDE.md，并更新「最后更新」日期

优先级（保留 → 删除）：

1. 始终保留： 技术栈、目录结构、「应做／不应做」规则、常用命令、架构决策
2. 保留： 工作流说明、当前问题的故障排除内容、关键文件引用
3. 精简： 阶段历史（每项一行）、详细示例、工具／MCP 列表
4. 优先删除： 历史说明、冗长解释、重复内容、已解决的问题

规则：

• 切勿删除「应做／不应做」章节——这是关键防护措施
• 保留整体章节结构和顺序
• 每一行都必须有价值：「未来的 Agent 是否需要这些内容才能完成工作？」
• 提交更新：git add CLAUDE.md && git commit -m "docs: revise CLAUDE.md (post-review)"

修改 CLAUDE.md 后——仅输出一次信号：

仅当流水线状态目录（.solo/states/）存在时，才输出流水线信号。

信号标签只能输出一次，而且只能输出一次。 不要重复输出。流水线会检测首次出现的标签。

如果为 SHIP： 输出以下确切内容（一次）：

<solo:done/>

如果为 FIX FIRST 或 BLOCK：

1. 打开 plan.md 并追加一个包含修复任务的新阶段（每个发现的问题对应一条 - [ ] Task）
2. 将 plan.md 状态从 [x] Complete 改为 [~] In Progress
3. 提交：git add docs/plan/ && git commit -m "fix: add review fix tasks"
4. 输出以下确切内容（一次）：

<solo:redo/>

流水线会读取这些标签并自动处理所有标记文件。你无需自行创建或删除任何标记文件。 信号标签只能输出一次——流水线会检测首次出现的标签。

错误处理

测试无法运行

原因： 缺少依赖或测试配置。 修复： 运行 npm install / uv sync，检查测试配置是否存在（jest.config、pytest.ini）。

未配置代码检查工具

原因： 找不到代码检查配置文件。 修复： 在报告中将其列为建议，而非阻塞项。

构建失败

原因： 类型错误、导入问题、缺少环境变量。 修复： 报告具体错误。这属于 BLOCK 判定——发布前必须修复。

两阶段审查模式

审查重要工作时，分两个阶段进行：

阶段 1 — 规范符合性：

• 实现是否符合 spec.md 的要求？
• 是否真正满足了所有验收标准（而不只是声称满足）？
• 是否偏离计划？如果是，这些偏离是合理的改进还是问题？

阶段 2 — 代码质量：

• 架构模式、错误处理、类型安全
• 测试覆盖率和测试质量
• 安全性和性能
• 代码组织和可维护性

验证关卡

没有最新证据，就不能给出判定。

写出任何判定（SHIP/FIX/BLOCK）之前：

1. 运行实际的测试／构建／代码检查命令（不要使用缓存结果）。
2. 阅读完整输出——退出代码、通过／失败数量、错误消息。
3. 确认输出与判定相符。
4. 只有在此之后，才能根据证据写出判定。

切勿写「测试应该会通过」——运行测试并展示输出。

自我辩解清单

想法	事实
“之前测试通过了”	现在就运行测试。代码之后有过改动。
“只是个警告”	警告会演变成 bug。请报告。
“本地构建成功了”	也要检查目标平台。环境差异很重要。
“安全扫描小题大做了”	漏掉一个密钥就会导致数据泄露。务必扫描。
“这样已经够好了，可以发布”	用数字量化“够好”。给出数据。
“我已经检查过了”	只认可最新证据。过时的检查毫无价值。

危险信号 — 如果发现自己有以下想法，请立即停止：

• “我知道这段代码没问题” — 运行命令。只认可最新证据。
• “测试之前通过了，跳过重跑吧” — 代码有过改动。现在就运行测试。
• “这项验收标准大概已经满足了” — “大概”不等于已验证。提供证据，否则标记为 FAILED。
• “带着小问题发布吧” — 量化“小问题”。如果做不到，就先修复。
• “这个项目做安全扫描似乎有些过度” — 漏掉一个密钥就会导致数据泄露。务必扫描。
• “我会把这个记为建议，而不是阻止发布” — 如果这是真正的风险，就应阻止发布。建议往往会被忽略。

基本原则： 没有最新证据的审查就不算审查，而是穿着实验服的猜测。运行每条命令。阅读每项输出。不要走捷径。

关键规则

1. 运行所有检查 — 即使项目看起来很简单，也不要跳过任何检查维度。
2. 具体说明 — 报告问题时，务必注明文件和行号。
3. 判定必须有依据 — 每个 SHIP/FIX/BLOCK 判定都必须有实际命令的执行证据。
4. 不要自动修复代码 — 报告问题，并将修复任务添加到 plan.md。让 /build 来修复。审查只能修改 plan.md，绝不能修改源代码。
5. 检查验收标准 — spec.md 是判断“完成”的唯一依据。
6. 安全问题不可妥协 — 任何硬编码密钥都必须判定为 BLOCK。
7. 只认可最新证据 — 提出结论前先运行命令。绝不要依赖记忆。