일상 워크플로

이 가이드는 AWR과 함께하는 반복 가능한 일상 루틴을 안내합니다: 프로젝트 상태를 확인하고, 태스크를 클레임하거나 재개하고, 진행 상황을 기록하고, 체크포인트를 저장하고, 핸드오프하여 여러분 — 또는 에이전트 — 이 정확히 중단된 지점에서 이어받을 수 있게 합니다.

시작하기 전에 프로젝트가 초기화되어 있고 기본 개념(작업 항목, 세션, 클레임, 체크포인트)을 알고 있는지 확인하세요 — 빠른 시작과 개념을 참조하세요. 같은 루틴이 MCP를 통해서도 작동합니다; MCP를 참조하세요.

버전에 대한 참고: 아래의 일부 기능(action 뷰와 work edit)은 현재 소스 트리를 반영하며 릴리스된 패키지에서는 활성화되지 않았을 수 있습니다. 설치된 버전이 무엇을 지원하는지 보려면 awr --help를 실행하세요.

1. 하루 시작: 다음 액션 찾기

다른 무엇보다 먼저 상태 확인을 실행하세요:

awr status

awr status와 MCP 도구 awr_project_status는 기본적으로 action 뷰(view="action")입니다. 열린 작업을 네 개의 큐로 구분하며, 큐당 최대 다섯 개의 항목과 정확한 전체 개수 및 생략된 개수를 보여줍니다:

반복 가능한 셀렉터로 선택을 좁힐 수 있습니다 — 교집합으로 적용됩니다:

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.revision이 아니라 session show의 최상위 project_revision을 사용하세요. 충돌 시에는 재시도 전에 그 사이의 변경 사항을 검사하세요.
• 체크포인트는 소스 기반의 다음 액션을 절대 다시 쓰지 않습니다. 계약을 변경하려면 권위 있는 소스를 편집하세요.

5. YAML을 직접 편집하지 않고 작은 필드 수정

소스 계획에 작은 수정이 필요할 때 — 예를 들어 소스는 "Draft the guide"라고 하는데 실제 다음 단계가 "Review the conclusion"인 경우 — 편집을 미리 봅니다:

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으로 전체 기록을 확인; 완료 영수증 없는 중단된 저장은 복구 체크포인트가 아님.

더 많은 실패 모드는 문제 해결을, 이 루틴의 용어는 개념을 참조하세요.