プラグマティックプログラマーフレームワーク

Hunt & Thomas の著作『The Pragmatic Programmer』(20周年記念版)に基づくシステムレベルのソフトウェア職人技へのアプローチ。システム設計、アーキテクチャレビュー、コード執筆、またはエンジニアリング文化のアドバイスを行う際に、これらの原則を適用してください。このフレームワークはメタレベルに対応しています。単にコードを書く方法ではなく、ソフトウェアについてどう考えるかです。

コアプリンシパル

あなたの職人技を大切にしてください。 ソフトウェア開発は継続的な学習、規律ある実践、そして個人的な責任を求める職人技です。プラグマティックプログラマーは目の前の問題を超えて考えます――彼らはあらゆる技術的決定の文脈、トレードオフ、長期的な影響を考慮します。

基礎: 優れたソフトウェアは優れた習慣から生まれます。プラグマティックプログラマーは幅広い知識ポートフォリオを維持し、明確にコミュニケーションを取り、重複を徹底的に避け、コンポーネントを直交したものに保ち、すべてのコード行を生きた資産として扱い、その価値を自分たちの場所で獲得する必要があります。目標は完璧さではなく――変更しやすく、理解しやすく、信頼できるシステムを構築することです。

スコアリング

目標: 10/10 ソフトウェアデザイン、アーキテクチャ、またはコードをレビューまたは作成する際、以下の原則への準拠に基づいて 0～10 で評価してください。10/10 はすべてのガイドラインとの完全な一致を意味し、低いスコアは対処すべきギャップを示しています。常に現在のスコアと 10/10 に到達するために必要な具体的な改善を提供してください。

プラグマティックプログラマーフレームワーク

長く愛用されるソフトウェアを構築するための7つのメタプリンシパル:

1. DRY (繰り返すな)

コアコンセプト: すべての知識は、システム内で単一の、曖昧でない、権威のある表現を持つ必要があります。DRY は知識についてのもので、コードについてではありません――重複したロジック、ビジネスルール、またはコンフィグは、重複した構文よりもはるかに危険です。

なぜ機能するのか: 知識が重複している場合、複数の場所で変更を加える必要があります。やがて1つが見落とされ、矛盾が生じます。DRY はバグの表面積を減らし、システムの変更を容易にします。

主要な洞察:

• DRY は知識と意図に適用され、テキスト的類似性には適用されません――異なるビジネスルールに役立つ同一のコードブロック2つは、重複ではありません
• 重複には4つのタイプがあります: 強制(環境が強制)、不本意(開発者が気付かない)、せっかち(抽象化に怠ける)、開発者間(複数の人が重複する)
• コードを言い換えるコメントは DRY に違反します――コメントは 何 ではなく なぜ を説明すべきです
• データベーススキーマ、API 仕様、ドキュメントは、単一のソースから生成されない場合、すべて重複の原因です
• DRY の反対は WET です: 「Write Everything Twice」または「We Enjoy Typing」

コード適用:

コンテキスト	パターン	例
設定値	単一の真実の源	DB 接続を1つの env ファイルで定義し、どこからでも参照
検証ルール	共有スキーマ	クライアント及びサーバー検証に JSON Schema または Zod スキーマを使用
API コントラクト	仕様から生成	OpenAPI 仕様は型、ドキュメント、クライアントコードを生成
ビジネスロジック	ドメインモジュール	税金計算を1つのモジュール内で定義し、コントローラー全体に分散させない
データベーススキーマ	マイグレーション駆動	スキーマをマイグレーションで定義し、ORM モデルを DB から生成

参照: references/dry-orthogonality.md

2. 直交性

コアコンセプト: 2つのコンポーネントは、1つの変更が他方に影響しない場合、直交しています。コンポーネントが自己完結し、独立し、単一の明確な目的を持つシステムを設計します。

なぜ機能するのか: 直交したシステムはテストしやすく、変更しやすく、副作用が少ないです。データベース層を変更しても、UI は壊れません。認証プロバイダーを変更しても、ビジネスロジックは気にしません。

主要な洞察:

• 質問してください: 「特定の関数の背後にある要件を劇的に変更した場合、何個のモジュールに影響するか?」答えは1つであるべきです
• 無関係なもの間の影響を排除します――ログの変更は請求を決して破るべきではありません
• レイヤード アーキテクチャは直交性を促進します: プレゼンテーション、ドメインロジック、データアクセス
• グローバルデータを避けます――すべてのグローバル状態のコンシューマーは、それに結合されています
• フレームワーククラスから継承を強制するツールキットとライブラリは、直交性を減らします

