code-that-fits-in-your-head

頭の中に収まるコード

Mark Seemann の 2021 年の書籍に基づく、持続可能なソフトウェアのためのエンジニアリング上のヒューリスティクスと、エージェント時代に加えられた変更点を明確に示しています。

コード例は C# を中心にしていますが、すべてのルールとツールの表は言語に依存しません。

哲学（このスキルが存在する理由）

ソフトウェア開発は、構築ではなく、主として設計活動です。エージェントが文章の大部分を生成しても、できあがったシステムのレビュー、運用、拡張、所有は、依然として人が担います。ここで紹介するヒューリスティクスは、ソフトウェアを持続可能にするためのものです。つまり、理解しやすく、アーキテクチャの劣化に強く、何千もの意思決定を経た後でも変更コストが低い状態を実現します。

第 1 章の基本的なメンタルモデル：

比喩	的を射ている点	見落としている点
家を建てる	計画、構造	ソフトウェアは長く使われます。構築フェーズはありません（コンパイルは無料です）。依存関係はどこからでも始められます
庭を育てる	剪定、リファクタリング、手入れ	コードはそれだけでは改善しません。生成されたコードにも継続的な管理が必要です
芸術／職人技	スキル、熟達、状況に応じた知識	スケールしません。新参者への指針がありません
エンジニアリング（目指す姿）	ヒューリスティクス、レビュー、承認、チェックリスト	まだその段階にはありません。物理的な構築の計算は当てはまりません

「曖昧さのない詳細なプログラムの記述と、プログラミングという行為は、同じものです。」— Kevlin Henney

コードエージェントにとっての実践的な意味：

1. 優れたソフトウェアは長く使われます。 明確な境界を保ち、将来の変更コストを抑える変更を優先してください。
2. 敵はタスクの規模ではなく、複雑さです。 アーキテクチャ、計画、受け入れ基準が適切であれば、エージェントは数万行に及ぶ変更を完了できます。不必要な結合、重複、隠れた作用、検証不能な大量の変更は避けてください。スコープが大きいという理由だけで拒否してはいけません。
3. ルールではなく、ヒューリスティクスです。 ルールを適用したり緩和したりする前に、その目的を理解してください。プロジェクトの方針は、一般的な書式やワークフローの慣例より優先されます。
4. 検証は設計の一部です。 型、テスト、スキーマ、アーキテクチャチェック、可観測性、明示的な受け入れ基準によって、人とエージェントの両方が書いたコードに制約を設けます。
5. コードは負債です。 生成されたコードの量は進捗ではありません。負債を積み上げずに問題を解決する、最小限で一貫性のある設計を優先してください。

持続可能性、読みやすさ、脳の限界を考慮した設計について詳しくは、references/foundations/ を参照してください。

このスキルの使い方

1. ユーザーのタスクを特定します（作成、レビュー、デバッグ、セキュリティレビュー、セットアップなど）。
2. guidelines.md を読みます。タスクや症状に対応する参考ファイルがまとめられています。
3. 現在のタスクに関連する参考ファイルだけを読み込みます（段階的な情報開示）。
4. ルールを適用します。不明な場合は、相互参照について references/practices-glossary/ を確認してください。
5. あるルールがリポジトリで繰り返し役立つとわかった場合は、運用に組み込みます（workflows/operationalize-finding.md）。これにより、ゲートとプロジェクトのエージェント向け指示に反映され、継続的に適用されます。

章の索引

トピック	次の場合に使用します…
references/foundations/	持続可能性、読みやすさ、複雑さの制御、負債としてのコード
references/codebase-setup/	コードベースを立ち上げる、または引き継ぐ場合 — git、ビルドの自動化、警告をエラーとして扱う設定
references/outside-in-tdd/	新機能をテストファーストで実装する場合。ウォーキングスケルトン、AAA、三角測量、悪魔の代弁者、テストの編集
references/encapsulation/	不変条件を備えた型を設計する場合。DTO とドメインモデル、常に有効な状態、Postel の法則、「検証するのではなくパースする」
references/decomposition/	メソッドやシステムの複雑さを制御する場合。循環的複雑度、凝集度、結合度、フィーチャーエンヴィー、フラクタルアーキテクチャ
references/api-design/	公開 API を設計する場合。アフォーダンス、ポカヨケ、CQS、コミュニケーションの階層、コメントより命名
references/separation-of-concerns/	横断的関心事を追加する場合。デコレーターパターン、ロギング、ログに記録する内容、パフォーマンスと可読性
references/teamwork-git/	コミットの作成、変更のレビュー、継続的インテグレーション、集団的な所有権
references/evolution/	稼働中のシステムを変更する場合。フィーチャーフラグ、ストラングラーパターン、バージョニング、定期的な依存関係の更新、コンウェイの法則
references/troubleshooting/	不具合をデバッグする場合。科学的手法、ラバーダッキング、再現をテストにする方法、二分探索、非決定的な不具合
references/security/	脅威モデリング。STRIDE（なりすまし、改ざん、否認、情報漏えい、DoS、権限昇格）
references/code-navigation/	コードベースへのオンボーディング。全体像、ファイル構成、循環依存、プロパティベーステスト、振る舞いに基づくコード分析
references/tooling/	実行可能な測定コマンド。複雑度、循環依存、重複、デッドコード、ホットスポット、ミューテーションテスト
references/practices-glossary/	書籍で名前が付けられたプラクティスとその現在の状況を確認する場合

⚠️ 編集上の追記（書籍の内容ではありません）

以下のフォルダーは、Seemann の書籍の内容ではありません。2021 年の書籍では扱われていない、エージェント固有の課題をカバーするために独自に追加したものです。これらのファイルを Seemann に帰属させないでください。references/agent-native/knowledge.md を参照してください。

トピック	次の場合に使用します…
references/agent-native/	エージェント固有の検証の完全性、ハルシネーションと依存関係の根拠付け、実行可能なガードレール、説明責任のあるレビュー

ワークフロー

複数の手順からなるワークフローは workflows/ にあります。

タスク	ワークフロー
プルリクエスト／コードをレビューする	workflows/review-code.md
新機能をゼロから追加する	workflows/add-feature-outside-in.md
不具合を調査して修正する	workflows/debug-defect.md
新しいエンドポイントの脅威モデリングを行う	workflows/threat-model.md
繰り返し見つかる問題を実行可能なゲートにし、プロジェクトのメモリに保存する	workflows/operationalize-finding.md

ルーティング層全体（タスク → ファイル、症状 → ファイル）については、guidelines.md を参照してください。