improve-codebase-architecture

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

../coding-standards/SKILL.md に基づいて、アーキテクチャスキャンを実施します。スキャン対象の境界内で、リファクタリング候補を優先順位付きの短いリストとして1つ提示してください。

仕様を作るのではなく、スキャンしてください。 根拠に基づく所有権の移動を特定した時点で終了します。ファイルの編集、リファクタリングの実行、ドキュメントの更新、ADR の作成、工数の見積もり、最終的なインターフェースの設計、技術仕様書の作成は行わないでください。移行、互換性、段階的な展開、バックフィルについて記録するのは、リポジトリの根拠またはユーザーの意図によって確認できる現在の制約に限ります。スキャン中にこれらの設計を行わないでください。

1. スキャン対象の境界を定める

ユーザーが指定した範囲（リポジトリ、ディレクトリ、機能、モジュール、ファイル群、関心事）を使います。この境界によって、候補を提示できる範囲が決まります。根拠を確認するために必要な場合は、その範囲外の直接の呼び出し元、依存関係、コンポジションルート、テストを調べます。これらをエビデンス・ハローとして記録しますが、そこから候補を提示してはいけません。

有効なスコープが指定されていない場合：

1. リポジトリの構成と主要なエントリーポイントを調べます。
2. リポジトリが小さい場合、または依頼内容が明らかに1つの領域を中心としている場合に限り、スコープを推定します。
3. それ以外の場合は、ユーザーがスコープを選択できるように質問を1つだけします。

../coding-standards/SKILL.md を読みます。スキャン対象の境界と、その祖先ディレクトリをリポジトリのルートまで検索し、CONTEXT.md、CONTEXT-MAP.md、同等のドメイン用語ファイル、意思決定インデックスを探します。リポジトリのドキュメントと ADR のコレクションを検索し、その境界を明示する、または境界に適用される意思決定を探します。見つかった適用対象のソースをすべて確認し、スコープ内のコード、テスト、エビデンス・ハローにある先例も調べます。

完了条件： 候補の対象範囲とエビデンス・ハローが明示されていること、コーディング規約が読み込まれていること、指定されたコンテキストと意思決定の保管場所が検索されていること、見つかった適用対象のソースをすべて確認していること、関連する先例を特定するか、存在しないことを記録していること。

2. エビデンスマップを作成する

ファイルの読み取りと検索のみを使用してください。テスト、型チェック、リンター、フォーマッター、ビルド、パッケージスクリプト、静的解析コマンドは実行しないでください。

境界内のアーキテクチャ上の対象について、非公開のエビデンスマップを作成してください。

• 公開およびランタイムのエントリーポイント
• ドメインおよびアプリケーションのモジュール群
• 外部、永続化、プロセス／ランタイムの境界
• 副作用とリソースのライフタイムを所有する箇所
• これらの接合部をテストするテスト

各箇条書きをインベントリーのカテゴリとして扱ってください。各カテゴリについて、該当する対象、同等のグループ、または対象が存在しないか該当しない場合はその理由を記録してください。対象をグループ化するのは、所有関係と呼び出しフローの形が同じ場合に限り、グループの代表的なファイルを記録してください。

形が異なるものごとに、エントリーポイントまたは直接の呼び出し元から、関連する境界や副作用（存在する場合）を経て、呼び出し元から見える結果に至るまで、少なくとも1つの動作を追跡してください。その接合部に既存のテストがあるかを調査し、見つからなかった場合はその旨を記録してください。対象またはグループ、代表的なファイル、呼び出し経路、結果、既存のテストによる証拠、該当する規約、所見を記録してください。

雰囲気ではなく、エビデンスを重視してください。 アーキテクチャ上の摩擦、つまり繰り返し発生する、境界をまたぐ、呼び出し元に漏れ出す、所有関係を不明瞭にする、または実際の接合部を通した動作のテストを妨げる設計上の負担や正確性のリスクを調べてください。単独のコードスメルは局所的な改善であり、アーキテクチャ上の候補ではありません。

このスキャンでは、インベントリーに含まれる対象が規定する懸念に対処する場合、そのコーディング規約の原則を該当するとみなします。既存のリポジトリを調査してから新たに考案することは、常に該当します。番号付きの各原則を内部で検討し、以下を行ってください。

• 該当するか、該当しないかを分類する
• 該当する各原則について、調査した具体的なコード、呼び出し経路、テスト、値、またはランタイム上の接合部を記録する
• 各所見を、局所的な改善またはアーキテクチャ上の摩擦に分類する

広範囲のスキャンでは、並行して調査し、観察事項を集めてもかまいません。ただし、候補の最終的な選定と順位付けは、一貫した総合判断として行ってください。

完了基準： すべてのインベントリーカテゴリについて、追跡するか、記録済みの同等グループとして示すか、または理由を添えて存在しないか該当しないものとして記載すること。エビデンスの対象範囲を超えた調査と、意図的に対象外としたものをすべて記録すること。番号付きのすべての規約を検討し、該当する規約については調査したエビデンスを示すこと。残す所見はすべて、具体的なアーキテクチャ上の摩擦に基づくこと。裏付けのない所見は除外してください。

3. 候補を形成し、順位付けし、絞り込む

