コードベース アーキテクチャの改善: 浅いモジュールを深いモジュールに再構築します。

障害モード: 「AI が不正なコードベースをさまよっている」

Matt の講演の 4 番目の失敗モードは、次のような絵の比喩です。

「コードベース内の浅いモジュールは次のようになります。小さな BLOB が多数あり、AI はそれらを修正する前に、多数のモジュールを調べてすべての依存関係を理解する必要があります。」

"AI is really good at creating codebases like this. So you'll have a situation where AI doesn't understand what your code is doing. It will attempt to explore the code, but because it's poorly laid out, filled with shallow modules, it doesn't get to the right module in time, or doesn't understand all the dependencies."

これは AI プログラミング特有の悪循環です。

AI 写代码倾向于产生 shallow 模块（小、多、互相依赖）
    ↓
代码库变得 shallow
    ↓
下次 AI 进来探索更难，更容易写错
    ↓
更多 shallow 模块被加进去
    ↓
代码库越来越烂，AI 越来越无能

このサイクルを断ち切るには、手動によるリバース リファクタリングを定期的に実行し、浅いモジュールを深いモジュールにマージする必要があります。まさに /improve-codebase-architecture が行うことです。

古典的な理論: Ousterhout のディープ モジュール

John Ousterhout はスタンフォード大学の CS 教授 (Tcl 言語と Raft 論文の著者) です。彼の 2018 年の著書「A Philosophy of Software Design」では、シンプルだが強力な定規を提案しています。

モジュールの「深さ」 = インターフェースの隠れた複雑さ

理想的なモジュールは奥深く、ユーザーは短いインターフェイスを見るだけで済み、複雑さは内部に隠されています。極端な反例は浅いモジュールです。インターフェイスは実装とほぼ同じくらい複雑です。これは、カプセル化がないことを意味します。ユーザーは実装を直接見ることもできます。

Ousterhout の判断: 優れたコード ベースは、少数の深いモジュールで構成されています。悪いコードベースは、多数の浅いモジュールで構成されています。これは、「関数をできるだけ小さくし、ファイルをできるだけ短くし、モジュールをできるだけ多くする」という従来の定説とは完全に反対です。彼は、そのような定説がまさに浅いモジュールを生み出すと信じています。

Matt の拡張機能: 削除テスト

マットは、オーステルハウトの理論を運用工学テストに翻訳し、削除テストと呼びました。

Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.

人間の言葉:

• 削除すると複雑さがなくなります → このモジュールは本来パススルー (トランジット) であり、動作しないので切断してください
• 削除すると、複雑さが N 人の発信者に広がります → 元々は複雑さを隠すのに役立ちます。非常に奥深いので、そのままにしてください。

このテストの利点は、双方向であることです。「削除する必要がある薄いパッケージ」と「抽出する必要がある共通ロジック」の両方を識別できます。コードの一部を削除した後に複雑さが 5 か所に広がることがわかった場合、このコードは深いモジュールに抽出する価値があることを意味します。

重要な用語 (Matt の正確な定義)

improve-codebase-architecture/SKILL.md には これらの単語を厳密に使用することが必要な用語集があります。「コンポーネント」、「サービス」、「API」、および「境界」に偏らないようにしてください。

いくつかの基本原則:

• 削除テスト: 上記を参照
• インターフェイスはテスト面です: テストはインターフェイスを通じてのみ実行できます。これはモジュールの詳細なテスト容易性の基礎です。
• ** 1 つのアダプター = 仮想の継ぎ目。 2 つのアダプター = 本物のシーム**: 実装が 1 つだけのインターフェイスは偽シームです。 実際のジョイントには少なくとも 2 つのアダプターが必要です

最後のものは特に直感に反します。多くのチームは「将来の拡張に備えて」事前にインターフェイスを抽象化しますが、実際には実装は 1 つだけです。 Matt の判断: 無駄、削除。 2番目が実現するまで待ちます。これはYAGNIと同じ起源を持ちます。

スキルのワークフロー

1. 探索する

スキルはまず AI に CONTEXT.md と docs/adr/ を読み取らせ、次に subagent_type=Explore を使用してサブエージェントをコード ベースに送信します。

厳密なインスピレーションの代わりに、摩擦を信号として使用します。

• Where does understanding one concept require bouncing between many small modules?
• Where are modules shallow — interface nearly as complex as the implementation?
• Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
• Where do tightly-coupled modules leak across their seams?
• Which parts of the codebase are untested, or hard to test through their current interface?

