clean-code-ts-react

Robert C. Martin（Uncle Bob）による TypeScript 5.x + React 19 のベストプラクティス

Robert C. Martin の Clean Code（2008）のクラフトマンシップの原則を、現代の TypeScript と React 向けに再表現したものです。11 カテゴリーにわたる 61 のルールを、コード変更のライフサイクル全体における認知コストの高さに応じて優先順位付けしています。例では TS 5.x と React 19 の慣用的な書き方を使用していますが、ルールが重視するのは特定の API ではなく、時代を超えた原則です。

このスキルの特徴

一般的なクリーンコードのコピーと異なる点は、次の 3 つです。

1. 現代的な慣用表現を手段として使います。 例では TS 5.x（satisfies、ブランド型、判別可能なユニオン、const 型パラメーター）と React 19（関数コンポーネント、フック、use()、該当する場合は Server Components）を使用します。ただし、ルールの主眼は常に原則であり、構文ではありません。
2. 「適用すべきでない場合」を重視します。 すべてのルールに、原則を柔軟に適用すべき具体的な状況を 2～3 件示しています。一般的な但し書きではなく、実際に起こりうる状況です。ループカウンターには i を使ってもかまいません。一度しか使わないコードを DRY にする必要はありません。一部の HOC は避けられません。
3. 原則の衝突を扱うメタカテゴリーがあります。 カテゴリー 11 では、よくある緊張関係を明示します。DRY と単一責任、小さな関数と深いモジュール（Ousterhout）、型の厳密さと使いやすい API、仕様としてのテストとドキュメントなどです。どの原則を柔軟に扱うべきか判断できることが、シニアとしての証です。

適用する場面

次のようなときに、これらのガイドラインを参照してください。

• 新しい TypeScript または React のコードを書き、クラフトマンシップの観点からフィードバックを得たいとき
• 明瞭さ、命名、抽象化についてプルリクエストをレビューするとき
• 既存コードを読みやすさや保守性のためにリファクタリングするとき
• 関数、フック、コンポーネントの API を設計するとき
• 切り出し、抽象化、重複のどれを選ぶか判断するとき
• クリーンコードの 2 つのルールの緊張関係を解消するとき（カテゴリー 11 を参照）

このスキルではなく、次を使ってください。

• react：React 19 の API パターン（並行レンダリング、Server Components、ref-as-prop、useActionState、プロバイダーとしての<Context>）
• typescript：コンパイラーのパフォーマンス、tsconfig の調整、型システムのパフォーマンス
• refactor：機械的なリファクタリングのワークフロー
• tdd：TDD のワークフロー自体

優先度別のルールカテゴリー

順序は、変更のライフサイクル全体（読む → 理解する → 変更する → 検証する → リリースする → 保守する）における認知コストを表します。初期段階での問題は後続段階に波及します。悪い名前は、読むたびに理解を妨げます。

優先度	カテゴリー	影響度	プレフィックス	ルール
1	意味が明確な名前	CRITICAL	name-	8
2	関数、コンポーネント、フック	CRITICAL	func-	8
3	自己文書化（型とコメント）	HIGH	doc-	5
4	フォーマット（Prettier にとどまらない）	HIGH	fmt-	4
5	エラー処理	HIGH	err-	7
6	データの形状と不変性	MEDIUM-HIGH	data-	6
7	境界	MEDIUM-HIGH	bound-	4
8	継承より合成	MEDIUM-HIGH	comp-	6
9	テスト	MEDIUM	test-	5
10	創発とシンプルな設計	MEDIUM	emerge-	4
11	メタ：原則が衝突する場合	MEDIUM	meta-	4

合計：61 のルール。

クイックリファレンス

1. 意味が明確な名前（CRITICAL）

• name-intention-revealing — 意図が明確に伝わる名前を使う
• name-avoid-disinformation — 誤解を招く名前を避ける
• name-meaningful-distinctions — 意味のある区別をつける
• name-component-pascal-case — コンポーネントにはパスカルケースの名詞句を使う
• name-hook-use-prefix — フックには useX の動詞句を使う
• name-handler-convention — イベントハンドラーには onX / handleX を使う
• name-boolean-predicate — 真偽値の変数には is／has／can を使う
• name-types-pascal-case — 型とインターフェースにはパスカルケースを使う

2. 関数、コンポーネント、フック（CRITICAL）

• func-small — 関数、コンポーネント、フックは小さく保ちます
• func-one-thing — 1つのことだけを行います
• func-abstraction-level — 関数ごとに抽象化レベルを1つにします
• func-minimize-arguments — 長い引数リストよりオブジェクトパラメーターを優先します
• func-no-side-effects — 隠れた副作用（特にレンダー時）を避けます
• func-command-query-separation — コマンドとクエリを分離します
• func-dry — 概念が分岐するまではDRYを守ります
• func-custom-hook-extract — 再利用可能な状態を持つロジックはカスタムフックに切り出します

3. 自己文書化：型とコメント（HIGH）

