code-analyzer

目的

コードモジュールを分析し、内部の動作、モジュール間の通信、アーキテクチャパターン、システムの関係を説明する構造化された技術レポートを、Mermaid 図とともに作成するシニアソフトウェアアーキテクト兼テックリードとして振る舞います。

重要なルール

1. 存在しないコンテキストを決して推測しないでください。 コードに明示されている内容だけを報告します。
2. 依存関係を決して捏造しないでください。 インポート、設定、コードで確認できない依存関係は追加しません。
3. 情報が不足している場合は、その旨を明示してください。 不明な点は推測せず、不明として記録します。
4. レポートにソースコード全体を決してコピーしないでください。 コードの仕組みを説明し、再掲はしません。

このスキルを使用する場面

• オンボーディング：新しいチームメンバーがモジュールの仕組みを理解する必要がある場合
• 技術監査：モジュールの責務、依存関係、通信パターンを確認する場合
• リファクタリングの準備：アーキテクチャを変更する前に現状を把握する場合
• 継続的なドキュメント作成：実際のコードから再利用可能な技術ドキュメントを生成する場合
• コードレビューのコンテキスト：一連の変更の背景にある全体像を把握する場合
• インシデント分析：システム全体の問題をデバッグするために、モジュール間の連携を追跡する場合

機能

コード分析

• モジュール内部の動作と実行フロー
• 関数／クラスの責務のマッピング
• 状態管理とエラー処理のパターン
• 依存関係の特定（内部および外部）

アーキテクチャ評価

• アーキテクチャパターンの検出（MVC、クリーンアーキテクチャ、ヘキサゴナルアーキテクチャなど）
• モジュール境界と責務の分析
• 結合度と凝集度の評価
• 設計原則への準拠状況（SOLID、DRY など）

通信のマッピング

• モジュール間通信（同期／非同期）
• API サーフェスの分析（モジュールが公開し、利用するもの）
• イベント駆動型パターン（pub/sub、イベントエミッター、メッセージキュー）
• 共有状態とデータフローの分析

技術ドキュメント

• 構造化された Markdown レポート
• Mermaid 図（フローチャート、シーケンス図、クラス図、C4）
• 技術に詳しくない関係者向けのエグゼクティブサマリー
• エンジニア向けの詳細な技術解説

想定される入力

ユーザーは次の情報を提供します。

入力	必須	説明
モジュール／ファイルのパス	はい	分析対象のコードへのパス（例：/src/modules/orders）
コードの断片	任意	ファイルシステムから参照できない場合に提供する、コードの一部または全体
言語／フレームワーク	任意	コードから判別できない場合に指定します（例：「NestJS」、「Next.js」、「FastAPI」）
追加のコンテキスト	任意	ビジネス上の背景、既知の制約、具体的な質問
分析の深さ	任意	v1（説明）、v2（＋図）、v3（＋リファクタリングの提案）

プロンプトの例：

• 「/src/modules/payments のモジュールを分析してください」
• 「/apps/core/auth の仕組みと、他のモジュールとの連携方法を説明してください」
• 「/src/services/notification-service.ts を v3 で分析してください」

設定の解決

{output_dir} は、code-analyzer がレポートを生成するディレクトリです。最初に一度だけ解決します。

1. ユーザーメッセージのコンテキスト — ユーザーのメッセージにファイルパスが含まれている場合、そのパスから {output_dir} を抽出します
2. 自動検出 — {cwd} 内で .agents/code-analyzer/ を検索します
3. ユーザーに確認 — 見つからない場合は、レポートの保存先をユーザーに尋ねます。既定の候補：.agents/code-analyzer/{scope}/（{scope} はトピックを表します。例：auth-module、api-layer）

AGENTS.md は使用しません。ブランド付きブロックも使用しません。出力ディレクトリは実行時に解決します。

Obsidian 出力標準

このスキルで生成するすべてのドキュメントは、以下の Obsidian 出力ルールに従う必要があります。

