solo-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/review

This skill is self-contained — follow the instructions below instead of delegating to external review skills (superpowers, etc.) or spawning Task subagents. Run all checks directly.

Final quality gate before shipping. Runs tests, checks security, verifies acceptance criteria from spec.md, audits code quality, and generates a ship-ready report with go/no-go verdict.

本Skill是独立的——请遵循以下说明操作，不要委托给外部审查Skill（如超级能力等）或生成Task子Agent。直接运行所有检查。

发布前的最终质量门禁。运行测试、检查安全性、验证spec.md中的验收标准、审计代码质量，并生成包含是否可发布结论的就绪报告。

When to use

适用场景

After

/deploy

(or

/build

if deploying manually). This is the quality gate.

Pipeline:

/deploy

→ /review

Can also be used standalone:

/review

on any project to audit code quality.

在/deploy之后（若手动发布则在/build之后）使用，这是质量检查环节。

流水线：/deploy → /review

也可独立使用：对任意项目执行/review以审计代码质量。

MCP Tools (use if available)

MCP工具（如有则使用）

```
session_search(query)
```
— find past review patterns and common issues
```
project_code_search(query, project)
```
— find similar code patterns across projects
```
codegraph_query(query)
```
— check dependencies, imports, unused code

If MCP tools are not available, fall back to Glob + Grep + Read.

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

若MCP工具不可用，则退回到Glob + Grep + Read方式。

Pre-flight Checks

预检检查

1. Architecture overview (if MCP available)

1. 架构概览（若MCP可用）

codegraph_explain(project="{project name}")

Returns: stack, languages, directory layers, key patterns, top dependencies, hub files. Use this to detect stack and understand project structure.

codegraph_explain(project="{project name}")

返回内容：技术栈、编程语言、目录层级、核心模式、主要依赖、枢纽文件。利用此信息检测技术栈并理解项目结构。

2. Essential docs (parallel reads)

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

```
CLAUDE.md
```
— architecture, Do/Don't rules
```
docs/plan/*/spec.md
```
— acceptance criteria to verify (REQUIRED)
```
docs/plan/*/plan.md
```
— task completion status (REQUIRED)
```
docs/workflow.md
```
— TDD policy, quality standards, integration testing commands (if exists)

Do NOT read source code at this stage. Only docs.

```
CLAUDE.md
```
— 架构、Do/Don't规则
```
docs/plan/*/spec.md
```
— 待验证的验收标准（必填）
```
docs/plan/*/plan.md
```
— 任务完成状态（必填）
```
docs/workflow.md
```
— TDD策略、质量标准、集成测试命令（若存在）

此阶段请勿读取源代码，仅读取文档。

3. Detect stack

3. 检测技术栈

Use stack from

codegraph_explain

response (or

CLAUDE.md

if no MCP) to choose tools:

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
```

使用

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. Smart source code loading (for code quality spot check)

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

Do NOT read random source files. Use the graph to find the most important code:

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

Read only the top 3-5 hub files (most connected = most impactful). For security checks, use Grep with narrow patterns (

sk_live

password\s*=

) — not full file reads.

请勿随机读取源文件，利用代码图查找最重要的代码：

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*=

）——不要读取完整文件。

Review Dimensions

审查维度

Makefile convention: If

Makefile

exists in project root, always prefer
make
targets over raw commands. Use

make test

instead of

npm test

make lint

instead of

pnpm lint

make build

instead of

pnpm build

. Run

make help

(or read Makefile) to discover available targets including integration tests.

Run all 12 dimensions in sequence. Report findings per dimension.

Makefile约定：若项目根目录存在

Makefile

，优先使用
make
命令而非原生命令。用

make test

替代

npm test

，

make lint

替代

pnpm lint

，

make build

替代

pnpm build

。执行

make help

（或读取Makefile）以发现可用命令，包括集成测试。

按顺序运行全部12个维度，按维度报告发现的问题。

1. Test Suite

1. 测试套件

Run the full test suite (prefer

make test

if Makefile exists):

bash

undefined

运行完整测试套件（若存在Makefile则优先使用

make test

）：

bash

undefined

If Makefile exists — use it

若存在Makefile——使用它

make test 2>&1 || true

Fallback: Next.js / Node

备选：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


Report:
- Total tests: pass / fail / skip
- Coverage percentage (if available)
- Any failing tests with file:line references

**Integration tests** — if `docs/workflow.md` has an "Integration Testing" section, run the specified commands:
- Execute the CLI/integration commands listed there
- Verify exit code 0 and expected output format
- Report: command run, exit code, pass/fail

swift test 2>&1 || true


报告内容：
- 测试总数：通过/失败/跳过
- 覆盖率百分比（若可用）
- 失败测试的文件:行号引用

**集成测试**——若`docs/workflow.md`包含“Integration Testing”章节，运行指定命令：
- 执行列出的CLI/集成命令
- 验证退出码为0且输出格式符合预期
- 报告：执行的命令、退出码、通过/失败

2. Linter & Type Check

2. 代码规范检查与类型校验

bash

undefined

bash

undefined

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


Report: warnings count, errors count, top issues.

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


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

3. Build Verification

3. 构建验证

bash

undefined

bash

undefined

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


Report: build success/failure, any warnings.

npm run build 2>&1 || true


报告：构建成功/失败、所有警告。

4. Security Audit

4. 安全审计

Dependency vulnerabilities:

bash

undefined

依赖漏洞检查：

bash

undefined

Node

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

Python

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


**Code-level checks** (Grep for common issues):
- Hardcoded secrets: `grep -rn "sk_live\|sk_test\|password\s*=\s*['\"]" src/ app/ lib/`
- SQL injection: look for string concatenation in queries
- XSS: look for `dangerouslySetInnerHTML` without sanitization
- Exposed env vars: check `.gitignore` includes `.env*`

Report: vulnerabilities found, severity levels.

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*`

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