疑わしい点を見つけるたびに、削除テストを適用します。削除すると複雑さが消えるか、それとも広がるか? 「分散する」という答えは、さらに深める価値のある候補です。

2. 現在の候補者 (発言候補者)

候補者の番号付きリストを提示します。

1. Files: src/orders/parser.ts, src/orders/validator.ts, src/orders/normalizer.ts
   Problem: 三个文件互相调用，理解 Order 入站需要在三处跳转
   Solution: 合并为单一 OrderIntake 模块，对外只暴露 parse(raw) → ValidatedOrder
   Benefits:
     - Locality: Order 入站的所有逻辑、错误处理、bug 修复集中一处
     - Leverage: 调用方从理解 3 个接口降为 1 个
     - Tests: 只需测 parse() 的输入输出，不再需要 mock 内部协作

要件:

• CONTEXT.md 語彙を使用してドメイン (「FooBarHandler」ではなく「注文受付モジュール」) について話します。
• 用語集 (「継ぎ目」、「深さ」、「局所性」) を使用して建築について話します。
• インターフェイス デザインをすぐに提案しないでください – ユーザーが最初に興味のある候補を選択できるようにします

候補者が既存の ADR と競合する場合 - 競合により ADR を再検討する必要がある場合にのみ言及し、それを明確にマークします。

"contradicts ADR-0007 — but worth reopening because…"

ADR で禁止されているリファクタリングをすべて掘り出さないでください。

3. グリルループ

ユーザーが候補を選択した後、グリル モードにドロップします (/grill-with-docs から継承)。

• デザイン ツリーをウォークスルーします - 制約、依存関係、深くした後のモジュールの形状、継ぎ目の後ろに隠れているもの、どのテストが生き残れるか
• 副作用はすぐに発生します:
• 深化モジュールにCONTEXT.mdにない名前を付ける→すぐにCONTEXT.mdに追加
• 拷問で曖昧な用語が先鋭化 → CONTEXT.mdをすぐに更新
• ユーザーは負荷を理由に候補者を拒否 (重要、将来の探索者が知っておくべきこと) → ADR の生成を提案
• 深化モジュールのさまざまなインターフェイス設計を検討したい → INTERFACE-DESIGN.md 別のプロセスにジャンプ

ドキュメントの保守とアーキテクチャの変革は同じ会話で行われます。2 回繰り返すことはありません。

実際のケース: メイバ・アーメドの実践

