핵심 개념

AWR은 프로젝트의 작업 사실을 어떤 단일 에이전트 대화 밖에 보관하여, 작업이 컨텍스트 손실, 에이전트 교체, 재시작에서도 살아남게 합니다. 이 문서는 그 모델 뒤에 있는 다섯 가지 아이디어를 설명합니다; 빠른 시작의 명령들과 일상 워크플로의 루틴이 그다음 자연스럽게 읽힐 것입니다.

핵심 원칙: 소스 파일(레저, 계획)이 권위 있는 원본이며, 런타임이 저장하는 모든 것 — 세션, 클레임, 증적 — 은 그 사실들의 검증 가능한 프로젝션입니다. AWR은 누락된 의도를 지어내지 않으며, 대화 트랜스크립트가 기록된 사실을 대신하도록 허용하지 않습니다.

프로젝트 사실: 소스 레저

AWR의 소스 레저는 일반 프로젝트 파일에 보관하는 작은 작업 계약입니다: work-ledger.yaml 같은 YAML 레저이거나, AWR을 통해 읽기 전용으로 유지되고 원래 파일에서 편집되는 기존 Markdown 레저(*-ledger.md)입니다. 레저는 두 종류의 사실을 기록합니다:

목표(Goals) — 프로젝트가 달성하려는 것, 성공 기준과 함께. 목표는 불확실할 때 draft, candidate, needs_confirmation일 수 있고, 소스 자료나 사용자 지시로 뒷받침될 때 active 또는 confirmed입니다. AWR은 선언을 검사할 뿐, 목표가 사람이 의도한 것과 일치한다고 보증하지는 않습니다.
작업 항목(Work items) — 아래에서 설명하는 태스크들.

최소 레저는 다음과 같습니다:

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은 기존 파일을 절대 덮어쓰지 않으며, 검사(inspection)는 재구성 가능한 프로젝션 캐시만 갱신합니다 — 목표, 태스크 파일, 실행 상태는 건드리지 않습니다.

태스크: 작업 항목

작업 항목은 레저의 태스크 하나입니다. 핵심 필드는 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 같은 프로젝트 수준의 조직화 상태도 보고합니다. 일상적으로 가장 중요한 두 가지: ready는 최소 하나의 태스크가 소스에 선언된 목표, 인수 기준, 다음 액션, 해결된 선행 조건을 갖추었다는 뜻이고, awaiting_verification은 레저가 태스크들이 완료되었다고 말하지만 인수 보고서가 아직 모두 검증되지 않았다는 뜻입니다.

체크포인트와 세션

세션은 작업 항목에 대한 한 에이전트의 작업 연결입니다. 체크포인트는 그 세션이 어디에 있는지에 대한 영구 기록입니다: 지속된 다음 액션, 열린 루프, 그리고 실제 AWR 이벤트와 소스 델타 — 대화의 복사본이 아닙니다.

클라이언트 세션이 시작되거나 컴팩션 후 재개되면, AWR은 체크포인트로부터 구축된 복구 컨텍스트를 반환합니다. 턴이 멈추거나 끝날 때, 변경된 다음 액션과 열린 루프는 손실되기 전에 저장됩니다:

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

작업 변경이 없는 중복 이벤트는 체크포인트를 재사용하고, 진행 상황이 변경된 이어지는 턴은 새 체크포인트를 생성합니다. 하나의 정직한 경계: 이를 자동화하는 네이티브 훅 어댑터는 현재 Codex에만 설치됩니다. 다른 호스트는 L0 바인더(--client generic)를 사용하는데, 이는 훅을 설치하지 않고 호스트 대화를 활성 AWR 세션에 연결합니다. 어댑터는 트랜스크립트 본문을 절대 읽지 않습니다 — 모델이 말한 것이 아니라 여러분이 알려준 것을 기록합니다.

클레임과 핸드오프

클레임은 세션이 태스크를 실행하기 전에 보유하는 명시적 잠금입니다. AWR은 실행 전에 세션 클레임을 획득하도록 요구하며, 완료 시에도 이를 재확인합니다 — 이것이 두 에이전트가 같은 태스크를 몰래 작업하는 것을 방지하는 방법입니다.

핸드오프는 작업을 한 세션이나 클라이언트에서 후속자로 옮깁니다. 리비전 검사와 후속 전이를 포함하여 세션을 명시적으로 재개합니다:

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는 상태 보고서에서 별도의 카운트로 유지됩니다.

하나의 태스크, 처음부터 끝까지

위 레저의 검색 태스크로 전체를 연결해 봅시다:

사실. awr --project /absolute/project init --accept를 실행하면, search 목표와 search-api 작업 항목이 있는 레저가 권위 있는 원본이 됩니다.
태스크. 작업 항목이 인수 기준과 다음 액션을 담고 있으므로 프로젝트는 ready를 보고합니다.
세션과 클레임. 하나의 스냅샷에서 작업을 준비한 다음, 코드를 건드리기 전에 세션 클레임을 획득합니다:

   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에 대해 검증됨으로 보여줍니다.

다음 단계

빠른 시작 — 이 개념들을 처음으로 실행해 봅니다.
일상 워크플로 — 준비, 클레임, 체크포인트, 완료의 반복 루프.