コード適用:

コンテキスト	パターン	例
アーキテクチャ	レイヤード分離	Controller -> Service -> Repository、各々置き換え可能
依存関係	依存性注入	SlackClient 具体クラスではなく、Notifier インターフェースを渡す
テスト	隔離されたユニットテスト	データベース、ネットワーク、またはファイルシステムなしにビジネスロジックをテスト
コンフィグ	環境駆動	フィーチャーフラグをコンフィグに置き、ビジネスロジック内の if ブランチではなく
デプロイメント	独立したサービス	支払いサービスを再デプロイしなくても、認証サービスをデプロイ

参照: references/dry-orthogonality.md

3. トレーサー弾とプロトタイプ

コアコンセプト: トレーサー弾は、すべてのシステムレイヤーを最小限の機能で接続するエンドツーエンド実装です。プロトタイプ(廃棄型)とは異なり、トレーサー弾コードは本番コード――薄いながらも実在するものです。

なぜ機能するのか: トレーサー弾は即座のフィードバックを提供します。すべての機能を埋める前に、エンドツーエンドでシステムがどのように見えるかを確認できます。ユーザーは実在するものを見ることができ、開発者は構築するためのフレームワークを持ち、統合の問題が早期に浮上します。

主要な洞察:

• トレーサー弾: システムを通す薄いながらも完全なパス(UI -> API -> DB)――それを保持します
• プロトタイプ: 単一の危険な側面の焦点を絞った探索――それを廃棄します
• トレーサー弾は「暗い中での射撃」の際に機能します――要件が曖昧で、アーキテクチャが未証明
• トレーサーが外れた場合、調整して再び射撃します――反復のコストは低いです
• プロトタイプは廃棄として明確にラベル付けされるべきです――プロトタイプが本番コードになることは決してありません

コード適用:

コンテキスト	パターン	例
新規プロジェクト	垂直スライス	1つの機能をエンドツーエンドで構築: ボタン -> API -> DB -> レスポンス
不確実な技術	スパイク プロトタイプ	WebSocket パフォーマンスが十分かどうかをテストしてから、コミット
フレームワーク評価	スタック全体でのトレーサー	ログインフローをフルフレームワークで構築し、その後それを選択
マイクロサービス	ウォーキング スケルトン	hello-world サービスをフル CI/CD パイプライン経由でデプロイ
データパイプライン	エンドツーエンドフロー	1つのレコードを取り込みから変換まで出力へ

参照: references/tracer-bullets.md

4. コントラクト設計と断定的プログラミング

コアコンセプト: 前提条件(実行前に真である必要がある)、事後条件(実行後に保証される)、クラス不変式(常に真である)を通じて、ソフトウェアモジュールの権利と責務を定義し、強制します。コントラクトが違反された場合、すぐに大きく失敗します。

なぜ機能するのか: コントラクトは仮定を明示的にします。データを静かに破損させたり、無効な状態で歩み続けたりする代わりに、システムは問題の時点で停止します――バグを可視化し、追跡可能にします。死んだプログラムは嘘をつきません。

主要な洞察:

• 前提条件: 呼び出し側の責任――「正の整数のみを受け入れます」
• 事後条件: ルーチンの保証――「ソート済みリストを返します」
• 不変式: 常に真――「アカウント残高は決して負にならない」
• 早期に停止: 死んだプログラムは、障害のあるプログラムよりもはるかに少ないダメージを与えます
• 起こらないはずのことにはアサーションを使用し、起こる可能性のあることにはエラーハンドリングを使用します
• 動的言語では、ランタイムチェックと保護句を通じてコントラクトを実装します

コード適用:

コンテキスト	パターン	例
関数エントリ	前提条件ガード	関数の開始時に assert age >= 0, "Age cannot be negative"
関数終了	事後条件チェック	返す前に返却されたリストがソート済みであることを検証
クラス状態	不変式検証	すべての状態ミューテーションの後に呼ばれる validate! メソッド
API 境界	スキーマ検証	処理する前にリクエストボディをスキーマに対して検証
データパイプライン	ステージアサーション	ETL 変換後のアサーション行数が期待値と一致

参照: references/contracts-assertions.md

5. 割れた窓理論

コアコンセプト: 1つの割れた窓――悪い設計のコード、悪い管理上の決定、「後で修正します」というハック――が腐食を開始させます。一旦システムがネグレクトの兆候を示すと、エントロピーは加速し、規律は崩壊します。

