AWR
GitHub
한국어
English中文Españolहिन्दीPortuguêsРусский日本語한국어DeutschFrançais

빠른 시작

GitHub에서 소스 보기

이 워크스루는 AWR을 새로 설치하는 시점부터 검증된 세션 핸드오프까지 안내합니다: CLI를 설치하고, 프로젝트를 초기화하고, 작업 세션을 시작하고, 후속 세션이 첫 세션이 멈춘 지점에서 이어받을 수 있음을 증명합니다. 모든 것이 복사-붙여넣기로 실행 가능하며, AWR은 자체 SQLite를 번들로 포함합니다.

1. AWR 설치

AWR은 npm과 PyPI에서 네이티브 패키지로 배포됩니다. 두 채널 모두 동일한 Rust CLI(awr)와 MCP 서버(awr-mcp)를 설치하며, 별도의 JavaScript나 Python SDK는 없습니다.

npm 사용 시(Node 22.14 이상 필요):

npm install -g @originoneai/agent-work-runtime@0.5.1

또는 pip 사용 시, 가상 환경 안에서(Python 3.9 이상 필요):

python -m pip install agent-work-runtime==0.5.1

두 실행 파일을 확인합니다:

awr --version
awr-mcp --version

지원 플랫폼은 macOS 15+(arm64 및 Intel x64), glibc 2.39 이상의 Linux x64 및 arm64(Ubuntu 24.04 기준선), 그리고 Windows x64입니다. Linux에서는 먼저 glibc를 확인하세요:

ldd --version | head -n 1

npm 설치의 경우 선택적 의존성을 활성화한 상태로 유지하세요 — 런처가 플랫폼별 네이티브 패키지를 해석합니다. 설치 스크립트나 네트워크 다운로더는 없으며, pip 휠은 바이너리를 내장합니다. 애플리케이션 작성자를 위한 세 번째 채널도 있습니다: 호스트 앱이 내장할 수 있는 두 바이너리의 고정된 네이티브 페이로드로, 이 경우 사용자는 런타임에 Node, Python, Rust가 전혀 필요 없습니다.

2. 프로젝트 초기화

초기화는 두 단계 작업입니다: 미리보기, 그다음 명시적 승인입니다. --accept를 전달하기 전까지는 아무것도 기록되지 않습니다.

AWR_PROJECT=/absolute/path/to/your/project
awr --project "$AWR_PROJECT" init

미리보기를 읽으세요: AWR이 찾은 인벤토리 — 기존 Markdown 작업 레저, YAML 소스, 목표 — 와 제안하는 소스 매핑을 보여줍니다. 기존 파일은 절대 덮어쓰지 않으며, 원본 문서가 권위 있는 원본으로 남습니다. 미리보기가 올바르다면 승인합니다:

awr --project "$AWR_PROJECT" init --accept

빈 프로젝트라면 목적을 미리 명시하세요:

awr --project "$AWR_PROJECT" init --goal "Deliver a document portal" --accept

Markdown 레저가 비표준 상태 단어를 사용한다면 초기화 시점에 매핑하세요:

awr --project "$AWR_PROJECT" init \
  --status-map pending=planned --status-map complete=completed --accept

그다음 조직화 보고서를 확인합니다:

awr --project "$AWR_PROJECT" intake inspect --json

보고서의 organization.state는 현재 상태를 알려줍니다: ready는 최소 하나의 작업이 소스에 선언된 목표, 인수 기준, 다음 액션, 해결된 선행 조건을 갖추었다는 뜻입니다. needs_organization은 무언가 누락되었다는 뜻이며 — 보고서의 정렬된 actions가 소스 파일에 무엇을 추가해야 하는지 알려줍니다.

3. 작업 세션 시작

세션은 AWR의 작업 소유권 단위입니다. 이 명령들은 모든 호출에 프로젝트 경로와 JSON 출력을 실어주는 작은 셸 헬퍼를 사용합니다:

AWR_BIN=$(command -v awr)
AWR_WORK=INTAKE-001          # a task key from your intake report
AWR_AGENT=agent-primary      # a label for who is working
AWR_MODEL=your-current-model # a recorded label; AWR does not invoke the model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

실행 가능한 것을 확인한 다음, 클레임(작업 항목에 대한 런타임 소유권)과 현재 프로젝트 리비전으로 세션을 시작합니다:

awrj ready
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")

작업 컨텍스트를 컴파일합니다 — 목표, 인수 기준, 기록된 사실, 이력이 제한된 패킷으로 조립됩니다:

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가 발생하면 --budget을 늘리고, SourceStale이 발생하면 awrj 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"

체크포인트는 미완료 작업도 기록할 수 있습니다; 테스트 통과나 인수 기준 충족의 증명이 아닙니다.

5. 새 세션에서 작업 계속하기

계속하기가 작동함을 증명하려면, 첫 번째 세션을 종료하고 그것으로부터 재개하세요 — 새 에이전트, 머신, 호스트 대화가 사용할 것과 동일한 인계 경로입니다. 종료는 클레임을 해제합니다; 소스 작업을 완료로 표시하지는 않습니다:

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

이제 재개합니다. 어떤 에이전트든 — 다른 에이전트이거나, 나중의 같은 에이전트이거나 — 이전 세션으로부터 후속 세션을 만듭니다:

AWR_PREDECESSOR="$AWR_SESSION"
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent successor --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")

두 가지 확인으로 핸드오프가 작동했음을 검증합니다:

  • jq -e '.context_ready'가 0으로 종료: 후속 세션이 마지막 성공 체크포인트를 포함하여 이전 세션의 기록된 컨텍스트를 받았습니다.
  • 재개된 세션은 새 ID를 가집니다 — 재개는 기존 세션을 변경하는 것이 아니라 새 AWR 세션을 생성합니다.

언제든지 복구 상태를 읽기 전용으로 확인할 수도 있습니다:

awrj recovery inspect --session "$AWR_SESSION"

코딩 에이전트의 채팅 안에서 작업 중이라면? 호스트 대화를 AWR 세션에 바인딩하여 체크포인트가 호스트 컴팩션에서도 살아남게 하세요:

awrj client bind --client generic --external-session "myhost:$HOST_CONVERSATION_ID" \
  --work "$AWR_WORK" --session "$AWR_SESSION"

AWR은 호스트의 프로세스 메모리를 전송하거나 임의의 기존 프로세스를 인수하지 않습니다 — 연속성은 명시적으로 기록된 것에서 나옵니다.

다음 단계