5. Acceptance Criteria Verification

5. 验收标准验证

Read

docs/plan/*/spec.md

and check each acceptance criterion:

For each

- [ ]

criterion in spec.md:

Search codebase for evidence it was implemented.
Check if related tests exist.
Mark as verified or flag as missing.

Update spec.md checkboxes. After verifying each criterion, use Edit tool to change

- [ ]

- [x]

in spec.md. Leaving verified criteria unchecked causes staleness across pipeline runs — check them off as you go.

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

After updating checkboxes, commit:

git add docs/plan/*/spec.md && git commit -m "docs: update spec checkboxes (verified by review)"

读取

docs/plan/*/spec.md

并检查每条验收标准：

对于spec.md中的每条

- [ ]

标准：

在代码库中查找已实现的证据。
检查是否存在相关测试。
标记为已验证或标记为缺失。

更新spec.md复选框。验证每条标准后，使用编辑工具将spec.md中的

- [ ]

改为

- [x]

。已验证的标准若未勾选会导致流水线运行时信息过时——请逐一勾选。

验收标准：
  - [x] 用户可通过邮箱注册——在app/auth/signup/page.tsx及测试中找到实现
  - [x] 仪表板显示项目列表——在app/dashboard/page.tsx中找到实现
  - [ ] Stripe结账功能可用——路由存在但无测试覆盖

更新复选框后提交：

git add docs/plan/*/spec.md && git commit -m "docs: update spec checkboxes (verified by review)"

6. Code Quality Spot Check

6. 代码质量抽查

Read 3-5 key files (entry points, API routes, main components):

Check for TODO/FIXME/HACK comments that should be resolved
Check for console.log/print statements left in production code
Check for proper error handling (try/catch, error boundaries)
Check for proper loading/error states in UI components

Report specific file:line references for any issues found.

读取3-5个关键文件（入口点、API路由、核心组件）：

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

报告发现的问题时需包含具体的文件:行号引用。

7. Plan Completion Check

7. 计划完成情况检查

Read

docs/plan/*/plan.md

Count completed tasks
```
[x]
```
vs total tasks
Flag any
```
[ ]
```
or
```
[~]
```
tasks still remaining
Verify all phase checkpoints have SHAs

读取

docs/plan/*/plan.md

：

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

8. Production Logs (if deployed)

8. 生产日志（若已部署）

If the project has been deployed (deploy URL in CLAUDE.md, or

.solo/states/deploy

exists if pipeline state directory is present), check production logs for runtime errors.

Read the

logs

field from the stack YAML (

templates/stacks/{stack}.yaml

) to get platform-specific commands.

Vercel (Next.js):

bash

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

Look for:

Error

FUNCTION_INVOCATION_FAILED

, unhandled rejections, hydration mismatches.

Cloudflare Workers:

bash

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

Look for: uncaught exceptions, D1 errors, R2 access failures.

Fly.io (Python API):

bash

