uncle-bob-craft

Uncle Bob Craft

Robert C. Martin（Uncle Bob）の基準を、コードレビューと本番環境向けのコードに適用します。対象となるのは、Clean Code、Clean Architecture、The Clean Coder、Clean Agile、そしてデザインパターンを適切に扱うことです。このスキルは、既存の @clean-code スキル（Clean Code の書籍に焦点を当てています）と、プロジェクトのリンター／フォーマッターを補完するものであり、それらに取って代わるものではありません。

適用範囲

ここで扱うのは状況に応じた設計上のヒューリスティックであり、あらゆる編集でインターフェース、レイヤー、テストの導入を必須とする普遍的な要件ではありません。プロジェクトのアーキテクチャと言語ごとのエラー処理規約を尊重し、原則の名前を挙げるだけでなく、具体的な変更リスクを根拠として推奨事項を説明してください。以下の例では、元の金額の増加を維持しています。これは割引ではなく、率の乗数です。

概要

このスキルは、Uncle Bob の著作全般から、コードのレビューと作成に関する原則をまとめたものです。対象は、命名と関数（@clean-code 経由）、アーキテクチャと境界（Clean Architecture）、プロ意識と見積もり（The Clean Coder）、アジャイルの価値観と実践（Clean Agile）、そしてデザインパターンの適切な使用と誤用です。構造、依存関係、状況に応じた SOLID、コードの臭い、プロとしての実践を評価する際に使用してください。このスキルが示すのは、作法と設計の基準のみです。構文やスタイルのチェックは対象外であり、引き続きリンターとフォーマッターが担います。

このスキルを使う場面

• コードレビュー：依存性ルール、境界、SOLID、コードの臭いに関するヒューリスティックを適用し、具体的なリファクタリングを提案します。
• リファクタリング：何を抽出するか、どこに境界を設けるか、デザインパターンが妥当かどうかを判断します。
• アーキテクチャの議論：レイヤーの境界、依存関係の方向、関心事の分離を確認します。
• デザインパターン：パターンを導入する前に、適切な使用か、カーゴ・カルト的な使用や過剰使用かを見極めます。
• 見積もりとプロ意識：Clean Coder の考え方（断ること、持続可能なペース、三点見積もり）を適用します。
• アジャイルの実践：プロセスについて議論する際に、Clean Agile（アイアンクロス、TDD、リファクタリング、ペアプログラミング）を参照します。
• プロジェクトのリンター、フォーマッター、自動テストの代わりとして、またはそれらに優先するものとして使用しないでください。

出典別のまとめ

出典	焦点	参照先
Clean Code	名前、関数、コメント、フォーマット、テスト、クラス、コードの臭い	詳細については @clean-code を使用してください。このスキルでは、レビューと本番環境向けのコード作成にあたって参照します。
Clean Architecture	依存性ルール、レイヤー、境界、アーキテクチャにおける SOLID	reference.md と references/clean-architecture.md を参照してください。
The Clean Coder	プロ意識、見積もり、断ること、持続可能なペース	reference.md と references/clean-coder.md を参照してください。
Clean Agile	価値観、アイアンクロス、TDD、リファクタリング、ペアプログラミング	reference.md と references/clean-agile.md を参照してください。
デザインパターン	使用する場面、誤用、カーゴ・カルト	reference.md と references/design-patterns.md を参照してください。

デザインパターン：適切な使用と誤用

• パターンを使うのは、実際の設計上の問題（振る舞いの違い、ライフサイクル、横断的関心事など）を解決する場合です。「エンタープライズらしく」見せるためではありません。
• カーゴ・カルトを避ける：「このコードベースには Factory／Strategy／Repository があるべき」という理由だけで追加しないでください。重複や硬直性によって抽象化が正当化される場合に追加します。
• 誤用の兆候：あらゆるクラス名にパターン名が含まれている、ロジックがなく委譲するだけのレイヤーがある、単純なコードをかえって追いにくくするパターンを使っている。
• 目安：重複が3回目になりそうなとき、または変更理由が2つ目に達したときにパターンを導入します。意図が明確になるよう、コードまたはドキュメントでパターン名を示してください。

