programming-principles

プログラミングの原則（14 冊）

mattpocock/agent-rules-books リポジトリから抽出した原則です。古典的なソフトウェアエンジニアリング書籍に基づく、事前作成済みの 14 種類の AGENTS.md ルールセットをまとめています。コードレビュー、リファクタリング、設計、実装の際に、このスキルを直接利用してください。書籍ごとの詳細な内容については、該当するリファレンスファイルを読み込んでください。

タスクと書籍の対応表

タスクの内容…　　　　　　　　　　　　　読み込む／適用する原則 ──────────────────────────────────────────────────────────────────────── 日常的な実装とコードレビュー　　　　　　Clean Code、Code Complete 既存コードのリファクタリング　　　　　　Refactoring、WELC アーキテクチャ／依存関係の管理　　　　　Clean Architecture、APoSD ドメインモデリング／ビジネスルール　　　DDD、DDD Distilled、IDDD エンタープライズアプリのパターン／階層化 PoEAA 本番環境の信頼性／安定性　　　　　　　　Release It! データの一貫性／スケーラビリティ／イベント DDIA エンジニアリングの技術／自動化　　　　　Pragmatic Programmer API／モジュール境界の設計　　　　　　　 APoSD レガシーコード／リスクの高い変更　　　　WELC、Refactoring

コード評価の実施方法

書籍の原則と実際のリポジトリ調査を組み合わせた、構造化された再現可能なワークフローについては、references/code-assessment-workflow.md を参照してください。評価フレームワークの読み込み、リポジトリと GitHub のコンテキストの確認、既存の issue／PR との重複排除、書籍と優先度による指摘事項の分類、各指摘事項が issue に値するかどうかの判断を扱います。

横断的な原則

複数の書籍から統合した原則を、関心事ごとにまとめています。

命名とコミュニケーション

• コードベース全体で、1 つの概念には 1 つの用語を使います。名称の変更は設計作業です。
• 名前は仕組みではなく、抽象概念を表すようにします。技術的な実装の詳細よりも、ドメインの語彙を優先してください。
• 関数には動詞、クラス／型には名詞、ブール値には述語を使います。
• 説明のコメントが必要な名前は、適切な名前ではありません。
• コメントは根拠、契約、警告、明白でない制約のために記述します。コードの説明や、不適切な名前の埋め合わせに使ってはいけません。

関数とルーチン

• 関数ごとに抽象化レベルを 1 つにします。全体像から詳細へと流れるように記述します。
• パラメーターは少なくします。ブール値のフラグがある場合は、関数を分割します。
• コマンド（変更する）とクエリ（回答する）を分離します。両方を行ってはいけません。
• モジュールが約 400 行を超える場合や、全体の範囲を把握するのにスクロールが必要な場合は、分割を検討します。実行順序やフレームワークの慣習ではなく、安定した責務の境界で分割してください。
• 正常系の処理は読みやすくします。エラー処理、エッジケース、クリーンアップはメインの流れから切り離します。
• 正確な名前を付けられないほど長い関数は、長すぎます。処理を抽出してください。

アーキテクチャと境界

• ソースコードの依存関係は、より高レベルの方針に向かって内側を指します。ドメインとユースケースが、フレームワーク、データベース、UI、ベンダー SDK をインポートしてはいけません。
• 外部依存関係（HTTP クライアント、ファイルシステム、データベース、ベンダー SDK など）はすべて、内側のレイヤーが所有するトレイトまたはインターフェースの背後に置く必要があります。アプリケーションやドメインのロジック内でインフラストラクチャのコードを直接インスタンス化することは、構造上の違反です（依存性逆転の原則）。
• フレームワーク、データベース、配信方式、デバイスは外側のレイヤーの詳細です。ポート、ゲートウェイ、アダプターの背後に置いてください。
• 技術レイヤー（controllers/、services/、repositories/）ではなく、まずビジネス機能／ユースケースを基準に構成します。
• 依存関係のルール：内側のレイヤーが必要なインターフェースを所有し、外側のレイヤーがそれらを実装します。
• 境界は、サイズや慣習ではなく、変化のしやすさと方針の重要性を基準に選びます。
• ラッパー、レイヤー、抽象化は、追加する複雑さよりも多くの複雑さを隠す必要があります。処理をそのまま通すだけのレイヤーは負債です。

データと状態

