review-process

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Development Process Fitness Review

开发流程健康度评审

Judge how a repository is developed, not what its code does: whether a newcomer can set it up, whether checks actually run, how changes reach the default branch, and whether decisions are visible. Much of that evidence lives in git history rather than in any file, so this review reads both.

Reference: Fundamentals of Software Development, Fundamentals of Agile Software Development, Fundamentals of Software Project Management — see also Fundamentals

评估一个仓库是如何开发的，而不是它的代码具有什么功能：新成员能否完成设置、检查是否真正运行、变更如何进入默认分支，以及决策是否可见。大部分证据存在于 Git 历史而非任何单个文件中，因此本次评审会同时读取这两类证据。

参考：软件开发基础、敏捷软件开发基础、软件项目管理基础——另见基础。

Domain Knowledge

领域知识

```
references/rubric.md
```
is the scoring source: severity definitions, 1-10 anchors per dimension, N/A rules, accepted evidence locations, and the overall formula. It is short; read it first.
```
references/checklist.md
```
is what to check, grouped by the seven dimensions, including pitfalls a quick existence check misses.
```
scripts/git-evidence.sh
```
gathers the history and layout numbers the rubric uses.
```
references/wisdom.md
```
is optional background generated from the source articles (about 45k tokens). Never read it whole; grep it by heading when you need the reasoning behind a practice, such as
```
grep -n "Trunk-Based" references/wisdom.md
```
.

```
references/rubric.md
```
是评分依据：包含严重性定义、各维度的 1-10 分锚点、N/A 规则、可接受的证据位置以及总体计算公式。文件很短；请先阅读它。
```
references/checklist.md
```
是检查内容，按七个维度分组，并包含快速存在性检查容易遗漏的潜在问题。
```
scripts/git-evidence.sh
```
收集评分规则所依据的历史记录和布局数据。
```
references/wisdom.md
```
是由源文章生成的可选背景资料（约 45k tokens）。绝不整份读取；当需要了解某项实践背后的推理时，按标题进行 grep，例如
```
grep -n "Trunk-Based" references/wisdom.md
```
。

Configuration

配置

Invoke the resolver CLI to obtain effective weights and thresholds for the review target. Never load

fitness-config.json

directly.

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

is this skill's directory; the resolver ships two levels up in the plugin's

scripts/

. If your agent does not expand the variable, substitute the directory containing this

SKILL.md

Where

<target>

is the file or directory under review. The CLI walks up to discover any module override and merges it with the root config. Copy the

Config:

and

Effective weights:

lines from the resolver output into the report header (the template has the slots) as the provenance trail (AC-03.1, AC-08.2). The

effective

object inside the JSON block delimited by

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

carries

statusThresholds

, which override the default status bands in rubric.md. If the resolver is not at that path (for example a standalone install), use

scripts/fitness-config.py

from a checkout of the plugin; if none is available, write

Config: resolver unavailable (defaults)

and use the rubric.md bands.

调用解析器 CLI，获取评审目标的有效权重和阈值。绝不直接加载

fitness-config.json

。

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

是此 skill 的目录；解析器随插件提供，位于上两级的

scripts/

中。如果你的 Agent 无法展开该变量，请替换为包含此

SKILL.md

的目录。

<target>

是待评审的文件或目录。CLI 会向上遍历以发现模块级 override，并将其与根配置合并。请将解析器输出中的

Config:

和

Effective weights:

行复制到报告标题中（模板中已有相应占位符），作为来源追踪记录（AC-03.1、AC-08.2）。由

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

<!-- END_EFFECTIVE_CONFIG_JSON -->

注释标记包围的 JSON 代码块内，

effective

对象包含

statusThresholds

，它会覆盖 rubric.md 中的默认状态区间。如果解析器不在该路径下（例如独立安装），请使用从插件检出副本中的

scripts/fitness-config.py

；如果均不可用，请写入

Config: resolver unavailable (defaults)

并使用 rubric.md 中的区间。

Workflow

工作流

