full-repo-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Full-Repo Review : Codebase Health Check

全仓库审查：代码库健康检查

Orchestrates a comprehensive 3-wave review against ALL source files in the repository, not just changed files. Delegates the actual review to the

comprehensive-review

skill. Produces a prioritized issue backlog instead of auto-fixes.

When to use: Quarterly health checks, after major refactors, onboarding to a new codebase, or any time you want a systemic view of codebase quality.

How it differs from comprehensive-review: This skill changes the SCOPE phase to scan all source files instead of git diff, and changes the output from auto-fix to a prioritized backlog report. The review waves themselves are identical.

针对仓库中的所有源文件（而非仅变更文件）协调执行全面的三轮审查。将实际审查工作委托给

comprehensive-review

skill。生成优先级排序的问题积压，而非自动修复。

适用场景：季度健康检查、重大重构后、新代码库入职培训，或任何需要系统性了解代码库质量的场景。

与comprehensive-review的区别：该skill会修改范围阶段，改为扫描所有源文件而非git diff，同时将输出从自动修复改为优先级积压报告。审查流程本身是完全一致的。

Operator Context

操作上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Full-Scope, Not Diff-Scope: Always review ALL source files. Never fall back to git diff. The entire point of this skill is codebase-wide coverage.
Report, Don't Auto-Fix: Output is a prioritized backlog (
```
full-repo-review-report.md
```
), not auto-applied fixes. Full-repo auto-fix is impractical and risky -- the user triages and batches fixes.
Deterministic Pre-Check First: Run
```
score-component.py
```
before the LLM review. Deterministic checks are cheap and catch structural issues (missing frontmatter, no error handling section) that LLM reviewers shouldn't waste tokens on.
Delegate to comprehensive-review: This skill orchestrates scope and output. The actual 3-wave review is performed by
```
comprehensive-review
```
with
```
--review-only
```
mode.

全范围而非差异范围：始终审查所有源文件，绝不回退到git diff。该skill的核心价值就是覆盖整个代码库。
仅报告，不自动修复：输出为优先级积压报告（
```
full-repo-review-report.md
```
），而非自动应用的修复。全仓库自动修复不切实际且风险极高——需由用户进行分类处理和批量修复。
先执行确定性预检查：在LLM审查前运行
```
score-component.py
```
。确定性检查成本低，可捕获结构问题（如缺失前置内容、无错误处理章节），避免LLM审查浪费token在这类问题上。
委托给comprehensive-review：该skill仅负责协调范围和输出。实际的三轮审查由
```
comprehensive-review
```
以
```
--review-only
```
模式执行。

Default Behaviors (ON unless disabled)

默认行为（默认开启，可禁用）

Score Pre-Check: Run
```
score-component.py --all-agents --all-skills
```
and include scores in the report
Severity Aggregation: Group findings by CRITICAL/HIGH/MEDIUM/LOW
Systemic Pattern Detection: Identify patterns that appear across multiple files/directories
Report Artifact: Write
```
full-repo-review-report.md
```
to repo root

分数预检查：运行
```
score-component.py --all-agents --all-skills
```
并将分数纳入报告
严重程度聚合：按CRITICAL/HIGH/MEDIUM/LOW分组展示问题
系统性模式检测：识别出现在多个文件/目录中的模式
报告产物：将
```
full-repo-review-report.md
```
写入仓库根目录

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需启用）

--directory [dir]: Review only a single directory (e.g.,
```
scripts/
```
) instead of the full repo. Useful for splitting a large repo into manageable chunks.
--skip-precheck: Skip the
```
score-component.py
```
deterministic pre-check. Only use if the script is unavailable or you need faster iteration.
--min-severity [level]: Only include findings at or above a severity threshold (CRITICAL, HIGH, MEDIUM) in the report. Default: include all.

--directory [dir]：仅审查单个目录（如
```
scripts/
```
）而非整个仓库。适用于将大型仓库拆分为可管理的模块。
--skip-precheck：跳过
```
score-component.py
```
确定性预检查。仅在脚本不可用或需要更快迭代时使用。
--min-severity [level]：仅在报告中包含严重程度达到或高于指定阈值（CRITICAL、HIGH、MEDIUM）的问题。默认：包含所有问题。

Capabilities

能力范围

What This Skill CAN Do

该Skill可实现的功能

Discover all source files across scripts/, hooks/, skills/, agents/, docs/
Run deterministic health scoring on all agents and skills via
```
score-component.py
```
Invoke comprehensive-review in
```
--review-only
```
mode with the full file list
Aggregate findings by severity into a prioritized backlog report
Identify systemic patterns that appear across multiple files