なぜ機能するのか: 心理学。コードがクリーンでよくメンテナンスされていると、開発者はそれをそのように保つための社会的プレッシャーを感じます。コードが既に乱雑になっている場合、さらに乱雑さを追加する閾値は0に低下します。品質は個々のヒロイックな努力ではなく、チームの習慣です。

主要な洞察:

• 割れた窓(悪い設計、誤った決定、悪いコード)を修復されないままにしないでください
• 今すぐ修正できない場合は、板を張ります: チケット付きで TODO を追加し、フィーチャーを無効にし、スタブで置き換えます
• 変化の触媒になります: 将来の働く一瞥を人々に示します(石スープ)
• 遅い劣化を監視します(ゆでカエル)――時間の経過とともに技術債メトリクスを監視します
• 最初のハックが最も高価なのは、その後のすべてのハックへの許可を与えるからです

コード適用:

コンテキスト	パターン	例
レガシーコード	窓を板で張る	フィーチャーを追加する前に、悪いコードをクリーンなインターフェースでラップ
コードレビュー	新しい債務への不寛容	チケットなしで // TODO: fix later を追加する PR を拒否
技術債	債務予算	各スプリントの20%を割れた窓の修正に割り当てる
新しいチームメンバー	クリーンなオンボーディング パス	最初のタスク: コードベースを学ぶために割れた窓を修正
監視	エントロピー メトリクス	リント違反、テストカバレッジ トレンドを時間の経過で追跡

参照: references/broken-windows.md

6. 可逆性と柔軟性

コアコンセプト: 最終決定はありません。データベース、フレームワーク、ベンダー、アーキテクチャ、およびデプロイメント対象について気を変えることを簡単にするシステムを構築します。変更のコストは変更の範囲に比例する必要があります。

なぜ機能するのか: 要件は変わります。ベンダーは買収されます。テクノロジーは支持を失います。アーキテクチャにこれらのいずれかについてハードコードされた仮定がある場合、すべての変更は書き直しになります。柔軟なアーキテクチャは決定を構造ではなくコンフィグとして扱います。

主要な洞察:

• サードパーティの依存関係を独自のインターフェースの背後に抽象化します――ベンダー API が決してビジネスロジックに漏れないようにします
• 「フォーク道テスト」を使用します: Postgres から DynamoDB に1週間で切り替えられますか? 合わない場合は、結合されています
• メタデータ駆動システム(コンフィグファイル、フィーチャーフラグ)は、ハードコードされたロジックよりも柔軟です
• YAGNI は時期尚早な抽象化にも適用されます――必要な具体的な証拠がない限り、柔軟性を構築しないでください
• 可逆性は将来を予測することについてではなく、自分自身を隅に追い込まないことについてです

コード適用:

コンテキスト	パターン	例
データベース	リポジトリパターン	ビジネスロジックは pg.query(...) ではなく repo.save(user) を呼び出す
外部 API	アダプター/ラッパー	PaymentGateway インターフェースが Stripe をラップし、後で Braintree に切り替え
フィーチャーフラグ	ランタイム トグル	新しいチェックアウトフロー、フラグの背後、数秒でロールバック
アーキテクチャ	イベント駆動デカップリング	サービスは直接 HTTP 呼び出しではなくイベント経由で通信
デプロイメント	コンテナ抽象化	Docker化されたアプリは AWS、GCP、またはベアメタルで変更なしで実行

参照: references/reversibility.md

7. 見積りと知識ポートフォリオ

コアコンセプト: 範囲、モデル構築、コンポーネントへの分解、範囲割り当てを理解することで、信頼性のある見積りを習得します。財務ポートフォリオのように学習を管理します: 定期的に投資し、多様化し、リバランスします。

なぜ機能するのか: 見積りは誠実に行われた場合、ステークホルダーとの信頼を構築します(「2週間正確」よりも「1～3週間」が優れている)。知識ポートフォリオは、テクノロジーが変わる際に関連性を保ちます――学習を停止するプログラマーは効果的であることを停止します。

主要な洞察:

• 「この見積りは何のためか?」と聞いてください――文脈が精度を決定します(予算計画対スプリント計画)
• PERT を使用: (楽観的 + 4倍最も可能性が高い + 悲観的) / 6
• 見積りをコンポーネントに分解し、各々を見積ります; 合計は単一の推測より正確です
• 見積りログを保持します: 見積りと実績を比較し、キャリブレーション
• 知識ポートフォリオ ルール: 定期的に投資(毎週何かを学習)、多様化(スタックのみ学習しない)、リスク管理(安全で投機的な賭けを混ぜる)、安く買って高く売る(新興テクノロジーを早期に学習)

