プランレビューと監査証跡

ユーザーの目標とワークフローの境界

この実践的なワークフローは、開発者およびレビューエージェントがソフトウェアの提案、技術仕様、およびアーキテクチャプランをリポジトリの実証的証拠に照らして監査する手順を案内します。レビュー担当者はプランの主張を保存されているプロジェクトの制約と比較し、個別のライフサイクル段階 (planned、submitted、merged、released、verified) にわたる変更を追跡し、承認された合意決定を不可変の来歴帰属とともに永続化します。

利用資格と前提条件

監査およびプランレビュー機能は、MCP クライアントプロファイルおよびスタンドアロンの Skill CLI 全体で提供されます:

• MCP cursor-plugin および ordinary-full プロファイル: 包括的なレビュー機能を提供します: get_project_context (読み取り専用プロジェクトパック)、recall_context、search_knowledge、update_project_decision (決定の遷移: resolve、supersede、reopen)、update_project_todo (作業項目の遷移: accept、assign、block、unblock、complete、cancel)、および query_audit (イベントおよび統合レコードの監査)。
• MCP claude-plugin プロファイル: get_project_context、recall_context、create_pending_decision、resolve_decision、record_event、remember、recall、および todo を含みます。
• MCP generic-public、chatgpt-public、および public-only プロファイル: クイックサマリー用の focus="blockers" または focus="status" を指定した get_project_summary(project_id, focus)、および統計用の memory_overview をサポートします。
• スタンドアロン Skill (Claude Code、Codex、OpenClaw): 提供される 1.1.35 help.mjs からの逐語的コマンド: recall-context (84-87行)、search (80-83行)、remember (72-75行)、update (44-47行)、todo-add/list/done (112-123行)、および activity/stats (64-71行)。
• 前提条件: プロジェクトコンテキストおよび監査履歴を照会するための読み取りスコープ (memory:read)、決定を記録し作業項目を更新するための書き込みスコープ (memory:write)。

1 つの完全なタスク: サービス移行プランの監査

この合成監査チュートリアルでは、エージェントがプロジェクト proj_security_core の認証アップグレード提案をレビューし、リポジトリの制約に対して主張を検証し、作業項目を遷移させ、承認された結果を保存します。

プロジェクトの制約と監査履歴を取得する

recall-context または get_project_context を使用して、確立されたプロジェクトガイドラインを取得し、以前の決定の来歴を検査します:

node scripts/xmemo-skill.mjs recall-context --query "token revocation policy session lifetime proj_security_core" --max_items 6 --max_tokens 2500

作業項目のステータスを遷移させ、決定を記録する

レビュー TODO を完了としてマークし、来歴を付与して正式な解決策を保存します:

node scripts/xmemo-skill.mjs todo-done --id todo_rev_401
node scripts/xmemo-skill.mjs remember --content "Approved plan auth_migration_v3: enforced 24h token revocation, strict mutual TLS, and zero unauthenticated fallback. Verified by reviewer audit." --path "plans/auth_migration_v3"

観察可能な結果

構造化されたプラン監査により、個別のライフサイクルマイルストーンを反映した不可変で検証可能な証跡が作成されます:

• 5 つの異なるマイルストーン状態: プランと作業項目は明示的な段階を経て進行します: planned (ドラフト仕様) -> submitted (正式レビュー要求) -> merged (実装統合完了) -> released (パッケージ化およびデプロイ完了) -> verified (デプロイ後検証合格)。planned を released や verified と混同しないでください。
• 決定論的な監査証跡: query_audit は、イベントのタイムスタンプ、実行エージェントの agent_id、対象のメモリ/決定 ID、および変更前後の状態差分を含む構造化レコードを返します。
• 来歴の保持: recall または recall_context でメモリを照会すると、正確な認可セッションとタイムスタンプを識別する不可変の来歴メタデータが開示されます。

エージェントがアクセスできるもの

プランレビューと監査を実行するエージェントは、構造化され境界付けられた表現と対話します:

• 追記専用の監査ログ: 監査イベントログは追記専用 (append-only) です。エージェントは過去の決定監査レコードを上書き、不正変更、または削除することはできません。
• バージョン DAG と後継関係: 既存の決定またはメモリを更新すると、その先行バージョンにリンクされた新しいバージョンが作成されます。以前の状態は後継されたバージョンとして引き続き取得可能です (cursor-plugin / ordinary-full の list_memory_versions)。
• 証拠に基づくコンテキスト: recall ツールはプロジェクトメモリから抽出された事実証拠を返すため、エージェントが未検証のモデル推論を記録されたプロジェクト決定と誤認するのを防ぎます。

共有とストレージの境界

監査レコードと決定は、厳格なマルチテナントおよびプロジェクトパーティションによって管理されます:

• プロジェクトスコープの境界設定: project:proj_security_core にバインドされた決定と作業項目は、無関係な個人プロジェクトや外部チームスペースから隔離されたままになります。
• スクラッチパッドの除外: 一時的な開発者の下書きメモ (スクラッチパッド)、ローカルデバッグログ、および一時的な思考を永続的な決定レコードに書き込んではいけません。
• 帰属の不可変性: サーバーは、認証された呼び出し元の owner_identity および source_identity をすべての決定に刻印します。クライアントが他のエージェントを偽造またはなりすますことはできません。

障害回復

標準的な解決手順に従って、監査の不一致やレビューの競合を管理します:

• 未検証のプランの主張または矛盾: 提案されたプランが既存のアーキテクチャ決定と矛盾する場合、決定を解決済みにしないでください。不一致を説明する詳細な resolution_note を添えて、action="supersede" または action="reopen" で決定を遷移させます。
• 作業項目または決定 ID の欠落: 参照されている todo_id または decision_id が見つからない場合は、todo-list (Skill) または get_project_context(project_id="proj_security_core") を使用してアクティブな項目を照会し、正規の ID を特定します。
• スコープ権限の拒否: エージェントに対象プロジェクトの書き込み権限がない場合、update_project_decision は HTTP 403 Forbidden を返します。ロールの割り当てについてプロジェクト管理者にエスカレーションしてください。

関連リファレンス

関連するセキュリティの概念、来歴の詳細、および作業項目の管理については、以下のガイドを参照してください:

• 来歴と帰属: 呼び出し元帰属の詳細については /docs/concepts/provenance-attribution を参照してください。
• TODO 作業項目リファレンス: プロジェクトタスク追跡については /docs/tools/todos を参照してください。
• 元帳取引リファレンス: 財務およびリソース監査については /docs/tools/ledger を参照してください。
• 再開とエージェントハンドオフ: セッションチェックポイント作成ワークフローについては /docs/guides/resume-and-handoff を参照してください。
• プロジェクトガイド: プロジェクトワークスペースの編成については /docs/concepts/projects を参照してください。