• 無効な状態を表現できない型を優先します。閉じた集合には列挙型を、意味のあるプリミティブには値オブジェクトを使い、ブール値は二者択一の意味に限って使います。
• データの所有権を明確にします。信頼できる唯一の情報源と、派生データ、キャッシュデータ、一時的なデータを区別します。
• 共有可変状態、グローバル変数、暗黙のコンテキストは、導入する価値を示す必要のあるコストとして扱います。
• ID、ライフサイクル、変更、読み込みの動作を明確にします。
• システムに関する知識は、それぞれ権威ある表現を一つだけ持たせます。それ以外はすべて導出または生成します。

テスト

• テストもプロダクションコードです。読みやすく、決定的で、振る舞いに沿ったものにします。
• 内部実装の詳細ではなく、外部から見える振る舞いに焦点を当てます。
• テストされていないコードの振る舞いを変更する前に、特性テストを追加します。
• バグを修正するときは、そのバグを検出できたはずの回帰テストを追加します。
• 無視されたテスト、不安定なテスト、スキップされたテストは、未解決の問題として扱います。
• テストにおけるボーイスカウトルール：テストスイートを、着手前よりもきれいな状態にします。

エラーと失敗の処理

• 次を区別します。プログラマーエラー（assert）、契約違反（panic/fail）、想定されるドメイン上の失敗（return/result 型）、再試行可能な失敗、恒久的な失敗。
• 依存関係、タイムアウト、再試行、キュー、縮退状態はすべて、遅延、不完全、または長期化する形で失敗し得るものとして扱います。
• すべての外部呼び出しにタイムアウトを設定します。無限待機は認めません。指数バックオフとジッターを用いて、有限回の再試行を行います。検証エラーや恒久的な失敗は再試行せず、再試行可能な結果とそうでない結果を区別します。
• 信頼境界で外部入力を検証します。プロセス外から届くデータの形式、サイズ、意味を決して信用しません。
• 処理を続けることで回復不能な問題が隠れる場合は、速やかに失敗させます。監視と分離がある場合に限り、「クラッシュさせる」方針を採用します。

リファクタリングと変更

• リファクタリングとは、振る舞いを変えずに構造を改善することです。機能追加や再設計を整理として偽装してはいけません。
• 小さく、元に戻せて、ビルド可能な手順で進めます。局所的に推論できないほど大きなパッチは分割します。
• 変更を妨げている構造上の摩擦を特定します。機能追加をより安全または単純にできる場合に限り、その前にリファクタリングします。
• 目につく問題をすべて直すのではなく、現在の妨げとなっている問題に対処します。次の整理が推測にすぎなくなったら、そこで止めます。
• 同じ編集が3回目に現れたら、重複を取り除きます。
• モジュールが約400行を超える場合、または3つ以上の異なる責務を扱う場合は、分割します。一文で説明できないモジュールは、責務を抱えすぎています。まとまりのあるサブ概念を切り出します。
• 名前を変更する、抽出する、インライン化する、移動する、分割する、置き換えるといった、最も単純で名前の付いた操作を優先します。

書籍ごとの簡潔なルール

『Clean Code』（Martin）

読みやすさ、局所的な推論、保守性を重視します。「動くコードはきれいなコード」という考えを正します。

• 関数：一つのことを、一つの抽象度で行い、上から下へ物語が流れるようにする
• 名前：意図が伝わり、発音しやすく、用語ごとに一つの概念を表す
• ブール値フラグ、出力パラメーター、隠れた副作用を使わない
• コメントは理由や制約の説明に限り、処理の説明には使わない
• テストもプロダクションコードとして扱う：読みやすく、決定的で、高速にする
• ボーイスカウトルール：変更したコードを、着手前よりきれいにする

『A Philosophy of Software Design』（Ousterhout）

深いモジュール、情報隠蔽、複雑さの軽減を重視します。「慣れ親しんだパターンは単純」という考えを正します。

• 深いモジュール：インターフェースは小さく、意味のある複雑さを内部に隠す。薄いラッパーは避ける
• 詳細を所有するモジュールの中に、複雑さを引き寄せる
• 実装方法ではなく、呼び出し側が知る必要のあることを中心にインターフェースを設計する
• より強い不変条件によって例外の範囲を狭める。無効な状態を定義上なくす
• コメントで設計上の判断や隠れた複雑さを記録する
• 名前、一貫性、明快さは、いずれも設計情報である

クリーンアーキテクチャ（Martin）

ビジネスルールをフレームワーク、データベース、UI から独立させます。「詳細がアーキテクチャである」という考えを正します。

