decodie-explain

Decodie — 説明モード

開発者が選択または貼り付けた特定のコードについて、説明します。チャット上で、会話形式の読みやすい説明を直接生成します。

このモードではソースコードは読み取り専用で、デフォルトでは一時的なものです。ユーザーが明示的に保存を求めない限り、.decodie/ には何も書き込みません。

セットアップ

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

対象範囲と入力

ユーザーが選択、貼り付け、または場所を指定したコードを対象とします。プロジェクトをスキャンしたり、ファイルを検索したりはしません。

コードが提供されていない場合は、説明してほしいコードを共有するようユーザーに尋ねます。

出力形式

説明はチャット上で会話形式の Markdown として作成します。依頼がない限り、ディスクには書き込みません。

1. 概要

コードが何をするのかを大まかに説明する、2～3文の短い段落です。

2. 詳細な解説

複雑な箇所や、すぐには分かりにくい箇所ごとに、以下を示します。

• コードの抜粋を含むフェンス付きコードブロック
• 何をするのか、なぜそうするのか、どのようなパターンや慣用表現が使われているのかの説明
• 該当する場合はパターン名（例：「ガード節」「メモ化」）

複雑さに応じて、2～5箇所を目安に解説します。簡単なコードは省略します。

3. 潜在的な問題

バグ、セキュリティ上の懸念、パフォーマンスの問題、エッジケースを列挙します。それぞれについて、以下を記載します。

• severity：info、warning、error のいずれか
• description：問題の内容と、どのような場合に発生するか
• suggestion：対処方法

問題が見つからない場合は、その旨を明確に伝えます。

4. 改善点

リファクタリングの機会、最新の代替手段、読みやすさを高める方法を示します。それぞれについて、以下を記載します。

• description：提案する変更
• rationale：変更による利点

5. 重要な概念

押さえておくべき主要なパターン、原則、言語機能を箇条書きで示します。

説明の保存（明示的な依頼があった場合のみ）

ユーザーが明示的に依頼した場合にのみ保存します。

セットアップ

1. プロジェクトのルートに .decodie/ があるか確認します。なければ作成します。

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

2. セッション ID を決定します。.decodie/sessions/で、今日の日付に該当するexplain-YYYY-MM-DD-NNNのうち最大のNNN` を探し、1 を加えます。

セッションエントリのフィールド

以下の内容をセッションファイルに書き込みます。

• code_snippet：提供された選択コード。
• explanation：概要セクション。
• alternatives_considered：該当する場合は代替案。そうでなければ空文字列。
• key_concepts：主要な概念の配列。
• breakdowns：{ code_excerpt, explanation, pattern? } の配列。
• issues：{ severity, description, suggestion } の配列。
• improvements：{ description, rationale } の配列。

インデックスエントリ

• id：形式は entry-{unix-timestamp}-{random-4-hex-chars}
• decision_type："explanation"
• content_file：セッションファイルへの相対パス。例：sessions/explain-2026-03-27-001.json

コードの出所となるファイルを特定できる場合は、内容に基づくアンカリング情報を含めます。

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

既知の出所がなく、コードが貼り付けられた場合は、references を空にしてもかまいません。

セッションの終了

timestamp_end を設定し、簡潔な summary を書き込み、次のように確認します。「説明をセッション <session_id> のエントリ <id> として保存しました。」

データ形式

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

重要な注意事項

• 依頼がない限り、一時的なものとして扱います。 ユーザーが永続化を明示的に依頼した場合にのみ、.decodie/ に書き込みます。
• コードに合わせて解説の詳しさを調整します。 5 行のユーティリティに、5 つの詳細な解説は必要ありません。
• 不確かな点は正直に伝えます。 コードが曖昧な場合は、その旨を伝えます。