Load the rubric — Read
```
references/rubric.md
```
and
```
references/checklist.md
```
. Run the resolver above.
Scope — Identify the repository root containing the target and whether the user asked a specific question (for example "is this ready for contributors?"). That question shapes the Direct Answer and which findings lead.
Decide applicability — For each of the seven dimensions, decide whether anything in scope can be judged. Mark the rest
```
N/A — <reason>
```
per rubric.md; a missing artifact that should exist is a low score, not N/A.
Gather git evidence — Run
```
bash "${CLAUDE_SKILL_DIR}/scripts/git-evidence.sh" <repo-root>
```
. It is read-only and prints: commit counts and authors; conventional-commit rate and vague subjects over the last 100 non-merge commits; how changes reach the default branch (PR merge commits,
```
(#N)
```
squash subjects, direct commits on
```
--first-parent
```
); stale branches; root vs nested workflows; LICENSE/CONTRIBUTING/CODEOWNERS presence; lockfiles; README/CONTRIBUTING references sorted into
```
readme_paths_missing
```
(path-like refs, bare doc/config names like
```
RUN.md
```
,
```
uv run X.py
```
scripts, and
```
cd
```
targets that resolve nowhere; the strongest stale-doc evidence, with the deleting commit when one exists; script arguments are resolved from the last
```
cd
```
in the same code block),
```
readme_paths_elsewhere
```
(a tracked file ends with that path, or a script is not in the directory its
```
cd
```
implies: decide whether the doc means a subdirectory before citing),
```
readme_paths_ignored
```
(gitignored outputs, never a defect), and
```
readme_tokens_skipped
```
(model IDs, packages, domains, versions; not paths); and developer-specific absolute paths. If the script cannot run, use the equivalent commands directly:
- ```
git log --no-merges -n 100 --format=%s main | grep -cE '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)($.+$)?!?: '
```
  for the convention rate
- ```
git log --first-parent --merges --oneline main | wc -l
```
  and
```
git log --first-parent --no-merges --format=%s main | grep -cE '$#[0-9]+$$'
```
  for PR-merged changes; the remaining first-parent commits are direct pushes
- ```
git ls-files | grep '/\.github/workflows/'
```
  for nested workflows that never run
A shallow clone or a non-git directory makes history items N/A; say so instead of guessing.
Scan the repository — Walk
```
references/checklist.md
```
section by section with Glob, Grep, and Read: README and contributor docs, CI files, manifests and lockfiles per module, layout and config, setup scripts, ADRs and changelogs. Verify each pitfall the script flagged by opening the file before citing it.
Score and find — Score each applicable dimension against its rubric.md anchors. Record findings with severity from rubric.md and a location in one of the accepted forms.
Self-check, then write — Before writing the report, confirm: every
```
path:line
```
exists and says what the finding claims; every
```
commit <sha>
```
resolves; every finding has confidence >= 7; measured rates match the script output; the overall equals the stated computation; no secret values are reproduced (refer to them by file:line only). Then write the report.

加载评分规则——阅读
```
references/rubric.md
```
和
```
references/checklist.md
```
，并运行上述解析器。
确定范围——识别包含目标的仓库根目录，并确定用户是否提出了具体问题（例如“它准备好接受贡献者了吗？”）。该问题会影响“直接回答”以及哪些发现需要优先呈现。
判断适用性——对七个维度逐一判断范围内是否有可评判内容。其余维度按照 rubric.md 标记为
```
N/A — <原因>
```
；本应存在却缺失的产物应计为低分，而不是 N/A。
收集 Git 证据——运行
```
bash "${CLAUDE_SKILL_DIR}/scripts/git-evidence.sh" <repo-root>
```
。该脚本是只读的，会输出：提交数量和作者；最近 100 个非 merge commit 的 Conventional Commits 比率及含糊主题；变更进入默认分支的方式（PR merge commit、带
```
(#N)
```
的 squash subject、
```
--first-parent
```
上的直接 commit）；陈旧分支；根目录 workflow 与嵌套 workflow；LICENSE/CONTRIBUTING/CODEOWNERS 是否存在；lockfile；README/CONTRIBUTING 引用，并将其分类到
```
readme_paths_missing
```
（类似路径的引用、诸如
```
RUN.md
```
的裸文档或配置名称、
```
uv run X.py
```
脚本，以及无法解析到任何位置的
```
cd
```
目标；同时提供最有力的陈旧文档证据，并在存在时附上删除它的 commit；脚本参数根据同一代码块中最后一个
```
cd
```
进行解析）、
```
readme_paths_elsewhere
```
（某个受版本控制的文件以该路径结尾，或脚本不在其
```
cd
```
所指向的目录中；引用前应先判断文档是否意在描述子目录）、
```
readme_paths_ignored
```
（被 gitignore 的输出，绝不视为缺陷）以及
```
readme_tokens_skipped
```
（模型 ID、包、域名和版本；它们不是路径）；此外还会输出开发者特定的绝对路径。如果脚本无法运行，请直接使用等效命令：
- ```
git log --no-merges -n 100 --format=%s main | grep -cE '^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)($.+$)?!?: '
```
  ，用于计算 Conventional Commits 比率
- ```
git log --first-parent --merges --oneline main | wc -l
```
  和
```
git log --first-parent --no-merges --format=%s main | grep -cE '$#[0-9]+$$'
```
  ，用于统计通过 PR 合并的变更；其余 first-parent commit 为直接 push
- ```
git ls-files | grep '/\.github/workflows/'
```
  ，用于查找永远不会运行的嵌套 workflow
