architecture-survey について
architecture-surveyは、モジュール境界、呼び出し元、コミット履歴を根拠に、変更が難しくなっている領域を見つけるリポジトリ調査スキルです。深くする候補をリスクや推奨事項とともに順位付けし、コードは変更しません。
主な機能
- 01モジュール境界とコミット履歴の調査
- 02浅いモジュールと仮説的な境界の特定
- 03境界をまたぐ振る舞いの確認
- 04根拠とリスクによる調査結果の順位付け
- 05優先して深くする候補の提案
- 06リポジトリを変更しない調査
活用シーン
- 01チケット対応後のリファクタリング候補探し
- 02変更が難しくなった領域の調査
- 03アーキテクチャ判断に向けた根拠の整理
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/architecture-surveyを入力して読み込まれたか確認します。
詳細
測量士はリーフを測量し、船長は浚渫するかどうかを決めます。 測量では水面を読み、根拠を添えて調査結果を報告し、そこで終了します。これはロフトの保守版です。ロフトが建築前に設計上の問いに一つ答えるのに対し、測量は建築後に「このリポジトリでは、どこが変更しにくくなっていて、どこを深くすればよいのか」に答えます。
測量のタイミング
- 定期的に — アクティブな開発を数日進めるごと、またはチケットをまとめて取り込んだ後。
- 臨時に、先週よりリポジトリの変更が難しくなったと感じたとき。たとえば、編集で必要以上に多くのファイルに触れる、呼び出し元を一つ満たすためにインターフェースが膨らむ、無関係な理由でテストを一斉に更新しなければならない、といった場合です。
任意の引数を指定すると、測量対象をディレクトリまたは領域に絞れます。引数がなければ、リポジトリ全体を測量します。
測量
- リポジトリのアーキテクチャ原則（CLAUDE.md、ADR）と、
docs/standards/architecture.mdにあるシームの用語定義（シームとディープモジュールの定義）を読みます。 - 対象領域のモジュールグラフをたどります。方向が指定されていない場合は、ヤードの活発な水域に重点を置いてたどります。まずコミット履歴を十分に読み、繰り返し登場する領域を手がかりに測量範囲を決めます。将来の編集が行われる場所を深くすることに効果があるためです。履歴が分散していてホットスポットがない場合は、対象を広げます。
- 次の3種類の所見を探します。
- 浅いモジュール — インターフェースは広いのに振る舞いは薄く、呼び出し元がモジュールに隠されている以上のことを把握しています。
- 仮説上のシーム — 境界を越えるアダプターが一つだけで、2つ目の呼び出し元がありません。呼び出し元の数を数えて確認できます。
- 誤ったシームの背後にあるロジック — データを所有していない境界の向こう側に振る舞いがあります。
疑わしいものすべてに撤去テストを適用します。モジュールを削除した場合、その複雑さは消えるでしょうか（制服を着た単なる中継）？ それとも呼び出し元全体に再び現れるでしょうか（荷重を支えるもの）？ 荷重を支える浅さだけを所見とします。
報告
候補は、リスクに対する効果の大きさで順位付けします。各候補には次の項目を含めます。
- 根拠 — インターフェース、呼び出し元、振る舞いを示すファイルと行番号。
- 深くする手立て — 何を深くするか、統合するか、移動するかを一文で記します。
- リスクに関する注記 — 手立てが影響する範囲と、壊れる可能性があるもの。
各候補には、ヤードで共有される所見の用語を明記します。重大度（浅さがどれだけ摩擦を引き起こしているか）、確信度（測量による所見はヒューリスティックな分類であり、性質上低くなります。尺度のうち機械的に確認できる側は、乾ドックの --check 監査が担います）、実行可能性（深くする手立てが、報告だけを見て着手できるほど具体的かどうか）です。最後に最優先の推奨事項を示します。最初に深くすべき候補とその理由を記します。船長が読むカードは一枚で、リーフ全体ではありません。
航海日誌との矛盾。 既存のADRに反する候補を挙げるのは、摩擦が実際にある場合に限ります。その場合、カードにADRと、水域の状況が変わった理由を記載します。理論上の矛盾は報告に含めません。航海日誌に記された却下事項を、標準では再検討しません。
ヤードに図解スキルがある場合、報告を視覚的に表現してもかまいません。ただし、どちらの場合も正本となるのは文章による報告です。
引き継ぎ
レポートは意思決定の材料であり、作業そのものではありません。候補はミッションブリーフ（フェーズ 1 の開始）に取り入れるか、次の取り組みに向けた検討材料にします。調査で提案し、船長が判断します。
最有力候補をその場で検討します。 船長が調査結果を保留せず、すぐに行動に移すことを望む場合、レポートの最有力候補は、同じセッション内で行う設計ツリーインタビューの最初の質問になります。ここで実施するのは、フェーズ 1 の開始時に行うフロンティアプロトコルです。この候補を掘り下げるには何が必要か、コストはいくらか、何が可能になるかを検討します。証拠は新鮮で、船長もその場にいます。ここで検討した発見事項は、古びるのを待つレポートではなく、決定済みの取り組みです。調査では引き続き編集を行いません。インタビューで判断し、実施は開始時の独自のゲートを通じて行います。
船長が重要な理由を添えて却下した候補は、ADR として提案します。適用する ADR の基準は開始時と同じです（元に戻しにくい、背景なしでは意外性がある、実質的なトレードオフがある）。これにより、次回の調査で同じ暗礁が再び候補に挙がるのを防ぎます。理由を添えずに却下された場合は、そのまま消えていきます。
対象外
- コードの編集は行いません。 調査ではリファクタリングを行いません。「まだ新鮮だから」という理由でも行いません。
- ゲートではありません。 レポートを理由に何かがブロックされることはありません。
- ドライドックのドリフト監査には統合しません。
--checkの対象は、引き続き機械的に厳密に確認できるものだけです。確信度の高い発見事項に限ります。アーキテクチャに関する判断は確信度の低いヒューリスティックであり、混在させると契約が希薄になります。
完了の定義
すべての発見事項について、証拠、順位付け、リスクに関する注記を含むレポートが作成され、ファイルが一切変更されていなければ、調査は完了です。