fly logs --app {name} 2>&1 | tail -50

Look for:

ERROR

CRITICAL

, OOM, connection refused, unhealthy instances.

Supabase Edge Functions:

bash

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

iOS (TestFlight):

Check App Store Connect → TestFlight → Crashes

If local device:

log stream --predicate 'subsystem == "com.{org}.{name}"'

Android:

bash

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

Check Google Play Console → Android vitals → Crashes & ANRs

If no deploy yet: skip this dimension, note in report as "N/A — not deployed".

If logs show errors:

Classify: startup crash vs runtime error vs intermittent
Add as FIX FIRST issues in the report
Include exact log lines as evidence

Report:

Log source checked (platform, command used)
Errors found: count + severity
Error patterns (recurring vs one-off)
Status: CLEAN / WARN / ERRORS

若项目已部署（CLAUDE.md中包含部署URL，或存在流水线状态目录时

.solo/states/deploy

存在），检查生产日志中的运行时错误。

读取栈YAML文件（

templates/stacks/{stack}.yaml

）中的

logs

字段，获取平台特定命令。

Vercel（Next.js）：

bash

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

查找：

Error

、

FUNCTION_INVOCATION_FAILED

、

、未处理的拒绝、 hydration不匹配。

Cloudflare Workers：

bash

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

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

Fly.io（Python API）：

bash

fly logs --app {name} 2>&1 | tail -50

查找：

ERROR

、

CRITICAL

、OOM、连接拒绝、实例不健康。

Supabase Edge Functions：

bash

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

iOS（TestFlight）：

查看App Store Connect → TestFlight → Crashes

若为本地设备：

log stream --predicate 'subsystem == "com.{org}.{name}"'

Android：

bash

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

查看Google Play Console → Android vitals → Crashes & ANRs

若尚未部署：跳过此维度，在报告中注明“N/A — 未部署”。

若日志中存在错误：

分类：启动崩溃/运行时错误/间歇性错误
在报告中列为“FIX FIRST”问题
包含精确的日志行作为证据

报告：

检查的日志来源（平台、使用的命令）
发现的错误：数量 + 严重级别
错误模式（重复出现/单次出现）
状态：CLEAN（无异常）/ WARN（警告）/ ERRORS（错误）

9. Dev Principles Compliance

9. 开发原则合规性检查

Check adherence to dev principles. Look for

templates/principles/dev-principles.md

(bundled with this skill), or check CLAUDE.md or project docs for architecture and coding conventions.

Read the dev principles file, then spot-check 3-5 key source files for violations:

SOLID:

SRP — any god-class/god-module doing auth + profile + email + notifications? Flag bloated files (>300 LOC with mixed responsibilities).
DIP — are services injected or hardcoded? Look for
```
new ConcreteService()
```
inside business logic instead of dependency injection.

DRY vs Rule of Three:

Search for duplicated logic blocks (Grep for identical function signatures across files).
But don't flag 2-3 similar lines — duplication is OK until a pattern emerges.

KISS:

Over-engineered abstractions for one-time operations?
Feature flags or backward-compat shims where a simple change would do?
Helpers/utilities used only once?

Schemas-First (SGR):

Are Pydantic/Zod schemas defined before logic? Or is raw data passed around?
Are API responses typed (not
```
any
```
/
```
dict
```
)?
Validation at boundaries (user input, external APIs)?

Clean Architecture:

Do dependencies point inward? Business logic should not import from UI/framework layer.
Is business logic framework-independent?

Error Handling:

Fail-fast on invalid inputs? Or silent swallowing of errors?
User-facing errors are friendly? Internal errors have stack traces?

Report:

Principles followed: list key ones observed
Violations found: with file:line references
Severity: MINOR (style) / MAJOR (architecture) / CRITICAL (data loss risk)

检查是否遵循开发原则。查找

templates/principles/dev-principles.md

（随本Skill捆绑），或查看CLAUDE.md或项目文档中的架构与编码规范。

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

SOLID原则：

SRP（单一职责原则）——是否存在同时处理认证+用户信息+邮件+通知的上帝类/上帝模块？标记职责混杂的臃肿文件（>300行代码且职责不单一）。
DIP（依赖倒置原则）——服务是注入的还是硬编码的？查找业务逻辑中使用
```
new ConcreteService()
```
而非依赖注入的情况。

DRY原则与三次法则：

查找重复的逻辑块（使用Grep查找跨文件的相同函数签名）。
但不要标记2-3行相似代码——出现模式前的重复是可接受的。