• 依存関係は内側を向きます。ドメインはフレームワーク、DB、UI、ベンダーをインポートしません。
• エンティティは企業の不変条件を守り、ユースケースは1つのアクションを調整します。
• フレームワーク、DB、デリバリーは、ポート／アダプターの背後にある外側のレイヤーの詳細です。
• 内側のレイヤーがインターフェースを所有し、外側のレイヤーが実装します。
• 共有によってユースケースを統合しません。異なるアクターによる重複はそのままにします。
• コアのテストは、実際のDB、ネットワーク、フレームワーク、ハードウェアなしで実行できます。

Code Complete（McConnell）

構築の規律、欠陥の削減、検証可能なコードを扱います。「入力することが構築である」という考えを正します。

• 複雑なルーチンを書く前に、一貫した抽象度で疑似コードを作成します。
• すべての信頼境界で入力を検証します。プログラマーの前提条件にはアサーションを使います。
• 適切な抽象度でエラーを処理します。破損状態から黙って処理を続けてはいけません。
• 複雑さの増大は、欠陥のリスクそのものです。複雑に絡み合ったルーチンは分割します。
• 小さく検証可能な単位で構築し、頻繁に統合します。
• コメントでは、仕組みではなく意図、制約、契約を説明します。

Domain-Driven Design（Evans）＋ DDD Distilled（Vernon）

ユビキタス言語、境界づけられたコンテキスト、戦術的パターンを扱います。「モデルはデータスキーマである」という考えを正します。

• 用語やモジュールを解釈する前に、境界づけられたコンテキストを明確にします。
• コンテキスト内では、1つの概念に1つの用語を使います。コードにはユビキタス言語を反映させます。
• 集約は小さく、ルートを1つ持ち、不変条件で保護し、既定では1トランザクションにつき1つにします。
• 値オブジェクトは不変とし、生成時に検証し、値で比較します。
• リポジトリは、テーブルや ORM の行ではなく、ドメインオブジェクトを返します。
• ドメインイベントは過去形で表すビジネス上の事実であり、プロパティ変更の通知ではありません。
• すべてのコンテキスト境界に腐敗防止層を設けます。
• コアドメインには豊かなモデルを用い、支援サブドメインはよりシンプルに保ちます。

Implementing DDD（Vernon）

集約、イベント、サービス、永続化に関する実践的な DDD を扱います。「CRUD に名前を付け直せば DDD になる」という考えを正します。

• 他の集約は、オブジェクトグラフではなく識別子で参照します。
• エンティティや値オブジェクトに適さない操作には、ドメインサービスを使います。
• アプリケーションサービスはユースケースを調整します。ドメイン上の判断は担いません。
• 整合性や表現の要件に応じて、別個のモデルが必要な場合は CQRS を使います。
• イベントの並びが適切な永続化モデルとなる場合に限り、イベントソーシングを使います。
• 不変条件、有効／無効な状態遷移、イベントを直接テストします。

Patterns of Enterprise Application Architecture（Fowler）

エンタープライズアプリのレイヤー構成とパターンを扱います。「パターンが多いほど設計が優れている」という考えを正します。

• 要件に応じてビジネスロジックのパターンを選びます。トランザクションスクリプト → テーブルモジュール → ドメインモデル。
• ユースケースの調整とトランザクション境界にはサービスレイヤーを使います。
• リポジトリはドメイン用語でやり取りし、データマッパーは SQL をドメインオブジェクトから切り離します。
• 1つの論理的なコミットには作業単位を使い、1つのスコープ内で識別子ごとに1つのオブジェクトを保つにはアイデンティティマップを使います。
• レイヤーをまたぐ境界にはリモートファサードと DTO を使い、ドメインの内部を決して漏らしません。
• セッション状態は、スケーリングを考慮したうえで、クライアント、サーバー、DB のいずれで管理するかを意図的に選びます。

Refactoring（Fowler）

振る舞いを維持しながら構造を改善します。「クリーンアップは書き直しである」という考えを正します。

• 観測可能な振る舞いを維持します。振る舞いの変更と構造の変更を分離します。
• 小さく、元に戻せて、テスト可能な手順で進めます。リスクの高い作業の前に安全網を用意します。
• 準備的リファクタリングでは、機能追加を妨げている構造を事前に整えます。
• 目に付くすべてのコードの臭いではなく、現在の妨げとなっているコードの臭いを対象にします。
• 名前の付いた最も単純な操作を使います。名前の変更、抽出、インライン化、移動、カプセル化、置換。
• 要求された変更が容易になり、妨げとなっていたコードの臭いがなくなったら終了します。

