clean-code

クリーンコード

コードは、人が読んだり、変更したり、削除したりするためのものです。設計、命名、複雑さ、コメントの4つを確認します。それぞれに、感覚ではなく具体的な基準があります。

サブスキルへの案内

関数、クラス、ファイル内で動作を保ったままリファクタリングする場合は、 refactoring/SKILL.mdを読んでください。コードの臭いの一覧、手法の選択ガイド、 ガードレールが記載されています。動作を変更する場合（testing（TCRDD のリファレンス））や、ファイルをまたぐ依存関係を整理する場合 （mikado-method）には使用しないでください。

1. 人が把握できる規模のメンタルモデルを設計する

同じニーズが独立して少なくとも3回現れるまでは、具体的な解決策を優先してください。抽象化は書くのは簡単ですが、後から読む人が理解して追跡するにはコストがかかります。将来必要になるかもしれないという仮定は、抽象化を追加する理由にはなりません。

症状を別の特例分岐で覆い隠すのではなく、原因そのものに対処してください。優れた修正は、コード内の経路を減らすか、問題を引き起こした共通ルールを修正します。

チャンクは、リポジトリ → サービス → モジュール → 関数という境界で、読者がタスクの範囲外を無視できるようにします。各チャンクは、その内部だけで理解できる一貫性を保ってください。スライスは、可観測性、復旧可能性、アクセシビリティ、セキュリティなど、そうした境界を横断する関心事です。影響を受けるチャンクを通る経路を見つけやすく、追いやすくしてください。ひとつのチャンクを整然と見せるためだけに、横断的な関心事を隠してはいけません。

複雑さの中には、ドメインに由来するものもあります。税務、コンプライアンス、その他の実際のルールを、単純に見えても誤ったモデルに押し込めないでください。最短の表現ではなく、新しい読者が追加の文脈なしに正しく理解できる設計を優先してください。

2. 命名

モジュール、ファイル、関数、クラス、変数の名前はすべて、それだけで意図が伝わる必要があります。何をするのかを知るために、本体を読む必要があってはいけません。

運用上の確認項目を、次の順に示します。

1. 意図が伝わる：名前には、どのように処理するかではなく、何をするか、何を保持するかを表します（dではなくelapsedTimeInDays）。名前の説明にコメントが必要なら、その名前は不適切です。
2. 混同しない：見分けにくい名前の組み合わせ（userListとusersListなど）は使わないでください。また、実際にList型でないものをlistと呼ばないでください。同じ概念に複数の名前を使ったり、異なる概念に同じ名前を使ったりしないでください。
3. ノイズを減らす：意味を加えないノイズ語（data、info、manager、object、Impl）を取り除いてください。ProductInfoとProductの両方がある場合、実際には名前で区別できません。短いほうを優先し、残りは文脈（フォルダー、型）に任せてください。
4. 頭字語や略語を避ける：calcInvTotではなくcalculateInvoiceTotalを使ってください。ただし、ドメインで正式名称より一般的な頭字語（id、url、html）は例外です。その場合も、大文字・小文字の表記規則をひとつ選び、一貫して使ってください。
5. 検索しやすくする：短いループのインデックスを除き、マジックナンバーや一文字の名前は使わないでください。5やnではなくMAX_RETRY_COUNTを使ってください。grepで検索できる名前は、検索できない名前より優れています。
6. 品詞を使い分ける：クラスや型には名詞句（Invoice、PaymentProcessor）を、関数やメソッドには動詞句（calculateTotal、isValid、hasExpired）を使ってください。名詞のような名前の関数は要注意です。返す値にちなんだ名前を付けるべきなのに付けていないか、処理を詰め込みすぎている可能性があります。
7. 概念ごとに単語を統一する：コードベース全体で、ひとつの操作にはひとつの動詞を選んでください。同じ種類の操作にfetch／retrieve／getを混在させたり、同じ種類の変更にadd／insert／appendを混在させたりしないでください。新しい類義語を導入する前に、コードベースに既存の規則がないか確認してください。

3. 循環的複雑度

関数ごとの上限：

• 人間が作成したコード：≤ 4
• エージェントが作成したコード（Claude／AI 生成）：≤ 6

数え方：1から始め、if、else if、case、for、while、catch、条件式内の &&／||、三項演算子ごとに+1します。関数が上限を超えたら、完了と見なす前にリファクタリングしてください。そのままにして先へ進んではいけません。

振る舞いを保つ変更では、単に上限に収めるためだけに関数を抽出するのではなく、リファクタリングのサブスキルを使って手法を選んでください。

数値を達成することだけを目的にリファクタリングしてはいけません。無理のある4より、すっきりした5のほうが優れています。上限は詳しく確認するきっかけであり、うまく取り繕うための絶対条件ではありません。

4. コメント

大した問題ではありません。コメントを神聖視したり、指標を満たすために書いたりしないでください。理解にコメントが必要なコードは、通常、まず書き直すべきです（より適切な名前を付ける、関数を抽出するなど）。ただし、何かを伝える方法としてコメントが最も明確なら、そのまま書いてください。

