Back to Details

clean-code-reviewer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clean Code Reviewer

Clean Code 审查器

Orchestrates a full code review by inspecting the diff, selecting relevant skills, and dispatching concurrent review passes for style and correctness.
通过检查diff、选择相关技能，并并行启动风格与正确性审查流程，统筹完成完整的代码审查。

Review Target

审查目标

If the user specifies what to review, use that target exactly. Valid targets include specific files, directories, commit ranges, branches, pull requests, changed files, or the full codebase.
If the user does not specify a target, default to the current worktree:
  1. If there are staged or unstaged changes, review the working tree diff.
  2. If the working tree is clean, review the current branch against the repository default branch.
  3. Detect the default branch from 
    origin/HEAD
    , falling back to 
    main
    then 
    master
    .
Before starting the review, state the selected target briefly. Ask what to review only when no meaningful target can be inferred.
如果用户指定了审查对象，则严格使用该对象。有效的审查对象包括特定文件、目录、提交范围、分支、拉取请求、已修改文件或整个代码库。
如果用户未指定审查对象，则默认使用当前工作树：
  1. 如果存在暂存或未暂存的变更，审查工作树的diff（
    git diff
    和 
    git diff --cached
    ）。
  2. 如果工作树干净，审查当前分支与仓库默认分支的差异。
  3. 通过
    origin/HEAD
    检测默认分支，若失败则依次回退到
    main
    、
    master
    。
开始审查前，简要说明选定的审查对象。仅当无法推断出有意义的审查对象时，才询问用户需要审查的内容。

Diff Detection

Diff 检测

For diff-based review targets, determine the comparison to inspect:
  1. Run 
    git status
    . If there are staged or unstaged changes, review the working tree diff (
    git diff
    and 
    git diff --cached
    ).
  2. If the working tree is clean, find the base branch. Detect it with 
    git symbolic-ref refs/remotes/origin/HEAD
    (strips the 
    refs/remotes/origin/
    prefix), falling back to 
    main
    then 
    master
    if that fails. Diff the current branch against it: 
    git diff $(git merge-base HEAD <base>)..HEAD
    .
  3. If the branch has no commits ahead of the base, there is nothing to auto-detect. Ask the user what they want reviewed: specific files, a directory, or the full codebase.
  4. Run 
    git diff --name-only
    (with the appropriate target) to get the list of changed files.
对于基于diff的审查对象，确定需要检查的对比内容：
  1. 运行
    git status
    。如果存在暂存或未暂存的变更，审查工作树的diff（
    git diff
    和 
    git diff --cached
    ）。
  2. 如果工作树干净，找到基准分支。通过
    git symbolic-ref refs/remotes/origin/HEAD
    检测（去除
    refs/remotes/origin/
    前缀），若失败则依次回退到
    main
    、
    master
    。对比当前分支与基准分支的差异：
    git diff $(git merge-base HEAD <base>)..HEAD
    。
  3. 如果当前分支相对于基准分支没有超前提交，则无法自动检测。询问用户需要审查的内容：特定文件、目录或整个代码库。
  4. 运行
    git diff --name-only
    （搭配对应的审查对象）获取已修改文件列表。

Full Codebase Review

全代码库审查

When the user asks to review the entire codebase (or a large directory), a diff-based review does not apply. Instead:
  1. Prioritize by risk. Review in this order:
    • Entry points and public API surfaces (exported modules, route handlers, SDK interfaces)
    • Authentication, authorization, and security-sensitive code
    • Complex business logic and state management
    • Data access, boundary code, and external integrations
    • Utilities, helpers, and shared components
  2. Batch by module. Group files by their owning module or directory. Review one batch at a time, or dispatch concurrent agents per batch.
  3. Focus on structural issues. Without a diff to narrow scope, prioritize findings that affect architecture, correctness, and security over minor style issues.
  4. Cap findings per batch. Report the top 5-10 findings per module to keep the review actionable. Flag if a module needs deeper follow-up.
  5. Produce a summary. After all batches, produce a prioritized list of the most impactful findings across the codebase.
当用户要求审查整个代码库（或大型目录）时，基于diff的审查不再适用，需按以下方式操作：
  1. 按风险优先级排序。按以下顺序审查：
    • 入口点与公共API表面（导出模块、路由处理器、SDK接口）
    • 认证、授权及安全敏感代码
    • 复杂业务逻辑与状态管理
    • 数据访问、边界代码及外部集成
    • 工具类、辅助函数及共享组件
  2. 按模块分批。按所属模块或目录对文件进行分组。每次审查一个批次，或为每个批次分配并行审查代理。
  3. 聚焦结构性问题。没有diff缩小范围时，优先关注影响架构、正确性和安全性的问题，而非次要的风格问题。
  4. 限制每个批次的问题数量。每个模块最多报告5-10个关键问题，确保审查结果具备可操作性。若模块需要更深入的跟进，需标记说明。
  5. 生成总结报告。所有批次审查完成后，生成全代码库范围内影响最大的问题优先级列表。

