日常ワークフロー

このガイドでは、AWRでの繰り返し可能な日常ルーチンを説明します。プロジェクトの状態を確認し、タスクに クレームを取るか再開し、進捗を記録し、チェックポイントを取り、ハンドオフして、あなた —— または エージェント —— が止まった場所から正確に再開できるようにします。

始める前に、プロジェクトが初期化済みで、基本概念（作業アイテム、セッション、クレーム、チェックポイント）を 理解していることを確認してください —— クイックスタートとコンセプトを 参照。同じルーチンはMCP経由でも動きます。MCPを参照してください。

バージョンについての注意: 以下の一部の機能（アクションビューとwork edit）は現在のソースツリーを反映して おり、リリース済みパッケージでは有効になっていない場合があります。お使いのインストールがサポートする内容は awr --helpで確認してください。

1. 一日の始まり: 次のアクションを見つける

他の何より先に、ステータスチェックを実行します:

awr status

awr statusとMCPツールのawr_project_statusは、デフォルトでアクションビュー（view="action"）になり ます。未完了の作業を4つのキューに分け、各キュー最大5件のエントリーと、正確な合計数・省略数を表示します:

繰り返し指定可能なセレクターで選択を絞り込めます —— それらは積集合になります:

awr status --work GUIDE-1 --goal GOAL-1 --milestone M1

キューはナビゲーションであり、認可ではありません。クレームと完了チェックはそれぞれの操作で引き続き強制 されます。awr readyはより狭い意味 —— 新規クレームの対象 —— を保ち、進行中の作業は省略します。

2. タスクにクレームを取る、または再開する

シェルごとに一度セットアップし、すべてのコマンドをプロジェクト紐付け・JSON形式にします:

AWR_BIN=/absolute/path/to/awr
AWR_PROJECT=/absolute/path/to/initialized/project
AWR_WORK=EXAMPLE-001
AWR_AGENT=agent-primary
AWR_MODEL=your-current-model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

新しい作業。新しいセッションの下でクレームを取得:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
  --provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
  --expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")

クレームはランタイムのオーナーシップであり、ソースの作業ステータスを書き換えません。その作業のセッションが すでに存在する場合は、session showで検査してオーナーシップを確認してください —— 別のエージェントや モデルはsession resumeで自分のセッションに継続します。

3. コンテキストをコンパイルする

編集前に、セッションのコンテキストパケットを構築します:

awrj context bootstrap --session "$AWR_SESSION" --budget 1000 \
  > "$AWR_NOTES/bootstrap.json"
jq -e '.context.complete' "$AWR_NOTES/bootstrap.json"

awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
  --budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"

ブール値だけでなく、パケットそのものを読んでください。BudgetExceededの場合は予算を広げるかスコープを 絞り、SourceStaleの場合はまずawr source reindexを実行してください。

4. 作業し、チェックポイントを取る

実際に起きたこと —— 失敗、不足していたコンテキスト、未解決ループ —— を記録します:

AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
  --context-hash "$AWR_CONTEXT_HASH" \
  --digest "Record the work actually done; do not invent a passing review." \
  --next-action "State the exact next operator or agent action." \
  --open-loop "List every unresolved loop." \
  --expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"

チェックポイントについて理解しておくべき点:

• --agentは呼び出し元の申告です。セッションと一致しないものは再開ガイダンス付きで拒否されます。 一致するものも未検証のままです —— CLIはラベルの背後の実際のモデルを認証できません。省略すると 発生元はundeclaredとして記録されます。
• ダイジェストとコンテキストハッシュはあなたの主張です。実際に最後に使ったハッシュを使ってください。 保存されたチェックポイントは、検証済みのコンテキスト、合格したテスト、完了した作業を証明しません。
• リビジョンガードには、session showのトップレベルのproject_revisionを使います。 session.revisionではありません。コンフリクト時は、再試行前に介在した変更を検査してください。
• チェックポイントはソースに裏付けられた次のアクションを決して書き換えません。契約を変更するには、 権威あるソースを編集してください。

5. YAMLを手編集せずに小さなフィールド修正を行う

ソース計画に小さな修正が必要なとき —— 例えばソースには「ガイドの下書き」とあるが、実際の次のステップは 「結論のレビュー」という場合 —— まず編集をプレビューします:

awr --json work edit GUIDE-1 --request-key guide-next-1 --actor writer \
  --reason 'Clarify the review step' --next-action 'Review the conclusion'

レスポンスには、ソースの場所、新旧の値、承認に使うフィンガープリントが表示されます。それらを確認し、 同じコマンドに以下を追加して再実行します:

--accept --source-fingerprint SOURCE_FINGERPRINT \
--expected-preview PREVIEW_FINGERPRINT --expected-revision REVISION

サポートされるフィールドは--title、--summary、--priority、--next-actionです。結果が不確かな レスポンスの後はhost status --key guide-next-1を確認してください。フィールド編集はオーナーシップ、 ライフサイクル、検証を一切変更しません。

6. セッションを終了する —— またはハンドオフする

一日の作業を止めるとき:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
  --expected-revision "$AWR_REV"

終了はクレームを解放します。ソースの作業を完了にはしません。作業をきれいに再開できるようにするのは、 ステップ4のチェックポイントです。

7. あなた（またはエージェント）が止めた場所から再開する

後で —— または別のエージェントから —— 前任セッションから再開します:

AWR_PREDECESSOR=the-recorded-awr-session-id
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent "$AWR_AGENT" --provider generic --model "$AWR_MODEL" \
  --budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")

再開は新しいAWRセッションを作成します。ホストのネイティブチャットを切り替えるものではありません。その後、 コンテキストを再度コンパイルし（ステップ3）、継続してください。ホストのコンパクション後、同じAWRセッション がまだアクティブなら、単に再度コンパイルすればよいです —— session resumeは実際のハンドオフのために 取っておいてください。

計画と最後に記録されたものを比較するには、status --view actionとwork show KEYが公開するprogress オブジェクトを確認します:

• source_next_action —— ソース計画からの権威あるテキスト。そのロケーター、ソースリビジョン、鮮度付き。
• latest_checkpoint_next_action —— この正確な作業、ブランチ、オーナーシップに対する最新のチェック ポイント。なければnull。
• differs_from_source —— チェックポイントのテキストがソースと食い違うときにtrue。問題ではなく観察結果 です。進捗の保存は元の契約を変更せず、完了を確立することもありません。

進捗テキストは240文字に制限されます（truncatedフラグ付き）。全文はwork show KEYと session show SESSIONで確認してください。

問題が起きたとき

• 不確かな保存レスポンス → host status --key REQUEST_KEYを確認。host recoverは検査済みの保留中の 操作にのみ使用。
• リビジョンコンフリクト → statusで現在のproject_revisionを読み、それで再試行。
• 疑わしいチェックポイント → session show SESSIONで完全なレコードを読む。完了領収書のない中断された 保存はリカバリーチェックポイントではありません。

より多くの障害パターンはトラブルシューティングを、このルーチンの語彙は コンセプトを参照してください。