code-review

コードレビュー

最近の変更に対して、シニアレベルの徹底的なコードレビューを実施します。複雑なロジック、アーキテクチャ、エッジケースを人が重点的にレビューします。スタイルのチェックは自動ツールに任せます。

関連スキル：

• kavak-documentation - Kavak 固有のパターン、ロギング／メトリクスの標準、GitLab CI テンプレートを確認します
• レビュー時に Kavak のベストプラクティスを確認するには、kavak-platform/platform_docs_search MCP ツールを使用します

クイックスタート

# 1. Get review range
BASE_SHA=$(git rev-parse HEAD~1)  # or: git merge-base main HEAD
HEAD_SHA=$(git rev-parse HEAD)

# 2. See what changed
git diff --stat $BASE_SHA..$HEAD_SHA
git diff --name-only $BASE_SHA..$HEAD_SHA --diff-filter=ACMR

# 3. After review, run quality gates (detect project type)

言語別の品質ゲートコマンド：

言語	Lint	ビルド	テスト
Go	golangci-lint run	go build ./...	go test ./...
Node/TS	npm run lint	npm run build	npm test
Python	ruff check .	python -m py_compile	pytest
Java	./mvnw checkstyle:check	./mvnw compile	./mvnw test

レビューのタイミング

このワークフローは、セルフレビューとピアレビューの両方に適用されます。

必須： タスクの完了後、機能の実装後、マージ前。

有用： 行き詰まったとき（新たな視点を得るため）、リファクタリング前（ベースラインを確認するため）、複雑なバグの修正後。

レビューの心構え

• 急がず、徹底的に - 結論を出す前に、関連するコードをすべて読みます
• 証拠に基づく - 実行パスをたどり、バグがあると決めつけません
• 指摘するだけでなく、修正する - 問題を特定し、解決します
• 範囲を絞る - 効果的なレビューのため、一度にレビューするのは400行未満にします

ワークフロー

1. 差分の範囲を特定する

変更されたファイルをすべて特定します。

git diff --name-only HEAD~1 --diff-filter=ACMR

リスト内の各ファイルについて、実際の差分ハンクがないものはスキップします。

2. 意図と要件を把握する

コードをレビューする前に、コードが何をすべきかを把握します。

• 元のタスク／課題：何が依頼されましたか？
• プロダクトへの影響：ユーザーに何を提供しますか？
• 受け入れ基準：「完了」とは何ですか？

次のように確認します。「実装は要件を満たしていますか？」

3. 各ファイルをレビューする

変更されたファイルと各差分ハンクについて、既存のコードベースの文脈に照らして評価します。

必須： Critical／Major の問題を指摘する前に、実行パス全体をエンドツーエンドでたどります。問題を防ぐ防御的なコードがないことを確認します。エラーパス、キャンセル、エッジケースを考慮します。

4. レビュー項目

次の項目に重点を置きます。アーキテクチャ（パターンへの適合、結合の回避）、正確性（エッジケース、エラー処理）、セキュリティ（入力検証、シークレット、OWASP）、パフォーマンス（N+1 クエリ、メモリ）、ロギング／メトリクス（カーディナリティの急増）。スタイルのチェックはリンターに任せます。

11項目すべてを含む完全なチェックリスト：references/checklist.md ロギングとメトリクスの標準：references/logging-metrics-review.md

5. プロジェクトのルールを確認する

必須： 次のファイルやフォルダーにあるルールを確認し、遵守します。

• .claude/CLAUDE.md または CLAUDE.md（ルート）
• .cursor/rules/ フォルダー
• AGENTS.md
• そこに定義されているすべてのパターンと規約に従います

6. 問題を報告して修正する

確認済みの問題ごとに、次を記載します。

• ファイル：<path>:<line-range>
• 問題：1行の要約
• 修正：簡潔な変更案

重要度：

• Critical（P0）：セキュリティの脆弱性、データ損失、クラッシュ
• Major（P1）：重大なバグ、パフォーマンスの問題、アーキテクチャ違反
• Minor（P2）：コードスタイル、軽微な改善
• Enhancement（P3）：あると望ましい改善

必須：問題を特定したら、すべて直ちに修正します。

1. 優先度の高いものから開始します（Critical → Major → Minor）
2. 問題ごとに次を実行します。
   • コードを修正する
   • 修正によって問題が発生しないことを確認する
   • チェックポイントコミット：git add -A && git commit -m "fix: brief description"
3. すべての問題が解決するまで続けます

7. 品質ゲートを実行する

すべての問題を修正した後、プロジェクトの種類に応じて lint → build → test を実行します（「クイックスタート」の表を参照）。

いずれかのゲートに失敗した場合は、直ちに修正してコミットします。

8. 最終レポート

次の構成で出力します。

### Strengths

[What's well done - be specific with file:line references]

### Issues Found & Fixed

- **Critical**: [count] - [brief list]
- **Major**: [count] - [brief list]
- **Minor**: [count] - [brief list]

### Quality Gates

- Lint: ✓/✗
- Typecheck: ✓/✗
- Build: ✓/✗
- Tests: ✓/✗

### Assessment

**Ready to proceed?** [Yes / Yes with notes / No - needs fixes]
**Reasoning:** [1-2 sentence technical assessment]

問題がない場合：「コードレビューが完了しました。問題は見つかりませんでした。すべての品質ゲートに合格しました。作業を進める準備ができています。」

参考資料

参考資料	目的
references/checklist.md	詳細なレビュー用チェックリスト
references/severity-guide.md	問題の重大度を分類する方法
references/common-issues.md	よくある問題（TypeScript/Node）
references/common-issues-go.md	よくある問題（Go）
references/security-owasp.md	OWASP Top 10 セキュリティチェックリスト
references/feedback-guide.md	建設的なフィードバックの方法
references/logging-metrics-review.md	ログ形式とメトリクスのカーディナリティ基準
references/self-review-workflow.md	開発中の自動セルフレビュー

ベストプラクティス

1. 推測しない - 問題を指摘する前に、関連するコードをすべて読む
2. すぐに修正する - 報告するだけでなく、修正してコミットする
3. チェックポイントコミット - ロールバックしやすいように、修正ごとに個別にコミットする
4. まず検証する - バグがあると主張する前に、実行経路をたどる
5. プロジェクトルールを優先する - .cursor/rules/ と AGENTS.md を必ず確認する
6. 速やかに対応する - チームメイトの作業を妨げないよう、速やかにレビューする
7. 範囲を限定する - 効果的にレビューするため、一度にレビューするのは400行未満にする

原則：レビュー → 修正 → 検証 → コミット。問題を特定するだけで修正しないレビューは不完全です。