アーキテクチャの変更によって、不変条件、ポリシー、変換、オーケストレーション、副作用、リソースのライフタイム、ランタイムの調整を誰が担うかが変わります。残すことにした摩擦要因をそれぞれ、現在の所有者または呼び出し元から、提案する所有者への所有権の移動に置き換えます。所有者の最終的なインターフェースは設計しないでください。

すべての候補を、標準のカテゴリごとではなく、スキャン対象範囲全体で一緒に順位付けします。アーキテクチャ上の効果、つまり導入するインターフェース、間接性、または仕組みに対して、取り除ける具体的な負担やリスクの範囲と影響度を基準に順位付けしてください。影響を受ける呼び出し元、動作、ランタイムの所有権、テストを考慮します。効果が同程度の場合は、より強い根拠を優先し、次に、より小さく一貫した所有権の移動を優先します。

同じ根本的な摩擦要因に対処する候補、または同じ所有権の移動を必要とする候補は統合します。副次的な標準の改善は、より有力な候補の利点として扱います。見た目だけの変更、根拠のない変更、妥当な既存の局所的な慣例と矛盾する変更、推測に基づく柔軟性、単独のクリーンアップ、またはアーキテクチャを装った実装作業にすぎない候補は除外します。根拠の基準を満たす候補がない場合はゼロ件を含め、候補は最大5件まで残します。

推奨の強さは一貫して使ってください。

• Strong — 摩擦要因、所有権の移動、その効果が具体的な根拠によって裏付けられている場合。
• Worth exploring — 摩擦要因は裏付けられているものの、所有権の移動またはその効果が、正確な未検証の主張に依存している場合。

確認可能な調査を先送りするために Worth exploring を使わないでください。許可された読み取りと検索で検証できる主張は、すべて先に解決してください。ソースの調査では必要な根拠を得られない場合に限り、情報の不足を残します。

完了条件： 残る候補はすべて、具体的な摩擦要因、現在から提案先への所有権の移動、その効果の根拠、既存のテスト根拠、検証の接点、推奨の強さを明記していること。未確定の主張はすべて、ソースからは検証できない正確な根拠の不足であること。候補は5件を超えないこと。

4. 結果を提示する

すべての結果の冒頭に、候補の対象範囲、補足的に参照した根拠の範囲、対象としたインベントリのカテゴリ、判断の基準となるコンテキストまたは決定の情報源、重要な除外事項を記載した簡潔なスキャン概要を示します。

候補が残らなかった場合は、根拠に裏付けられたアーキテクチャ候補が見つからなかったことを述べ、観察された兆候を除外した理由を説明します。最有力候補をでっち上げたり、ユーザーに tech-spec ワークフローの開始を求めたりしないでください。

それ以外の場合は、順位順に簡潔な候補カードを提示します。摩擦要因を証明するために十分な代表的根拠を引用してください。すべての発生箇所を列挙する必要はありません。

### <Candidate title> — <Strong | Worth exploring>

- **Standards:** <applicable coding-standard principle names>
- **Files/modules:** `path:line`, `path:line`
- **Current friction:** <caller burden, risk, duplicated policy, poor seam, or test friction>
- **Evidence:** <concrete call path, repetition, leaked representation, invalid state path, or test contortion>
- **Ownership move:** <current owner or callers> -> <proposed owner>
- **Expected leverage:** <burden or risk removed relative to new machinery>
- **Existing test evidence:** <test path:line or none found>
- **Verification seam:** <public interface or real adapter through which the move would be tested>
- **Evidence gap:** <required only for Worth exploring; the exact source-unverifiable claim>
- **Context/ADR note:** <optional; only for a durable term, conflict, or decision>

呼び出しフロー、データフロー、所有権、またはランタイムのトポロジーを文章よりも明確に示せる場合は、簡潔な現在／提案の ASCII 図を使います。

安定したドメイン用語を明確にする場合に限り、CONTEXT.md に追加する正確な記述を提案します。具体的な摩擦要因が見直しを正当化する場合に限り、ADR との不整合に言及します。

最後に、次の内容を記載します。

Top recommendation: <candidate title> — <why it has the greatest architectural leverage>

Which candidate would you like to prepare for the tech-spec workflow?

完了条件： スキャン概要から順位付けの対象全体が明らかであること。各カードが候補の要件を満たしていること。すべての主張が引用された根拠または正確な根拠の不足に結び付いていること。候補がゼロ件の場合、その分岐に推奨が含まれていないこと。

選定後：引き継ぎを準備する

結果を提示したらそこで停止します。この分岐は、ユーザーが候補を選択した後にのみ実行してください。

../tech-spec/ 向けに、次の項目を含む簡潔な概要を準備します。

• 候補のタイトルと関連するファイル／モジュール。
• 問題、現在の摩擦要因、収集した根拠。
• 現在から提案先への所有権の移動。
• 該当するコーディング標準の原則。
• 既知の制約と不変条件。
• 想定される接点、境界、アダプター、呼び出し経路。
• 未解決の質問。
• 該当する場合は、コンテキストまたは ADR に関する提案。

概要を渡した後、ユーザーにそれを使って @tech-spec を呼び出すよう伝えてください。このスキル内で仕様書を呼び出したり、作成したりしないでください。

完了条件： 概要内のすべての主張がスキャン時の根拠に結び付いているか、未解決の質問として明記されていること。収集したすべての制約、不変条件、影響を受ける経路が含まれていること。ユーザー自身が呼び出す形での引き継ぎを明示的に伝えていること。