File Inspection

文件分类

From the changed file list, classify each file:
PatternTrack
.ts
, 
.tsx
(no JSX)		TypeScript
.tsx
with React imports or JSX		React + TypeScript
.css
, 
.module.css
, 
.scss
, styled templates, Tailwind classes		CSS
Test files (
*.test.*
, 
*.spec.*
)		Tests
New or moved 
.ts
, 
.tsx
, 
.jsx
, 
.module.css
files		File Organization
To detect new or moved files, run 
git diff --diff-filter=AR
(with the same target used above). If any 
.ts
, 
.tsx
, 
.jsx
, or 
.module.css
files appear, add "File Organization" to the tracks for the Style Pass.
根据已修改文件列表，对每个文件进行分类：
匹配模式审查领域
.ts
, 
.tsx
（无JSX）		TypeScript
包含React导入或JSX的
.tsx
文件		React + TypeScript
.css
, 
.module.css
, 
.scss
, styled模板, Tailwind类		CSS
测试文件（
*.test.*
, 
*.spec.*
）		Tests
新增或移动的
.ts
, 
.tsx
, 
.jsx
, 
.module.css
文件		文件组织
为检测新增或移动的文件，运行
git diff --diff-filter=AR
（搭配上述相同的审查对象）。如果出现任何
.ts
, 
.tsx
, 
.jsx
或
.module.css
文件，在风格审查流程的审查领域中添加“文件组织”。

Dispatch Concurrent Reviews

并行启动审查流程

Run two review passes in parallel:
并行运行两个审查流程：

Style Pass

风格审查流程

Step 1 — Read the index skill(s) based on file classification:
FilesRead
.ts
, 
.tsx
(TypeScript)
../clean-typescript/SKILL.md
React (JSX / React imports)
../clean-react/SKILL.md
+ 
../clean-typescript/SKILL.md
.css
, 
.module.css
, 
.scss
, styled, Tailwind
../clean-css/SKILL.md
Test files (
*.test.*
, 
*.spec.*
)
../clean-typescript-tests/SKILL.md
or 
../clean-react-tests/SKILL.md
New/moved 
.ts
, 
.tsx
, 
.jsx
, 
.module.css
../clean-react-file-organization/SKILL.md
Step 2 — Read relevant sub-skills. Scan the diff and identify which rule categories appear. Then read only the sub-skill files that match before writing findings. Do not load all sub-skills — only the ones relevant to what is actually in the diff.
All skills are installed as siblings in the same directory. Reference TypeScript sub-skills with the sibling path pattern 
../clean-typescript-{topic}/SKILL.md
and React sub-skills with 
../clean-react-{topic}/SKILL.md
. Use the Skill Routing table in each index to map rule codes to sub-skill names.
Step 3 — Apply and report. Apply all loaded skills to the diff. Report findings with rule IDs.
步骤1 — 根据文件分类读取索引技能：
文件类型读取的技能文档
.ts
, 
.tsx
（TypeScript）
../clean-typescript/SKILL.md
React（JSX / React导入）
../clean-react/SKILL.md
+ 
../clean-typescript/SKILL.md
.css
, 
.module.css
, 
.scss
, styled, Tailwind
../clean-css/SKILL.md
测试文件（
*.test.*
, 
*.spec.*
）
../clean-typescript-tests/SKILL.md
或 
../clean-react-tests/SKILL.md
新增/移动的
.ts
, 
.tsx
, 
.jsx
, 
.module.css
../clean-react-file-organization/SKILL.md
步骤2 — 读取相关子技能。扫描diff并识别出现的规则类别，仅读取匹配的子技能文件后再记录问题。不要加载所有子技能——只加载与diff中实际内容相关的子技能。
所有技能都安装在同一目录的同级位置。使用同级路径模式
../clean-typescript-{topic}/SKILL.md
引用TypeScript子技能，使用
../clean-react-{topic}/SKILL.md
引用React子技能。利用每个索引中的技能路由表，将规则代码映射到子技能名称。
步骤3 — 应用并报告。将所有加载的技能应用到diff中，附带规则ID报告问题。

Correctness Pass

正确性审查流程

Load 
clean-code-reviewer-correctness
. Apply it to the full diff. This pass reviews for functional bugs, security vulnerabilities, performance issues, and test coverage gaps. It ignores style.
加载
clean-code-reviewer-correctness
，将其应用到完整的diff中。此流程审查功能性bug、安全漏洞、性能问题和测试覆盖缺口，忽略风格问题。

Merging Results

合并审查结果

