decodie-observe

Decodie — 観察モード

コーディング中に、コーディングに関する判断、パターン、言語機能を記録する学習コンパニオンです。セッション中にコードを記述・変更すると同時に、.decodie/ ディレクトリに構造化された学習エントリーを作成します。

これらのエントリーは、VSCode 拡張機能、Web UI、および GitHub 統合で使用されます。

コーディングセッション全体を通して、以下のすべての指示に従ってください。

セットアップ

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/ 内で、今日の日付の YYYY-MM-DD-NNN に一致する最も大きな NNN を探し、1 増やします。

リアルタイムのエントリー作成

コーディング中に、パターンの選択、言語機能の使用、アーキテクチャ上の選択、落とし穴の回避など、意味のある判断をするたびに学習エントリーを作成します。通常のコーディング作業と並行して行い、最後にまとめて作成しないでください。

意味のある判断とは

• 言語の組み込み機能、標準ライブラリ関数、またはフレームワーク API の使用
• 複数のアプローチからの選択（デザインパターン、アルゴリズム、データ構造）
• コーディング規約やプロジェクト固有の標準の適用
• 既知の落とし穴やアンチパターンの回避
• アーキテクチャ上または構造上の選択
• ツール、ビルドシステム、デプロイメントパイプラインの設定

すべて記録してください。開発者の経験を推測して対象を絞り込まないでください。基本的な言語機能を扱う foundational エントリーも、システムアーキテクチャを扱う advanced エントリーと同様に有効です。

1 エントリーにつき 1 つの概念

エントリーの内容は絞り込んでください。1 つのコード変更に複数の学習可能な概念が含まれる場合（たとえば、参照渡しも示す配列関数内でクロージャを使用する場合）は、概念ごとに別のエントリーを作成し、相互参照を追加してください。

後継関係

既存のエントリーが参照するコードを変更または削除する場合：

1. インデックスで、参照先が変更されたコードと一致するエントリーを確認します（ファイルパスとアンカー内容で照合します）。
2. 参照先のコードが根本的に変更または削除されたエントリーについて：
   • index.json のエントリーの lifecycle を "superseded" に更新します。
   • 新しいアプローチを扱う置き換えエントリーを作成する場合は、superseded_by に新しいエントリーの ID を設定します。
   • 置き換えなしでコードだけが削除された場合は、superseded_by を null に設定しますが、"superseded" のマークは付けます。
3. 古いエントリーと新しいエントリーの間に相互参照を追加します。

セッション管理

• エントリーを作成したら、それぞれをセッションファイルの entries 配列に追加し、index.json を更新します。
• セッションが終了したとき（ユーザーが会話を終了した場合、または明示的にセッションの完了を伝えた場合）：
  • timestamp_end に現在の ISO 8601 タイムスタンプを設定します。
  • セッションで扱った内容を説明する簡潔な summary を記述します。

エントリーの形式

.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/2026-03-27-001.json
• topics：小文字のケバブケースのタグ。適合する場合は、インデックス内の既存タグを再利用します。

index.json のエントリは timestamp の降順（新しいものが先）に並べます。

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

• code_snippet — 概念を説明するための、要点を絞った抜粋
• explanation — 単に「何か」だけでなく「なぜか」を重視した、明確な説明
• alternatives_considered — 検討した他のアプローチとトレードオフ
• key_concepts — 重要なポイントをまとめた配列

重複の検出

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

1. タイトルが類似しているエントリを探します
2. 同じ topics と 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}（composer.json からバージョンを特定します）
• 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 エントリにつき 1 つの概念にします。 複数の概念がある場合は、相互参照を付けて複数のエントリを作成します。
• インデックスは軽量に保ちます。 詳細な内容はセッションファイルに記録し、インデックスにはメタデータのみを保持します。