如果是浅克隆或目录不是 Git 仓库，则历史相关项目标记为 N/A；请明确说明，不要猜测。
扫描仓库——使用 Glob、Grep 和 Read，逐节检查
```
references/checklist.md
```
：README 和贡献者文档、CI 文件、各模块的 manifest 和 lockfile、目录布局与配置、安装脚本、ADR 和 changelog。引用脚本标记出的每个潜在问题之前，先打开相应文件进行核实。
评分并查找发现——根据 rubric.md 中的锚点评分每个适用维度。按照 rubric.md 记录严重性，并提供符合可接受形式的位置。
自检后编写报告——编写报告前确认：每个
```
path:line
```
都存在且内容支持该发现的描述；每个
```
commit <sha>
```
都能解析；每项发现的置信度均不低于 7；实测比率与脚本输出一致；总体分数等于所声明的计算结果；不复现任何 secret 值（仅通过 file:line 引用）。然后编写报告。

Confidence and Severity

置信度与严重性

Only report findings with confidence >= 7/10. For each finding, ask:

Did you observe it directly (a file you opened, a command you ran), rather than infer it from a name or convention?
Does it point to a location a maintainer can check:
```
path:line
```
,
```
path (absent)
```
,
```
commit <sha>
```
, or a
```
git log
```
measurement with its numbers?
Does it matter for how the project is developed today? A practice the project never claimed (Conventional Commits in a repo with no convention, PR review in a solo trunk-based repo) is not a defect unless the user's question or a written policy makes it one.
Is it a process gap rather than something another review owns (runtime reliability, test quality, code security)?

If any answer is no, leave it out. Missing a marginal finding costs less than a report full of noise.

Severity definitions (CRITICAL, HIGH, MEDIUM, LOW) with process examples are in

references/rubric.md

仅报告置信度 >= 7/10 的发现。针对每项发现，询问：

是否直接观察到问题（打开过相关文件或运行过相关命令），而不是根据名称或惯例推断？
是否指向维护者可以核查的位置：
```
path:line
```
、
```
path (absent)
```
、
```
commit <sha>
```
，或附带具体数字的
```
git log
```
测量结果？
是否会影响项目当前的开发方式？如果项目从未声称采用某项实践（例如，在没有相关约定的仓库中要求 Conventional Commits，或要求采用 PR 评审的 solo Trunk-Based 仓库），则不应视为缺陷，除非用户的问题或书面政策明确要求它。
这是否属于流程缺口，而不是应由其他评审负责的领域（运行时可靠性、测试质量、代码安全）？

如果任一答案为否，则不要报告。漏掉一项边缘发现，比提交一份充斥着噪声的报告代价更低。

严重性定义（CRITICAL、HIGH、MEDIUM、LOW）及其流程示例见

references/rubric.md

。

Scoring Dimensions (1-10 each)

评分维度（每项 1-10 分）

Score with the anchors in

references/rubric.md

;

references/checklist.md

lists what to inspect for each.

Documentation Quality — README completeness and accuracy, contributor guides, LICENSE text, architecture and decision docs, API docs
Development Workflow — CI that actually runs, automated tests and lint, branch strategy, commit conventions and message quality
Code Review Practices — How changes reach the default branch, PR templates, CODEOWNERS, PR size, policy vs practice
Dependency Management — Lockfiles per manifest, version bounds, update automation, vulnerability scanning, license compliance
Project Organization — Directory structure, module boundaries, configuration separation, entry points, .gitignore and tracked artifacts
Portability — Hardcoded absolute paths, configurable endpoints, OS-specific tooling, reproducible environments, line endings
Technical Leadership Signals — Vision and roadmap, decision records, iteration evidence, backlog and debt tracking, governance

根据

references/rubric.md

中的锚点评分；

references/checklist.md

列出了每个维度需要检查的内容。

文档质量——README 的完整性与准确性、贡献者指南、LICENSE 文本、架构与决策文档、API 文档
开发工作流——真正运行的 CI、自动化测试和 lint、分支策略、提交约定与消息质量
代码评审实践——变更进入默认分支的方式、PR 模板、CODEOWNERS、PR 规模、政策与实际实践
依赖管理——每个 manifest 对应的 lockfile、版本范围、更新自动化、漏洞扫描、许可证合规
项目组织——目录结构、模块边界、配置分离、入口点、.gitignore 和受版本控制的产物
可移植性——硬编码的绝对路径、可配置的端点、依赖特定 OS 的工具、可复现环境、行尾符
技术领导力信号——愿景与路线图、决策记录、迭代证据、backlog 与技术债务跟踪、治理机制

Output Format

输出格式

Produce a markdown report with this structure:

markdown

undefined

生成采用以下结构的 Markdown 报告：

