pre-ship-review

发布前审查

在任何检查点（PR、发布、里程碑）发布代码前进行结构化质量审查：捕获发生在集成边界上的问题——在这些边界处，契约、示例、常量和测试必须彼此一致。

核心论点：AI 生成的代码擅长构建独立组件，却会系统性地在组件之间的边界处出错。此技能会系统检查这些边界。

自我演进的技能：此技能会随着使用而改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要延后。仅针对真实且可复现的问题进行更新。

何时使用此技能

在发布任何重要代码前使用：

• 涉及多个相互连接的新模块的拉取请求
• 整合多位贡献者或多个分支工作的发布
• 必须通过质量门槛才能继续推进的里程碑
• 任何需要验证含有示例、跨文件常量或接口扩展的代码的检查点

以下情况无需使用：单文件外观调整、仅更新文档、依赖项升级。

---

TodoWrite 任务模板

必须执行：开始审查前，选择并加载合适的模板。

模板 A：新功能发布

1. Detect changed files and scope (git diff --name-only against base branch)
2. Run Phase 1 - External tool checks (Pyright, Vulture, import-linter, deptry, Semgrep, Griffe)
3. Run Phase 2 - cc-skills orchestration (code-hardcode-audit, dead-code-detector, pr-gfm-validator)
4. Run Phase 2 conditional checks based on file types changed
5. Phase 3 - Verify every function parameter has at least one caller passing it by name
6. Phase 3 - Verify every config/example parameter maps to an actual function kwarg
7. Phase 3 - Check for architecture boundary violations (hardcoded feature lists, cross-layer coupling)
8. Phase 3 - Verify domain constants and formulas are correct (cross-reference cited sources)
9. Phase 3 - Audit test quality - do tests test what they claim (not side effects)?
10. Phase 3 - Check for implicit dependencies between new components
11. Phase 3 - Look for O(n^2) patterns where O(n) suffices
12. Phase 3 - Verify error messages give actionable guidance
13. Phase 3 - Confirm examples reflect actual behavior, not aspirational behavior
14. Compile findings report with severity and suggested fixes

模板 B：错误修复发布

1. Verify the fix addresses root cause, not symptom
2. Verify the fix does not mask information flow
3. Check that new test reproduces the original bug (fails without fix)
4. Run Phase 1 - External tool checks on changed files
5. Run Phase 2 - cc-skills checks on changed files
6. Verify constants consistency if any values changed
7. Compile findings report

模板 C：重构发布

1. Verify all callers updated to match new signatures
2. Run Phase 1 - External tool checks (especially Griffe for API drift)
3. Run Phase 2 - cc-skills checks (especially dead-code-detector)
4. Verify examples/docs updated to match new parameter names
5. Verify no dead imports from removed features
6. Check for introduced cross-boundary coupling
7. Compile findings report

---

三阶段工作流

阶段 1：外部工具检查（约 15 秒，可并行）

对已更改的文件运行静态分析工具。未安装的工具可跳过（优雅降级）。

Detect scope:
  git diff --name-only $(git merge-base HEAD main)...HEAD

Run in parallel:
  pyright --outputjson <changed_py_files>          # Type contracts
  vulture <changed_py_files> --min-confidence 80   # Dead code / YAGNI
  lint-imports                                      # Architecture boundaries
  deptry .                                          # Dependency hygiene
  semgrep --config .semgrep/ <changed_files>        # Custom pattern rules
  griffe check --against main <package>             # API signature drift

各工具的检查内容：

工具	反模式	安装
Pyright（严格模式）	接口契约、返回类型、跨文件类型错误	pip install pyright
Vulture	死代码、未使用的常量/导入（YAGNI）	pip install vulture
import-linter	架构边界违规、禁止的导入	pip install import-linter
deptry	未使用/缺失/传递依赖	pip install deptry
Semgrep	非确定性、静默吸收参数、禁止的模式	brew install semgrep
Griffe	破坏性 API 变更、与基础分支相比的签名偏移	pip install griffe

优雅降级：如果某个工具未安装，记录警告并跳过。绝不要因为缺少一个可选工具而导致整个审查失败。

详细的工具操作流程请参阅 自动化检查参考。 安装说明请参阅 工具安装指南。

阶段 2：cc-skills 编排（约 30 秒，可由子 Agent 并行执行）

调用可补充外部工具的现有 cc-skills。

始终运行：

• code-hardcode-audit -- 硬编码值、魔法数字、泄露的密钥
• dead-code-detector -- 多语言死代码检测（Python、TypeScript、Rust）
• pr-gfm-validator -- PR 描述中的链接有效性（创建 PR 时）

根据已更改的文件类型有条件地运行：

条件	要调用的技能
Python 文件有更改	impl-standards（错误处理、常量、日志记录）
更改了 500 行以上	code-clone-assistant（重复代码检测）
插件/钩子文件有更改	plugin-validator（结构、静默失败）
Markdown/文档有更改	link-validation（失效链接、路径策略）

阶段 3：人工判断审查（Claude 辅助）

这些检查需要理解意图、领域正确性和架构适用性。请逐项手动检查。

检查 1：架构边界

• “核心”层中的新代码是否引用了“插件”或“能力”层中的名称？
• 是否存在硬编码的功能/插件名称列表？（违反边界）
• 若要添加另一个此类功能实例，是否需要修改核心代码？

