| name | html-reports-arch |
| description | html-reports の architecture レポート群をコードベース構造に対する写像として管理するスキル。
分割統治パターンで偵察→動的タスク生成→Agent 委譲→統合→再計画→飽和判定を回し、
特定言語/フレームワークに依存しないアーキテクチャ可視化を行う。
ページは時系列ではなく構造に対応 (overview / module-* / flow-*)。
Use when: "アーキ更新", "architecture refresh", "html-reports-arch",
"アーキスナップショット", "コードベース図を更新", "コードベース可視化",
"/arch-refresh", "loop /arch-refresh", "architecture 再生成",
"ユースケース分析", "依存関係マップ"
|
html-reports-arch
html-reports の architecture ページ群を「コードベースに対する写像」として管理する補助スキル。
設計思想
1. 時系列ではなく構造に基づく写像
architecture は他種別と異なり 日付 prefix を付けない。
ファイル名はコードベース上の役割を直接表す:
.claude/reports/architectures/
├── overview.html ← 全体像 (常設、必須)
├── module-<name>.html ← 主要モジュール毎 (可変、コードベース依存)
├── flow-<name>.html ← 横断ユースケース (可変)
└── _archived/ ← 削除されたページ
更新時は既存ページを in-place 上書きする。
2. 分析手順は固定しない — 分割統治で動的に組み立てる
重要原則: コードベースは Unity だったり Next.js だったり Go monorepo だったりするので、
「asmdef を grep して...」のような固定チェックリストは持たない。
代わりに orchestrator パターンで動的に分析タスクを生成・委譲・統合・再計画する。
本スキルが明示するのは「メタな手順」(どう探索するか) であって、「具体的なコマンド」ではない。
ページ種別と CLI
| slug 規則 | テンプレ | 用途 |
|---|
overview (固定) | architecture-overview.html | 全体像 (常設、必須) |
module-<name> | architecture-module.html | 個別モジュール (内部構造 + Ports) |
flow-<name> | architecture-flow.html | 横断ユースケース (シーケンス + コントラクト) |
mise run report:new -- architecture overview "コードベース全景"
mise run report:new -- architecture module-domain "Domain 層"
mise run report:new -- architecture flow-checkout "Checkout フロー"
ファイル名は日付 prefix なし。new-report.sh が slug prefix で page を自動判定し、
HEAD コミットハッシュを <meta name="report:commit"> と _index.js の commit_hash に埋め込む。
可視化スタック (CDN ロード)
| ライブラリ | 用途 |
|---|
| Cytoscape.js + cytoscape-dagre | 依存グラフ (pan/zoom, クリック詳細, レイアウト切替) |
| ECharts | Treemap / Sankey |
| Mermaid | シーケンス図 |
テンプレ側は <script id="arch-data" type="application/json">{...}</script> と
コンテナ要素を提供。_assets/arch-viz.js が JSON を読んで描画。
Claude は JSON データだけを埋める。HTML 構造・CSS・JS は触らない。
トリガー
自然言語: 「アーキ更新して」「architecture refresh」「html-reports-arch」「/arch-refresh」
定期実行: /loop 1w /arch-refresh
動作フロー (orchestrator パターン)
orchestrator スキルと同じ「計画→委譲→統合→再計画」のループを architecture 生成・更新に適用する。
Phase 0: トリガー受付 + モード判定
.claude/skills/html-reports-arch/scripts/detect-changes.sh
出力の verdict で分岐:
| verdict | モード | 進む先 |
|---|
INITIAL | 初回作成 | Phase 1 → 2 → 3 → ... 全部 |
NO_CHANGE | 変化なし | 何もしない (報告のみ) |
MINOR | 軽微 (<10 files) | Phase 7.minor のみ (updated と commit_hash 更新) |
MODERATE | 中程度 (10-49 files) | 影響モジュールを特定して Phase 3-7 をサブセット実行 |
MAJOR | 大幅 (50+ files / 新規モジュール / 削除モジュール) | Phase 2 から再構成 |
Phase 1: 偵察 (Reconnaissance) — 唯一の固定フェーズ
コードベース汎用の最小情報を集める。言語/フレームワークに依存しない探索だけを行う。
実行する偵察コマンドの種類 (具体的なコマンドはコードベース次第):
- 規模感:
git ls-files | wc -l, find . -maxdepth 3 -type d
- ビルド境界 manifest: 環境にあるものを
fd / find
(例: package.json, *.csproj, Cargo.toml, go.mod, pubspec.yaml, pom.xml, Gemfile, mix.exs, pyproject.toml, *.asmdef, etc.)
- エントリポイント候補:
main.*, index.*, Program.cs, app.*, Bootstrap*, cmd/*/main.go
- ドキュメント:
README*, ARCHITECTURE*, docs/, *ADR*
- バージョン/ツール:
.tool-versions, mise.toml, package.json の dependencies
偵察結果から内部的に把握すべきこと:
| 観点 | 何を判断するか |
|---|
| 言語 / フレームワーク | C# Unity / Next.js / Go / Python / Rust / 混在 |
| 規模 | ファイル数, トップレベルディレクトリ数 |
| ビルド境界 | asmdef / package / module の単位 |
| パラダイム | レイヤード / Clean / DDD / hexagonal / monorepo / microservice |
| 既存ドキュメント | どこに何が書いてあるか (重複分析を避けるため) |
この phase 自体は subagent に出さない (偵察結果は Phase 2 の判断に直結する起点なので、メイン Claude が握る)。
1.x 既存の静的解析ツールを検出する (必須)
偵察の一環として、コードベースに 既に存在する静的解析ツール を必ず検出する。
本スキルは特定ツールを要求しないが、環境に既にあるものは Phase 3 で優先的に活用する。
理由:
- 既存ツールは言語固有の依存関係を正確に抽出できる (grep より精度が高い)
- LOC / 複雑度 / 結合度などのメトリクスを取得済み
- JSON / SARIF / dot 等の機械可読出力 → arch-data に直接流し込める
- プロジェクト独自の規約 / 除外設定を既に反映している
検出する場所:
mise tasks --no-header 2>/dev/null | grep -iE 'analy|inspect|metric|dep|graph|lint'
npm run 2>/dev/null | grep -iE 'analy|lint|check|dep'
make -qp 2>/dev/null | grep -E '^[a-z-]+:' | grep -iE 'analy|metric'
fd -t x . scripts/ tools/ bin/ 2>/dev/null | head -20
検出した解析ツールを tools_available として内部的にメモし、Phase 3 のタスク生成で参照する。
CLI 存在 vs task wrapper 存在の分類 (重要)
検出時は 2 つを別カテゴリで記録する:
| カテゴリ | 例 | 扱い |
|---|
| 1. task wrapper として登録済 | mise run analyze, npm run lint, make metrics で起動できる | 第一選択。Phase 3 でそのまま Bash 経由で呼ぶ |
| 2. CLI 単体は PATH にあるが wrapper 無し | unilyze / jb inspectcode がインストール済だが mise tasks に未登録 | 第二選択。直接 CLI を Bash 呼びする。同時に "tooling debt" として記録 |
カテゴリ 2 で発見した CLI は Phase 7 の生成物に反映する:
- overview ページの
notes セクションに「Tooling debt: 以下の解析 CLI が手元にあるが mise タスクに登録されていない: <list>」と明示
- もしくは Phase 7 終了後にユーザーに別タスクとして提案: 「
unilyze / jb inspectcode を mise.toml の [tasks."analyze:*"] に登録しますか?」
これにより「インストール済なのに毎回手で叩く」状況を可視化し、CI 化やドキュメント化の起点を提供する。
Phase 2: 写像構成の決定 (Map Design)
偵察結果から、必要な architecture ページの構成を決める。
判断は 2 つの直交軸で別々に行う (1 軸の単一表で束ねるとケース漏れが出るため):
軸 1: module-* ページの数 (build boundaries 由来)
| build boundary 数 | module-* 構成 |
|---|
| 1-2 | (overview に統合、独立 module-* 無し) |
| 3-7 (Layered) | 主要 boundary に 1 ページずつ (合計 3-7 件) |
| 8+ (大規模) | 重要度で 5-8 件に絞り、残りは overview 内のテーブルだけで触れる |
| DDD / Bounded Context | per Bounded Context (module-<bc>) |
| Microservice | per service (module-<service>) |
| Monorepo | per top-level package (module-<package>) |
軸 2: flow-* ページの数 (cross-cutting use cases 由来)
| 3 モジュール以上を横断する主要 UC の数 | flow-* 構成 |
|---|
| 0-1 | (overview の「主要ユースケース」セクションに統合、独立 flow-* 無し) |
| 2-4 | 各 UC に 1 ページ (合計 2-4 件) |
| 5+ | 重要度上位 3-5 件に絞り、残りは将来 architecture-usecases.html 等の一覧ページに集約検討 |
重要: 軸 1 と軸 2 は 独立に判定する。
例: 「5 modules + 2 cross-cutting UC」なら module-* 5 件 + flow-* 2 件 = overview + 7 子ページ。
逆に「8 modules でも cross-cutting UC が 1 件」なら flow ページは作らず overview 内のセクションで済ます。
ユーザー確認: 初回 + MAJOR モード時に必ず構成案を提示して承認を得る。
提案: 以下 N ページで構成します。
- overview (全体像)
- module-domain (... 責務サマリ)
- module-application (... 責務サマリ)
- flow-checkout (主要ユースケース)
承認 / 修正 / その他?
★ 完遂保証: /goal を発動してから Phase 3 へ
構成承認後、Phase 3 開始前に /goal コマンドで完遂条件を設定する。これにより以下が達成されるまで Claude が粘り強くターンを継続する。
/goal <条件文>
完遂条件テンプレート (構成に合わせて埋める):
/goal 以下が全て満たされている: (1) .claude/reports/architectures/ に
overview.html および計画した module-*.html / flow-*.html が全て存在する。
(2) 各 HTML の <script id="arch-data"> 内の nodes が overview なら 15 件以上、
module なら 10 件以上で、主要モジュールに responsibility と key_files が
埋まっている。 (3) _index.js の各 architecture エントリで scent.one_line /
scent.key_terms (3 件以上) / tags / related が補完されている。
(4) _index.js の各エントリの commit_hash が現在の HEAD と一致している。
/goal の動作:
- 各ターン終了後、Haiku 等の小型モデルが条件達成を yes/no 判定
- 未達ならメインモデル (Opus / Sonnet) で次ターン継続
- 達成で自動終了
これにより Phase 5 (再計画) の途中で「もう十分かな」と早めに切り上げる傾向を抑制し、飽和まで本当に粘り強く回すことが担保される。
注意:
- 条件文は Haiku が文章を読んで判定できる粒度 で書く (具体的すぎない数値羅列より、人間が読んで判定できる形)
- 4000 文字以内
- 途中でユーザーがキャンセルしたければ
/goal clear
- 現在の goal を確認したければ引数なしで
/goal
Phase 3: 分析タスクの動的生成 (TaskCreate / TodoWrite)
決定した各 page に必要な分析を 動的にタスク化する。
ハードコードしたチェックリストは使わず、偵察結果に応じて適切なタスクを組み立てる。
タスクの設計原則:
- 1 タスク = 1 つの subagent で完結する単位
- 並列実行可能なものは同時に複数発行 (Agent ツールの並列呼び出し)
- 言語固有の探索は Explore に委譲 (メイン Claude の context 節約)
- 構造化された出力を要求 (JSON 推奨、後で arch-data に流し込みやすい形)
- Phase 1.x で検出した
tools_available を最優先、無ければ grep / fd フォールバック
- 環境にあるツールを暗黙的に活用、無いものは要求しない (本スキルは特定ツール依存ゼロ)
ツール活用パターン (環境にあるものから選ぶ)
| 分析カテゴリ | ツール例 (環境にあれば) | 出力形式 | arch-data への流し込み |
|---|
| LOC / ファイル数 | tokei --output json / scc --format json / cloc --json | JSON | nodes の loc, files |
| 依存関係 (.NET) | jb inspectcode --format=Json / unilyze / dotnet list package --include-transitive | JSON / SARIF | edges (kind=deps), modules |
| 依存関係 (JS/TS) | madge --json / dependency-cruiser --output-type json / tsc --noEmit | JSON | edges (kind=deps, impl) |
| 依存関係 (Go) | go list -json -deps ./... / go-callvis -format json | JSON | edges |
| 依存関係 (Rust) | cargo modules generate tree --bin <name> / cargo metadata --format-version 1 | JSON / tree | edges |
| 依存関係 (Python) | pydeps --show-deps --no-output / pyright --outputjson | JSON | edges |
| AST 横断検索 (汎用) | tree-sitter / ast-grep / semgrep --json | JSON | nodes / edges / call sites |
| メトリクス / 複雑度 | プロジェクトの解析 task (mise run analyze 等) | 任意 | nodes の重み付け |
| Call graph | go-callvis / pycallgraph / clang -emit-llvm 系 | dot / JSON | edges (kind=data) |
| 既存スキル委譲 | csharp-diagnose / quality-audit / プロジェクト固有スキル | スキル依存 | nodes + modules |
ツール優先のフロー (推奨)
各分析タスクを subagent に出す前に、メイン Claude が以下の順で判断:
1. 同じ目的を達成する project-specific task はあるか?
├── あり → mise / npm script を Bash で実行、JSON を parse
└── なし
2. 同じ目的の標準ツールが PATH にあるか?
├── あり → そのコマンドを Bash で実行
└── なし
3. Claude Code skill で対応するものはあるか?
├── あり → Skill ツールでスキル発動
└── なし
4. → subagent (Explore) に grep / fd ベースの探索を依頼
ツール出力 → arch-data 変換のためのプロンプト例:
Agent(
subagent_type: "Explore",
description: "tokei 出力を arch-data nodes に変換",
prompt: "
入力: $(tokei --output json src/) の出力 JSON。
タスク: 各 top-level directory を 1 node として
[{ id, label, layer, loc, files }] に変換。
layer は heuristic で推定 (Domain / Application / ...)。
出力: JSON 配列。
"
)
ツール非依存原則 (再掲)
- ツールが無くても本スキルは動く (subagent + grep でフォールバック)
- ツールがあればより正確になる、というだけ
- Phase 8 報告で「どのツールを使ったか」を必ず明示し、再現性を確保
タスクの種別 (例 = コードベース次第で増減):
| 種別 | 出すべき subagent | 期待出力 |
|---|
| 境界の LOC / file 数集計 | (簡易ならメイン Claude が直接 Bash) | [{ id, files, loc }] |
| 各境界内の public 型一覧 | Explore | [{ id, label, kind, loc }] |
| モジュール間の依存抽出 | Explore | [{ from, to, kind }] |
| 1 モジュールの責務サマリ | Explore (or Plan) | responsibility 文字列 |
| エントリポイントから N 階層下の呼び出し追跡 | Explore | call chain |
| ユースケース命名 (test ファイル名から) | Explore | [{ name, files, description }] |
| ユースケース実装パス追跡 | Explore | step-by-step (actor, target, action) |
| データ変換ポイント抽出 | Explore | { from_type, to_type, location } |
| 用語抽出 (固有名詞) | Explore | [{ term, definition_hint, location }] |
TodoWrite で全タスクを可視化し、進捗をユーザーに見せる。
Phase 4: 委譲実行 (Agent.parallel)
タスクを Agent ツールで実行。独立タスクは 1 メッセージ内で複数並列呼び出し。
Agent(
subagent_type: "Explore",
description: "Domain 層の型抽出",
prompt: "
タスク: <path>/Domain/ 配下の public 型を列挙。
各型について: id (FQN), label, kind (class/interface/record/struct), loc, files。
出力: JSON 配列 [{ id, label, kind, loc, files }]
制約: 環境にある grep/fd で済む範囲。
"
)
サブタスク入力テンプレ (orchestrator 流):
- タスク: 具体的に何を抽出するか
- スコープ: 対象パス / 除外
- 期待出力: フォーマット (JSON が望ましい)
サブタスク完了レポートを受けたら次のフェーズへ。
Phase 5: 統合 + 再計画 (Re-plan Loop)
各タスクの完了レポートを集めて arch-data JSON を構築する。
重要: ここで止まらない。不足を発見したら Phase 3 に戻り新タスクを動的生成する。
再計画のトリガー例:
| 発見 | 動的生成する次タスク |
|---|
| ある module の Port が想定より多い | その module の Port を全て列挙する Explore |
| ユースケース X の実装パスが追えない | callsite を 1 階層深く追跡する Explore |
| 用語集が薄い (3 件以下) | Domain 層の固有名詞をさらに掘る Explore |
| Treemap が偏っている (1 モジュールが極端に大) | その module 内をさらに細分化 |
| ユーザーが特定領域に関心を示した | その領域を集中分析する Explore |
これを 飽和 まで繰り返す。
Phase 6: 飽和判定
以下を複数満たしたら「これ以上の深掘りは ROI が低い」と判断:
- 連続 2 ラウンドで新タスクが生成されない
- arch-data nodes が overview で 15-50、各 module で 20-40 に達した
- 主要モジュールに responsibility / key_files / ports / depends_on が埋まった
- 主要 flow ページの 8 セクション (Trigger / Outcome / Path / Matrix / Data / Error / Test / Call sites) が埋まった
飽和に達するか、ユーザーが明示的に「もう十分」と言ったら Phase 7 へ。
Phase 7: ページ生成
各 page を順に:
new-report.sh architecture <slug> でスケルトン生成
<script id="arch-data"> の JSON を Write で埋める (統合した分析結果)- 自然言語部 (TL;DR / 用語集 / オンボーディングルート / 規約) を Edit で書く
_index.js の対応エントリを補完
scent.one_line, scent.key_terms, scent.reading_minutestags (3-5 個)related (同 architecture 内の他ページ + 関連 decision/review)- 旧ページ置換時は
supersedes: [旧 id]
<meta name="report:updated"> を今日に、<meta name="report:commit"> を HEAD に- アーカイブ / supersede 操作の整合性確認 (削除や置き換えを行ったときの必須ステップ):
Phase 7.minor (差分軽微時のショートカット)
detect-changes.sh verdict が MINOR のとき:
- HTML 本体は触らない
_index.js の updated と commit_hash のみ書き換え- ユーザーには「軽微な変化のみ、本文更新は不要」と報告
Phase 8: 報告
ユーザーに簡潔に:
- 実行した analysis ラウンド数
- 生成した分析タスク総数 (subagent / 直接 Bash / 既存スキルの内訳)
- 活用した既存解析ツール一覧 (
tools_available のうち実際に使ったもの。例: tokei / madge / csharp-diagnose skill / プロジェクトの mise run analyze)
- 使えなかった理由があれば明記 (例:
unilyze インストール済だが出力フォーマットが想定外)
- 採用した分岐 (新規 / 部分更新 / 軽微更新)
- 生成・更新したページ一覧
_index.js の commit_hash 更新
HTML を書くときの必須ルール
Mermaid を必ず描画させる
末尾の reports.js / arch-viz.js 読み込みは 必ず type="module" を付けない:
<script src="../_assets/reports.js"></script>
<script src="../_assets/arch-viz.js"></script>
<script type="module" src="../_assets/reports.js"></script>
arch-data JSON 以外は触らない
<script id="arch-data" type="application/json"> 以外の HTML 構造・CSS・JS は触らない。
テンプレを信頼する。これを破ると Cytoscape / ECharts 描画が壊れる。
arch-data JSON のスキーマ
{
"metadata": { "title", "commit", "layers": [...] },
"nodes": [
{
"id": "domain.scenario.ScenarioData",
"label": "ScenarioData",
"layer": "domain",
"lod": 2,
"loc": 280, "files": 3,
"url": "module-domain.html",
"parent": "domain.scenario",
"kind": "record"
}
],
"edges": [
{
"from": "...", "to": "...",
"kind": "deps|impl|data|domain",
"lod": 1,
"label": "string"
}
],
"modules": {
"<node_id>": {
"responsibility": "...",
"key_files": [...], "ports": [...], "depends_on": [...],
"related_reports": [{ path, title }]
}
}
}
LOD の使い方
| LOD | 含めるノード | 典型ノード数 |
|---|
| 0 | レイヤー (粗粒) | 3-7 |
| 1 | 主要モジュール | 10-25 |
| 2 | モジュール内の型 / コンポーネント | 30-60 |
| 3 | クラスメソッド / ファイル | 100+ (任意) |
lod フィールドは「このノードが表示される最小 LOD」。
L1 を見ているとき、L0/L1 ノードは表示、L2/L3 は非表示。
各モジュールのデータを arch-data に 明示的に階層展開 することで LOD slider が意味を持つ。
階層展開しない場合は L1=L2 になって slider の意味がなくなる (アンチパターン)。
flow ページの 8 セクション
flow ページは以下を埋めることで「ユースケース分析」を漏れなく表現する:
- Trigger Contract (起動条件 / 入力 / 認可)
- Outcome Contract (成功時の状態変化 / 副作用 / 出力)
- Implementation Path (UI → UseCase → Domain → Repo → DB のクラスチェーン)
- Module Participation Matrix (モジュール × R/W/Notify)
- Data Transformation (型変換: DTO → Domain → Persistence)
- Error Landscape (失敗ポイント / 影響範囲 / 補償)
- Test Coverage (既存テストの場所 + 何を保証するか)
- Real Call Sites (file:line の実呼出箇所)
このうち何を埋められるかは Phase 3 の動的タスクで決まる。
Mermaid シーケンスだけで終わらせない。
失敗・例外
.claude/reports/ がない: html-reports の init を促す- git リポジトリでない: 警告のみで処理続行 (commit_hash 不要)
- 既存 commit_hash が無効 (force-push 等):
HEAD~50 を基点
detect-changes.sh が NO_CHANGE: 「変化なし、更新不要」と報告して終了- Cytoscape / ECharts CDN ロード失敗: HTML 内に赤字エラー表示 (
arch-viz.js が自動)
関連スキル
html-reports: 本体スキル。architecture テンプレと new-report.sh を提供。orchestrator: 分割統治パターンの原型。本スキルは architecture 専用にカスタマイズ。loop: 定期実行する場合に組み合わせる (/loop 1w /arch-refresh)。
