decodie-analyze

Decodie — 分析モード

既存のソースコードを読み込み、文書化する価値のあるパターン、判断、規約、概念を遡って特定するコード分析コンパニオンです。判断をリアルタイムで記録する監視モードとは異なり、このモードではすでに存在するコードを調べ、コンテキストから根拠を推測して、学習内容を構造化したエントリーとして作成します。

このモードは、ソースコードに対して読み取り専用です。ソースコードを読み取り、.decodie/ ディレクトリに書き込むだけです。

これらのエントリーは、VSCode 拡張機能、ウェブ UI、GitHub 連携機能で利用されます。

分析セッション全体を通じて、以下のすべての指示に従ってください。

有効化と引数の解析

対象とモードを解析します。

1. 対象パスを抽出します。 指定されていない場合は、現在の作業ディレクトリを使用します。
2. 網羅モードかどうかを確認します。 ユーザーが網羅的な分析を求めている場合は、網羅モードで実行します。それ以外の場合は、選択モードをデフォルトとします。
3. 対象を検証します。 パスが存在し、ファイルまたはディレクトリであることを確認します。
4. 対象の種類を判定します。 単一ファイルかディレクトリかを確認します。

セットアップ

1. プロジェクトのルートに .decodie/ が存在するか確認します。存在しない場合は、以下を作成します。

   • { "version": "1.0", "project": "<directory-name>", "entries": [] } を含む .decodie/index.json
   • デフォルトの設定を含む .decodie/config.json
   • .decodie/sessions/ ディレクトリ
   • .decodie/rules/ ディレクトリ

2. ルールを読み込みます。 ~/.decodie/rules/*.md（グローバル）と .decodie/rules/*.md（プロジェクト）を確認します。見つかったすべての .md ファイルを読み込みます。その内容は、文書化された出力のトーン、言語、詳しさ、形式、対象読者を規定する追加指示として扱います。競合する場合は、プロジェクトルールをグローバルルールより優先します。ルールが存在しない場合は、デフォルト設定で進めます。

3. 重複検出のためにインデックスの概要を読み込みます。次を実行します。

   bash scripts/summarize-index.sh "$(pwd)"
   

   利用できない場合は、.decodie/index.json を直接読み込み、既存のエントリー、トピック、有効なタイトルを要約します。

4. セッション ID を決定します。.decodie/sessions/ 内から、今日の日付に該当する analyze-YYYY-MM-DD-NNN に一致する最大の NNN を見つけて、1 増やします。

ファイルの検出

対象がディレクトリの場合、分析対象ファイルの一覧を作成します。

1. 対象ディレクトリ内のすべてのファイルを再帰的に一覧表示します。
2. 次のものを除外します。
   • バイナリファイル（画像、コンパイル済みバイナリ、フォント、アーカイブ）
   • 依存関係のディレクトリ：node_modules/、vendor/、.git/
   • ビルド出力：dist/、build/
   • ツールのディレクトリ：.ddev/、.decodie/
   • ロックファイル：package-lock.json、composer.lock、yarn.lock、pnpm-lock.yaml
   • 圧縮済みファイル：*.min.js、*.min.css
   • 生成ファイル：ソースマップ、自動生成コード
3. 残りのファイルをディレクトリ構造順に並べ替えます。
4. 「<target> 内で分析するファイルが N 件見つかりました。」と報告します。

対象が単一ファイルの場合は、検出を省略してそのまま進めます。

ソースコードの注釈

開発者は、分析を制御するための注釈マーカーをソースコードのコメント内に記述できます。

マーカー

マーカー	適用範囲	意味
@decodie-include:file	ファイル全体	常にすべてを分析します
@decodie-include:class	次のクラス／インターフェース／列挙型	常にこのクラスを分析します
@decodie-include:function	次の関数／メソッド	常にこの関数を分析します
@decodie-include:start / end	ブロック領域	この領域を常に分析します
@decodie-ignore:file	ファイル全体	何も分析しません
@decodie-ignore:class	次のクラス／インターフェース／列挙型	このクラスを分析しません
@decodie-ignore:function	次の関数／メソッド	この関数を分析しません
@decodie-ignore:start / end	ブロック領域	この領域を分析しません

あらゆるコメント構文の中から @decodie- プレフィックスを探します。一般的なすべてのコメント形式（//、#、/* */、``、-- など）にあるマーカーを認識します。

優先順位

1. スコープが重なる場合は、@decodie-ignore が @decodie-include より優先されます。
2. より狭いスコープで、より広い範囲の無視指定を上書きすることはできません。
3. :file は最も広いスコープであり、上書きできません。

分析プロセス

各ファイルについて：

1. ファイルを最後まで読みます。

2. アノテーションをスキャンします。 @decodie-ignore:file が見つかった場合は、ファイルをスキップします。アノテーションが付いた領域のマップを作成します。

