architecture

構造が変更に抵抗している箇所を見つけ、深化を提案します。つまり、より小さなインターフェースの背後に振る舞いを移すリファクタリングです。これにより、コードはテストしやすくなり、エージェントも把握しやすくなります。

新しいコードベースや領域では、まだ摩擦を見つける手がかりがありません。その場合は探索を省き、インタビュー（ステップ 3）に進んで構造と規約を定め、結果を ARCHITECTURE.md に記録します。

このスキルが扱う規約は conventions/ にまとめられており、作業に関係するものだけを読み込みます。implement は実装時にそれらに従います。

デフォルトでは高速に進めます。ユーザーが指定した領域や摩擦だけを調べ、有力な候補をいくつか示し、求められるまではインターフェースの並行設計は保留します。ディープモード（deep スキルが有効な状態）では、コードベース全体を調べ、すべての候補を挙げ、選ばれた候補のインターフェースを並行して設計します。

用語

毎回、LANGUAGE.md の用語を使います。モジュール、インターフェース、実装、深さ、継ぎ目、ポート、アダプター、レバレッジ、局所性です。「コンポーネント」、「サービス」、「API」、「境界」という言葉に流れると、このスキルが明確にしようとしている区別がぼやけます。特に重視する確認事項は次のとおりです。

• 削除テスト：そのモジュールを削除したとき、複雑さは消えるでしょうか（単なる受け渡し役だった）、それともすべての呼び出し元に複雑さが再び現れるでしょうか（そのモジュールには存在価値があった）。
• テストは、呼び出し元が通るインターフェースを通して実行します。
• 2つ目のアダプターが継ぎ目を埋めたとき、その継ぎ目は実在するものになります。
• 複数の利用者を持つインターフェースは約束です。 その背後を深めるときは、呼び出し元が依存しているものを形作り直さず、追加によって実現します。インターフェースを破壊的に変更する場合は、紛れ込ませるリファクタリングではなく、計画すべき移行です。

ドメインモデルに沿って作業を進めます。適切な継ぎ目の名前は CONTEXT.md から導き、docs/adr/ の決定事項は確定済みの前提として扱い、未解決の問いにはしません。書式については、TERMS.md と DECISION-RECORD.md を参照してください。

プロセス

1. 調べる

まず、文書化されている内容を確認します。ARCHITECTURE.md（モジュール、継ぎ目、不変条件を記した最新の地図。そこから変わった点だけを再導出します）、各コンテキストの用語集を含む CONTEXT.md または CONTEXT-MAP.md、そして対象領域に近い ADR を確認してください。ファイルがないことは特に言及する必要はありません。ただし、例外が1つあります。ARCHITECTURE.md のない複雑なコードベースでは、今回の実行内容をもとに FORMAT.md に従って初版を作成することを一度だけ提案し、ユーザーが承認した内容だけを書き込みます。

次に、ユーザーが指定した領域のコードを読みます。ハーネスがサブエージェントを起動する場合はそこで、そうでなければここで読みます。チェックリストに沿うのではなく、摩擦を追ってください。注目すべき兆候は次のとおりです。

• 1つの概念を理解するために、多数の小さなモジュールをたどる必要がある。
• インターフェースが、その背後のコードとほとんど同じくらい複雑である。
• テストのためだけに純粋なヘルパーが切り出されている一方で、バグはその呼び出し方に潜んでいる。
• モジュール同士が深く絡み合い、あるモジュールへの変更が隣のモジュールに波及する。
• テストがない、または現在のインターフェースでは書けるテストがない。

浅く見えるモジュールすべてに削除テストを行います。

2. 提案する

深化の候補を番号付きで列挙します。それぞれについて、次の項目を示します。

• ファイル：関係するモジュール。
• 摩擦：現在の構造によって何が難しくなっているか。
• 変更：何を移すのかを平易な言葉で説明します。
• 効果：レバレッジと局所性の面での利点と、変更後のテストがどのようなものになるか。

ドメインの要素には CONTEXT.md の用語を、構造の要素には LANGUAGE.md の用語を使います。「InvoiceHelper」や「invoice サービス」ではなく、「Invoice 発行モジュール」と呼んでください。

ADR に反する候補は、摩擦がその決定を再検討するだけの根拠となる場合に限って提示し、「ADR-0007 を再検討する。理由は……」のように明記します。ADR ですでに除外されているリファクタリングは候補に含めません。

インターフェースはまだ提案しません。どの候補を詳しく検討するかを尋ねて締めくくります。

3. インタビュー

選んだ候補に対して core-interview スキルを実行します。決定する項目は、制約、依存関係（DEPENDENCIES.mdに従って並べ替えます）、深掘りするモジュールの形、その境界の裏側にあるもの、残すテストです。

決まった内容は、その都度記録します。

• CONTEXT.mdにない概念の名前を付けた、深掘りするモジュール：drillと同じ方法で用語を追加し、ファイルがまだ存在しなければ作成します。会話を通じて曖昧な用語が明確になった場合は、その項目を更新します。
• 新しいモジュール、境界の移動、または新しい不変条件：FORMAT.mdに従ってARCHITECTURE.mdを更新します。
• ユーザーが、今後のレビューで必要になる理由を添えて却下した候補：同じ候補が再提案されないよう、ADRの作成を提案します。「今はやらない」のような一時的な理由や、明白な理由の場合は作成しません。
• 選んだモジュールの代替インターフェース：INTERFACE.md。

結果が実装作業となる場合は、SPEC-FORMAT.mdに従ってdocs/specs/<slug>.mdに仕様を書き、深掘りしたインターフェースと残すテストを受け入れ基準とし、implementに引き渡します。