コード適用:

コンテキスト	パターン	例
スプリント計画	範囲見積り	単一の数字ではなく、信頼レベル付きの「3～5日」
新しいテクノロジー	時間制限スパイク	「2日間評価します; その後、適切に見積ることができます」
大規模プロジェクト	ボトムアップ分解	< 1日のタスクに分割し、統合用バッファで合計
学習	週次投資	新しい言語、ツール、またはドメインに1時間/週
キャリア成長	ポートフォリオ多様化	深さ(専門知識)と幅(隣接スキル)のミックス

参照: references/estimation-portfolio.md

一般的なミステイク

ミステイク	なぜ失敗するのか	修正
異なる目的に役立つ類似コードを DRY する	無関係な概念間の結合を作成; 1つの変更が他方を破る	偶然のコード類似性ではなく、知識のみを DRY する
トレーサー弾をスキップしてレイヤーバイレイヤーで構築	統合の問題が遅く浮上; エンドツーエンドフィードバックなし	最初に1つの薄い垂直スライスを構築
「後でリファクタリングするから」と割れた窓を無視	エントロピーが加速; 後は来ない; チームモラルが低下	すぐに修正するか、追跡チケット付きで板を張る
単一ポイント の見積りをコミットメント	偽の精度を作成; 見積が外れたときに信頼を削ぐ	常に信頼レベル付き範囲を提供
すべてを最初から「柔軟」にする	過度なエンジニアリング; YAGNI; 必要な証拠なし抽象化	具体的な必要性の証拠がある場合に柔軟性を追加
「パフォーマンスのため」本番環境からアサーションを削除	アサーションが捕捉するバグはデータを静かに破損	重要なアサーションを保持; 削除する前にベンチマーク
グローバル状態を「便利なために」使用	直交性を破壊; すべてのモジュールは結合	依存性注入と明示的なパラメーターを使用

迅速な診断

質問	いいえ の場合	アクション
ビジネスロジックに触れずにデータベースを変更できますか?	直交性違反	リポジトリ/アダプターパターンを導入
エンドツーエンドスライスが機能していますか?	トレーサー弾の欠落	展開する前に1つの垂直スライスを構築
すべてのビジネスルールはちょうど1つの場所で定義されていますか?	DRY 違反	権威のあるソースを特定し、重複を削除
新しい開発者がこのコードベースを「クリーン」と呼ぶでしょうか?	割れた窓が存在	専用クリーンアップスプリントをスケジュール
見積りには範囲と信頼レベルが含まれていますか?	見積り問題	PERT または範囲ベースの見積りに切り替え
このデプロイメントを5分以内にロールバックできますか?	可逆性ギャップ	フィーチャーフラグとブルーグリーンデプロイを追加
毎週何か新しいことを学んでいますか?	知識ポートフォリオ停滞	週次学習時間をスケジュールし、それを追跡

参照ファイル

• references/dry-orthogonality.md -- DRY知識対コード重複、重複の4つのタイプ、設計とテストでの直交性
• references/tracer-bullets.md -- トレーサー弾対プロトタイプ開発、ウォーキングスケルトン構築、トレーサーコードでの反復
• references/contracts-assertions.md -- コントラクト設計、前提条件/事後条件/不変式、断定的プログラミングパターン
• references/broken-windows.md -- ソフトウェア エントロピー、割れた窓理論、石スープ戦略、劣化との戦い
• references/reversibility.md -- 柔軟なアーキテクチャ、デカップリング戦略、ベンダーロックインの回避、フォーク道決定
• references/estimation-portfolio.md -- PERT見積り、分解テクニック、知識ポートフォリオ管理

さらに詳しく読む

• The Pragmatic Programmer: Your Journey to Mastery, 20th Anniversary Edition by Andrew Hunt and David Thomas

著者について

Andrew Hunt はプログラマー、著者、出版社です。彼は Pragmatic Bookshelf を共同設立し、Agile Manifesto の17人の元の著者の1人でした。彼の仕事はソフトウェア開発の人間的側面――チームがどのように学び、コミュニケーションを取り、時間の経過とともに品質を保つかに焦点を当てています。

David Thomas はプログラマーおよび著者で、Pragmatic Bookshelf を共同設立しました。彼は「DRY」(Don't Repeat Yourself)および「Code Kata」という用語を作り出しました。日本外での Ruby 採用の先駆者で、「Programming Ruby」(Pickaxe book)を共著し、開発者の実用性を教条主義よりも数十年間提唱してきました。