コードベースアーキテクチャの改善

アーキテクチャ上の摩擦を浮き彫りにし、深化機会 — 浅いモジュールを深いものに変えるリファクタリング — を提案します。目的は検証可能性と AI ナビゲーション可能性です。

用語集

これらの用語は全ての提案で正確に使用してください。一貫した言語が重要です。「component」「service」「API」「boundary」に流れ込まないでください。完全な定義は LANGUAGE.md にあります。

• Module — インターフェースと実装を持つ任意のもの（関数、クラス、パッケージ、スライス）。
• Interface — モジュールを使うために呼び出し元が知る必要があるすべてのもの：型、不変条件、エラーモード、順序、設定。型シグネチャだけではありません。
• Implementation — 内部のコード。
• Depth — インターフェースでのレバレッジ：小さなインターフェースの背後に多くの振る舞いがあること。Deep = 高いレバレッジ。Shallow = インターフェースが実装とほぼ同等の複雑さ。
• Seam — インターフェースが存在する場所；その場所で編集せずに振る舞いを変更できる場所。（「boundary」ではなくこれを使用）
• Adapter — seam でインターフェースを満たす具体的なもの。
• Leverage — 呼び出し元が depth から得るもの。
• Locality — メンテナーが depth から得るもの：変更、バグ、知識が 1 箇所に集中すること。

主要原則（完全なリストは LANGUAGE.md を参照）：

• 削除テスト：モジュールを削除することを想像してください。複雑性が消えれば、パススルーでした。N 個の呼び出し元全体に複雑性が再び現れれば、それは価値を生み出していました。
• インターフェースはテスト表面です。
• 1 つのアダプター = 仮説的 seam。2 つのアダプター = 実際の seam。

このスキルはプロジェクトのドメインモデルによって 情報提供されます。ドメイン言語は良い seam に名前を与えます；ADR は、このスキルが再度検討すべきでない決定を記録します。

プロセス

1. 探索

触れている領域の プロジェクトのドメイン用語集と ADR を最初に読んでください。

その後、subagent_type=Explore で Agent ツールを使ってコードベースを歩んでください。厳密なヒューリスティックに従わず、有機的に探索し、摩擦を感じた場所をメモします：

• 1 つの概念を理解するために多くの小さなモジュール間を行き来する必要がある場所はどこですか？
• shallow なモジュール — インターフェースが実装とほぼ同等の複雑さのもの — はどこですか？
• 純粋関数がテスト可能性のためだけに抽出されているが、実際のバグは呼び出され方に隠れている場所はどこですか？（locality がない）
• 密結合モジュールが seam を越えて漏れ出ている場所はどこですか？
• コードベースのどの部分がテストされていない、または現在のインターフェースを通じてテストするのが難しいですか？

疑わしいものに対して 削除テスト を適用してください：削除することで複雑性を集約するか、単に移動するだけか？「はい、集約します」が欲しい信号です。

2. 候補を提示

深化機会の番号付きリストを提示してください。各候補について：

• Files — 関連するファイル/モジュール
• Problem — 現在のアーキテクチャが摩擦を引き起こしている理由
• Solution — 何が変わるかについての平易な英語での説明
• Benefits — locality と leverage の観点から説明、また テストがどのように改善されるかについても説明

CONTEXT.md のボキャブラリーをドメインに使用し、LANGUAGE.md のボキャブラリーをアーキテクチャに使用してください。 CONTEXT.md が「Order」を定義している場合、「the Order intake module」と話してください — 「the FooBarHandler」ではなく、「the Order service」でもなく。

ADR 競合：候補が既存の ADR と矛盾する場合、摩擦が ADR を再開するほど実在するときだけサーフェスしてください。明確にマークしてください（例："contradicts ADR-0007 — but worth reopening because…"）。ADR が禁止するすべての理論的なリファクタをリストしないでください。

まだインターフェースを提案しないでください。ユーザーに聞いてください：「これらのどれを探求したいですか？」

3. グリリングループ

ユーザーが候補を選んだら、グリリング会話に入ります。設計ツリーを一緒に歩んでください — 制約、依存性、深化されたモジュールの形状、seam の背後に何があるか、どのテストが生き残るか。

決定が結晶化するにつれて、副作用はインラインで発生します：

• CONTEXT.md にない概念の後に深化モジュールを命名していますか？ その用語を CONTEXT.md に追加してください — /grill-with-docs と同じ規律で（CONTEXT-FORMAT.md を参照）。存在しない場合はファイルを遅延作成します。
• 会話中に曖昧な用語を鋭くしていますか？ CONTEXT.md をそこで更新します。
• ユーザーが負荷をかけている理由で候補を拒否していますか？ ADR を提供してください。フレーム："Want me to record this as an ADR so future architecture reviews don't re-suggest it?" 理由が実際に将来のエクスプローラーが同じことを再提案しないために必要な場合のみ提供 — ephemeral な理由（「今は価値がない」）と自明な理由はスキップしてください。ADR-FORMAT.md を参照してください。
• 深化モジュールの代替インターフェースを探求したいですか？ INTERFACE-DESIGN.md を参照してください。