レガシーコード改善ガイド（Feathers）

テストされていないコードを安全に変更します。「最初にすべきことは書き直し」という考えを正します。

• レガシーコードとは、信頼できるテストがないコードです。再設計の前に、現状の振る舞いを明らかにします。
• シーム（周囲のコードを編集せずに振る舞いを変更できる箇所）を見つけるか、作ります。
• 変更を加える前に、変更を妨げている依存関係を1つ取り除きます。
• 挿入には Sprout Method、Sprout Class、Wrap Method、Wrap Class を使います。
• 変更後は、その領域を変更前よりテストしやすい状態にします。
• 避けるべきこと：隠れた依存関係の拡大、見た目だけのリファクタリング、大規模な書き直し

データ集約型アプリケーションの設計（Kleppmann）

分散データ、一貫性、イベント、レプリケーションを扱います。「すべてがローカル／順序どおり／厳密に1回だけ実行される」という考えを正します。

• 信頼できる唯一の情報源、派生表現、一貫性に関する期待を明示します。
• クラッシュ、部分書き込み、重複、タイムアウトを通常の入力として扱います。
• 書き込みの意味を明確にします。いつ永続化されるか。いつ可視になるか。競合をどう扱うか。古い読み取りを許容するか。
• イベントは事実を表します。コンシューマーは遅延、重複、再生、バージョン管理されたペイロードに対応できるようにします。
• スキーマ、API、イベントは、旧バージョンと新バージョンの読み取り側／書き込み側にまたがって進化します。
• ワークロードに関係する局所性に基づいてパーティションを分割し、ホットキーやパーティション間のコストを明示します。
• トランザクションと分離レベルは、画一的な既定値ではなく、実際の不変条件に合わせます。

Release It!（Nygard）

本番環境の信頼性と安定性パターンを扱います。「ハッピーパスが動けば本番環境に対応できている」という考えを正します。

• すべての外部呼び出しにタイムアウトを設定します。無限に待機させません。バックオフを伴う、上限付きの再試行を行います。
• サーキットブレーカー、バルクヘッド、迅速な失敗によって、依存先の障害を分離します。
• 過負荷時の動作を設計します。キューを有限にし、負荷を制限し、重要なトラフィック向けの容量を確保します。
• 起動、ヘルスチェック、マイグレーション、運用制御は、再起動可能かつ可観測にします。
• 外部からの応答は、信頼する前に形式、妥当性、意味を検証します。
• あらゆる境界で可観測性を確保します。レイテンシ、飽和度、エラー、キューの深さ、ブレーカーの状態を確認します。

達人プログラマー（Hunt & Thomas）

エンジニアリングの技量、説明責任、自動化を扱います。「ローカルで編集すれば完了」という考えを正します。

• 事実ごとに信頼できる情報源を1つだけ持ちます。それ以外はそこから導出するか、追跡できるようにします。
• 直交性を保ちます。独立したコンポーネント、狭いインターフェース、分離された関心事を維持します。
• 隔離された部品を積み上げるより、トレーサーバレットを使います。アーキテクチャを早い段階でエンドツーエンドに検証します。
• 繰り返し発生し、エラーが起きやすく、忘れやすい作業を自動化します。
• フィードバックループを短くします。関連するテスト、自動チェック、早期に得られる低コストな兆候を活用します。
• 割れ窓：小さな品質低下が当たり前になる前に修正するか、目に見える形で封じ込めます。
• 再現した事実に基づいてデバッグします。観察し、切り分け、説明し、修正し、検証します。

Refactoring.Guru

コードの不吉な臭いと手法のカタログです。「パターンなら常に正解」という考えを正します。

• 手法を選ぶ前に、不吉な臭いを診断します。
• 最もシンプルな対処を優先します。抽出する前に名前を変更し、再設計する前に抽出します。
• それぞれの不吉な臭いには、固有の根本原因と対処方法があります。
• カタログの全容については、references/refactoring-guru.full.md を参照してください。

互換性ガイド

競合する書籍（同等の指針として読み込まないでください）：

• DDD ❌ PoEAA — データ所有権のパラダイムが異なります
• IDDD ❌ PoEAA — 実装レベルで同じ競合があります

重複する書籍（どれか1つを選んでください。同様の方向性を示しています）：

