コアコンセプト

AWRは、プロジェクトの作業の事実を単一のエージェント会話の外に保持するため、コンテキストの喪失、エージェントの切り替え、再起動があっても作業が生き残ります。この記事ではそのモデルの背後にある5つの考え方を説明します。クイックスタートのコマンドと日常ワークフローのルーチンが、自然に読めるようになるはずです。

中核となる原則: ソースファイル（レジャー、計画）が権威であり、ランタイムが保存するものすべて —— セッション、クレーム、証跡 —— はそれらの事実の検証可能なプロジェクションです。AWRは欠けている意図を捏造することはなく、会話のトランスクリプトが記録された事実の代わりになることも許しません。

プロジェクトの事実: ソースレジャー

AWRのソースレジャーは、通常のプロジェクトファイルに保持する小さな作業契約です。work-ledger.yaml のようなYAMLレジャー、または既存のMarkdownレジャー（*-ledger.md）で、後者はAWR経由では読み取り専用のままで、元のファイルで編集します。レジャーは2種類の事実を記録します。

ゴール —— プロジェクトが達成しようとしていること、成功基準付き。ゴールは不確かな場合は draft、candidate、needs_confirmation、ソース資料やユーザーの指示に裏付けられた場合は activeまたはconfirmedになります。AWRは宣言をチェックしますが、ゴールが人間の意図と一致していることを保証するものではありません。
作業アイテム —— タスク。以下で説明します。

最小のレジャーは次のようになります:

goals:
  - id: search
    title: Let readers find documents
    status: active
    summary: The user requested search in the existing portal; see README.md.
    success_criteria: [Readers find a requested document]
work_items:
  - id: search-api
    title: Add document search
    status: ready
    goal: search
    acceptance: [A matching query returns the requested document]
    next_action: Implement the search handler using the current document index

これらのファイルはinitでAWRの管理下に入れます。プレビューを承認するまで何も書き込まれません:

awr --project /absolute/project init
awr --project /absolute/project init --accept
awr --project /absolute/project intake inspect --json

initは既存のファイルを決して上書きせず、インスペクションは再構築可能なプロジェクションキャッシュを更新するだけです —— ゴール、タスクファイル、実行状態に触れることはありません。

タスク: 作業アイテム

作業アイテムはレジャー内の1つのタスクです。その主要フィールドは、AWRが実際にチェックできるものです。

acceptance —— 完了基準: タスクが完了したときに観察可能な形で真であるべきこと。完了レポートは後でこれらの正確な基準に照らしてチェックされます。
next_action —— 永続化された次のステップ。リカバリーにおいて最も価値のあるフィールドで、新しいセッションが履歴を読み直さずに継続できるようにします。
補助フィールド: summary、goal、kind、paths、tags、priority、depends_on、owner、 milestone。

タスクは、明示的に判明している事実のみを記述したJSONドラフトから作成します:

awr work create --input draft.json

作成は常にドラフトを生成します。欠けているゴールや必須の事実は可視のまま残り、ドラフトは何かを実行または完了する許可を与えません。適用は別の明示的なステップです。

AWRはまた、not_initialized、needs_organization、ready、blocked、 awaiting_verification、completed、closed_without_completionといったプロジェクトレベルの整理状態を報告します。日常的に最も重要なのは2つです。readyは少なくとも1つのタスクにソースで宣言されたゴール、受け入れ基準、次のアクション、解決済みの前提条件があることを意味し、 awaiting_verificationはレジャー上ではタスクが完了しているが、受け入れレポートのすべてがまだ検証されていないことを意味します。

チェックポイントとセッション

セッションは、あるエージェントが作業アイテムに対して持つ作業中のアタッチメントです。チェックポイントは、そのセッションがどこにいるかの永続的な記録です。永続化された次のアクション、未解決ループ、実際のAWRイベントとソースの差分を含み、会話のコピーではありません。

クライアントセッションが開始またはコンパクション後に再開されると、AWRはチェックポイントから構築されたリカバリーコンテキストを返します。ターンが停止または終了すると、変更された次のアクションと未解決ループが失われる前に保存されます:

awr client progress --client codex --external-session CLIENT_ID \
  --next-action "Apply the reviewer corrections" --open-loop "Independent review remains"