markdown

undefined

Development Process Fitness Report

开发流程健康度报告

Target: <repository root, or the scoped path(s)> Config: <copied from resolver output> Effective weights: <copied from resolver output>

目标： <仓库根目录，或限定范围的路径> Config: <从解析器输出复制> Effective weights: <从解析器输出复制>

Direct Answer

直接回答

(Only when the user asked a specific question: answer it in 2-4 sentences, citing the findings that decide it.)

（仅当用户提出具体问题时：用 2-4 个句子回答，并引用决定答案的发现。）

Summary

摘要

Dimension	Score	Key Finding
Documentation Quality	X/10	...
Development Workflow	X/10	...
Code Review Practices	X/10	...
Dependency Management	X/10	...
Project Organization	X/10	...
Portability	X/10	...
Technical Leadership Signals	X/10	...
Overall	X/10	Status

(A dimension that does not apply shows

N/A — reason

in the Score column.)

Overall = mean of <list the scored dimensions> = X.X<, capped at 4.0 because of a CRITICAL finding>.

维度	评分	关键发现
文档质量	X/10	...
开发工作流	X/10	...
代码评审实践	X/10	...
依赖管理	X/10	...
项目组织	X/10	...
可移植性	X/10	...
技术领导力信号	X/10	...
总体	X/10	状态

（不适用的维度应在“评分”列中显示

N/A — 原因

。）

总体 = <已评分维度的平均值> = X.X<若存在 CRITICAL 发现，则上限为 4.0>。

Git Evidence

Git 证据

Commits: N total, N authors; last commit <date>
Conventional commits: N/100 (N%); vague subjects: N
Default branch integration: N PR merges, N squash-merged PRs, N direct commits (first-parent)
CI workflows at root: <list or none>; nested (never run): <list or none>

提交：共 N 个，N 位作者；最近提交于 <日期>
Conventional Commits：N/100（N%）；含糊主题：N
默认分支集成：N 个 PR merge，N 个 squash-merged PR，N 个直接 commit（first-parent）
根目录 CI workflow：<列表或 none>；嵌套且永远不会运行：<列表或 none>

Detailed Findings

详细发现

Finding 1: [Title]

发现 1：[标题]

Severity: CRITICAL / HIGH / MEDIUM / LOW
Confidence: X/10
Dimension: [which scoring dimension]
Location: path:line | path (absent) | commit <sha> | git log <command>: <numbers>
Description: What the issue is and why it matters.
Evidence: What you observed (quoted line, command output).
Impact: What goes wrong for contributors or quality.
Remediation: Concrete fix or specific steps.

(repeat for each finding, ordered by severity)

严重性： CRITICAL / HIGH / MEDIUM / LOW
置信度： X/10
维度： [评分维度]
位置： path:line | path (absent) | commit <sha> | git log <command>: <numbers>
描述： 问题是什么，以及它为何重要。
证据： 观察到的内容（引用行、命令输出）。
影响： 会对贡献者或质量造成什么后果。
修复建议： 具体修复方式或明确步骤。

（对每项发现重复此结构，并按严重性排序。）

Documentation Quality (X/10)

文档质量（X/10）

Evidence: [specific files and observations] Strengths: ... Gaps: ...

[Repeat for each dimension]

证据： [具体文件及观察结果] 优势： ... 差距： ...

[对每个维度重复]

Action Items (up to 5, by impact)

行动项（最多 5 项，按影响排序）

[CRITICAL/HIGH/MEDIUM] Description -- location
...

[CRITICAL/HIGH/MEDIUM] 描述 -- 位置
...

Checklist Reference

检查清单参考

See references/checklist.md in the review-process skill for the full process checklist.

有关完整的流程检查清单，请参阅 review-process skill 中的 references/checklist.md。

Reference

参考

Based on Fundamentals of Software Development, Fundamentals of Agile Software Development, Fundamentals of Software Project Management, and guidance from https://jeffbailey.us/categories/fundamentals/


Write the report to `docs/process-review.md` at the root of the repository that contains the target, unless the user gives a path. Create `docs/` if needed. For a review scoped to a subdirectory or file set, write `docs/process-review-<scope-slug>.md` instead (for example `docs/process-review-match-ranker.md`) so a scoped run does not replace the whole-repo report.

基于软件开发基础、敏捷软件开发基础、软件项目管理基础，以及 https://jeffbailey.us/categories/fundamentals/ 中的指导。


除非用户指定路径，否则请将报告写入目标所在仓库根目录的 `docs/process-review.md`。如有必要，请创建 `docs/`。对于范围限定为某个子目录或文件集的评审，请改为写入 `docs/process-review-<scope-slug>.md`（例如 `docs/process-review-match-ranker.md`），以免限定范围的评审覆盖整个仓库的报告。