コードの臭いとヒューリスティクス（概要）

コードの臭い／ヒューリスティクス	意味
硬直性	小さな変更で多くの編集が必要になります。
脆弱性	変更によって無関係な箇所が壊れます。
移植性の低さ	別のコンテキストで再利用するのが困難です。
粘性	手っ取り早い方法は簡単ですが、適切な方法を実行するのは困難です。
不必要な複雑さ	先回りして作られた抽象化や、使われていない抽象化です。
不必要な重複	DRY に違反し、同じ考えが複数の箇所にあります。
不透明性	コードを理解するのが困難です。

コンパクトに編集上の観点で分類したもの（C/T 識別子は書籍で正式に使われているヒューリスティクスの識別子ではありません）は、reference.md にあります。レビューではこれらを使って問題を明示し、リファクタリング（抽出、依存関係の移動、境界の導入）を提案してください。

レビューと本番コード

コンテキスト	適用すること
コードレビュー	依存関係ルールと境界を確認します。SOLID を状況に応じて適用し、コードの臭いを列挙して、具体的なリファクタリングを 1 つか 2 つ提案します（例：関数の抽出、依存関係の逆転）。テストとプロフェッショナリズムも確認します（テストがあること、明らかな場当たり的な回避策がないこと）。
新しいコードの作成	小さな関数と単一責任を優先します。内側に依存するようにします（クリーンアーキテクチャ）。TDD を行う場合は、まずテストを書きます。重複や変化によって正当化されるまでは、パターンを使わないようにします。
リファクタリング	一度に 1 つのコードの臭いを特定します。テストを通したまま、小さな手順でリファクタリングします。振る舞いを追加する前に、名前と構造を改善します。

仕組み

コードをレビューする場合

1. 境界と依存関係ルール：依存関係が内側を向いていることを確認します（例：ユースケースが UI や DB の詳細に依存していないこと）。references/clean-architecture.md を参照してください。
2. 状況に応じた SOLID：変更されたコードに該当する場合、単一責任、開放／閉鎖、リスコフの置換、インターフェース分離、依存性逆転を確認します。
3. コードの臭い：硬直性、脆弱性、移植性の低さ、粘性、不必要な複雑さや重複、不透明性を探し、ファイルや箇所とともに列挙します。
4. 具体的な提案：リファクタリングを 1 つか 2 つ提案します（例：「これを X という名前の関数に抽出する」「このレイヤーが具体的な DB クライアントに依存しないよう、インターフェースを導入する」）。
5. テストと仕事の質：確認できたテストカバレッジと、具体的な先送りリスクを報告します。TODO コメントから、作者のプロフェッショナリズムや作業ペースを推測しないでください。

コードを作成またはリファクタリングする場合

1. 小さく、単一の目的を持つ関数とクラスを優先します。命名と構造には @clean-code を使用します。
2. 依存関係を内側に向けます。ビジネスルールは中心に、アダプターは外側に配置します。
3. デザインパターンは、重複や変化によって正当化される場合にのみ導入します。
4. テストが通った状態を保ちながら、小さな手順でリファクタリングします。

例

例 1：コードレビュー用プロンプト（コピーして使用可能）

Uncle Bob の考え方に沿ったレビューを依頼するには、これを使用します。

Please review this change using Uncle Bob craft criteria (@uncle-bob-craft):
1. Dependency Rule and boundaries — do dependencies point inward?
2. SOLID in context — any violations in the touched code?
3. Smells — list rigidity, fragility, immobility, viscosity, needless complexity/repetition, or opacity.
4. Suggest one or two concrete refactors (e.g., extract function, invert dependency).
Do not duplicate lint/format; focus on structure and design.

例 2：変更前／変更後（抽出して命名）

変更前（不透明で、複数の処理を行う）：

