複利エンジニアリング: 劣化ではなく加速するコードベース

多くのコードベースは成長とともに遅くなります。私のコードベースは加速します。.claude/インフラストラクチャとして95のフック、44のスキル、14の設定ファイルを構築した結果、新しい機能の追加コストは前回よりも低くなっています。インフラがより多くの作業を引き受けてくれるからです。¹

TL;DR

複利エンジニアリングとは、機能を追加するたびに次の機能の構築コストが下がるコードベースのことです。私はこれを実際に体験しました。Claude Codeのフックシステムは3つのフックから始まり、95にまで成長しました。最初のフックは構築に1時間かかりました。最近のフックは10分で完成します。インフラ（ライフサイクルイベント、設定の読み込み、状態管理、テストハーネス）がすでに存在しているからです。反対のパターンであるエントロピーエンジニアリングは、機能を追加するたびに次の機能のコストが増加するコードベースを指します。3年目に1年目より速くリリースできるチームと、停滞に陥るチームの違いは、エンジニアリング上の意思決定がプラスに複利するか、マイナスに複利するかにかかっています。

複利の実践：私の.claude/インフラストラクチャ

成長曲線

最初のフック（git-safety-guardian.sh）では、フックのライフサイクル全体を構築する必要がありました。PreToolUseイベントの理解、JSON入力をパースするbashスクリプトの作成、エラーケースの処理、手動テストです。95番目のフックはそのインフラをすべて継承しました。フックあたりの作成時間が6分の1に減ったのは、フックが単純になったからではなく、インフラがより多くの作業を処理するようになったからです。

何が複利するのか

パターンの一貫性。 すべてのフックは同じ構造に従います。JSON入力を読み取り、jqでパースし、条件をチェックし、判定結果をJSONで出力します。どのフックを読んでも、開発者（またはAIエージェント）はすぐにパターンを認識できます。私の12モジュールのブログリンターも同じ一貫性の原則に従っています。各モジュールは同じインターフェース（check(content, meta) -> findings）をエクスポートするため、新しいモジュールの追加は容易です。

設定駆動の振る舞い。 14のJSON設定ファイルすべてが、もともとハードコードされていた閾値やルールをエンコードしています。議論の合意閾値をPythonのハードコードされた0.70からdeliberation-config.jsonに移行したことで、コード変更なしにタスクタイプごとに調整できるようになりました（セキュリティ=85%、ドキュメント=50%）。²

テストインフラ。 最初の20のフックにはテストがありませんでした。テストハーネスの追加（48のbash統合テスト、81のPythonユニットテスト）には2週間かかりました。それ以降のすべてのフックは、フィクスチャ、アサーションヘルパー、テストランナーがすでに存在しているため、5分以内にテスト付きで出荷できます。

メモリシステム。 MEMORY.mdファイルは、セッションをまたいでエラー、意思決定、パターンを記録します。54のエントリにより、同じミスを繰り返すことを防いでいます。フック#23で発見した((VAR++))のbashの落とし穴は、フック#24から#95まで同じバグを防いできました。各エントリは将来のすべてのセッションにわたって複利します。³

複利モデル

正の複利

エンジニアリングの生産性は複利の公式に従います。

Productivity(n) = Base × (1 + r)^n

ここでrは機能あたりの生産性変化率、nはリリースした機能の数です。

正のr（複利）： 各機能が次の機能を2〜5%安くします。50機能後：1.03^50 = 4.38倍の生産性向上。

負のr（エントロピー）： 各機能が次の機能を2〜5%高くします。50機能後：0.97^50 = 0.22倍の生産性、つまり78%の劣化。

50機能後のこの2つの軌道の差は、エンジニアリング速度で20倍の開きになります。⁴

私の実際の数値

blakecrosley.comは、1つのFastAPIルートと1つのHTMLテンプレートから始まりました。9ヶ月後の状況です。

最後の行が複利の成果です。新しいリンターモジュールの追加に15分しかかからないのは、モジュールインターフェース、CLI統合、テストハーネス、CIパイプラインがすでに存在しているからです。最初のモジュールはそのインフラが何もなかったため3時間かかりました。⁵

私自身のコードベースにおけるエントロピーの例

複利は自動的には起こりません。私もエントロピーを経験してきました。

ContentMetaスキーマの安易な決定

ブログ記事のContentMetaデータクラスを1回のセッションで定義しました。title、slug、date、description、tags、author、publishedです。category、series、hero_image、scripts、stylesは含めませんでした。後からの各追加で、パーサーの修正、メタデータを利用するすべてのテンプレートの更新、パイプライン全体の再テストが必要になりました。3ヶ月にわたる5回の追加は、最初にスキーマを慎重に設計するよりも合計で多くの時間を費やしました。これは意思決定のタイミングの問題です。不可逆的な意思決定には事前の分析が必要です。

