architecture-deepener

name	architecture-deepener
description	コードベースから deepening（深化）の機会を発見し、shallow なモジュールを deep に作り変えてテスタビリティと AI ナビゲート性を高めるアーキテクチャ改善スキル。「アーキテクチャを改善して」「モジュールの深さをレビューして」「密結合なモジュールを統合して」「コードベースをテストしやすくして」などで発動する。HTML レポートで候補提示し grilling で設計を詰める。
metadata	{"version":"1.1.2","tier":"experimental","category":"maintenance","tags":["architecture","refactoring","deep-modules","testability","seams"]}

Architecture Deepener

アーキテクチャ上の摩擦を可視化し、deepening（深化）の機会 — shallow なモジュールを deep なモジュールへ作り変えるリファクタリング — を提案する。狙いはテスタビリティとAI ナビゲート性の向上。

このスキルは「直接修正する」スキルではない。候補の発見 → HTML レポート提示 → grilling（深掘り対話）→ インターフェース設計という探索・合意形成のワークフローを駆動する。実際の修正適用は code-simplifier 等の実装スキルに委ねてよい。

---

用語集（すべての提案でこの語彙を厳密に使う）

語彙の一貫性こそが要点。「component」「service」「API」「boundary」へ流れない。完全な定義は references/language.md。

• Module（モジュール） — インターフェースと実装を持つもの全般（関数・クラス・パッケージ・層をまたぐスライス）。規模に依存しない。
• Interface（インターフェース） — 呼び出し側がそのモジュールを正しく使うために知らねばならないすべて。型シグネチャだけでなく、不変条件・順序制約・エラーモード・必要な設定・性能特性を含む。
• Implementation（実装） — モジュールの内側のコード。
• Depth（深さ） — インターフェースにおけるレバレッジ。小さいインターフェースの背後に大量の振る舞いがある＝deep。インターフェースが実装とほぼ同じ複雑さ＝shallow。
• Seam（シーム）（Michael Feathers）— その場を編集せずに振る舞いを差し替えられる場所。インターフェースが存在する位置。「boundary」とは言わない。
• Adapter（アダプタ） — シームでインターフェースを満たす具体物。
• Leverage（レバレッジ） — 深さから呼び出し側が得るもの。学ぶインターフェース量あたりの能力。
• Locality（局所性） — 深さから保守者が得るもの。変更・バグ・知識・検証が一箇所に集中する。

主要原則（全リストは references/language.md）:

• 削除テスト（deletion test）: そのモジュールを削除すると想像する。複雑さが消えるなら pass-through（素通し）だった。複雑さが N 個の呼び出し側に再出現するなら、そのモジュールは価値を生んでいた。
• インターフェースこそがテスト面（test surface）である。
• アダプタ1個 = 仮説的なシーム。アダプタ2個 = 本物のシーム。

このスキルはプロジェクトのドメインモデルに情報を与えられる。ドメイン言語は良いシームに名前を与え、ADR は再蒸し返ししてはならない決定を記録する。

---

パス解決

このSKILL.mdが置かれているディレクトリを SKILL_DIR、その親を SKILLS_DIR とする。関連スキルは名前で検索する: ${SKILLS_DIR}/[skill-name]/SKILL.md。

---

プロセス

1. 探索（Explore）

最初に探索範囲を絞る。ユーザーが対象を指定していればそれに従う。指定がなければ git log --name-only などで最近繰り返し変更されたファイル群を確認し、変更頻度の高い領域を優先する。変更が分散して明確なホットスポットがなければ探索範囲を広げる。deepening は将来の変更コストを下げる投資なので、動いていない領域を最初から網羅的に調べない。

次に、対象領域のドメイン用語集（CONTEXT.md / ドメイングロッサリ。なければ domain-modeler の成果物）と ADR を読む。

次に Agent ツールを subagent_type=Explore で使ってコードベースを歩く。硬直的なヒューリスティクスに従わず、有機的に探索し、摩擦を感じる場所を記録する:

• 1つの概念を理解するのに、多数の小さなモジュールを行き来する必要がある場所はどこか
• shallow なモジュール — インターフェースが実装とほぼ同じ複雑さ — はどこか
• テスタビリティのためだけに純粋関数を抽出したが、本当のバグは「どう呼ばれるか」に潜んでいる（locality がない）場所はどこか
• 密結合なモジュールがシームを越えて漏れている場所はどこか
• 現在のインターフェースを通してはテストできない・テストしにくい場所はどこか

shallow だと疑うものには削除テストを適用する: 削除したら複雑さが集中するか、ただ移動するだけか。「集中する（yes）」が欲しいシグナル。

2. 候補を HTML レポートとして提示

