知識キャプチャ
自動使用
任意のリポジトリタスクに対する最終応答の前に、ファイルが変更された、テストが実行された、または決定/発見/フォローアップが行われた場合、現在のセッション/ワークフローに対してアクティブな session キャプチャを1つだけ作成または更新します。これは検証後、バックログクリーンアップまたは承認を求める前に行ってください。
スキルが再度呼び出されたからといって、新しいキャプチャを毎回作成しないでください。このワークフローに対してアクティブなキャプチャパスが既に分かっている場合は、そのファイルを更新してください。それ以外の場合は、.ai/raw/active-session.json を候補として読み取り、アクティブポインタを確認します。信頼できるアクティブキャプチャが存在しないか、ワークフローが明らかに変更された場合は、新しい生キャプチャを作成し、ポインタを置き換えてください。
現在のタスクの詳細を後で利用できるように十分にキャプチャしてください。現在のワークフローに対するアクティブキャプチャのみを読み取り/更新してください。v0.2では、無関係なキャプチャの読み取り、更新、重複排除、マージ、同期、コミット、公開、昇格は行わないでください。
ヘルパーがファイルを書き込んだだけではキャプチャは完了しません。事実が判明しているセクション、特に「User request」「Changes and evidence」「Decisions and discoveries」「Open questions and next steps」に「Not captured.」を残さないでください。
アクティブキャプチャを更新する場合は、現在のワークフローステップ後にそのキャプチャがどうあるべきかという全体を書き込んでください。デルタのみの追記メモは行わないでください。現在のタスクコンテキスト、可視ファイル、差分、テスト、コマンド結果、引き継ぎテキストを証拠として使用します。継続性が不明瞭な場合は、欠落したコンテキストを捏造する代わりに、新しいキャプチャを作成してください。
キャプチャを現在の現実に合わせ、中間的な思考のすべてに合わせないでください。以前の決定が変更され、それに伴って作業内容も変更された場合は、最終的/現在の決定と証拠をキャプチャしてください。以前の決定は、実装されたコード、ロールバック、未解決のリスク、または未解決の質問を説明する場合にのみ保持し、純粋に理論上の放棄された選択肢は省略してください。
キャプチャは .ai/raw/<type-folder>/YYYY-MM-DDTHH-mm-ssZ--<type>--<topic-slug>.md に保存してください。同じファイル名が既に存在する場合は、.md の前に --2、--3 などを追加してください。
タイプ: session -> sessions、discussion -> discussions、investigation -> investigations、decision -> decisions、handoff -> handoffs。
session キャプチャの場合、アクティブワークフローキャプチャへのローカルポインタとして .ai/raw/active-session.json を維持してください。これはすべての最終応答後にクリアせず、再開、圧縮、引き継ぎをサポートします。新しいワークフローキャプチャが開始されたときに置き換えてください。
キャプチャ
/capture は現在のセッションキャプチャの作成/更新として扱ってください。/capture <type> は、<type> が session、discussion、investigation、decision、または handoff の場合、そのキャプチャタイプとして扱ってください。
コンテキスト圧縮、コンパクション、または引き継ぎの前に、意味のある作業や決定がまだキャプチャされていない場合は、先にキャプチャを行ってください。
Nodeが利用可能な場合、依存関係なしのヘルパーを使用して、最初のキャプチャを作成したり、既知のアクティブキャプチャを --update <path> で置き換えたり、ポインタが指すキャプチャを --update-active で置き換えたりできます。詳細なセクション化された情報は --stdin 経由で渡すか、直接Markdownを書き込んでください。ヘルパーはデフォルトでタイトル/サマリーのみのキャプチャをブロックします。これらは有用なセッション知識を失うためです。
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --summary "Fixed expired refresh token behavior" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update-active --stdin
stdinには references/raw-capture-schema.md のMarkdown見出しを指定してください。Nodeやシェルの実行が利用できない場合は、直接Markdownを作成または更新してください。
アクティブセッションキャプチャには次の順序を使用してください:
- 現在のコンテキストでアクティブパスが既知の場合は、そのパスを更新します。
- それ以外の場合は、
.ai/raw/active-session.jsonを候補ポインタとして読み取ります。 - ポインタとランタイムの両方が
agent_session_idを公開しており、それらが一致する場合は、それを更新します。 - セッションIDが異なる場合、欠落している場合、または利用できない場合でも、ユーザーリクエストや引き継ぎが明らかに同じワークフローを継続している場合は、それを更新し、ポインタをリフレッシュします。
- 上記以外の場合は、新しいキャプチャを作成し、ポインタを置き換えます。最新のファイル名の推測で選択することは絶対に避けてください。
ガードレール
- 有用な生の詳細をキャプチャしますが、トランスクリプト、大規模なログ、ファイル全体は避けてください。
- 変更されたファイル、テスト、コマンド、証拠は「Changes and evidence」の下に配置してください。複数のファイルが変更された場合は、目的別にグループ化してください。
- まれで、明白でない、または決定に関連するコマンド/結果のみを含めてください。後で重要にならない日常的なコマンドは省略してください。
- アクティブキャプチャの再編成は、それを正確かつ有用にするためにのみ行ってください。事実を捏造したり、時代遅れの理論をあたかもまだ真実であるかのように静かに保持したりしないでください。
agent_session_idは有用なガードレールとして扱いますが、ワークフローの定義としては扱わないでください。新しいエージェントセッションでも同じワークフローを継続できます。--agent-session-idは、ランタイムが安定した現在のセッション、会話、スレッド、または実行IDを明確に公開している場合にのみ使用してください。利用できない場合は省略してください。決して捏造しないでください。- シークレット、認証情報、APIキー、秘密鍵、顧客のプライベートデータ、無関係な個人メモリを除外してください。
- 機密コンテンツが存在する場合は、キャプチャを作成せず、まず抽象的に要約してください。
- 生のローカル専用状態は、
.ai/raw/パスとスキルポリシーから取得され、キャプチャごとのワークフローフィールドからは取得されません。 - Nodeヘルパーはオプションとして扱ってください。直接ファイルを作成することも依然として有効です。
保存後、パス、タイプ、および作成されたか更新されたかを報告してください。ヘルパーがキャプチャをブロックした場合は、警告を報告し、生コンテンツを保存しないでください。
参考資料
references/raw-capture-schema.mdは、手動で書き込むときやスキーマを変更するときにのみ読み取ってください。references/active-session-example.mdは、更新されたワークフローキャプチャがどのように見えるべきか不明な場合に読み取ってください。references/agent-portability.mdは、このスキルを別のエージェントに適応させるときにのみ読み取ってください。