code-quality

コード品質

レビュー、リファクタリング、デバッグを検証ゲートと組み合わせて、体系的にコードを改善します。

モジュールの選択

必要なこと	モジュール	参照
フィードバックを受け取る	レビュー	references/code-review-reception.md
レビューを依頼する	レビュー	references/requesting-code-review.md
完了を宣言する前に検証する	レビュー	references/verification-before-completion.md
複雑さを軽減する	リファクタリング	references/oop-refactoring-catalog.md
関数型パターン	リファクタリング	references/functional-refactoring-patterns.md
コードの臭いを見つける	リファクタリング	references/code-smells-reference.md
テスト戦略	リファクタリング	references/testing-strategies.md
バグを調査する	デバッグ	references/systematic-debugging.md
根本原因を追跡する	デバッグ	references/root-cause-tracing.md
検証を追加する	デバッグ	references/defense-in-depth.md
修正を検証する	デバッグ	references/verification.md

---

基本原則

YAGNI、KISS、DRY — 常にこれらを守ってください。

率直に、遠慮なく、要点をまっすぐ伝え、簡潔にしてください。

社交上の配慮より技術的な正確さを優先してください。 実装前に検証してください。推測する前に質問してください。主張する前に根拠を示してください。

---

コードレビュー

フィードバックを受け取る

パターン： 読む → 理解する → 検証する → 評価する → 応答する → 実装する

ルール：

• ❌ 形だけの同意は禁止（「おっしゃるとおりです！」「いい指摘ですね！」）
• ❌ 検証前の実装は禁止
• ✅ 要件を言い換えて確認し、質問し、理由を添えて異議を唱えてください
• ✅ YAGNI を確認するため、提案を実装する前に grep で使用箇所を検索してください

情報源：

• 人間のパートナー → 理解してから実装する
• 外部レビュアー → 実装前に技術的に検証する

レビューを依頼する

タイミング： 主要機能の実装後、マージ前、複雑な修正後

手順：

1. SHA を取得します：BASE_SHA=$(git rev-parse HEAD~1)、HEAD_SHA=$(git rev-parse HEAD)
2. /code-review を実行し、WHAT、PLAN、SHA、DESCRIPTION を渡します
3. Critical は直ちに修正し、Important は先に進む前に修正し、Minor は記録します

検証ゲート

このセッションで結果を証明するコマンドを実行し、その出力を読んでから結果を主張してください。その根拠がなければ、主張は推測にすぎません。

ゲート： 特定する → 実行する → 読む → 検証する → その後で主張する

レビューの指摘事項（自分のものでもサブエージェントのものでも）を報告する前に、さらに次の4点を確認してください。

1. ガード： 同じ経路上で検索したガードの名前を挙げ、それがなぜバグを防がないのか説明してください。
2. 意図： .okf/ やその他のプロジェクトドキュメントを検索し、その振る舞いを確認してください。意図した動作として記載されている場合、それはバグではなくポリシー上の問題です。
3. 起源： コミットを原因とする前に、git log -S または git show <sha>^:<file> を実行してください。コミットメッセージから過去の動作を推測しないでください。
4. 行番号： エージェントの要約ではなく、自分でファイルを読んで確認した行番号を示してください。

---

リファクタリング

考え方

徹底的にシンプルにしてください。振る舞いは厳密に維持してください。すべてを測定してください。

リファクタリングは毎回、小さく安全に行い、すぐにテストし、測定可能な改善につなげてください。

手順

1. 評価 - ベースラインの指標を取得し、コードの臭いを特定し、技術的負債を分類します
2. セーフティネット - テストカバレッジを確認し、特性テストを追加します
3. レッド・グリーン・リファクタリング - 失敗するテストを書き、最小限の実装で通し、設計を改善します
4. パターンの適用 - SOLID、デザインパターン、関数型の変換を適用します
5. 検証 - 改善を測定し、振る舞いが維持されていることを確認します

コードの臭い（5つのカテゴリ）

1. 肥大化： 長すぎるメソッド、大きすぎるクラス、長すぎるパラメーターリスト
2. OO の誤用： Switch 文、一時フィールド
3. 変更を妨げるもの： 発散する変更、ショットガン手術
4. 不要なもの： 重複コード、デッドコード、怠惰なクラス
5. 結合の問題： 機能への執着、不適切な親密さ

よく使うパターン

OOP： メソッドの抽出、インライン化、一時変数をクエリに置き換える、ガード節 関数型： Map／Filter／Reduce、純粋関数、合成、不変性

---

デバッグ

核心原則

根本原因を調査する前に修正してはいけません

手当たり次第の修正は時間を浪費し、新たなバグを生みます。

4つの手法

1. 系統的なデバッグ（references/systematic-debugging.md）

• フェーズ 1：根本原因の調査
• フェーズ 2：パターン分析
• フェーズ 3：仮説の検証
• フェーズ 4：実装

2. 根本原因の追跡（references/root-cause-tracing.md） コールスタックをさかのぼり、最初のトリガーを見つけます。

3. 多層防御（references/defense-in-depth.md） 各レイヤーで検証します：入口 → ビジネスロジック → 環境 → デバッグ

4. 検証（references/verification.md） コマンドを実行します。出力を読みます。その後で結果を報告します。

クイックリファレンス

Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md
  Found root cause? → defense-in-depth.md
  About to claim success? → verification.md

危険信号

次のように考えたら、立ち止まってください：

• 「とりあえず応急処置して、後で調査しよう」
• 「Xを変えて試してみるだけ」
• 「たぶんXが原因だから、修正してみよう」
• 「これで動くはず」／「直ったようだ」

---

リファレンス

コードレビュー

• references/code-review-reception.md - 対応プロトコル
• references/requesting-code-review.md - 依頼手順
• references/verification-before-completion.md - 検証のチェックポイント

リファクタリング

• references/oop-refactoring-catalog.md - Martin Fowlerのパターン
• references/functional-refactoring-patterns.md - 関数型プログラミングの変換
• references/code-smells-reference.md - 23のコードスメル、5つのカテゴリ
• references/testing-strategies.md - 特性テスト、TDD

デバッグ

• references/systematic-debugging.md - 4フェーズのフレームワーク
• references/root-cause-tracing.md - コールスタック分析
• references/defense-in-depth.md - 多層検証
• references/verification.md - 検証プロトコル

---

要点

1. レビュー： 社交的な振る舞いより技術的な厳密さを重視します
2. リファクタリング： 小さく、安全に、テストし、測定できるようにします
3. デバッグ： まず根本原因を特定し、一度で修正します
4. 常に： 主張する前に証拠を確認します

検証します。疑問を持ちます。それから実装します。証拠を確認します。それから報告します。