作業が変わっていない重複イベントは既存のチェックポイントを再利用し、進捗が変わった継続ターンは新しいチェックポイントを作成します。1つの正直な境界: これを自動化するネイティブフックアダプターは、現在 Codex向けのみインストールされています。他のホストはL0バインダー（--client generic）を使い、ホスト会話をアクティブなAWRセッションにアタッチしますが、フックはインストールしません。アダプターはトランスクリプトの本文を決して読みません —— モデルが言ったことではなく、あなたが伝えたことを記録します。

クレームとハンドオフ

クレームは、セッションがタスクを実行する前に保持する明示的なロックです。AWRは実行前にセッションクレームの取得を要求し、完了時にそれを再チェックします —— これにより、2つのエージェントが黙って同じタスクで作業することを防ぎます。

ハンドオフは、作業をあるセッションやクライアントから後続者へ移します。リビジョンチェックと後続トランジションを伴う明示的なセッション再開を行います:

awr session resume --from-session AWR_SESSION_ID --agent successor \
  --provider generic --model selected-model --no-claim --expected-revision REVISION

あるいは、新しいクライアント会話を前任者にバインドします:

awr client bind --client generic --external-session NEW_CLIENT_ID \
  --work INTAKE-001 --from-session AWR_PREDECESSOR_ID

ハンドオフが移すのは記録された事実 —— レジャー状態、チェックポイント、実行履歴 —— であり、プロセスメモリではありません。シャットダウンフックは参考情報です。クレームを解放したりセッションを終了したりすることは決してなく、それらはハンドオフ時のあなたの明示的な責任のままです。

デリバリーと受け入れ

受け入れは、AWRが意図的に厳格にしている部分です。誰かがレジャーにstatus: completedと書いたからといってタスクは完了になりません。登録された完了レポートがレジャーの現在の受け入れ基準に照らして検証されたときに完了となります。

完了レポートは、実際に実行されたコマンド、実際に検証されたスコープ、時刻、名前付きチェックを記録します —— 各チェックは正確な受け入れ基準に対応し、意図した結果ではなく観察された結果を記述します:

{
  "version": 1,
  "work_item": "WORK",
  "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "command": "the command or verification procedure actually executed",
  "scope": ["the scope actually verified"],
  "verified_at": 1,
  "checks": [{
    "name": "independent check name",
    "passed": true,
    "details": "the observed outcome, not an intended result",
    "criteria": ["an exact current source acceptance criterion"]
  }]
}

完了する前に、レポートをプリフライトします:

awr work prepare-completion WORK --report report.json --evidence-key KEY \
  --source-sha FULL_SHA --level locally_verified

プリフライトはコマンドを実行せず、証跡を登録せず、タスクを完了しません —— レポートのバイトを読み、証跡の引数と受け入れのマッピングを返します。完了自体は別の書き込みで、クレーム、依存関係、ソースの鮮度、レポートのバイトを再チェックします。プリフライト後にレポートを変更すると、そのダイジェストは無効になります。ソースで宣言された完了だけでは検証済みの領収書には決してならず、ステータスレポートではsource_completedとverified_completedは別々のカウントのままです。

1つのタスクを最初から最後まで

上のレジャーのsearchタスクで全体をつなげてみましょう:

事実。 awr --project /absolute/project init --acceptを実行すると、searchゴールと search-api作業アイテムを持つレジャーが権威になります。
タスク。 作業アイテムは受け入れ基準と次のアクションを持つため、プロジェクトはreadyと報告します。
セッションとクレーム。 1つのスナップショットから作業を準備し、コードに触れる前にセッションクレームを取得します:

   awr work prepare search-api --session AWR_SESSION_ID --source-sha FULL_SHA

チェックポイント。 作業中、awr client progressで進捗を保存し、クラッシュやコンパクションがあっても次のアクションと未解決ループが生き残るようにします。
ハンドオフ（必要な場合）。 後続者はawr session resume --from-session …で再開し、チャット履歴の再生なしに同じ事実を取得します。
デリバリー。 チェックが正確な受け入れ基準に対応するレポートを書き、 awr work prepare-completionでプリフライトし、その後初めて完了を記録します。ステータスにはそのタスクがソースSHAに照らして検証済みと表示され、単に完了とマークされたのではありません。

次に読むべきもの

クイックスタート —— これらのコンセプトを初めて実行します。
日常ワークフロー —— 準備、クレーム、チェックポイント、完了の定常ループ。