• コードが何をするかを説明するコメントより、自己文書化されたコードを優先してください。
• コメントは「なぜ」を説明する場合に価値があります。たとえば、すぐには分からないトレードオフ、外部制約への回避策、「明白な」方法から意図的に逸脱した理由などです。
• コードを言い換えただけのコメント（i++ の上にある // increment i など）は削除してください。
• 古くなったコメント（コードが現在は行わない振る舞いを説明するコメント）は、コメントがない状態よりも悪いため、見つけたら削除するよう指摘してください。
• TODO は、先送りした理由や、できれば担当者・時期など、実質的な情報を含むなら問題ありません。// TODO だけの記述は残す価値がありません。

5. CUPID レビュー

ユーザーがそのフレームワーク、または設計品質全般のレビューを求めた場合は、CUPID を使用してください。まず、言語、目的、ローカルの慣習、対象範囲を確認します。各特性について、具体的なコードを挙げ、次の形式を使ってください。

### C — Composable
**Rating:** 🟢 Strong / 🟡 Moderate / 🔴 Weak
**Observations:** specific code evidence
**Suggestions:** a direction-of-travel improvement

特性	確認する点
合成可能	範囲が絞られ、意図が分かる API。依存関係は最小限
Unix 哲学	外部から見て一貫した単一の目的。予想外の副作用がない
予測可能	振る舞いが明確で、失敗の範囲が限定され、状態が決定的
慣用的	言語やローカルの慣習に沿っており、車輪の再発明をしない
ドメインベース	フレームワークの構造ではなく、ドメインの語彙と境界に基づいている

シンプルさの原則（OAOO、三度目の法則、YAGNI、最もシンプルな方法）：シンプルさの原則。XP の実践（共同所有、ペア作業、CI、徹底的なリファクタリング）：XP の実践。 すでにうまく機能している点と、最も効果の高い改善点を1〜3つ挙げて締めくくってください。CUPID は目指す方向であり、準拠状況を判定するものではありません。トレードオフを認め、「違反している」「必ず〜しなければならない」といった表現は避けてください。特性をより深く分析する必要がある場合は、CUPID の完全なリファレンスを読んでください。

ハッカー精神（好奇心と職人技に導かれるエンジニアリング、オープンソースへの貢献姿勢。不正アクセスは拒否する）：ハッカー宣言。

注意点

• 主に人間が手作業で保守するコードに、エージェント向けの複雑度上限（6）を適用しないでください。現在の差分を書いたのが誰かではなく、今後そのファイルを誰が担当するかを確認してください。
• 命名と複雑度は相互に影響します。「複雑度が高い」ように見えるものの半分は、実際には「関数が何をするのかを隠す分岐の名前が不適切」なことが原因です。関数の抽出を試みる前に、名前の変更を試してください。
• あいまいさを招くようなノイズワードの削除にこだわらないでください。Product と ProductInfo の違いをなくすのはよい整理ですが、Product と ProductOwner は別の概念なので、そうしてはいけません。
• 1つの概念に1つの単語を使うという原則は、ファイル単位ではなくコードベース全体で確認するものです。同義語を導入する前に、既存の動詞を grep で検索してください。
• ドメインに由来する複雑さを無理に取り除かないでください。代わりに、その複雑さを明確にし、検証可能にしてください。
• CUPID スコアはレビューの観点であり、具体的な設計上の利点がないのにコードを抽出したり分割したりする理由ではありません。

---

ベンチマーク

シナリオ：.benchmarks/scenarios/clean-code-001-agent-code-review.md · 実行：2026-08-31 · ログ：.benchmarks/runs/2026-08-31/clean-code-001-agent-code-review.json

モデル	なし	あり	差分
claude-opus-4-8	67%	100%	+33%
claude-sonnet-4-6	83%	100%	+17%
claude-haiku-4-5	67%	67%	+0%

合格（実行 2026-08-31）。Opus +33（67→100）、sonnet +17（83→100）、haiku は上限に到達しています。デグレードはありません。ゲートは .agents/skills/skill-optimizer/rules/release-gates.md に準拠しています。

シナリオ：.benchmarks/scenarios/simple-001-root-cause-fix.md · 実行：2026-08-31 · ログ：.benchmarks/runs/2026-08-31/simple-001-root-cause-fix.json

モデル	なし	あり	差分
claude-opus-4-8	83%	100%	+17%
claude-sonnet-4-6	83%	100%	+17%
claude-haiku-4-5	83%	100%	+17%

条件付き合格（実行 2026-08-31）。小幅で一様な改善があり、デグレードはありません。ゲートは .agents/skills/skill-optimizer/rules/release-gates.md に準拠しています。

シナリオ：.benchmarks/scenarios/clean-code-002-cupid-review.md — このマージ後のベースライン／スキル有効時の再実行待ちです。