サードパーティ開発者の Mejba Ahmed は、このスキルを使用した経験を詳細に記録する記事 ["Deep Modules: The Claude Code Skill Saving My Codebase"] (https://www.mejba.me/blog/improve-codebase-architecture-skill-deep-modules) を作成しました。重要なポイント:

• 彼はもともとプロジェクトに 50 以上のファイルを持っていましたが、各ファイルの行数は 100 行未満でした - 典型的な浅いライブラリ
• /improve-codebase-architecture は 8 つの深化候補を使い果たしました
• 彼は 3 つの深化を選択しました (2 つのデータ処理モジュールが統合され、1 つのツールセットが統合されました)
• 結果: ファイル数は 50 以上から 30 以上に減少しましたが、合計コード サイズは基本的に同じままです - 複雑さは少数の深いモジュールに圧縮されています
• このライブラリにおけるクロードのその後のコード変更のヒット率が大幅に向上しました (彼は「60% から 90%」と述べました。これは厳密に測定したわけではありませんが、強いと感じました)

Mejba は次の注意事項もあります: 一度に 8 つずつ深めないでください。一度に 1 つだけを選択し、テストを実行し、コミットし、観察してから、次のものを選択します。それ以外の場合、完了後にロールバックする方法はありません。

インストールと使用方法

npx skills@latest add mattpocock/skills

improve-codebase-architecture + setup-matt-pocock-skills を確認してください。

電話: /improve-codebase-architecture

推奨リズム:

• 週に 1 回、または各スプリントの最後に実行
• または **集中的な開発の波が完了した後に一度実行します (AI コードを高頻度で作成した後は、浅いモジュールを積み上げることが特に簡単です)
• 急いでいるときは実行しないでください - 急いでいるときには消化する時間がないような大きな変化を示唆します。

一般的なプロセス:

1. /improve-codebase-architecture
2. AI探索 + N個の候補リスト（削除テスト引数付き）
3. 最も感じるものを選択します
4. グリルループ調整デザインにドロップ
5. AI 実装のリファクタリング (/tdd と一緒に実行することをお勧めします。リファクタリングにはテスト保護が必要です)
6. コミット + 観察
7. 1週間後にまた来てください

このスキルが Matt のワークフローの「クローズド ループ」であるのはなぜですか?

Matt のワークフロー図に戻ります。

/grill-me → /to-prd → /to-issues → /tdd → /improve-codebase-architecture → 回到 /grill-me

開始点にループバックしていることに注意してください。 /improve-codebase-architecture は 1 回限りのツールではなく、定期的なメンテナンスです。理由は次のとおりです。

1. AI はコードベースに浅いモジュールを追加し続けます (これはデフォルトの傾向であり、書きすぎると山積みになります)
2. ビジネスが進化し続けると、古い継ぎ目は時代遅れになります。
3. CONTEXT.md の用語は引き続き改良されており、古い名前は維持されません。

このスキルを実行するたびに、コードベースの AI フレンドリーさが更新されます。これは、LLM でコードベースを長期的に健全に保つ唯一の方法です。更新しないと、3 か月後に AI がコードベースで停止します。

この一連の考え方はスキルそのものよりも価値があります

/improve-codebase-architecture をまったくインストールしなくても、次の 3 つのことを覚えておくだけで、PR レビューの品質がワンランク上がります。

1. 削除テスト: 新しいモジュールを見つけるたびに、「削除したら、複雑さは消えるのか、それとも広がるのか?」と自問してください。
2. 少なくとも 2 つのアダプターを真に継ぎ目: 単一の実装インターフェイス = false abstract、削除
3. インターフェースはテスト面です: 測定できない = インターフェースの設計に問題があります

これら 3 つの項目には AI やスキルは必要ありません。これらはエンジニアリングの美学の貴重な通貨です。 Matt はこれらをバッチ実行用のスキルにラップしていますが、実際に活用するのは 3 つの原則そのものです。

注意事項

あまり深く入らないでください。 Ousterhout 自身は、ディープ モジュールは教義ではなく目標であると述べました。すべての機能を詰め込んだ大きな Util クラスはディープ モジュールではなく、神モジュールです。判断基準は「シンプルなインターフェース＋一貫した実装」であり、両方を満たす必要があります。

深化にはテスト保護が必要です。構造変更はリスクの高い操作であり、テストせずにあえてリファクタリングを行う = 責任を負うのを待つことになります。現在テストがない場合は、/tdd に移動してクリティカル パスにテストを追加してから戻ってきます。

ADR の決定は気まぐれに行われるべきではありません。グリル中に候補者を拒否すると、AI は簡単に ADR の生成を提案します。その理由が本当に「将来の人が知っておく必要がある」場合にのみ、ADR を受け入れます。そうしないと、docs/adr/ がジャーナル エントリでいっぱいになります。

コードの一部が浅くても問題ありません。ロガーラッパー、定数ファイル、一回限りのスクリプト - それらは浅いので問題ありません。このスキルは、抽象化を支援するふりをしながら、実際には混乱を加えている浅いモジュールを探します。

参考リソース

シリーズの結論

これまでの6つの記事をすべて読みました。ワークフロー全体を確認します。

/grill-me 或 /grill-with-docs   ← 谈清楚要做什么
        ↓
   /to-prd                       ← 凝固成 PRD
        ↓
   /to-issues                    ← 切成 vertical slice
        ↓
   /tdd                          ← 一个 slice 一个 slice 跑红绿
        ↓
   /improve-codebase-architecture ← 周期性深化
        ↓
        回到 /grill-me

このプロセスの精神は次の 1 つの文に凝縮できます。

**AI は地上の戦術兵士であり、あなたは戦略層です。 「問題の定義」「問題の分解」「問題のテスト」の3つを持ち帰って自分でやり、「コードを書く」ことはAIに任せる、これがAI時代のエンジニアの本当の立場です。 **

Matt の一連のスキルは究極の答えではありませんが、現段階でのベスト プラクティスです。 3 か月後にはもっと良いものがあるかもしれませんが、精神的な側面は変わりません。良いコード ベースは悪いコード ベースよりも常に重要であり、基本的なソフトウェア スキルは常に価値があります。

概要 に戻るか、最も便利なスキルを選択してインストールして試してください。