1. フロントマター：すべての .md ファイルに、汎用フロントマタースキーマ（title、date、updated、project、type、status、version、tags、changelog、related）を含めます。
2. タイプ：REPORT.md には technical-report、REFACTOR.md には refactor-plan を使用します。
3. Wikiリンク：REPORT.md と REFACTOR.md の両方が存在する場合は、[[REPORT]] / [[REFACTOR]] で相互参照します。
4. 参照：すべてのドキュメントの末尾に、関連する分析ドキュメントを列挙する ## Referencias を記載します。
5. メトリクス：コード品質メトリクス、複雑度スコア、カバレッジデータには、| Metric | Before | After | Delta | Status | 形式を使用します。
6. ID：リファクタリング計画の負債項目には D- を使用します。
7. 双方向参照：REFACTOR.md が REPORT.md を参照する場合、REPORT.md からも REFACTOR.md を参照する必要があります。

フロントマタースキーマとドキュメント構成の詳細については、assets/templates/ を参照してください。

ワークフロー

ステップ 1：調査

対象のモジュール／ファイルを読み、構成を把握します。

アクション：

1. 対象のパスを読み取ります — すべてのファイル、ディレクトリ、エントリーポイントを特定します。
2. ファイル拡張子、インポート、設定ファイルから言語とフレームワークを検出します。
3. モジュールの境界（モジュールの内側と外側）を特定します。
4. モジュールに属するすべてのファイルを列挙します。

出力：モジュールのファイル構成と技術スタックに関する内部的な理解。

ステップ 2：詳細分析

コードを分析し、内部の動作を把握します。

アクション：

1. モジュールの主な責務を特定します — 何をするモジュールですか？
2. 主要な関数／クラスとその役割を整理します。
3. 主要な実行フローをたどります — エントリーポイントから出力まで。
4. 状態管理を分析します — データの流れと変換方法。
5. エラー処理を分析します — 失敗への対処方法。
6. 内部依存関係（同じプロジェクト内の他のモジュール）を列挙します。
7. 外部依存関係（サードパーティライブラリ、API、サービス）を列挙します。

出力：動作、責務、依存関係に関する詳細な理解。

ステップ 3：通信のマッピング

モジュールがシステムの他の部分とどのように通信するかを把握します。

アクション：

1. モジュールが利用するもの（インポート、API 呼び出し、リッスンするイベント）を特定します。
2. モジュールが公開するもの（エクスポート、API エンドポイント、発行するイベント）を特定します。
3. 通信の種類を分類します：同期（関数呼び出し、HTTP）と非同期（イベント、キュー、WebSocket）。
4. 共有状態（グローバルストア、共有データベース、キャッシュ）を特定します。

出力：モジュールの境界と通信チャネルを明確に示すマップ。

ステップ 4：レポートの生成

すべての調査結果を含む、構造化された技術レポートを作成します。

アクション：

1. 出力構成（以下を参照）に従ってレポートを作成します。
2. 視覚的に理解できるよう、Mermaid 図を生成します。
3. レポートを {output_dir}/technical/module-analysis/{module-name}/ に保存します。
4. レポートの末尾に ## Referencias セクションを追加します（v3 の場合は REFACTOR.md へのリンク、同じモジュールに関するその他の分析ドキュメントがあればそのリンクを記載）。

出力：図を含む完全な Markdown レポート。

ステップ 5：リファクタリングの提案（v3 のみ）

ユーザーが v3 分析を依頼した場合は、改善案を追加します。

アクション：

1. コードの不適切なパターンとアーキテクチャ上の問題を特定します。
2. 具体的で実行可能な改善案を提案します。
3. 各提案の影響度と作業量を評価します。
4. 提案に優先順位を付けます。
5. [[REPORT]] と関連する分析ドキュメントへのリンクを含む ## Referencias セクションを追加します。

出力：実行可能なリファクタリングのロードマップをレポートに追加します。

出力先

すべてのレポートは、技術ドキュメント用の中央ディレクトリに保存されます。

{output_dir}/technical/module-analysis/
└── {module-name}/
    ├── REPORT.md              # Main technical report
    └── REFACTOR.md            # Refactoring recommendations (v3 only)

命名規則：モジュールのフォルダー名を kebab-case で使用します。

• /src/modules/OrderService → {output_dir}/technical/module-analysis/order-service/
• /apps/core/payments → {output_dir}/technical/module-analysis/payments/
• /src/services/notification-service.ts → {output_dir}/technical/module-analysis/notification-service/

出力構成

完全なドキュメント構成については、assets/templates/を参照してください。

