decodie-overview

Decodie — 概要モード

ファイル、ディレクトリ、またはプロジェクトの概要を高い視点から生成します。「これは何で、どのように構成されているか」に答えるもので、行ごとの説明ではありません。対象ごとに概要エントリーを1件生成し、オンボーディングの出発点として活用できます。

このモードは、デフォルトで永続化されます。概要は学習エントリーとして保存されます。同じ対象に対して再実行すると、バージョンが蓄積されるのではなく、既存の概要が上書きされます。

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

有効化と引数の解析

1. 対象パスを抽出します。 指定がない場合は、プロジェクトルートを使用します。
2. 対象を検証します。 対象が存在し、ファイルまたはディレクトリであることを確認します。
3. 対象のスコープを判定します。
   • ファイル — entry_points と dependencies は省略できます。
   • ディレクトリ — 通常、entry_points と dependencies が意味を持ちます。
   • プロジェクトルート — 4つすべての概要フィールドを適用します。
4. 再生成時の検索に使うため、対象パスを正規化します。
   • ファイル：相対パス（例：src/utils/helpers.ts）
   • ディレクトリまたはプロジェクトルート：末尾にスラッシュを付けた相対パス（例：src/auth/、./）

セットアップ

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/ 内で、本日の日付に対応する overview-YYYY-MM-DD-NNN に一致するもののうち、最も大きい NNN を見つけて、1つ増やします。

再生成と新規エントリー

生成する前に、既存の概要を確認します。

1. .decodie/index.json を読み込みます。
2. decision_type === "overview" で、sources が [<正規化された対象パス>] であるエントリーを探します。
3. 見つかった場合（再生成）：既存の id を再利用し、新しい内容を生成して、インデックスのエントリーをその場で更新します。以前のセッションファイルはディスクに残りますが、参照されなくなります。
4. 見つからない場合：新しい ID でエントリーを生成します。

生成プロセス

1. 対象を読み取ります。

   • ファイル：全体を読み込みます。
   • ディレクトリ：トップレベルのエントリーを一覧表示し、構造を示すファイル（package.json、composer.json、pyproject.toml、README.md など）を読み込み、代表的なソースファイルをいくつか確認します。
   • プロジェクトルート：さらに、エントリーポイントのマニフェストと依存関係のマニフェストを調べます。

2. 概要を構成する4つの要素を特定します。

   • purpose（必須） — このコードが何のためのものかを説明する2～4文です。実装ではなく、目的から説明を始めます。
   • structure（必須） — コードの構成（セクション、モジュール、主要なディレクトリとその役割）を説明します。
   • entry_points（任意） — 呼び出し可能なインターフェース：エクスポートされた関数、CLI コマンド、HTTP ルート、フレームワークのフックです。意味を持たない場合は省略します。
   • dependencies（任意） — 注目すべき内部または外部の依存関係と、それらが提供する機能です。些細な情報は省略します。

3. 平易な文章で記述します。 専門用語の多い箇条書きは避けます。目的は、人がプロジェクトに慣れるための説明を提供することです。スコープに応じて長さを調整します。

エントリーの生成

インデックスエントリのメタデータ

• id：再生成の場合は既存のものを再利用し、それ以外の場合は新しく生成します。形式：entry-{unix-timestamp}-{random-4-hex-chars}
• title：例：「概要：src/auth/ — トークンの発行と検証」
• experience_level："foundational"（概要はオンボーディングのエントリーポイントです）。
• decision_type："overview"
• topics：小文字のケバブケースのタグです。既存のタグを再利用します。
• lifecycle："active"
• sources：項目がちょうど1つの配列で、正規化された対象パスを指定します。
• references：単一ファイルの概要の場合は、そのファイルへの参照を1つ指定します。ディレクトリまたはプロジェクトの場合は、空の配列にします。
• content_file：セッションファイルへの相対パスです。例：sessions/overview-2026-03-27-001.json

セッションエントリのコンテンツ（概要の形式）

概要の形式を使用します。標準エントリとは異なります。

• decision_type："overview"
• purpose（必須）：対象コードの目的
• structure（必須）：対象の構成
• entry_points（任意）：呼び出し可能なインターフェース
• dependencies（任意）：主要な依存関係

セッションの終了

1. timestamp_endを設定します。
2. 対象と、新規作成または再生成のどちらであるかを記したsummaryを作成します。
3. 次の内容を確認します：
   • 新規作成：「セッション<session_id>で、<target>の概要をエントリ<id>として生成しました。」
   • 再生成：「<target>の概要を再生成しました（エントリ<id>）。」

データ形式

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

重要な注意事項

• 常に最新の状態にし、追記のみにはしません。 再実行すると、インデックスエントリが上書きされます。
• 対象ごとにエントリを1つ作成します。 ファイルごとのエントリに分割しないでください。それは分析モードの役割です。
• 不確実な点は正直に記述します。 対象の目的が曖昧な場合は、その旨を記載してください。
• 言語に依存しません。 プロジェクトで使用されている言語やフレームワークに合わせてください。
• データは自己完結型です。 .decodie/ディレクトリは、プロジェクトに影響を与えることなく削除できます。