通常はリポジトリに何も残さないよう、OS の一時ディレクトリに自己完結型 HTML を書き出す。一時ディレクトリは $TMPDIR（なければ /tmp、Windows は %TEMP%）から解決し、<tmpdir>/architecture-review-<timestamp>.html に書く。ユーザーが保存・共有・前回比較を求めた場合だけ、指定された永続パスへ直接書く。保存先が未指定なら、レポート提示後に保存先を1つだけ尋ねる。

HTML は インライン CSS とインライン SVG / HTML だけで構成し、外部 CDN・JavaScript・フォント・画像へ依存させない。file:// でオフライン表示できることを自己完結の条件とする。各候補に before/after の視覚化を付ける。

出力は常に日本語で書く。 レポートのタイトル、候補名、バッジ、図中ラベル、課題、解決案、利点、最優先候補を日本語に限定する。アーキテクチャ語彙も「モジュール・インターフェース・実装・深さ・深い・浅い・シーム・アダプタ・レバレッジ・局所性」の表記を使う。コード識別子、ファイル名、既存データの値だけは原文を残してよい。

OS に応じて開く（Linux: xdg-open、macOS: open、Windows: start）。開けない環境でも読めるよう絶対パスを必ず伝える。

各候補はカードとして:

• Files — 関与するファイル/モジュール
• Problem — 現アーキテクチャがなぜ摩擦を生むか（1文）
• Solution — 何が変わるか（平易な英語/日本語、1文）
• Benefits — locality と leverage、テストがどう改善するかで説明
• Before / After 図 — 並置。shallowness と deepening を描く
• Recommendation strength — Strong / Worth exploring / Speculative のいずれかをバッジで

レポート末尾に Top recommendation セクション: 最初に取り組むべき候補とその理由。

ドメインには CONTEXT.md の語彙を、アーキテクチャには references/language.md の語彙を使う。 CONTEXT.md が "Order" を定義しているなら「Order intake module」と呼ぶ。「FooBarHandler」でも「Order service」でもない。

ADR との衝突: 候補が既存 ADR と矛盾する場合、摩擦が ADR 再検討に値するほど現実的なときだけ提示する。カード内に明示する（例: 警告コールアウト「ADR-0007 と矛盾 — だが…の理由で再オープンの価値あり」）。ADR が禁じる理論上のリファクタを片端から列挙しない。

完全な HTML スキャフォールド・図パターン・スタイル指針は references/html-report.md。

ここではまだインターフェースを提案しない。ファイル書き出し後、ユーザーに問う:「どれを深掘りしますか？」

3. Grilling ループ（深掘り対話）

ユーザーが候補を選んだら、grilling 対話に入る。質問は1つずつ行い、回答を待ってから次へ進む。コードや環境から判定できる事実は自分で調べ、人間の決定だけを尋ねる。設計ツリーを一緒に歩く — 制約・依存・深化後モジュールの形・シームの背後に何が座るか・どのテストが生き残るか。

決定が固まるにつれ、副作用がインラインで起きる:

• 深化後モジュールを CONTEXT.md にない概念で命名する? → その用語を CONTEXT.md に追加する（ファイルがなければ遅延作成。ドメイン用語管理は domain-modeler / doc-coauthoring と同じ規律）。
• 対話中に曖昧な用語が鋭くなった? → その場で CONTEXT.md を更新する。
• ユーザーが根拠のある理由で候補を却下した? → ADR を提案する:「将来のアーキテクチャレビューが同じ提案を再生産しないよう、ADR に記録しますか？」。将来の探索者が同じ再提案を避けるのに実際に必要な理由のときだけ提案する（「今はやる価値がない」等の一時的・自明な理由はスキップ）。ADR の作成は doc-coauthoring に委ねてよい。
• 深化後モジュールの代替インターフェースを探りたい? → references/interface-design.md。

依存カテゴリ別の安全な深化手順（in-process / local-substitutable / ports & adapters / mock）とテスト戦略は references/deepening.md。

---

参照ファイル

知りたいこと	参照
アーキテクチャ語彙の完全定義・原則	references/language.md
依存カテゴリ別の安全な深化手順・テスト戦略	references/language.md と references/deepening.md
HTML レポートのスキャフォールド・図パターン・スタイル	references/language.md と references/html-report.md
代替インターフェース設計（並列サブエージェント）	references/language.md、references/deepening.md、references/interface-design.md

---

他スキルとの境界

• code-simplifier: 変更された diff を直接修正する。本スキルは shallow→deep の深化機会の発見・合意形成（HTML レポート + grilling）に特化し、合意した深化を実際に適用する段で code-simplifier と連携する。
• legacy-modernizer: 大規模・レガシーの段階的移行戦略を立てる。本スキルはモジュール単位の深さに焦点を当てる。
• codebase-onboarding: 既存コードベースを俯瞰解説する。本スキルは解説ではなく、改善（深化）候補の提案を行う。