Project Class Architect
リポジトリをインタラクティブなUMLクラス図に変換し、開発者が何百ものファイルを読む代わりに探索できるようにします。分析はエビデンスベースです。図内のすべてのクラス、属性、メソッド、リレーションシップは、それが由来するファイルと行を指し示します。何も捏造されていません。ヒューリスティックな発見には inferred というラベルが付けられます。
このファイル内のすべてのパスは、スキルディレクトリ（この SKILL.md を含むフォルダ）からの相対パスです。
必要条件
- Node.js 18以上 (
node --version)。スクリプトには依存関係はありません。このスキルに対してnpm installを実行しないでください。 - リポジトリへの読み取りアクセス。分析によってソースファイルが変更されることはなく、出力フォルダのみに書き込みます。
- Node.js が利用できない場合、最後に説明するフォールバックを使用してください。
ワークフロー
1. リポジトリを特定する
ユーザーが話しているプロジェクトの絶対パスを使用します（通常は現在のワークスペース）。以下のコマンドはスキルディレクトリから実行されるため、. のような相対パスはスキル自体を指すことになります。
2. 図を生成する
node scripts/class-architect.js generate "/absolute/path/to/repo"
便利なオプション（すべてのオプションについては CLI リファレンス を参照してください）：
| 必要なもの | オプション |
|---|---|
| フッターに作者を表示 | --author "名前" --author-role "ソフトウェアエンジニア" |
| 図のタイトル | --title "課金サービス" |
| 大規模リポジトリの一部のみ | --include "src/main/java/com/acme/billing/**"（繰り返し可能） |
| フォルダをスキップ | --exclude "legacy/**"（繰り返し可能） |
| 言語を制限 | --languages java,sql |
| テストも分析 | --include-tests |
| 初期表示/レイアウト | --view classes|er|overview|packages --layout grouped|layered|hierarchical|grid |
| カスタム出力フォルダ | --out "/path/to/output"（デフォルト <repo>/.class-architect） |
| HTML からローカルパスを除外 | --hide-root（「エディタで開く」リンクを無効化） |
このコマンドは、標準出力に JSON サマリーを出力します（進行状況は標準エラー出力に出力されます）。終了コード：0 成功、1 使用法エラー、2 分析可能なソースファイルなし、3 モデル検証失敗（書き込みなし）、4 内部エラー。
3. 結果を確認する
JSON サマリー（status、outputs、summary.counts、summary.insights、summary.edits、validation）を読んでください。出力フォルダに書き出されるもの：
diagram.html- インタラクティブ図（ブラウザで開いてください。オフラインでも動作します）。report.md/report.json- スキャンされたファイル、クラス、インターフェース、列挙型、リレーションシップ、推測されたリレーションシップ、未解決の参照、除外されたファイル（理由付き）、警告、インサイト。model.json- UMLモデル（唯一の信頼できる情報源）。overlay.json- ユーザー編集（ある場合）。
終了コードが 2 の場合は、--include / --languages を調整し、どのフォルダがなぜ除外されたかを（JSON details から）伝えてください。終了コードが 3 の場合は、検証エラーを報告してください。モデルを手動で編集してエラーを隠さないでください。
何百ものクラスがあるリポジトリの場合、図は Overview（モジュール）で開き、ユーザーがモジュールやパッケージにドリルダウンできるようにします。また、1つの境界コンテキストに対して --include を使用して焦点を絞った図を生成することもできます。
4. 図をユーザーに提示する
diagram.htmlのパス（およびoutputs.diagramUrlからのfile://URL）を提示してください。ユーザーが要求し、環境が許可する場合を除き、ブラウザを起動しようとしないでください。- レポートにある情報のみを要約してください：クラス/インターフェース/列挙型/リレーションシップの数、検出されたフレームワーク、依存関係の循環、アーキテクチャの発見、未解決の参照、警告。クラス名は正確に引用してください。
- inferred（命名規則、Goの構造的型付け）とマークされたリレーションシップは検証が必要であり、派生したテーブル/カラム名は派生とマークされていることを指摘してください。
- 主なインタラクションを指摘してください：クラスまたは行をクリックして検査（ソースファイルと行番号付き）、検索（
/）、フィルター、ビュー（Overview、Packages、Classes、Database ER）、拡大レンズ（L）、編集モード（E）、Insights、Export。詳細：インタラクティブ図ガイド。
5. コード変更後にリフレッシュする
同じコマンドを再度実行してください。実行すると：
- 変更されたファイルのみを再分析します（インクリメンタルキャッシュ）。
- すべてのユーザー編集を保持します（
overlay.jsonからのものと、ユーザーが Save ボタンでdiagram.htmlに保存した編集の両方）。 - 対象がコードから消えた編集を orphaned として報告します（保持され、決して静かに削除されません）。また、ソースの変更と競合する編集も報告します。
- 前回の実行と比較して、追加/削除/変更されたクラスを強調表示します。
- 前回の図のバックアップを保持します（
diagram.prev.html）。
ユーザーが図のコピーを別の場所にダウンロードした場合は、--edits "/path/to/saved-diagram.html" で渡してください。
6. オプション：ドキュメンテーションセクション
図は、元のテンプレートのコンポーネントを使用して、その下に追加のドキュメント（テーブル、フロー、ステップ、列挙型グリッド、バナーノート）を表示できます。コードで確認した事実のみを追加し、ソースファイルを引用してください。設定ガイド に従って JSON ファイルを作成し、--notes notes.json で渡してください。
ルール
- このスキルの一部として、分析対象のソースコードを変更、フォーマット、または「修正」しないでください。
- クラス、メンバー、リレーションシップを捏造しないでください。また、inferred リレーションシップを確定的なものとして提示しないでください。
overlay.jsonやユーザーが保存したdiagram.htmlを削除または上書きしないでください。CLI がそれらをマージします。- 出力フォルダ
.class-architect/は生成物です。ユーザーが図をコミットしたい場合を除き、.gitignoreに追加することを提案してください。 - 図やモデルをどこにもアップロードしないでください。これらにはプロプライエタリなコード構造が含まれている可能性があります。
スクリプトが実行できない場合のフォールバック
Node.js 18以上が利用できないか、コマンド実行が許可されていない場合：
- 関連するソースファイルを読み、UML モデルリファレンス に従って手動でモデル JSON を作成してください。コードで確認した要素のみを含め、
source.fileとsource.lineを設定してください。明示的でないものにはconfidence: "inferred"を設定してください。 templates/viewer.htmlをユーザーが図を配置したい場所（例：class-diagram.html）にコピーしてください。- コピー内の
<script type="application/json" id="pca-data">null</script>のnullを{"model": <あなたのモデル>, "overlay": null, "meta": {"title": "<プロジェクト名>"}}に置き換えてください。JSON 内では<は<として記述してください。 - または、ユーザーに
templates/viewer.htmlを開き、model.jsonをページにドロップするように伝えてください。
レイアウト、インタラクション、エクスポートは、生成された図とまったく同じようにブラウザで動作します。不足するのは、自動抽出、変更検出、検証レポートのみです。モデルが手動で作成されたことを明確に伝えてください。
その他のコマンド
node scripts/class-architect.js analyze "/abs/repo" # モデル + レポート、HTMLなし
node scripts/class-architect.js render --model model.json --out diagram.html
node scripts/class-architect.js validate --model model.json --html diagram.html
node scripts/class-architect.js diff --base old-model.json --head model.json
node scripts/class-architect.js edits --from saved-diagram.html --out overlay.json
node scripts/class-architect.js viewer --out viewer.html
node scripts/class-architect.js doctor
リファレンスファイル（必要なときのみ参照）
- references/CLI.md - すべてのコマンド、オプション、出力、終了コード。
- references/INTERACTIVE-DIAGRAM.md - ユーザーが図でできること、キーボードショートカット。
- references/RELATIONSHIPS.md - 各リレーションシップの種類と多重度がどのように決定されるか、エビデンスと信頼度。
- references/LANGUAGES.md - サポートされている言語、フレームワーク、ORM、および抽出される内容。
- references/CONFIGURATION.md -
class-architect.config.json、外部エンティティ、しきい値、ドキュメンテーションノート。 - references/UML-MODEL.md - モデル形式（フォールバックまたは他のツール用）。
- references/LIMITATIONS.md - 関連する場合に言及すべき既知の制限事項。