Back to Details

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
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
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
find skills/ -name "SKILL.md" 2>/dev/null

Agents

Agents

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

Docs

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

确定性健康评分

ComponentScoreGradeKey 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

错误处理

ErrorCauseSolution
No source files foundWrong working directory or empty repoVerify cwd is repo root with 
ls agents/ skills/ scripts/
score-component.py failsMissing script or dependencyProceed with warning; the LLM review still runs. Note gap in report.
comprehensive-review times outToo many files for single sessionSplit into directory-scoped runs: scripts/, hooks/, agents/, skills/ separately
Report write failsPermission or path issueTry 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

反合理化

RationalizationWhy WrongRequired Action
"Too many files, let's just review the important ones"Cherry-picking defeats the purpose of full-repo reviewReview 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 logicAlways run the full 3-wave review after pre-check
"We can auto-fix the obvious ones"This skill produces a report, not patchesWrite 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 valuableRun 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
    输出的完整结构