project-notes-context

プロジェクトノートのコンテキスト

プロジェクト固有の作業コンテキストを、リポジトリとは分離した private なローカルノートに保つ。この例では root ID を notes-work、ノートの配置を rules/ と projects/ とする。別の root ID や配置を使う場合は、スキル全体を自分の環境へ合わせて変更する。

コンテキストの読込み

1. Git ルートから現在のリポジトリ名を取得する。Git リポジトリでなければ処理を止める。
2. agent_notes MCP ツールと notes-work root が利用できる場合、まず rules/ を列挙する。プロジェクトノートを扱う作業では、project-notes- で始まる現在の共通規約を読む。
3. 既知の正本である projects/<repository-name>/overview.md と projects/<repository-name>/handoff.md は、列挙せず read_note で直接読む。どちらかが存在しない場合は、そのノートなしで続ける。
4. inbox は root_id: notes-work、path_prefix: projects/<repository-name>/inbox/、status: ["new", "triage"] を指定して list_notes で列挙し、現在の作業に関係するノートだけを read_note する。
5. 過去の判断理由が現在の作業に関係する場合だけ decisions.md を読む。
6. ノート、root、MCP サーバーが存在しない・利用できない場合はブロッカーにしない。リポジトリのコンテキストだけで作業を続け、ノートがないことだけを理由に新規作成しない。

コンテキストの更新

• ユーザーが依頼した場合、またはユーザーが保存に合意した永続的な判断が生まれた場合だけ、プロジェクトノートを作成・更新する。
• overview.md はプロジェクトの恒久的な概要、構成、技術選定、設計原則を扱う。handoff.md は現在のブランチ、未コミット変更、検証結果、現行の重要事項、次の行動を扱う。どちらも古い内容を追記で打ち消さず、現行の正を直接更新する。
• handoff.md に有効な管理ブロック（<!-- agent-notes:managed <id> --> と対応する終端）がある場合は、read_note で取得した SHA-256 を指定して update_managed_blocks を使う。現在地として整合させる複数のブロックは、一回の呼出しでまとめて更新する。
• 管理ブロックがない既存 handoff は、全文を読んだうえで SHA-256 付きの置換を使う。管理ブロックの導入はノート構造を変えるため、ユーザーが明示的に依頼または合意した場合だけ行う。管理ブロックが壊れている場合は推測して更新せず、書込みを行わずに原因を報告する。
• 複数の既存ノートを整合させるときは、対象すべてを先に読み、それぞれの SHA-256 を指定して batch_update_notes を使う。作成と移動は一括更新に混ぜない。
• 日付・判断・理由を簡潔にした記録を decisions.md に追記する。ブランチ固有の実装詳細・調査・検証・PR は branches/ に残す。
• activity_log が有効な場合、永続的な判断・成果・次の行動を残す更新には、ユーザーの依頼または判断を主語にした簡潔な activity_summary を添える。機械的な更新や一時的な試行には付けない。
• ノートを置換・移動する前には必ず読込みを行い、更新時に得た SHA-256 を指定する。

branch ノートの再照合

• Git リポジトリで実質的な作業を再開する時だけ、branches/ を対象に lifecycle: active のノートを列挙し、候補を読んでローカル Git の現在ブランチ、HEAD、ローカルブランチ一覧、作業ツリーと照合する。
• 全ローカルブランチを個別に評価しない。ノートの HEAD と実際の HEAD が異なるもの、ノート記載のブランチがローカルにないもの、非 base branch なのに対応する active ノートがない現在ブランチだけを、まとめて更新候補として報告する。
• 再照合そのものは読取り専用である。ユーザーが反映を依頼した場合だけ、対象ノートを再読込みして SHA-256 を指定し、安全な更新操作を行う。