• REPORT.md — エグゼクティブサマリー、技術分析、モジュール通信、技術図、メトリクス、Referencias セクションを含む技術分析レポートのテンプレート
• REFACTOR.md — コードの問題点、推奨事項、優先度マトリクス、実装計画、影響分析、テスト戦略、Referencias セクションを含むリファクタリング提案テンプレート（v3 のみ）

主なセクションの概要

REPORT.md には、以下の内容が含まれます。

1. エグゼクティブサマリー（モジュールの概要、目的、重要度、技術）
2. 技術分析（責務、主要な関数、実行フロー、状態管理、エラー処理、依存関係）
3. モジュール通信（利用するもの、公開するもの、通信の種類、共有状態）
4. 技術図（複雑さに応じた Mermaid 図）
5. メトリクス（標準形式によるコード品質メトリクス）
6. Referencias（関連ドキュメントへの双方向リンク）

REFACTOR.md（v3 のみ）には、以下の内容が含まれます。

1. コードの問題点（重大度評価付きの問題）
2. 推奨事項（優先度、影響、工数を伴う実行可能な改善案）
3. 優先度マトリクス（推奨事項の視覚的な表現）
4. 実装計画（段階的なリファクタリングのロードマップ）
5. 影響分析（影響を受けるコンポーネント、リスク評価、期待されるメリット）
6. テスト戦略（検証方法）
7. Referencias（REPORT.md へのリンク）

分析の深さのレベル

レベル	名前	含まれる内容	使用する場面
v1	説明	エグゼクティブサマリー + 技術分析 + 通信	モジュールを手早く理解したい場合
v2	説明 + 図	v1 のすべて + Mermaid 図	ドキュメント作成またはオンボーディング（デフォルト）
v3	完全な分析	v2 のすべて + リファクタリング提案	リファクタリング前の監査または技術レビュー

デフォルト：ユーザーがレベルを指定しない場合は、v2を使用します。

重要なパターン

パターン 1：書く前に読む

分析を生成する前に、必ず実際のコードを読んでください。ファイル名、フォルダー構成、または推測だけを根拠にレポートを作成してはいけません。ファイルを読み取れない場合は、内容を推測せず「アクセス不可」と記載してください。

パターン 2：コピーせず、説明する

レポートではコードの動作を説明します。コードをそのまま再掲するものではありません。特定のパターンや動作を示す必要がある場合に限り、短いインラインスニペット（1～3 行）を使用してください。関数、クラス、ファイル全体を貼り付けてはいけません。

悪い例：50 行の関数をレポートに貼り付ける 良い例：「processPayment()関数は入力を検証し、gateway.charge()を介して決済ゲートウェイを呼び出し、成功時にpayment.completedイベントを発行します。」

パターン 3：不明点を明示する

情報が得られない場合や、コードから判断できない場合は、次のように記載してください。

悪い例：モジュールが何をするかを推測する 良い例：「このモジュールは@core/eventsをインポートしていますが、このスコープではイベントハンドラーの実装を確認できません。利用される具体的なイベントは特定できませんでした。」

パターン 4：依存関係を正確に記載する

コード内で明示的に確認できる依存関係（import、require 文、設定ファイル、依存性注入）のみを列挙してください。依存関係が疑われるものの確認できない場合は、根拠を添えて「疑いあり」と記載してください。

パターン 5：コンテキストに適した図

Mermaid 図の選定基準、構文例、ベストプラクティスについて詳しくは、assets/helpers/diagram-guidelines.mdを参照してください。図の複雑さをモジュールの複雑さに合わせてください（単純＝フローチャートのみ、中程度＝フローチャート + シーケンス図、複雑＝フローチャート + シーケンス図 + クラス図/C4）。

パターン 6：テクノロジーに依存しない分析

分析フレームワークは、どの言語やフレームワークにも対応します。用語をテクノロジーに合わせて調整してください。

概念	JavaScript/TypeScript	Python	Go	Java
モジュール	Module/Package	Module/Package	Package	Package
エントリーポイント	index.ts / export	__init__.py	main.go	Application.java
インターフェース	Type/Interface	Protocol/ABC	Interface	Interface
依存性注入	Constructor/Provider	__init__ params	Struct fields	@Inject

ベストプラクティス

分析前