KISS原则：

针对一次性操作的过度工程化抽象？
在简单修改即可解决的场景中使用了功能标志或向后兼容垫片？
仅使用过一次的辅助工具/实用函数？

Schema优先（SGR）：

是否先定义Pydantic/Zod Schema再编写逻辑？还是直接传递原始数据？
API响应是否有类型（而非
```
any
```
/
```
dict
```
）？
是否在边界处进行验证（用户输入、外部API）？

整洁架构：

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

错误处理：

对无效输入是否快速失败？还是静默吞掉错误？
用户可见的错误是否友好？内部错误是否包含堆栈跟踪？

报告：

遵循的原则：列出观察到的核心原则
发现的违规：包含文件:行号引用
严重级别：MINOR（风格问题）/ MAJOR（架构问题）/ CRITICAL（数据丢失风险）

10. Commit Quality

10. 提交质量检查

Check git history for the current track/feature:

bash

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

Conventional commits format:

Each commit follows
```
<type>(<scope>): <description>
```
pattern
Types:
```
feat
```
,
```
fix
```
,
```
refactor
```
,
```
test
```
,
```
docs
```
,
```
chore
```
,
```
perf
```
,
```
style
```
Flag: generic messages ("fix", "update", "wip", "changes"), missing type prefix, too-long titles (>72 chars)

Atomicity:

Each commit = one logical change? Or monster commits with 20 files across unrelated features?
Revert-friendly? Could you
```
git revert
```
a single commit without side effects?

SHAs in plan.md:

Check that completed tasks have
```

```
comments
Check that phase checkpoints have
```

```

bash

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

Pre-commit hooks:

Read the stack YAML

pre_commit

field to know what system is expected (husky/pre-commit/lefthook) and what it should run (linter + formatter + type-checker). Then verify:

bash

undefined

检查当前分支/功能的Git历史：

bash

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

规范提交格式：

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

原子性：

每个提交对应一个逻辑变更？还是包含20个无关功能文件的巨型提交？
是否易于回滚？能否
```
git revert
```
单个提交而无副作用？

plan.md中的SHA：

检查已完成任务是否包含
```

```
注释
检查阶段检查点是否包含
```

```

bash

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

提交前钩子：

读取栈YAML的

pre_commit

字段，了解预期的系统（husky/pre-commit/lefthook）及其应运行的内容（代码规范检查+格式化+类型校验）。然后验证：

bash

undefined

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"


