working-docs

作業用ドキュメント

基本原則

_working/<topic>/ は外部タスクメモリです。後続の作業で実際に使うメモ、証拠、中間成果物だけを残します。

削除すると後続の行動、判断、引き継ぎ、監査に影響する場合に限り、そのファイルを残す価値があります。そのフォルダーがなくてもタスクを同じように完了できるなら、作成しないでください。

作業用ドキュメントは、依頼されたタスクに役立てるものです。タスクの範囲を広げたり、追加のレビューやテストを必要にしたり、簡単な作業をドキュメント化されたプロジェクトに変えたりするものではありません。

使用条件

ユーザーが作業用フォルダーを明示的に求めた場合は、作業用ドキュメントを使用します。それ以外の場合は、次の条件のうち少なくとも2つに当てはまる場合に使用します。

• タスクが複数の段階、情報源、ファイル、またはシステムにまたがる。
• 調査結果によって後から計画が変わる可能性がある。
• 中断、コンテキストの圧縮、または引き継ぎが予想される。
• 別のエージェントやプロセスが、名前の付いた中間成果物を必要とする。
• セッション後も結論を監査可能な状態にしておく必要がある。

一度限りの回答、軽微な編集、または次のツール呼び出し以降に中間状態が不要な作業には使用しないでください。スキルが事前に読み込まれている場合も、この条件を改めて確認してください。

保存場所

作業場所の近くに、通常はリポジトリのルートに、1つの固定フォルダーを作成します。ただし、ユーザーが別のパスを指定した場合はそれに従います。

<repo-root>/_working/<topic-slug>/
  README.md         # current state and entry point
  <other files>     # only evidence, drafts, prompts, or outputs later work needs

README.md を読めば、新しいエージェントが作業を再開できるようにします。元の要件、重要な制約、現在の状態、決定事項、ブロッカー、次のステップ、読むべきファイルを記載してください。

ユーザーが追跡を希望しない限り、_working/ はコミットに含めないでください。リポジトリのルートから有効な除外ルールを確認します。

git check-ignore -q _working/

除外されていない場合は、_working/ を .git/info/exclude に追加します。追跡対象の .gitignore を変更するのは、ユーザーがリポジトリ全体に適用するポリシーを明示的に希望した場合のみです。リポジトリ外では、Git の設定を作成せず、作業ディレクトリを使用します。

残す情報

後続の作業に役立つ情報だけを記録します。

• 決定事項と、その根拠となった証拠や制約。
• 繰り返すべきでない失敗したアプローチ。
• 結論に影響するパス、ID、バージョン、正確な入力、情報源への参照。
• ユーザーからの修正と、それによって計画がどう変わったか。
• 未解決の疑問、ブロッカー、復旧情報、次のステップ。
• 別の段階、プロセス、または担当者が使用する計画、プロンプト、草稿、レポート。

それ自体が証拠ではない生の出力を大量に貼り付けたり、最終回答を重複して記載したり、曖昧な活動記録を続けたり、テンプレートにあるというだけでファイルを作成したりしないでください。

作業メモリのサイクル

1. 本格的な作業の前に初期情報を記録します。 要件、重要な制約、現在の状態、次のステップを記載した README.md を作成します。
2. 重要な変化があったときに更新します。 決定事項、再利用可能な調査結果、方針の変更、継続的なブロッカー、作成した成果物は、その発生時に記録します。ツール呼び出しのたびに記録する必要はありません。
3. 記録が正式な根拠となる場面で読みます。 中断やコンテキストの圧縮の後、引き継ぎの前、エージェントからの応答の後、または記録した証拠に基づく決定の前に README.md を読みます。形式的に、変更のないファイルを繰り返し読み直さないでください。
4. 入口となる情報を最新に保ちます。 計画や状態に大きな変化があった場合は、権威ある成果物を示すように README.md を更新します。
5. 必要な情報がそろったら終了します。 後続の作業を再開でき、記載した成果物にすべて根拠があるなら、要約ファイルや、後続の作業に不要な体裁の調整を追加しないでください。

委任と引き継ぎ

別のエージェントやプロセスが作業用フォルダーを必要とする場合は、次のようにします。

• _working/<topic>/ の正確なパスを伝えます。
• 読むべき入力ファイルと、作成すべき出力ファイルを明示します。
• 重要な主張には、情報源のパスまたは証拠を示すよう求めます。
• 指定した出力を、根拠として使用する前に読みます。

ファイルを書いたという要約は、そのファイルが存在する証拠にはなりません。想定したファイルがない、または読み取れない場合は、委任したタスクを完了扱いせず、成果物が欠けていると報告してください。

範囲を限定した検証

作業中のドキュメントに関する主張は、必要最小限の直接確認で検証します。

1. 該当するフォルダーを一覧表示します。
2. README.md と、その存在または内容について主張する各成果物を読み返します。
3. 引き継ぎや最終回答に向けて、ブロッカーと次のステップが現在の状況を反映していることを確認します。

ここで検証するのは、作業の基盤となるドキュメントのみです。製品の動作、コード、デプロイ、ハードウェアに関する主張には、担当タスクからの証拠が必要です。作業中のドキュメントを確認したからといって、無関係なテスト、全テストスイート、レビュー、実環境での操作を行う必要はありません。