发现scripts/、hooks/、skills/、agents/、docs/下的所有源文件
通过
```
score-component.py
```
对所有Agent和Skill执行确定性健康评分
以
```
--review-only
```
模式调用comprehensive-review并传入完整文件列表
将问题按严重程度聚合为优先级积压报告
识别出现在多个文件中的系统性模式

What This Skill CANNOT Do

该Skill不可实现的功能

Auto-fix findings (by design -- output is a report for human triage)
Review non-source files (images, binaries, config files without .py/.md extension)
Replace PR-scoped comprehensive-review (different use case, different frequency)
Run individual review agents directly (delegates to comprehensive-review for wave orchestration)

自动修复问题（设计如此——输出供人工分类处理的报告）
审查非源文件（图片、二进制文件、无.py/.md扩展名的配置文件）
替代PR范围的comprehensive-review（使用场景不同、频率不同）
直接运行独立审查Agent（委托给comprehensive-review进行流程协调）

Instructions

操作步骤

Phase 1: DISCOVER AND PRE-CHECK

阶段1：发现与预检查

Goal: Identify all source files and run deterministic health checks.

Step 1: Discover source files

Build the complete file list by scanning these directories:

bash

undefined

目标：识别所有源文件并执行确定性健康检查。

步骤1：发现源文件

通过扫描以下目录构建完整文件列表：

bash

undefined

Python scripts (exclude test files and pycache)

Python脚本（排除测试文件和pycache）

find scripts/ -name ".py" -not -path "/tests/" -not -path "/pycache/*" 2>/dev/null

Hooks (exclude test files and lib/)

Hooks（排除测试文件和lib/）

find hooks/ -name ".py" -not -path "/tests/" -not -path "/lib/*" 2>/dev/null

Skills (SKILL.md files only)

Skills（仅SKILL.md文件）

find skills/ -name "SKILL.md" 2>/dev/null

Agents

find agents/ -name "*.md" 2>/dev/null

Docs

find docs/ -name "*.md" 2>/dev/null


Log the total file count. If zero files found, STOP and report: "No source files discovered. Verify you are in the correct repository root."

**Step 2: Run deterministic pre-check**

```bash
python3 ~/.claude/scripts/score-component.py --all-agents --all-skills --json

Parse the JSON output. Flag any component scoring below 60 (grade F) as a CRITICAL finding for the final report. Components scoring 60-74 (grade C) are HIGH findings.

Save the raw scores -- they go into the report's "Deterministic Health Scores" section.

GATE: At least one source file discovered AND score-component.py ran successfully. If the scoring script fails, proceed with a warning but do not skip the review phase.

find docs/ -name "*.md" 2>/dev/null


记录文件总数。如果未发现任何文件，停止操作并报告："未发现源文件。请确认当前处于正确的仓库根目录。"

**步骤2：执行确定性预检查**

```bash
python3 ~/.claude/scripts/score-component.py --all-agents --all-skills --json

解析JSON输出。将评分低于60（F级）的组件标记为最终报告中的CRITICAL问题。评分在60-74之间（C级）的组件为HIGH问题。

保存原始评分——这些将纳入报告的「确定性健康评分」章节。

检查点：至少发现一个源文件且score-component.py执行成功。如果评分脚本执行失败，可继续执行并在报告中注明该问题。

Phase 2: REVIEW

阶段2：审查

Goal: Run the comprehensive-review pipeline against all discovered files.

Step 1: Invoke comprehensive-review

Invoke the

comprehensive-review

skill with these overrides:

Scope: Pass the full file list from Phase 1 (use
```
--focus [files]
```
mode)
Mode: Use
```
--review-only
```
to skip auto-fix (this skill produces a report, not patches)
All waves: Do NOT use
```
--skip-wave0
```
or
```
--wave1-only
```
. Full-repo review needs maximum coverage.

The comprehensive-review skill handles Wave 0 (per-package), Wave 1 (foundation agents), and Wave 2 (deep-dive agents) internally.

Step 2: Collect findings

After comprehensive-review completes, gather all findings from its output. Each finding should have:

File: path and line number
Severity: CRITICAL / HIGH / MEDIUM / LOW
Category: security, architecture, dead-code, naming, etc.
Description: what the issue is
Suggested fix: how to resolve it

GATE: comprehensive-review completed and produced findings output. If it failed, include what partial findings exist and note the failure in the report.

目标：对所有发现的文件执行comprehensive-review流程。

步骤1：调用comprehensive-review

使用以下参数调用

comprehensive-review

skill：