def process(d):
    if d.get("t") == 1:
        d["x"] = d["a"] * 1.1
    elif d.get("t") == 2:
        d["x"] = d["a"] * 1.2
    return d

変更後（意図が明確で、抽象化のレベルが揃っている）：

def apply_rate_multiplier(amount: float, rate_type: int) -> float:
    if rate_type == 1:
        return amount * 1.1
    if rate_type == 2:
        return amount * 1.2
    return amount

def process(order: dict) -> dict:
    order["x"] = apply_rate_multiplier(order["a"], order.get("t", 0))
    return order

ベストプラクティス

• ✅ 命名、関数、コメント、書式設定には @clean-code を使用し、アーキテクチャ、境界、SOLID、コードの臭い、プロセスにはこのスキルを使用します。
• ✅ レビューでは、コードの臭いや原則を明示します（例：「依存関係ルール違反：ユースケースがウェブフレームワークからインポートしている」）。
• ✅ 確認された問題がある場合にのみ、具体的なリファクタリングを提案します。問題のないレビューでは提案が不要な場合もあります（抽出、名前変更、依存関係の逆転）。
• ✅ プロジェクトのリンターとフォーマッターは個別に実行します。このスキルはそれらの代わりにはなりません。
• ❌ 構文やスタイルの強制にこのスキルを使わないでください。それはリンターの役割です。
• ❌ 重複や変化について明確な理由がない限り、デザインパターンを追加しないでください。

よくある落とし穴

• 問題: すべてのクラスに Factory や Strategy が必要だと扱ってしまう。
  解決策: 実際の設計上の必要性（3 回目の重複、2 つ目の変更軸）がある場合にのみパターンを導入します。

• 問題: 「SOLID に違反している」とどこで、どのように違反しているかを示さずにレビューしてしまう。
  解決策: ファイルや関数を指し示し、どの原則かを明示します（例:「SRP: この関数はパースと永続化を行っている。parse と persist に分割する」）。

• 問題: 「Uncle Bob を適用した」という理由でプロジェクトのリンターを省略してしまう。
  解決策: このスキルは技巧と設計に関するものです。常にプロジェクトの lint と format を実行してください。

関連スキル

• @clean-code — Clean Code 本の詳細な内容（名前、関数、コメント、フォーマット、テスト、クラス、コードの臭い）。日々のコード品質にはこちらを、アーキテクチャや書籍横断的な基準には uncle-bob-craft を使用します。
• @architecture — 一般的なアーキテクチャの意思決定とトレードオフ。高レベルの構造を選ぶ際に使用し、依存関係ルールと境界には uncle-bob-craft を使用します。
• @code-review-excellence — コードレビューの実践。原則に基づくレビューには uncle-bob-craft と組み合わせます。
• @refactor-clean-code — クリーンコードに向けたリファクタリング。境界と SOLID を目的としたリファクタリングの際に uncle-bob-craft と併用します。
• @test-driven-development — TDD ワークフロー。Clean Agile および Clean Coder（要件としてのテスト、持続可能なペース）と整合します。

制限事項

• プロジェクトのリンターやフォーマッターの代わりにはなりません。 lint と format は別途実行してください。このスキルは設計と技巧の基準のみを提供します。
• 自動テストの代わりにはなりません。 テストを書くように促すことはできますが（Clean Coder、Clean Agile）、テストを実行したり生成したりはしません。
• ツール群を補完するものです。 既存の CI、lint、テストスイートと併せて使用してください。
• 構文やスタイルの強制は行いません。 構造、依存関係、コードの臭い、プロフェッショナルな実践に焦点を当てており、ブレースのスタイルや行の長さには関与しません。
• 要約であり、書籍そのものではありません。 完全な Clean Code のヒューリスティック、コンポーネント原則（REP/CCP/CRP、ADP/SDP/SAP）、詳細なストーリーは書籍にあります。ここでは最もよく使われる部分を参照しています。reference.md の「Scope and attribution」を参照してください。