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

---

3 フェーズのワークフロー

フェーズ 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 (strict)	インターフェース契約、戻り値の型、ファイル間の型エラー	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

適切な縮退動作：ツールがインストールされていない場合は、警告を記録してスキップします。任意のツールが 1 つ不足していることを理由に、レビュー全体を失敗させないでください。

ツールの詳しい手順については、自動チェックのリファレンスを参照してください。 インストール手順については、ツールのインストールガイドを参照してください。

フェーズ 2：cc-skills によるオーケストレーション（約 30 秒、サブエージェントで並列実行可能）

外部ツールを補完する既存の 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 のテストが、内部で A を呼び出す関数 B をテストしている）
• エッジケースは網羅されていますか？（空の入力、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 のテンプレートで 3 種類の出荷方式を網羅している
• 共通チェックリストに漏れや重複がない
• 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 が起動しない	スキルがマーケットプレイスにインストールされていない	/plugin list で確認します

---

参考ドキュメント

詳細については、以下を参照してください。

• 自動チェックのリファレンス -- フェーズ 1 の外部ツールの手順
• 判断チェックのリファレンス -- フェーズ 3 の人間による判断手順
• アンチパターンカタログ -- 例を含む全 9 カテゴリの分類
• ツールインストールガイド -- すべての外部ツールのインストールとセットアップ
• 進化ログ -- 変更履歴

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ってください。

0. 自分の場所を特定します。 — 編集する前に、この SKILL.md の正規パスを見つけます（このスキルの名前で Glob を実行します）。修正対象はこのファイルとその同階層の references/ のみです。他のドキュメントは対象にしません。
1. 何が失敗しましたか？ — 原因となった指示を修正します。再発する可能性がある場合は、アンチパターンとして追加します。
2. 予想以上にうまくいったことは何ですか？ — 推奨プラクティスにします。その理由を記録します。
3. 何が実態と乖離しましたか？ — スクリプト、リファレンス、外部依存関係のいずれかが実態と一致しなくなっている場合は、今すぐ修正します。
4. 記録します。 — すべての変更について、きっかけ、修正内容、根拠を含む evolution-log のエントリーを追加します。

先送りしないでください。次回の実行には、ここに残した状態が引き継がれます。

---

---