• doc-types-over-comments — コメントより型を優先します
• doc-satisfies-narrows-with-check — 推論される値をチェックするには satisfiesを使います
• doc-jsdoc-public-api — 公開APIや自明でない副作用にはJSDocを使います
• doc-avoid-redundant-comments — 冗長なコメントを避けます
• doc-delete-commented-out-code — コメントアウトされたコードを削除します

4. Prettierを超えるフォーマット（HIGH）

• fmt-vertical-density — 関連するコードは近くに、関連しないコードは離して配置します
• fmt-newspaper-order — 新聞のようにファイルを上から順に配置します
• fmt-team-rules-over-preference — 個人の好みよりチームの規約を優先します
• fmt-imports-grouped — インポートをソースごとにグループ化します

5. エラー処理（HIGH）

• err-early-return — 早期リターンを使ってエラー処理の分岐を簡潔にします
• err-result-vs-throw — throwとResultを意図的に選択します
• err-narrow-unknown — catchブロックでは必ずunknownの型を絞り込みます
• err-error-boundaries — レンダー時のエラーにはエラーバウンダリーを使います
• err-suspense-for-loading — 読み込み状態にはSuspenseを使います
• err-no-swallow — エラーを黙って握りつぶしてはいけません
• err-null-vs-undefined — ドメインごとにnullまたはundefinedのどちらかを選びます

6. データ形状と不変性（MEDIUM-HIGH）

• data-discriminated-unions-over-flags — ブール値フラグより判別可能なユニオンを使います
• data-readonly-by-default — 読み取り専用データにはreadonlyを指定します
• data-branded-types — ドメインの不変条件を型で表現するためにブランド型を使います
• data-dto-vs-domain — DTOとドメイン型を分離します
• data-demeter-prop-drilling — Propsの受け渡しはデメテルの法則に反していることがよくあります
• data-structural-typing-pitfalls — 構造的型付けによるエイリアス化に注意します

7. 境界（MEDIUM-HIGH）

• bound-wrap-third-party-hooks — サードパーティ製フックをカスタムフックでラップします
• bound-learning-tests — サードパーティの動作を確認する学習テストを書きます
• bound-isolate-framework — フレームワーク固有のコードを境界部分に隔離します
• bound-type-assertions-at-edges — 型アサーションは境界でのみ使用します

8. 継承より合成（中〜高）

• comp-children-over-props — 設定用の props より children を使って合成します
• comp-small-components — コンポーネントは小さく、まとまりのあるものに保ちます
• comp-avoid-hoc-stacks — 高階コンポーネントの多重化を避けます
• comp-context-only-when-needed — Context は DI に使用し、props の回避には使いません
• comp-render-props-vs-hooks — ロジックの再利用には render props より hooks を優先します
• comp-separate-construction-from-use — セットアップとレンダリングを分離します

9. テスト（中）

• test-behavior-not-implementation — 実装ではなく振る舞いをテストします
• test-mock-at-boundaries — 真の境界でのみモックを使用します
• test-first-principles — FIRST の原則を適用します
• test-one-concept — テストごとに 1 つの概念を検証します（アサーションの数ではありません）
• test-clean-as-production — テストコードにも本番コードと同等の注意を払います

10. 創発とシンプルな設計（中）

• emerge-four-rules — シンプルな設計の 4 つのルールを順番に適用します
• emerge-yagni-types — 型ジェネリクスの早すぎる導入を避けます
• emerge-premature-abstraction — 早すぎる抽象化を避けます
• emerge-reveal-intent — 表現力を最大限に高め、コードで意図を伝えます

11. メタ：原則が対立するとき（中）

このカテゴリが本領を発揮します — あるクリーンコードの原則を別の原則より優先する場面について、明確な指針を示します。

• meta-dry-vs-srp — 概念が分かれていく場合は DRY を曲げます
• meta-small-vs-deep — 間接化が理解を妨げる場合は、小さな関数より深いモジュールを優先します
• meta-types-vs-ergonomics — 安定した境界では型安全性より使いやすさを優先します
• meta-tests-as-spec-vs-doc — ファイルごとに、仕様としてのテストとドキュメントとしてのテストを選びます

使い方

「この名前付けでよいか？」「これを切り出すべきか？」といった個別の質問では、上のクイックリファレンスから該当するルールファイルを直接参照してください。

コードレビューやリファクタリングでは、優先度順にカテゴリを確認してください。まず名前と関数の形（最も広く影響します）、次にエラーとデータの形、その後に合成とテストを確認します。ファイルごとに確認するより、カテゴリごとにまとめて確認するほうが効率的です。

2 つの原則が対立しているように見える場合は、該当するメタルール（カテゴリ 11）を読んでください。優先する原則を選び、その判断を記録します。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリの定義と順序
assets/templates/_template.md	新しいルールを追加するためのテンプレート
metadata.json	バージョンとリファレンス情報

関連スキル

• .experimental/clean-code — 言語に依存しない元のクリーンコード（Java の例）。このスキルは TS+React 版です。
• .curated/react — React 19 固有のパターン（Server Components、並行レンダリング、ref-as-prop）。
• .curated/typescript — TS コンパイラのパフォーマンスと tsconfig の調整。
• .curated/refactor — 機械的なリファクタリングのワークフロー。
• .curated/tdd — TDD のワークフローそのもの。