• Clean Code 🔁 Pragmatic Programmer、Code Complete、APoSD — コード品質
• DDD 🔁 DDD Distilled、IDDD — 深さの異なるDDD。必要なレベルを選んでください
• Clean Architecture 🔁 IDDD、PoEAA — アーキテクチャ／レイヤリングの重複
• Refactoring 🔁 Refactoring.Guru — コード改善。戦略には Refactoring、カタログには Guru を選んでください

それ以外のすべての組み合わせは相互補完的です。既定では、常に読み込む主要な書籍を1冊選び、ほかの書籍はタスクに応じて読み込みます。

ローカル参照ファイル

各書籍のミニルールセットは、references/ 内のローカル参照ファイルとして利用できます。 次のコマンドで読み込みます。

skill_view(name='programming-principles', file_path='references/{book-dir}.mini.md')

ファイル	書籍
references/a-philosophy-of-software-design.mini.md	A Philosophy of Software Design
references/clean-architecture.mini.md	Clean Architecture
references/clean-code.mini.md	Clean Code
references/code-complete.mini.md	Code Complete
references/designing-data-intensive-apps.mini.md	Designing Data-Intensive Applications
references/domain-driven-design.mini.md	Domain-Driven Design
references/domain-driven-design-distilled.mini.md	DDD Distilled
references/implementing-domain-driven-design.mini.md	Implementing DDD
references/patterns-of-eaa.mini.md	Patterns of Enterprise App Architecture
references/refactoring.mini.md	Refactoring
references/refactoring-guru.mini.md	Refactoring.Guru
references/release-it.mini.md	Release It!
references/the-pragmatic-programmer.mini.md	The Pragmatic Programmer
references/working-effectively-with-legacy-code.mini.md	Working Effectively with Legacy Code
references/code-assessment-workflow.md	評価手法 — 書籍ではありませんが、実際のリポジトリに対してすべての書籍の内容を組み合わせるワークフローです

各書籍には、詳細な参照用のフルバージョン（11〜42 KB）もあります。完全なルールカタログが必要な場合に読み込んでください。オンデマンドで読み込みます。

skill_view(name='programming-principles', file_path='references/{name}.full.md')

注：references/refactoring-guru.full.md は、2つのパートファイル（refactoring-guru.full-smells-and-priorities.md と refactoring-guru.full-technique-playbook-and-safety.md）へ案内するインデックスです。インデックスを読み込むと「参照のパート」テーブルが表示されます。その後、必要なパートを読み込んでください。

フルファイル	書籍	サイズ
references/a-philosophy-of-software-design.full.md	A Philosophy of Software Design	13 KB
references/clean-architecture.full.md	Clean Architecture	17 KB
references/clean-code.full.md	Clean Code	13 KB
references/code-complete.full.md	Code Complete	12 KB
references/designing-data-intensive-apps.full.md	Designing Data-Intensive Applications	16 KB
references/domain-driven-design.full.md	Domain-Driven Design	42 KB
references/domain-driven-design-distilled.full.md	DDD Distilled	11 KB
references/implementing-domain-driven-design.full.md	Implementing DDD	12 KB
references/patterns-of-eaa.full.md	Patterns of Enterprise App Architecture	15 KB
references/refactoring.full.md	Refactoring	17 KB
references/refactoring-guru.full.md	Refactoring.Guru	インデックス + 2 パート
references/release-it.full.md	Release It!	13 KB
references/the-pragmatic-programmer.full.md	The Pragmatic Programmer	13 KB
references/working-effectively-with-legacy-code.full.md	Working Effectively with Legacy Code	13 KB

段階的開示パターン：日常的なガイダンス（トリガー、判断ルール、最終チェックリスト）にはミニファイルを読み込みます。詳細なセッション、監査、またはコードの匂いのインデックスや手法の参照を含む完全なルールカタログが必要な場合にのみ、フルファイルを読み込んでください。

既知の弱点（リポジトリへの批判より）

• 改善を実証する測定がありません。これらは原則に基づくもので、ベンチマークによる評価はされていません。ルールが実際の成果を改善するかどうかは、判断を加えてください。
• ルールセットを一度に読み込みすぎると、コンテキストが飽和します。常時有効にする主要なセットは最大1つ、オンデマンドのタスク固有セットも最大1つにしてください。
• ルールはインシデントではなく書籍に基づいています。エージェントにとって最も価値の高いルールは、理論ではなく実際の失敗から生まれます。
• 形式だけの遵守に陥るリスクがあります。エージェントがルールの文面に従う一方で、実際のタスクを見落とすことがあります。出力はルールへの適合ではなく、実際の要件に照らしてテストしてください。