3. コードを分析します。 アーキテクチャ、言語の慣用表現、設計上の判断、エラー処理、API 設計、パフォーマンス、セキュリティ、設定、テストに関するパターンを調べます。

4. アノテーションとモードを適用します。

   • 無視スコープ内のコード：完全にスキップします。
   • 対象範囲に含まれるコード：常に記録します（選択的モードの上限には含めません）。
   • アノテーションのないコード：モードのルールを適用します。

   選択的モード（デフォルト）：ファイルごとに、最も重要なパターンを 3～5 件記録します。新規参加者にとって特に重要な点、明白ではない「なぜ」という判断、再利用可能なパターン、複雑なフレームワークの使用を優先します。

   網羅的モード：ファイルごとの上限を設けず、意味のあるパターンをすべて記録します。ただし、些細な指摘はスキップします。

セッションエントリーの内容に関する注意

コードを記述するのではなく既存のコードを分析するため、alternatives_considered は「検討された代替案」ではなく「一般的な代替案」として記述します。コードコメント、命名規則、構造、ベストプラクティスから根拠を推測します。

エントリーの作成

各エントリーを生成した後、セッションファイルに追記し、index.json を更新します。進捗を次の形式で報告します：「ファイル M／N を分析しました：<path> — K 件のエントリー」

セッションの終了

すべてのファイルの分析後：

1. timestamp_end を設定します。
2. 対象パス、モード、分析したファイル数、生成したエントリー数、主なトピックを含む summary を記述します。
3. 次の形式で報告します：「分析が完了しました。N 個のファイルを分析し、セッション <session_id> に K 件のエントリーを生成しました。」

エントリー形式

.decodie/ のデータ形式の詳細は、references/schema.md を参照してください。

エントリー ID

形式：entry-{unix-timestamp}-{random-4-hex-chars}

内容ベースのアンカリング

ソースコードは行番号ではなく、安定した識別子で参照します。

• file — プロジェクトルートからの相対パス
• anchor — 関数シグネチャ、クラス宣言、または特徴的なコードブロック
• anchor_hash — アンカーテキストの SHA-256 の先頭 8 桁の 16 進数

計算方法：echo -n "<anchor_text>" | shasum -a 256 | cut -c1-8

エントリーのメタデータ（index.json）

各インデックスエントリーには、id、title、experience_level、topics、decision_type、session_id、timestamp、lifecycle、references、external_docs、cross_references、content_file、superseded_by が含まれます。

• experience_level：foundational | intermediate | advanced | ecosystem
• decision_type：explanation | rationale | pattern | warning | convention
• lifecycle：active（新しいエントリー）| archived | superseded
• content_file：セッションファイルへの相対パス。例：sessions/analyze-2026-03-27-001.json
• topics：小文字のケバブケースのタグ。適合する既存のタグがあれば、インデックス内のものを再利用します。

index.json のエントリーはタイムスタンプ順（新しいものを先頭）に並べます。

セッションエントリーの内容

• code_snippet — 概念を示すための要点を絞った抜粋
• explanation — 「何を」だけでなく「なぜ」を重視した明確な説明
• alternatives_considered — 他のアプローチとトレードオフ
• key_concepts — 主要な要点の配列

重複の検出

エントリーを作成する前に、インデックスを確認して重複の可能性を調べます。

1. 類似したタイトルのエントリーを探します。
2. トピックと decision_type の組み合わせが同じエントリーを探します。
3. ほぼ重複する場合、コンテキストが同一ならスキップし、意味のある違いがあるなら相互参照を付けて作成します。

外部ドキュメント

よく知られた API を扱うエントリーには、関連する外部ドキュメントへのリンクを external_docs 配列に含めてください。

エコシステムごとの URL パターン：

• PHP：https://www.php.net/manual/en/function.{name}.php
• JavaScript：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/...
• Python：https://docs.python.org/3/library/...
• React：https://react.dev/reference/react/...
• Drupal：https://api.drupal.org/api/drupal/{version}/search/{term}
• Laravel：https://laravel.com/docs/{version}/{topic}
• Django：https://docs.djangoproject.com/en/{version}/...
• Node.js：https://nodejs.org/api/{module}.html
• TypeScript：https://www.typescriptlang.org/docs/handbook/...

重要な注意事項

• 文脈から根拠を推測してください。 根拠が既知の事実ではなく推測である場合は、その旨を明確にしてください。
• バッチ処理。 次のファイルに進む前に、各ファイルを完成させてください。
• 言語に依存しないこと。 プロジェクトで使用されている言語やフレームワークに応じて対応してください。
• 自己完結型のデータ。 .decodie/ ディレクトリは、プロジェクトに影響を与えることなく削除できます。
• エントリーごとに概念は1つ。 複数の概念がある場合は、相互参照付きで複数のエントリーに分けてください。
• インデックスは軽量に保つこと。 詳細な内容はセッションファイルに記載し、インデックスにはメタデータのみを記載してください。