范围：传入阶段1得到的完整文件列表（使用
```
--focus [files]
```
模式）
模式：使用
```
--review-only
```
跳过自动修复（该skill生成报告而非补丁）
全流程：请勿使用
```
--skip-wave0
```
或
```
--wave1-only
```
。全仓库审查需要最大范围的覆盖。

comprehensive-review skill会在内部处理Wave 0（按包审查）、Wave 1（基础Agent）和Wave 2（深度审查Agent）。

步骤2：收集问题

comprehensive-review完成后，收集其输出中的所有问题。每个问题应包含：

文件：路径和行号
严重程度：CRITICAL / HIGH / MEDIUM / LOW
类别：安全、架构、死代码、命名等
描述：问题内容
建议修复方案：解决方法

检查点：comprehensive-review完成并生成问题输出。如果执行失败，收集已有的部分问题并在报告中注明失败情况。

Phase 3: REPORT

阶段3：报告

Goal: Aggregate all findings into a prioritized backlog report.

Step 1: Merge deterministic and LLM findings

Combine:

Phase 1 score-component.py results (structural health)
Phase 2 comprehensive-review findings (deep analysis)

Deduplicate where both sources flag the same issue. Keep the higher severity.

Step 2: Identify systemic patterns

Look for patterns that appear in 3+ files:

Repeated naming violations
Consistent missing error handling
Common anti-patterns across components
Documentation gaps that follow a pattern

These go into a dedicated "Systemic Patterns" section -- they represent the highest-leverage fixes because one pattern change improves many files.

Step 3: Write the report

Write

full-repo-review-report.md

to the repo root with this structure:

markdown

undefined

目标：将所有问题聚合为优先级积压报告。

步骤1：合并确定性与LLM问题

合并以下内容：

阶段1的score-component.py结果（结构健康）
阶段2的comprehensive-review问题（深度分析）

对两个来源标记的同一问题进行去重，保留更高的严重程度。

步骤2：识别系统性模式

寻找出现在3个及以上文件中的模式：

重复的命名违规
持续缺失的错误处理
组件间常见的反模式
存在规律的文档缺失

这些将纳入专门的「系统性模式」章节——这些是价值最高的修复点，因为一个模式的改进可优化多个文件。

步骤3：撰写报告

在仓库根目录写入

full-repo-review-report.md

，结构如下：

markdown

undefined

Full-Repo Review Report

全仓库审查报告

Date: {date} Files reviewed: {count} Total findings: {count} (Critical: N, High: N, Medium: N, Low: N)

日期：{date} 审查文件数：{count} 总问题数：{count}（CRITICAL: N, HIGH: N, MEDIUM: N, LOW: N）

Deterministic Health Scores

确定性健康评分

Component	Score	Grade	Key Issues
{name}	{n}	{A-F}	{summary}

组件	分数	等级	关键问题
{name}	{n}	{A-F}	{summary}

Critical (fix immediately)

CRITICAL（立即修复）

{file}:{line} : [{category}] {description}
- Fix: {suggested fix}

{file}:{line} : [{category}] {description}
- 修复方案：{suggested fix}

High (fix this sprint)

HIGH（本迭代修复）

Medium (fix when touching these files)

MEDIUM（修改相关文件时修复）

Low (nice to have)

LOW（可选优化）

Systemic Patterns

系统性模式

{pattern name}: Seen in {N} files. {description}. Fix: {approach}.

{pattern name}：出现在{N}个文件中。{description}。修复方案：{approach}。

Review Metadata

审查元数据

Waves executed: 0, 1, 2
Duration: {time}
Score pre-check: {pass/warn/fail}


**GATE**: Report file exists at `full-repo-review-report.md` and contains at
least the severity sections and deterministic scores.

---

执行流程：0、1、2
耗时：{time}
评分预检查：{通过/警告/失败}


**检查点**：`full-repo-review-report.md`已存在于仓库根目录，且至少包含严重程度章节和确定性评分。

---

Error Handling

错误处理

Error	Cause	Solution
No source files found	Wrong working directory or empty repo	Verify cwd is repo root with `ls agents/ skills/ scripts/`
score-component.py fails	Missing script or dependency	Proceed with warning; the LLM review still runs. Note gap in report.
comprehensive-review times out	Too many files for single session	Split into directory-scoped runs: scripts/, hooks/, agents/, skills/ separately
Report write fails	Permission or path issue	Try writing to `/tmp/full-repo-review-report.md` as fallback