- **Hooks installed?** Check config files exist AND hooks are wired (`core.hooksPath` for husky, `.git/hooks/pre-commit` for pre-commit/lefthook).
- **Hooks match stack?** Compare detected system with stack YAML `pre_commit` field. Flag mismatch.
- **`--no-verify` bypasses?** Check if recent commits show signs of skipped hooks (e.g., lint violations that should've been caught). Flag as WARN.
- **Not configured?** Flag as WARN recommendation — stack YAML expects `{pre_commit}` but nothing found.

Report:
- Total commits: {N}
- Conventional format: {N}/{M} compliant
- Atomic commits: YES / NO (with examples of violations)
- Plan SHAs: {N}/{M} tasks have SHAs
- Pre-commit hooks: {ACTIVE / NOT INSTALLED / NOT CONFIGURED} (expected: {stack pre_commit})

[ -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`跳过？** 检查近期提交是否有跳过钩子的迹象（如本应被捕获的代码规范违规）。标记为WARN。
- **未配置？** 标记为WARN建议——栈YAML期望`{pre_commit}`但未找到相关配置。

报告：
- 提交总数：{N}
- 符合规范格式：{N}/{M}
- 原子提交：是/否（包含违规示例）
- 计划SHA：{N}/{M}个任务包含SHA
- 提交前钩子：{已激活/未安装/未配置}（预期：{stack pre_commit}）

11. Documentation Freshness

11. 文档新鲜度检查

Check that project documentation is up-to-date with the code.

Required files check:

bash

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

CLAUDE.md:

Does it reflect current tech stack, commands, directory structure?
Are recently added features/endpoints documented?

Grep for outdated references (old package names, removed files):

bash

# 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:

Does it have setup/run/test/deploy instructions?
Are the commands actually runnable?

docs/prd.md:

Do features match what was actually built?
Are metrics and success criteria defined?

AICODE- comments:

bash

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

Flag unresolved
```
AICODE-TODO
```
items that were completed but not cleaned up
Flag unanswered
```
AICODE-ASK
```
questions
Check for
```
AICODE-NOTE
```
on complex/non-obvious logic

Dead code check:

Unused imports (linter should catch, but verify)
Orphaned files not imported anywhere
If
```
knip
```
available (Next.js):
```
pnpm knip 2>&1 | head -30
```

Report:

CLAUDE.md: CURRENT / STALE / MISSING
README.md: CURRENT / STALE / MISSING
docs/prd.md: CURRENT / STALE / MISSING
docs/workflow.md: CURRENT / STALE / MISSING
AICODE-TODO unresolved: {N}
AICODE-ASK unanswered: {N}
Dead code: {files/exports found}

检查项目文档是否与代码同步更新。

必填文件检查：

bash

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

CLAUDE.md：

是否反映当前技术栈、命令、目录结构？
最近新增的功能/端点是否已文档化？

查找过时引用（旧包名、已删除文件）：

bash

# 检查CLAUDE.md中提及的文件是否实际存在
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-注释：

bash

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
```
注释

死代码检查：

未使用的导入（代码规范检查工具应已捕获，但需验证）
未被任何地方导入的孤立文件
若Next.js项目中可用knip：
```
pnpm knip 2>&1 | head -30
```

报告：

CLAUDE.md：最新/过时/缺失
README.md：最新/过时/缺失
docs/prd.md：最新/过时/缺失
docs/workflow.md：最新/过时/缺失
未解决的AICODE-TODO：{N}
未回答的AICODE-ASK：{N}
死代码：{找到的文件/导出}

12. Visual/E2E Testing

12. 视觉/端到端测试

If browser tools or device tools are available, run a visual smoke test.

Web projects (Playwright MCP or browser tools):

Start dev server (use
```
dev_server.command
```
from stack YAML, e.g.
```
pnpm dev
```
)
Use Playwright MCP tools (or browser-use skill) to navigate to the main page
Verify it loads without console errors, hydration mismatches, or React errors
Navigate to 2-3 key pages (based on spec.md features)
Take screenshots at desktop (1280px) and mobile (375px) viewports
Look for broken images, missing styles, layout overflow

iOS projects (simulator):

Build for simulator:

xcodebuild -scheme {Name} -sdk iphonesimulator build

Install and launch on booted simulator
Take screenshot of main screen
Check simulator logs for crashes or assertion failures

Android projects (emulator):

Build debug APK:
```
./gradlew assembleDebug
```
Install and launch on emulator
Take screenshot of main activity

Check logcat for crashes or ANRs:

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

If tools are not available: skip this dimension, note as "N/A — no browser/device tools" in the report. Visual testing is never a blocker for SHIP verdict on its own.

Report:

Platform tested: {browser / simulator / emulator / N/A}
Pages/screens checked: {N}
Console errors: {N}
Visual issues: {NONE / list}
Responsive: {PASS / issues found}
Status: {PASS / WARN / FAIL / N/A}

若浏览器工具或设备工具可用，运行视觉冒烟测试。

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

启动开发服务器（使用栈YAML中的
```
dev_server.command
```
，如
```
pnpm dev
```
）
使用Playwright MCP工具（或browser-use Skill）导航到主页面
验证页面加载无控制台错误、hydration不匹配或React错误
导航到2-3个关键页面（基于spec.md中的功能）
在桌面（1280px）和移动端（375px）视口截图
查找破碎图片、缺失样式、布局溢出

iOS项目（模拟器）：

为模拟器构建：

xcodebuild -scheme {Name} -sdk iphonesimulator build

在已启动的模拟器上安装并启动应用
截取主屏幕截图
检查模拟器日志中的崩溃或断言失败

Android项目（模拟器）：

构建调试APK：
```
./gradlew assembleDebug
```
在模拟器上安装并启动应用
截取主活动页面截图

检查logcat中的崩溃或ANR：

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

若工具不可用：跳过此维度，在报告中注明“N/A — 无浏览器/设备工具”。视觉测试本身永远不会成为SHIP结论的阻碍。

报告：

测试平台：{浏览器/模拟器/真机/不适用}
检查的页面/屏幕：{N}
控制台错误：{N}
视觉问题：{无/列表}
响应式：{通过/存在问题}
状态：{通过/警告/失败/不适用}

Review Report

审查报告

Generate the final report:

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

生成最终报告：

代码审查：{project-name}
日期：{YYYY-MM-DD}

Verdict: {SHIP / FIX FIRST / BLOCK}

结论：{SHIP / FIX FIRST / BLOCK}

Summary

摘要

{1-2 sentence overall assessment}

{1-2句话的整体评估}

Tests

测试

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

总数：{N} | 通过：{N} | 失败：{N} | 跳过：{N}
覆盖率：{N}%
状态：{通过/失败}

Linter

代码规范检查

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

错误：{N} | 警告：{N}
状态：{通过/警告/失败}

Build

构建

Status: {PASS / FAIL}
Warnings: {N}

状态：{通过/失败}
警告：{N}

Security

安全

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

漏洞：{N}（严重：{N}，高：{N}，中：{N}）
硬编码密钥：{无/已发现}
状态：{通过/警告/失败}

Acceptance Criteria

验收标准

Verified: {N}/{M}
Missing: {list}
Status: {PASS / PARTIAL / FAIL}

已验证：{N}/{M}
缺失：{列表}
状态：{通过/部分通过/失败}

Plan Progress

计划进度

Tasks: {N}/{M} complete
Phases: {N}/{M} complete
Status: {COMPLETE / IN PROGRESS}

任务：{N}/{M}完成
阶段：{N}/{M}完成
状态：{已完成/进行中}

Production Logs

生产日志

Platform: {Vercel / Cloudflare / Fly.io / N/A}
Errors: {N} | Warnings: {N}
Status: {CLEAN / WARN / ERRORS / N/A}

平台：{Vercel / Cloudflare / Fly.io / 不适用}
错误：{N} | 警告：{N}
状态：{无异常/警告/错误/不适用}

Dev Principles

开发原则

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

SOLID：{通过/存在违规}
Schema优先：{是/存在原始数据}
错误处理：{通过/存在问题}
状态：{通过/警告/失败}

Commits

提交

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

总数：{N} | 符合规范：{N}/{M}
原子化：{是/否}
计划SHA：{N}/{M}
状态：{通过/警告/失败}

Documentation

文档

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

CLAUDE.md：{最新/过时/缺失}
README.md：{最新/过时/缺失}
未解决的AICODE-TODO：{N}
死代码：{无/已发现}
状态：{通过/警告/失败}

Visual Testing

视觉测试

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

平台：{浏览器/模拟器/真机/不适用}
页面/屏幕：{N}
控制台错误：{N}
视觉问题：{无/列表}
状态：{通过/警告/失败/不适用}

Issues Found

发现的问题

[{severity}] {description} — {file:line}
[{severity}] {description} — {file:line}

[{严重级别}] {描述} — {文件:行号}
[{严重级别}] {描述} — {文件:行号}

Recommendations

建议

{actionable recommendation}
{actionable recommendation}


**Verdict logic:**
- **SHIP**: All tests pass, no security issues, acceptance criteria met, build succeeds, production logs clean, docs current, commits atomic, no critical visual issues
- **FIX FIRST**: Minor issues (warnings, partial criteria, low-severity vulns, intermittent log errors, stale docs, non-conventional commits, minor SOLID violations, minor visual issues like layout overflow) — list what to fix
- **BLOCK**: Failing tests, security vulnerabilities, missing critical features, production crashes in logs, missing CLAUDE.md/README.md, critical architecture violations, app crashes on launch (simulator/emulator) — do not ship

{可执行的建议}
{可执行的建议}


**结论判定逻辑：**
- **SHIP（可发布）**：所有测试通过，无安全问题，验收标准全部满足，构建成功，生产日志无异常，文档最新，提交原子化，无严重视觉问题
- **FIX FIRST（优先修复）**：存在次要问题（警告、部分标准未满足、低严重性漏洞、日志中的间歇性错误、文档过时、不符合规范的提交、轻微SOLID原则违反、布局溢出等轻微视觉问题）——列出需要修复的内容
- **BLOCK（禁止发布）**：测试失败、存在安全漏洞、关键功能缺失、生产日志中存在崩溃记录、缺少CLAUDE.md/README.md、严重架构违规、应用启动崩溃（模拟器/真机）——禁止发布

Post-Verdict: CLAUDE.md Revision

结论后：CLAUDE.md修订

After the verdict report, revise the project's CLAUDE.md to keep it lean and useful for future agents.

生成结论报告后，修订项目的CLAUDE.md以保持简洁，方便后续Agent使用。

Steps:

步骤：

Read CLAUDE.md and check size:
```
wc -c CLAUDE.md
```
Add learnings from this review:
- New Do/Don't rules discovered during review
- Updated commands, workflows, or architecture decisions
- Fixed issues or gotchas worth remembering
- Stack/dependency changes (new packages, removed deps)
If over 40,000 characters — trim ruthlessly:
- Collapse completed phase/milestone histories into one line each
- Remove verbose explanations — keep terse, actionable notes
- Remove duplicate info (same thing explained in multiple sections)
- Remove historical migration notes, old debugging context
- Remove examples that are obvious from code or covered by skill/doc files
- Remove outdated troubleshooting for resolved issues
Verify result ≤ 40,000 characters — if still over, cut least actionable content
Write updated CLAUDE.md, update "Last updated" date

读取CLAUDE.md并检查大小：
```
wc -c CLAUDE.md
```
添加本次审查的经验总结：
- 审查过程中发现的新Do/Don't规则
- 更新后的命令、工作流或架构决策
- 已修复的问题或需要注意的陷阱
- 技术栈/依赖变更（新增包、移除的依赖）
若超过40000字符——严格精简：
- 将已完成的阶段/里程碑历史压缩为每行一个阶段
- 删除冗长的解释——保留简洁、可操作的说明
- 删除重复信息（同一内容在多个章节重复说明）
- 删除历史迁移说明、旧调试上下文
- 删除代码中已明确或Skill/文档已覆盖的示例
- 删除已解决问题的过时故障排除内容
验证最终内容≤40000字符——若仍超过，删除最无操作价值的内容
编写更新后的CLAUDE.md，更新“Last updated”日期

Priority (keep → cut):

优先级（保留→删除）：

ALWAYS KEEP: Tech stack, directory structure, Do/Don't rules, common commands, architecture decisions
KEEP: Workflow instructions, troubleshooting for active issues, key file references
CONDENSE: Phase histories (one line each), detailed examples, tool/MCP listings
CUT FIRST: Historical notes, verbose explanations, duplicated content, resolved issues

必须保留：技术栈、目录结构、Do/Don't规则、常用命令、架构决策
保留：工作流说明、当前问题的故障排除、关键文件引用
压缩：阶段历史（每行一个）、详细示例、工具/MCP列表
优先删除：历史记录、冗长解释、重复内容、已解决问题

Rules:

规则：

Never remove Do/Don't sections — critical guardrails
Preserve overall section structure and ordering
Every line must earn its place: "would a future agent need this to do their job?"

Commit the update:

git add CLAUDE.md && git commit -m "docs: revise CLAUDE.md (post-review)"

永远不要删除Do/Don't章节——这是关键的防护规则
保留整体章节结构与顺序
每一行内容都必须有存在的价值：“未来的Agent是否需要此信息来完成工作？”

提交更新：

git add CLAUDE.md && git commit -m "docs: revise CLAUDE.md (post-review)"

AFTER CLAUDE.md revision — output signal EXACTLY ONCE:

CLAUDE.md修订完成后——仅输出一次信号：

Output pipeline signal ONLY if pipeline state directory (

.solo/states/

) exists.

Output the signal tag ONCE and ONLY ONCE. Do not repeat it. The pipeline detects the first occurrence.

If SHIP: output this exact line (once):

<solo:done/>

If FIX FIRST or BLOCK:

Open plan.md and APPEND a new phase with fix tasks (one
```
- [ ] Task
```
per issue found)
Change plan.md status from
```
[x] Complete
```
to
```
[~] In Progress
```

Commit:

git add docs/plan/ && git commit -m "fix: add review fix tasks"

Output this exact line (once):

<solo:redo/>

The pipeline reads these tags and handles all marker files automatically. You do NOT need to create or delete any marker files yourself. Output the signal tag once — the pipeline detects the first occurrence.

仅当存在流水线状态目录（

.solo/states/

）时输出流水线信号。

仅输出一次信号标签，不要重复。流水线会检测第一次出现的信号。

若结论为SHIP：输出以下内容（仅一次）：

<solo:done/>

若结论为FIX FIRST或BLOCK：

打开plan.md并追加一个新的修复任务阶段（每个问题对应一个
```
- [ ] Task
```
）
将plan.md的状态从
```
[x] Complete
```
改为
```
[~] In Progress
```

提交：

git add docs/plan/ && git commit -m "fix: add review fix tasks"

输出以下内容（仅一次）：

<solo:redo/>

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

Error Handling

错误处理

Tests won't run

测试无法运行

Cause: Missing dependencies or test config. Fix: Run

npm install

uv sync

, check test config exists (jest.config, pytest.ini).

原因：缺少依赖或测试配置。解决：运行

npm install

uv sync

，检查测试配置是否存在（jest.config、pytest.ini）。

Linter not configured

代码规范检查工具未配置

Cause: No linter config file found. Fix: Note as a recommendation in the report, not a blocker.

原因：未找到代码规范检查配置文件。解决：在报告中注明为建议项，而非阻碍。

Build fails

构建失败

Cause: Type errors, import issues, missing env vars. Fix: Report specific errors. This is a BLOCK verdict — must fix before shipping.

原因：类型错误、导入问题、缺少环境变量。解决：报告具体错误。此情况判定为BLOCK结论——必须修复后才能发布。

Two-Stage Review Pattern

两阶段审查模式

When reviewing significant work, use two stages:

Stage 1 — Spec Compliance:

Does the implementation match spec.md requirements?
Are all acceptance criteria actually met (not just claimed)?
Any deviations from the plan? If so, are they justified improvements or problems?

Stage 2 — Code Quality:

Architecture patterns, error handling, type safety
Test coverage and test quality
Security and performance
Code organization and maintainability

审查重要工作时，使用两个阶段：

阶段1——需求合规性：

实现是否符合spec.md的要求？
所有验收标准是否实际满足（而非仅声称满足）？
是否存在与计划的偏差？若有，是合理的改进还是问题？

阶段2——代码质量：

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

Verification Gate

验证门禁

No verdict without fresh evidence.

Before writing any verdict (SHIP/FIX/BLOCK):

Run the actual test/build/lint commands (not cached results).
Read full output — exit codes, pass/fail counts, error messages.
Confirm the output matches your claim.
Only then write the verdict with evidence.

Never write "tests should pass" — run them and show the output.

无新鲜证据则不给出结论。

在给出任何结论（SHIP/FIX/BLOCK）前：

运行实际的测试/构建/代码规范检查命令（不要使用缓存结果）。
读取完整输出——退出码、通过/失败数量、错误消息。
确认输出与你的声明一致。
仅在此时结合证据给出结论。

永远不要写“测试应该通过”——运行测试并展示输出。

Rationalizations Catalog

合理化借口对照表

Thought	Reality
"Tests were passing earlier"	Run them NOW. Code changed since then.
"It's just a warning"	Warnings become bugs. Report them.
"The build worked locally"	Check the platform too. Environment differences matter.
"Security scan is overkill"	One missed secret = data breach. Always scan.
"Good enough to ship"	Quantify "good enough". Show the numbers.
"I already checked this"	Fresh evidence only. Stale checks are worthless.

想法	实际情况
“之前测试是通过的”	现在就运行测试。自那时起代码已变更。
“这只是一个警告”	警告会变成bug。报告它们。
“构建在本地是正常的”	也要检查平台环境。环境差异很重要。
“安全扫描是多余的”	遗漏一个密钥就可能导致数据泄露。始终进行扫描。
“足够好可以发布了”	量化“足够好”。展示数据。
“我已经检查过这个了”	仅接受新鲜证据。过时的检查毫无价值。

Critical Rules

关键规则

Run all checks — do not skip dimensions even if project seems simple.
Be specific — always include file:line references for issues.
Verdict must be justified — every SHIP/FIX/BLOCK needs evidence from actual commands.
Don't auto-fix code — report issues and add fix tasks to plan.md. Let
```
/build
```
fix them. Review only modifies plan.md, never source code.
Check acceptance criteria — spec.md is the source of truth for "done".
Security is non-negotiable — any hardcoded secret = BLOCK.
Fresh evidence only — run commands before making claims. Never rely on memory.

运行所有检查——即使项目看似简单，也不要跳过任何维度。
具体明确——报告问题时始终包含文件:行号引用。
结论必须有依据——每个SHIP/FIX/BLOCK结论都需要来自实际命令的证据。
不要自动修复代码——报告问题并在plan.md中添加修复任务。让/build来修复代码。审查仅修改plan.md，永远不要修改源代码。
检查验收标准——spec.md是“完成”的唯一依据。
安全是不可协商的——任何硬编码密钥都判定为BLOCK。
仅使用新鲜证据——做出声明前先运行命令。永远不要依赖记忆。