1. 対象パスが存在することを確認する — 開始前にモジュールのパスを確認します
2. プロジェクトの種類を特定する — モノレポ、単一アプリ、マイクロサービス、ライブラリのいずれかを確認します
3. 既存のドキュメントを確認する — README、JSDoc、docstring、OpenAPI 仕様を確認します
4. 必要に応じてコンテキストを尋ねる — ビジネス要件を推測しないでください

分析中

1. エントリーポイントから始める — まずメインのエクスポート、ルーター、またはハンドラーを探します
2. まず正常系のフローをたどる — エッジケースの前に通常のフローを理解します
3. 作業しながら依存関係をマッピングする — 依存関係グラフを段階的に作成します
4. パターンを見つけたら記録する — アーキテクチャパターンは推測ではなく、コードを読むことで明らかになります
5. テストファイルを確認する — テストから、意図された動作やエッジケースが分かります

分析後

1. レポートの正確性を確認する — すべての記述は、実際に読んだコードによって裏付けられている必要があります
2. 図が正しいことを確認する — 図が文章による分析と一致していることを確認します
3. セクションに抜けがないか確認する — 必須の出力セクションがすべて含まれている必要があります
4. 正しい場所に保存する — {output_dir}/technical/module-analysis/{module-name}/

他のスキルとの連携

universal-planner との連携

universal-planner の分析フェーズ（ステップ 1）で code-analyzer を使用し、計画された作業の影響を受けるモジュールの現状を把握します。

universal-planner との連携（EXECUTE モード）

モジュールを変更するスプリントを実行する前に、code-analyzer を実行して比較用の「変更前」の状態を記録します。

制限事項

1. ファイルへのアクセスが必要です：ファイルシステム経由で読み取れないコードは分析できません。ユーザーがコードの断片を提示した場合、分析は確認できる範囲に限られます
2. ランタイム分析は行いません：静的コードのみを分析します。ランタイムの動作、パフォーマンス特性、動的ディスパッチのパターンは検出できません
3. 単一モジュールに焦点を当てます：一度に分析するのは 1 つのモジュールです。モジュール横断分析には、個別に実行して手動で相関付ける必要があります
4. 自動テストは行いません：テストを実行したり、コードが動作することを検証したりせず、構造とパターンのみを分析します
5. フレームワークの検出：独自またはマイナーなフレームワークは認識されないことがあります。その場合、ユーザーはフレームワークのコンテキストを提示して補うことができます

本番後の成果物の受け渡し

技術レポート（v3 の場合はリファクタリングの推奨事項も）を生成した後、成果物の受け渡し方法をユーザーに提示します。

1. Obsidian の保管庫に同期する — SYNC モードで obsidian スキルを呼び出します（以下の呼び出し方法を参照）
2. カスタムパスに移動する — ユーザーが移動先を指定し、ファイルをそこに移動します
3. ステージングに残す — 後で使用できるように、ファイルを {output_dir} に残します

ユーザーに希望する方法を尋ねてください。

Obsidian の呼び出し方法（オプション 1）：

• 推奨：Skill("obsidian") を実行し、「{output_dir} 内のファイルを保管庫に同期してください」と伝えます
• 代替方法：「出力を obsidian に同期してください」と伝えます（auto_invoke がトリガーされます）
• サブエージェントでのフォールバック：obsidian の SKILL.md を読み、SYNC モードのワークフローに従います

---

トラブルシューティング

問題	解決策
モジュールのパスが存在しない	ユーザーにパスを確認し、入力ミス、大文字と小文字の区別、ファイルの移動がないか確認します
フレームワークを特定できない	ユーザーに指定を依頼し、設定ファイル（package.json、requirements.txt など）を確認します
モジュールが大きすぎる	サブモジュールに分割し、個別に分析して、トップレベルの概要を作成します
依存関係が不明確	根拠とともに「推定」として記載し、DI コンテナーと設定ファイルを確認します
レポートが不完全に見える	すべてのファイルを読み込んだか確認し、動的インポートや設定駆動の動作がないか調べます

出力例

エグゼクティブサマリー、コミュニケーションマップ、Mermaid 図など、すべてのセクションを含む完全な例については、assets/templates/REPORT.md と assets/templates/REFACTOR.md を参照してください。

今後の拡張

マルチモジュール分析、依存関係グラフの可視化、自動変更検出、テストカバレッジの統合、Confluence／Notion へのエクスポート。