Combine findings from both passes into a single report.
Deduplication rule: If the correctness pass flags a code region, suppress any style finding that overlaps the same region. The correctness fix will resolve the style issue — reporting both is noise. Only keep the style finding if it addresses a genuinely independent concern at the same location.
将两个流程的审查结果合并为一份报告。
去重规则：如果正确性审查流程标记了某段代码区域，抑制同一区域的任何风格问题记录。修复正确性问题通常会解决风格问题——同时报告两者属于冗余信息。仅当风格问题针对同一位置的真正独立问题时，才保留该记录。

Output Format

输出格式

text
undefined
text
undefined

Style

风格问题

[Findings grouped by file]
[按文件分组的问题记录]

Correctness

正确性问题

[Findings grouped by file]
[按文件分组的问题记录]

Verdict

审查结论

[Approve | Approve with suggestions | Request changes] [One-sentence summary referencing finding codes, e.g. "Request changes — [S1] is a security hole; [C2] will break existing callers."]

Each finding uses this format, with its code as the leading identifier:

```text
[S1] Severity: Block | Fix | Suggest
Category: Style (rule-id)
Location: path/to/file:line
Issue: What is wrong and why it matters.
Fix: Concrete next step.
text
[C1] Severity: Block | Fix | Suggest
Category: Correctness | Security | Performance | Test Coverage
Location: path/to/file:line
Issue: What is wrong and why it matters.
Fix: Concrete next step.
Style findings are numbered [S1], [S2], … in order of severity. Correctness findings are numbered [C1], [C2], … in order of severity. Numbers are assigned after merging so the user can reference any finding by code (e.g. "fix S2 and C1").
[批准 | 附建议批准 | 请求修改] [一句话总结，引用问题代码，例如："请求修改 — [S1] 存在安全漏洞；[C2] 会破坏现有调用方。"]

每个问题记录采用以下格式，以问题代码作为前置标识：

```text
[S1] 严重程度：阻断 | 需修复 | 建议优化
类别：风格（规则ID）
位置：path/to/file:line
问题：问题内容及影响原因。
修复方案：具体下一步操作。
text
[C1] 严重程度：阻断 | 需修复 | 建议优化
类别：正确性 | 安全性 | 性能 | 测试覆盖
位置：path/to/file:line
问题：问题内容及影响原因。
修复方案：具体下一步操作。
风格问题按严重程度编号为[S1]、[S2]……正确性问题按严重程度编号为[C1]、[C2]……编号在合并结果后分配，以便用户通过代码引用任意问题（例如："修复S2和C1"）。

Severity Definitions

严重程度定义

  • Block: Will break production, cause data loss, introduce a security vulnerability, or silently corrupt behavior. Must be fixed before merge.
  • Fix: Likely bug, likely vulnerability, or missing coverage for critical behavior. Should be fixed before merge.
  • Suggest: Potential improvement worth considering. Does not block merge.
  • 阻断：会导致生产环境崩溃、数据丢失、引入安全漏洞或静默破坏行为。合并前必须修复。
  • 需修复：可能存在bug、漏洞，或关键行为缺少测试覆盖。合并前应修复。
  • 建议优化：值得考虑的潜在改进点。不影响合并。

Verdict Rules

审查结论规则

  • Any Block finding → Request changes
  • Any Fix finding → Request changes
  • Only Suggest findings → Approve with suggestions
  • No findings → Approve
After the verdict, always close with:
Reply with the codes you want fixed (e.g. 
fix S1 C2
), 
all
to address everything, or 
blocks
to fix only Block findings.
If there are no findings, omit this prompt.
  • 存在任何阻断级问题 → 请求修改
  • 存在任何需修复级问题 → 请求修改
  • 仅存在建议优化级问题 → 附建议批准
  • 无问题 → 批准
结论之后，始终附上：
回复需要修复的问题代码（例如：
fix S1 C2
），或
all
修复所有问题，或
blocks
仅修复阻断级问题。
如果没有问题记录，则省略此提示。

AI Behavior

AI 行为规范

  • Do not review generated files, lock files, or vendored dependencies.
  • Do not flag issues in code that was not changed unless the change breaks it.
  • Keep the review focused. A 10-line diff should not produce 30 findings.
  • When unsure whether something is a bug or intentional, use Suggest severity and say why.
  • If the diff is too large to review thoroughly in one pass, say so and focus on the highest-risk files.
  • 不要审查生成文件、锁文件或第三方依赖代码。
  • 不要标记未修改代码中的问题，除非变更破坏了该代码。
  • 保持审查聚焦。10行的diff不应产生30条问题记录。
  • 不确定某内容是bug还是有意设计时，使用“建议优化”严重程度并说明原因。
  • 如果diff过大无法一次性彻底审查，需告知用户并聚焦高风险文件。