i18nキャッシュキーの衝突

翻訳キャッシュの簡易実装では、ブログのスラッグをキャッシュキーとして使用しました。同じスラッグの翻訳が異なるロケールに存在する場合、キャッシュが間違った言語を返していました。デバッグに3時間かかりました。修正は15分で完了しました（キャッシュキーにロケールプレフィックスを追加）。実装時に5分を節約した手抜きが、デバッグに3時間とシステム内のすべてのキャッシュキーのアーキテクチャレビューというコストを生みました。⁶

3.2GBのデバッグディレクトリ

フックのデバッグ出力が~/.claude/debug/にクリーンアップなしで蓄積されました。3ヶ月間でディレクトリは3.2GBに膨れ上がりました。後に構築したコンテキスト監査スキルがこれを検出し、7日より古いファイルをクリーンアップしましたが、クリーンアップのインフラは最初のデバッグ出力と同時に構築すべきでした。

複利する習慣

最適なパターンよりも一貫したパターン

50の機能で同じ「十分に良い」パターンを使うチームは、各機能に「最適な」パターンを個別に使うチームよりも速く動きます。一貫性は認知負荷を減らし、自動化ツールを可能にし、コードレビューを高速化します。⁷

私のフックシステムでは、一部のフックがPythonでより自然に表現できるにもかかわらず、95のフックすべてで同じbashパターンを使用しています。この一貫性により、1つのフックを読んだ人（またはAIエージェント）であれば、どのフックも理解できます。言語選択が最適でないことは、新しいフックの学習コストがゼロであることで十分に相殺されます。

インフラを最初の機能として構築する

blakecrosley.comでは、プロダクト機能を構築する前にCI/CDパイプライン、テストハーネス、デプロイワークフローを構築しました。当時は遅く感じる投資でした。それ以降のすべての機能は、自動テスト付きで2分以内にデプロイされています。⁸

マインドパレスパターン

私の.claude/ディレクトリは「マインドパレス」として機能しています。人間とAIの両方の利用に最適化された構造化ドキュメントの集合体です。

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

マインドパレスが複利するのは、新しいエントリが追加されるたびに将来の開発セッションで利用可能なコンテキストが豊かになるからです。54のMEMORY.mdエントリにより、AIエージェントは私がすでに解決した間違いを回避します。95のフックがあれば、新しいフックは確立されたパターンに従って自然に書けます。より豊かなコンテキストがより適切なAI生成コードを生み出し、次の機能をさらに安くします。⁹

AI時代の複利

AIは両方の方向を増幅する

AIコーディングアシスタントは、コードベースがすでに従っているパターンを加速させます。一貫したパターンを持つ私の95のフックは、AIが確立された構造に合わせるため、優れたAI生成フックを生み出します。5つの異なるフックスタイルを持つコードベースでは、AIが一貫したパターンを見つけられないため、より質の低いAI生成コードが生まれます。¹⁰

複利効果は二重になります。一貫したパターンは人間の開発を高速化し（認知負荷の軽減）、かつAI支援開発も高速化します（パターンマッチング）。一貫性のないパターンは両方を遅くします。

エージェントが読めるコードベース

私の.claude/インフラはAIエージェントによる利用を前提に設計されています。

• 構造化された設定（ハードコードされた値ではなくJSON）により、エージェントがプログラム的にパースできます
• 一貫した命名規則（フックはverb-noun.sh、スキル定義はSKILL.md）
• 機械検証可能な品質チェック（エージェントが自律的に実行する141のテスト）
• 明示的なドキュメント（MEMORY.md、ハンドオフ、docs/）をエージェントがセッション開始時に読み取ります

エージェント可読性への投資は、AIツールの能力向上に伴い複利します。¹¹

重要なポイント

エンジニア向け： - コードベースの成長に伴う「機能あたりの時間」を追跡しましょう。増加していればエントロピー、減少していれば複利です - 抽象化を抽出する前に「3回ルール」を適用しましょう。具体的な解決策を2回構築してから、3回目の発生時に再利用可能なパターンを抽出します - 各スプリントの15〜20%をインフラとツールの改善に投資しましょう。複利のリターンは3〜5スプリント以内に短期的な機能開発速度のコストを上回ります

エンジニアリングマネージャー向け： - エンジニアリングの健全性は、機能あたりのリードタイムの推移で測定しましょう。リードタイムの増加はエントロピーのシグナルです - ドキュメントとテストインフラは、オーバーヘッドではなく機能として扱いましょう。私のテストインフラへの投資（2週間）は、95のフック全体で50時間以上を節約しました

参考文献