错误	原因	解决方案
未发现源文件	工作目录错误或仓库为空	使用 `ls agents/ skills/ scripts/` 确认当前处于仓库根目录
score-component.py执行失败	脚本缺失或依赖问题	带警告继续执行；LLM审查仍会运行。在报告中注明该缺失。
comprehensive-review超时	单次会话处理文件过多	拆分为按目录执行的审查：分别处理scripts/、hooks/、agents/、skills/
报告写入失败	权限或路径问题	尝试作为备选方案写入 `/tmp/full-repo-review-report.md`

Anti-Patterns

反模式

Do NOT auto-fix findings

请勿自动修复问题

Why: Full-repo auto-fix touches too many files at once. Risk of cascading breakage is high and review of the fixes themselves would be a massive PR. Report findings for human triage.

原因：全仓库自动修复会同时修改大量文件。引发连锁故障的风险极高，且修复内容本身的审查会产生巨大的PR。应将问题写入报告供人工分类处理。

Do NOT skip the deterministic pre-check

请勿跳过确定性预检查

Why: score-component.py catches structural issues (missing YAML fields, no error handling section) cheaply. Skipping it wastes LLM tokens on issues a script can find in milliseconds.

原因：score-component.py可低成本捕获结构问题（如缺失YAML字段、无错误处理章节）。跳过该步骤会浪费LLM token在脚本可毫秒级发现的问题上。

Do NOT run on every PR

请勿在每个PR上运行

Why: This is expensive (all files through all waves). Use comprehensive-review for PR-scoped work. This skill is for periodic health checks.

原因：该操作成本高昂（所有文件经过全流程审查）。PR范围的工作请使用comprehensive-review。该skill仅用于定期健康检查。

Anti-Rationalization

反合理化

Rationalization	Why Wrong	Required Action
"Too many files, let's just review the important ones"	Cherry-picking defeats the purpose of full-repo review	Review ALL discovered files. If it's too large, split by directory -- don't skip.
"The score pre-check already found the issues"	Deterministic checks catch structure, not logic	Always run the full 3-wave review after pre-check
"We can auto-fix the obvious ones"	This skill produces a report, not patches	Write findings to the report. User decides what to fix and when.
"Wave 0 is slow, let's skip it"	Wave 0 per-package context is what makes full-repo review valuable	Run all three waves. No shortcuts on coverage.

合理化借口	错误原因	要求操作
"文件太多，我们只审查重要的文件吧"	选择性审查违背了全仓库审查的初衷	审查所有发现的文件。如果文件过多，按目录拆分——不要跳过。
"评分预检查已经发现了问题"	确定性检查仅捕获结构问题，无法发现逻辑问题	预检查后始终执行完整的三轮审查
"我们可以自动修复明显的问题"	该skill生成报告而非补丁	将问题写入报告。由用户决定修复内容和时机。
"Wave 0太慢了，我们跳过吧"	Wave 0的按包上下文是全仓库审查的核心价值所在	运行全部三轮流程。在覆盖范围上不要走捷径。

References

参考资料

Report Template -- Full structure for
```
full-repo-review-report.md
```
output

报告模板 ——
```
full-repo-review-report.md
```
输出的完整结构

full-repo-review

Original

Translation

Full-Repo Review : Codebase Health Check

全仓库审查：代码库健康检查

Operator Context

操作上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Default Behaviors (ON unless disabled)

默认行为（默认开启，可禁用）

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需启用）

Capabilities

能力范围

What This Skill CAN Do

该Skill可实现的功能

What This Skill CANNOT Do

该Skill不可实现的功能

Instructions

操作步骤

Phase 1: DISCOVER AND PRE-CHECK

阶段1：发现与预检查

Python scripts (exclude test files and pycache)

Python脚本（排除测试文件和__pycache__）

Hooks (exclude test files and lib/)

Hooks（排除测试文件和lib/）

Skills (SKILL.md files only)

Skills（仅SKILL.md文件）

Agents

Agents

Docs

Docs

Phase 2: REVIEW

阶段2：审查

Phase 3: REPORT

阶段3：报告

Full-Repo Review Report

全仓库审查报告

Deterministic Health Scores

确定性健康评分

Critical (fix immediately)

CRITICAL（立即修复）

High (fix this sprint)

HIGH（本迭代修复）

Medium (fix when touching these files)

MEDIUM（修改相关文件时修复）

Low (nice to have)

LOW（可选优化）

Systemic Patterns

系统性模式

Review Metadata

审查元数据

Error Handling

错误处理

Anti-Patterns

反模式

Do NOT auto-fix findings

请勿自动修复问题

Do NOT skip the deterministic pre-check

请勿跳过确定性预检查

Do NOT run on every PR

请勿在每个PR上运行

Anti-Rationalization

反合理化

References

参考资料

Python脚本（排除测试文件和pycache）