检查 2：领域正确性

• 数学公式是否正确？请与引用的论文交叉核对。
• 常量的标注是否正确？（例如，“每日”常量应使用每日值）
• 单位和时间段是否匹配？（年利率与日利率、季度 λ 与月度 λ）

检查 3：测试质量

• 每项测试是否都在验证其声称要测试的具体函数？
• 还是在测试副作用？（函数 A 测试函数 B，而函数 B 会在内部调用 A）
• 是否覆盖了边界情况？（空输入、NaN、单个元素、除以零）

检查 4：依赖透明度

• 如果组件 A 需要先运行组件 B，是否对此有文档说明？
• 排序要求是否在接口中明确说明，而不只是出现在示例中？

检查 5：性能

• 是否存在对同一数据进行嵌套循环的情况？（可能导致 O(n^2)）
• 是否存在可以改为滚动窗口或全样本操作的扩展窗口操作？
• 是否存在可以向量化的逐元素操作？

检查 6：错误消息质量

• 错误消息是否告诉用户该怎么做，而不只是说明出了什么问题？
• 验证错误是否指出了出错的具体参数/值？

检查 7：示例准确性

• 示例展示的功能是否确实能在代码中运行？
• 示例中的参数是否会被 **kwargs 或 **_ 悄然吸收？

详细的检查流程请参阅判断检查参考。

---

通用发布前检查清单

Phase 1 (Tools):
- [ ] Pyright strict passes on changed files (no type errors)
- [ ] Vulture finds no unused code in new files (or allowlisted)
- [ ] import-linter passes (no architecture boundary violations)
- [ ] deptry passes (no unused/missing dependencies)
- [ ] Semgrep custom rules pass (no non-determinism, no silent param absorption)
- [ ] Griffe shows no unintended API breaking changes vs base branch

Phase 2 (cc-skills):
- [ ] code-hardcode-audit passes (no magic numbers or secrets)
- [ ] dead-code-detector passes (no unused code)
- [ ] PR description links valid (pr-gfm-validator)

Phase 3 (Judgment):
- [ ] No new cross-boundary coupling introduced
- [ ] Domain constants and formulas are mathematically correct
- [ ] Tests actually test what they claim (not side effects)
- [ ] Implicit dependencies between components are documented
- [ ] No O(n^2) where O(n) suffices
- [ ] Error messages give actionable guidance
- [ ] Examples reflect actual behavior, not aspirational behavior

---

反模式目录

此技能基于 9 种集成边界反模式的分类法构建。完整目录包含示例、检测启发式和修复方法，请参阅反模式目录。

#	反模式	检测方法
1	接口契约违规	Pyright + Griffe + 手动追踪
2	误导性示例	Semgrep + 手动对比配置与代码
3	架构边界违规	import-linter + 手动审查
4	领域常量错误	Semgrep + 领域专业知识
5	测试缺口	mutmut + 手动测试审查
6	非确定性	Semgrep 自定义规则
7	YAGNI	Vulture + dead-code-detector
8	隐藏依赖	手动依赖追踪
9	性能反模式	手动复杂度分析

---

更改后检查清单

修改此技能后：

• 反模式目录反映真实情况中的发现
• 工具安装指南包含当前版本和命令
• TodoWrite 模板涵盖三种发布类型
• 通用检查清单完整且无冗余
• 所有 references/ 链接均可正常访问
• 将更改追加到 references/evolution-log.md

故障排查

问题	原因	解决方案
未找到工具	未安装外部工具	按照 tool-install-guide.md 安装，或跳过（优雅降级）
Vulture 误报过多	框架入口点看起来未被使用	创建允许列表：vulture --make-whitelist > whitelist.py
Semgrep 速度太慢	扫描大型代码库	仅针对更改的文件：semgrep --include=<changed>
import-linter 没有契约	项目未配置	在 pyproject.toml 中添加 [importlinter] 部分
Griffe 报告误报的破坏性更改	有意进行的 API 更改	使用 griffe check --against main --allow-breaking
第 3 阶段没有发现问题，但审查者发现了问题	新的反模式类别	添加到目录和 evolution-log.md
cc-skill 未触发	Skill 未安装到 marketplace	使用 /plugin list 检查

---

参考文档

如需详细信息，请参阅：

• 自动化检查参考 -- 第 1 阶段外部工具流程
• 判断检查参考 -- 第 3 阶段人工判断流程
• 反模式目录 -- 包含示例的完整 9 类分类体系
• 工具安装指南 -- 所有外部工具的安装和设置
• 演进日志 -- 更改历史

执行后反思

此技能完成后，在结束任务前进行反思：

0. 确定自身位置。 — 使用 Glob 搜索此技能的名称，找到此 SKILL.md 的规范路径，然后再进行编辑。所有修正都针对此文件及其同级的 references/ — 绝不修改其他文档。
1. 哪里出了问题？ — 修复导致问题的指令。如果问题可能再次发生，将其添加为反模式。
2. 哪些方面比预期更好？ — 将其提升为推荐做法，并记录原因。
3. 哪些内容出现偏差？ — 如果脚本、参考资料或外部依赖不再符合实际情况，立即修正。
4. 记录下来。 — 每项更改都要在 evolution-log 中记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切。

---

---