서론

본 기사는 다음의 미러입니다.

AI 코드 에이전트 (AI code agent)를 사용하면서 다음과 같은 경험을 한 적이 없으신가요?

• 처음에는 순조롭게 작업하고 있었는데, 도중에 다른 문제를 발견하여 원래 작업이 어디까지 진행되었는지 알 수 없게 된다.
• 설계 방침을 몇 번이나 설명했을 텐데, 다른 세션에서 재개하면 이전 전제로 돌아가 있다.
• 테스트는 실행된 것처럼 보이지만, 해당 프로젝트에서 정말로 필요한 검증 커맨드 (command)가 아니다.
• 리뷰에서 지적된 내용이 수정되었는지, 미대응인지, 기각되었는지 채팅 속에 파묻혀 버린다.
• 이전에 주의를 주었던 사항을 다음 세션에서 또 반복한다.
• "완료했습니다"라고 말했지만, 어떤 요구사항을 충족했는지, 어떤 커맨드로 검증되었는지, 어떤 파일이 변경되었는지, 어떤 리뷰 지적이 닫혔는지 추적할 수 없다.

이러한 문제는 코드 에이전트 (code agent)를 규모가 큰 프로젝트에서 사용하기 시작하면 나타납니다.

크고 복잡한 프로젝트에서는 작업 상태 그 자체가 복잡해집니다.

설계, 요구사항, 태스크 (task), 리뷰, 검증, 커맨드 (command), Git 상태, 사용자로부터의 수정 지시, 도중에 발생한 중단 작업 등이 얽히게 됩니다.

인간 사이의 개발에서도 이러한 정보는 Issue, Pull Request, 설계 문서, CI, 리뷰 코멘트, 커밋 히스토리 (commit history) 등에 분산되어 관리됩니다.

코드 에이전트에게 큰 작업을 맡길 때도, 본래는 이와 동일하게 작업 상태를 관리할 장소가 필요합니다.

그렇다면 작업 상태를 Markdown으로 관리하면 되지 않을까 하는 생각도 있습니다.

실제로 TASKS.md나 AGENT.md, WORKLOG.md와 같은 파일을 만들어 그곳에 작업 상태를 적고 있는 분들도 있을 것입니다.

이는 작게 시작하기에는 편리합니다.

인간도 읽기 쉽고, Git으로 차이(diff)도 추적할 수 있습니다.

하지만 큰 프로젝트에서 코드 에이전트에게 지속적으로 작업을 시키면 Markdown만으로는 힘들어집니다.

파일이 거대해지면 에이전트가 전체를 매번 올바르게 파악할 수 없게 됩니다.

• 어떤 기술이 최신인가.
• 어떤 태스크 (task)가 완료되었는가.
• 어떤 리뷰 지적이 미결 상태인가.
• 어떤 설계 판단이 현재도 유효한가.
• 어떤 검증 커맨드 (command)가 실제로 실행되었는가.
• 어떤 주의사항이 이미 규칙화되었는가.

이것들이 하나의 긴 Markdown에 뒤섞이면 상태 관리라기보다 거대한 메모가 됩니다.

최악의 경우, 에이전트가 grep으로 그럴싸한 문자열을 집어내어, 오래된 상태와 새로운 상태를 섞어서 해석합니다.

시계열(chronology)도 무너집니다.

• "이 지적은 나중에 해결되었는가"
• "이 설계 판단은 취소되었는가"
• "이 테스트 결과는 어떤 커밋 (commit)에 대한 것인가"
• "이 메모는 중단 전의 상태인가, 재개 후의 상태인가"
• "이 주의사항은 일회성 코멘트인가, 앞으로도 지켜야 할 규칙인가"

이런 것들이 모호해집니다.

크고 복잡한 프로젝트에서 코드 에이전트를 사용한다면, 작업 상태를 구조화하여 시계열로 추적할 수 있고, 필요한 관점별로 추출할 수 있는 장부가 필요합니다.

그래서 코드 에이전트의 작업 상태를 프로젝트 측에 구조화하여 남기기 위한 도구로서 agent-workbench를 만들었습니다.

리포지토리 (repository)는 여기입니다.

문서 (Docs)는 여기입니다.

agent-workbench란

agent-workbench는 코드 에이전트용 작업 장부입니다.

크고 복잡한 프로젝트에서 코드 에이전트가 긴 작업을 진행하기 위한 운용 레이어 (operation layer)로서 만들었습니다.

인간을 위한 태스크 관리 (task management) 도구가 아닙니다.

Trello나 GitHub Issues를 대신해 사용하는 것도 아닙니다.

목적은 코드 에이전트가 프로젝트 내에서 작업할 때, 현재의 작업 상태, 설계, 리뷰, 검증, 증거, 사용자의 수정 지시를 구조화하여 참조할 수 있도록 하는 것입니다.

프로젝트에는 다음과 같은 디렉토리가 생성됩니다.

.agent-workbench/
ledger.sqlite
designs/
...

중심이 되는 것은 .agent-workbench/ledger.sqlite입니다.

이는 프로젝트 로컬의 SQLite 장부입니다.

여기에 작업 단위, 설계 패키지, 태스크 (task), 체크리스트, 리뷰, 지적, 검증 결과, 커맨드 (command) 실행, Git 커밋 (commit), 변경 파일, 사용자의 수정 지시, KPT 등을 기록합니다.

즉, 에이전트가 '현재의 대화'나 '거대한 Markdown'뿐만 아니라, '프로젝트에 남겨진 구조화된 작업 상태'를 보고 움직일 수 있도록 하기 위한 것입니다.

왜 필요한가

큰 작업은 채팅만으로는 관리할 수 없다

코드 에이전트 (Code Agent)에게 맡기고 싶은 작업은 단순한 파일 편집만이 아닙니다.

예를 들어, 다음과 같은 작업이 있습니다.

- 기존 설계를 파악하기
- 사양(Specification)이나 제약 사항을 정리하기
- 구현 방침을 결정하기
...

이러한 작업에서는 중간의 판단이 후속 작업에 영향을 미칩니다.

• 어떤 설계 판단이 유효한가.
• 어떤 요구사항이 어떤 태스크 (Task)에 대응하고 있는가.
• 어떤 테스트를 실행해야 하는가.
• 어떤 리뷰 지적 사항이 아직 남아 있는가.
• 어떤 변경 사항이 이번 작업에 포함되어야 하는가.

이것들을 채팅 이력만으로 관리하면, 작업이 길어질수록 불안정해집니다.

에이전트가 문맥 (Context)을 놓치는 경우도 있습니다.

사람 측에서도 어디에 무엇을 적었는지 추적하는 것이 힘들어집니다.

agent-workbench에서는 이 상태를 채팅이 아닌 프로젝트 측에 남깁니다.

Markdown 관리는 거대해지면 파손되기 쉽다

작업 상태를 Markdown으로 관리하는 방법은 여러분도 자주 사용하고 계실 것입니다.

- TODO를 Markdown에 작성하기
- 작업 로그를 Markdown에 남기기
- 설계 판단을 Markdown에 추가하기
...

사람이 읽기만 한다면 그것만으로도 충분할 때가 있습니다.

하지만 코드 에이전트에게 지속적으로 사용하게 하는 상태 관리로서는 한계가 있습니다.

먼저, 파일이 커집니다.

커진 Markdown을 에이전트가 매번 올바르게 읽는다는 보장이 없습니다.

컨텍스트 (Context)에 다 들어가지 못하는 경우도 있습니다.

필요한 부분만 골라내려다 오래된 정보를 가져오는 경우도 있습니다.

다음으로, 시계열 (Timeline)이 깨지기 쉽습니다.

Markdown은 기본적으로 문서입니다.

추가, 편집, 이동, 삭제를 반복하면 '언제 상태인지', '어떤 변경에 의해 상태가 바뀌었는지'가 모호해집니다.

또한, 상태의 종류가 섞입니다.

태스크 목록, 설계 판단, 검증 로그, 리뷰 지적, 사용자 수정, 작업 메모가 하나의 파일에 섞이면, 에이전트는 그것을 상태로서 다루는 것이 아니라 문장으로서 검색합니다.

최악의 경우, grep으로 그럴싸한 행을 찾아내어 시계열도 상태 전이 (State Transition)도 무시하고 판단합니다.

이는 큰 프로젝트에서는 위험합니다.

agent-workbench에서는 작업 상태의 진실의 원천 (Source of Truth)을 SQLite 장부에 둡니다.

작업 단위, 리뷰 지적, 검증 결과, 커맨드 (Command) 실행, 완료 판정, 사용자 수정, KPT 등은 구조화된 레코드 (Record)로 취급합니다.

에이전트가 작업을 마음대로 전환한다

큰 프로젝트에서는 작업 중에 다른 문제가 발견되는 경우가 자주 있습니다.

• 문서를 업데이트하다가 CLI의 동작이 이상하다는 것을 깨닫는다.
• 구현을 하다가 기존 테스트의 전제가 깨져 있다는 것을 깨닫는다.
• 리뷰 중에 다른 모듈의 설계 누락을 발견한다.

이러한 중단 자체는 나쁜 것이 아닙니다.

문제는 원래 작업이 어디서 멈췄는지, 왜 멈췄는지, 돌아가기 전에 무엇을 확인해야 하는지가 모호해지는 것입니다.

코드 에이전트는 눈앞의 문제로 나아가 버리는 경우가 있습니다.

그 사이에 컨텍스트 압축 (Context Compression) 등이 들어가면 원래 문제를 잊어버리는 경우가 많습니다.

그 결과, 원래 작업이 방치됩니다.

agent-workbench에서는 작업 단위를 워크 유닛 (Work Unit)으로 취급합니다.

워크 유닛에는 active, suspended, blocked, closed, reopened, follow-up 등의 상태가 있습니다.

또한, 활성화 스택 (Activation Stack)을 통해 현재 작업, 중단, 복귀를 기록합니다.

예를 들어 다음과 같은 흐름입니다.

docs work가 active
↓
release wrapper의 문제가 발견됨
...

단순히 '나중에 돌아온다'라고 채팅이나 Markdown에 쓰는 것이 아니라, 작업 상태로서 중단과 복귀를 관리합니다.

설계와 구현이 어긋난다

큰 프로젝트에서는 설계와 구현의 대응 관계가 중요합니다.

코드 에이전트에게 설계 문서를 전달하여 구현하게 할 수는 있습니다.

다만, 자유 형식의 설계 메모만으로는 무엇이 요구사항이고, 무엇이 제약 사항이며, 무엇이 결정된 설계 판단인지가 모호해집니다.

그 결과, 에이전트는 "그럴듯한 구현"을 합니다.

하지만 그 구현이 어떤 요구사항 (requirements)을 충족하고 있는지, 어떤 설계 판단 (decisions)을 따르고 있는지, 어떤 검증 (validation)을 통해 확인되었는지 추적할 수 없다면 대규모 프로젝트에서는 위험합니다.

agent-workbench에서는 Design Package라는 형태로 설계 재료를 구조화합니다.

Design Package에는 사람이 읽기 위한 설계 설명뿐만 아니라, requirements, decisions, validation gate templates 등과 같은 기계 판독 가능한 (machine-readable) 정보를 포함합니다.

요구사항에는 REQ-001과 같은 안정적인 키 (key)를 부여합니다.

설계 판단에는 DEC-001과 같은 키를 부여합니다.

검증 조건은 validation gate로 정의합니다.

이를 통해 설계, 태스크 (task), 체크리스트 (checklist), 구현 증거 (implementation evidence), 검증 결과 (validation results), 리뷰 결과 (review results)를 서로 연결할 수 있도록 합니다.

검증 명령어를 추측하는 문제

대규모 프로젝트에서는 올바른 검증 명령어가 단순하지 않은 경우가 많습니다.

cargo test만으로는 부족하여 feature flag가 필요하거나,

특정 workspace member만을 대상으로 해야 하거나,

npm test가 아니라 pnpm test를 사용해야 할 수도 있습니다.

일반적인 테스트보다 Docs 생성이나 release wrapper의 검증이 더 중요한 경우도 있습니다.

코드 에이전트는 흔히 쓰이는 명령어를 추측하여 실행하는 경향이 있습니다.

그리고 잘못된 명령어를 실행했음에도 "테스트했습니다"라고 보고하는 경우가 있습니다.

이는 대규모 프로젝트에서 상당히 위험합니다.

agent-workbench에서는 command profile을 기록할 수 있습니다.

고정된 검증 명령어, 권장 명령어, 비권장 명령어, 실행 결과, 일탈 이유 등을 대장 (ledger)에 남길 수 있습니다.

에이전트는 작업 전에 command profile을 확인하여 프로젝트에서 사용해야 할 검증 명령어를 선택합니다.

검증 결과는 command usage나 validation gate run으로 기록합니다.

이를 통해 "어떤 명령어를 실행했는지", "그 결과는 어떠했는지", "어떤 요구사항의 검증 증거인지"를 추적할 수 있게 됩니다.

리뷰 지적 사항이 흘러가 버리는 문제

규모가 큰 작업은 리뷰가 한 번에 끝나지 않습니다.

• 설계 리뷰 (design review)
• 태스크 분해 리뷰 (task decomposition review)
• 구현 리뷰 (implementation review)
• 설계와 구현의 차이 리뷰 (diff review)
• 기정 지적 사항이 수정되었는지 확인

이 모든 것을 채팅이나 Markdown으로 처리하면 어떤 지적 사항이 아직 남아 있는지 파악하기 어려워집니다.

• 지적 사항이 수정되었는가?
• 수정은 되었으나 검증은 아직인가?
• 기각되었는가?
• 다른 지적 사항으로 파생되었는가?

agent-workbench에서는 review plan, review run, finding, closure, verification을 구분하여 다룹니다.

리뷰에서 나온 지적 사항을 finding으로 기록하고, 수정하면 closure를 기록하며, 필요에 따라 verification을 남깁니다.

리뷰를 단순한 "코멘트"가 아니라 작업 상태 (work state)로 취급하기 위한 메커니즘입니다.

같은 지적을 반복하는 문제

코드 에이전트를 사용하다 보면 비슷한 주의 사항을 몇 번이고 반복해야 할 때가 있습니다.

• 이 프로젝트에서는 이 테스트 명령어를 사용한다.
• 이 디렉토리는 직접 편집하지 않는다.
• 이 리뷰 관점을 반드시 확인한다.
• 이 형식으로 로그를 남긴다.
• 이 구현 방침은 채택하지 않는다.

이러한 지적 사항들이 채팅창 안에만 남아 있으면, 다음 세션에서 또다시 같은 실수를 반복할 가능성이 있습니다.

리뷰 지적 사항도 마찬가지입니다.

한 번 수정했을 터인 문제가 다른 태스크에서 다시 발생할 수 있습니다.

agent-workbench에서는 사용자 수정 사항이나 KPT를 기록할 수 있습니다.

그때뿐인 코멘트로 흘려보내는 것이 아니라, 다음 작업에서 참조할 수 있는 형태로 만듭니다.

예를 들어, Keep, Problem, Try로 정리함으로써 무엇을 지속할지, 무엇이 문제인지, 다음에 무엇을 시도해야 할지를 남길 수 있습니다.

또한 반복적으로 발생하는 지적 사항은 단순한 리뷰 코멘트가 아니라 규칙 (rule)이나 command profile, 체크리스트로 승격시킬 수 있습니다.

이를 통해 에이전트가 같은 실수를 반복하지 않도록 합니다.

"전에도 말했던 것"을 채팅 이력에서 찾는 것이 아니라, 프로젝트의 대장에 남겨 작업 전에 확인하게 하는 것이 목적입니다.

완료 보고에 증거가 없음

코드 에이전트는 작업이 끝난 것처럼 보이면 "완료했습니다"라고 말하기 쉽습니다.

하지만 큰 프로젝트에서는 자연어(Natural Language)로 된 완료 보고만으로는 부족합니다.

- 태스크(Task)가 닫혀 있는가
- 리뷰 지적 사항이 남아 있지 않은가
- 검증 명령어가 실행되었는가
...

이러한 것들을 확인할 수 없는 상태에서 "완료"되었다는 말을 들어도, 결국 인간 측에서 전부 확인하게 됩니다.

agent-workbench에서는 close-ready gate를 준비하고 있습니다.

close-ready는 작업을 종료해도 되는지 확인하기 위한 준비 단계(Readiness Gate)입니다.

태스크, 체크리스트, 리뷰, 지적 사항, 검증 명령어, repository state, work record 등을 확인하고, 부족함이 있다면 차단(Block)합니다.

즉, 에이전트가 "완료했습니다"라고 말하기 전에, 완료 조건을 구조적으로 확인하게 만드는 메커니즘입니다.

agent-workbench로 해결하는 것

agent-workbench가 해결하고자 하는 것은 코드 에이전트의 작업을 "그 자리의 채팅"이나 "거대한 Markdown"에서 "프로젝트의 작업 상태"로 옮기는 것입니다.

• 에이전트가 작업을 시작하기 전에 현재 상태를 확인한다.
• 작업 중에 설계 판단이나 검증 결과를 기록한다.
• 중단(Interrupt)이 발생하면 중단 이유와 복귀 조건을 남긴다.
• 리뷰 지적이 나오면 지적, 수정, 검증을 추적한다.
• 사용자 수정 사항이나 KPT를 남겨 동일한 지적을 반복하지 않도록 한다.
• 완료 전에 증거가 갖춰져 있는지 확인한다.

이를 자연어 메모만으로 수행하는 것이 아니라, CLI와 SQLite 대장(Ledger)을 통해 구조화합니다.

대략적으로 다음과 같은 것들을 다룹니다.

- 작업 단위
- 중단과 복귀
- 설계 패키지 (Design Package)
...

이를 통해 에이전트가 "다음에 무엇을 해야 하는지"를 채팅의 분위기나 grep 결과가 아닌, 대장을 통해 판단할 수 있도록 합니다.

사용법

agent-workbench는 기본적으로 인간이 CLI를 직접 입력하는 것이 아니라, 코드 에이전트에게 사용하도록 하는 것을 상정합니다.

인간은 에이전트에게 "무엇을 해주길 원하는지"와 "agent-workbench를 사용하여 상태 관리를 해주길 원하는 것"을 지시합니다.

여기서는 프로젝트 초기 상태부터 사용하는 경우와 기존 프로젝트에 도입하는 경우로 나눕니다.

설치

agent-workbench는 Agent Skill로서 설치합니다.

사용자 단위로 설치하는 경우는 다음과 같습니다.

gh skill install MuNeNiCK/agent-workbench agent-workbench \
--scope user \
--agent <target-agent>

프로젝트 단위로 설치하는 경우는 다음과 같습니다.

gh skill install MuNeNiCK/agent-workbench agent-workbench \
--scope project \
--agent <target-agent>

<target-agent>에는 이용 중인 코드 에이전트에 대응하는 값을 지정합니다.

프로젝트 초기 상태부터 사용하는 경우

신규 프로젝트나 아직 설계가 확정되지 않은 단계부터 사용하는 경우에는 곧바로 구현하게 하지 않습니다.

흐름은 다음과 같습니다.

1. agent-workbench를 초기화한다
2. 설계 메모 또는 설계서를 작성한다
3. 설계 메모를 Design Package로 가져온다
...

먼저 에이전트에게 다음과 같이 지시합니다.

이 프로젝트에서 $agent-workbench 를 사용할 수 있도록 초기화해 주세요.
초기화 후, 현재 상태, 다음에 필요한 작업, 이용 가능한 워크플로우를 보고해 주세요.

그다음 설계를 에이전트에게 전달합니다.
이미 설계를 작성한 경우에는 그것을 전달합니다.

다음 설계 메모를 바탕으로 이 프로젝트의 설계를 정리해 주세요.
아직 구현에는 들어가지 마세요.
요구사항, 제약 사항, 설계 판단, 검증 방침, 불명확한 점을 나누어 정리해 주세요.
...

또는 에이전트와 상담하며 설계를 만드는 경우에는 다음과 같이 의뢰합니다.

$agent-workbench 를 사용하여 이 프로젝트의 설계를 함께 정리해 주세요.
먼저 목적, 요구사항, 제약 사항, 설계 판단, 검증 방법을 도출해 주세요.
불명확한 점이 있다면 임의로 결정하지 말고 확인해 주세요.

...

설계 메모 또는 설계서가 완성되면, agent-workbench에 입력시킵니다.

지금까지 정리한 설계를 $agent-workbench 가 이해할 수 있는 Design Package로서 입력해 주세요.
요구사항, 설계 판단, 검증 게이트 (Verification Gate)를 구조화해 주세요.
입력 후, Design Package로서 부족한 정보, 모호한 점, 확인이 필요한 점을 보고해 주세요.

입력 후, 설계 리뷰 (Design Review)를 수행하게 합니다.

$agent-workbench 를 사용하여 설계 리뷰를 실행해 주세요.
요구사항 누락, 설계 판단의 모순, 검증 방침의 부족, 구현 전에 해결해야 할 블로커 (Blocker)가 없는지 확인해 주세요.
리뷰 결과는 대장에 기록해 주세요.

설계 리뷰에서 문제가 없다면, 설계를 close 시킵니다.

설계 리뷰 결과를 확인하고, 설계를 close할 수 있는지 판단해 주세요.
close할 수 없는 경우에는 미결된 지적 사항과 다음에 필요한 수정을 보고해 주세요.
close할 수 있는 경우에는 $agent-workbench 상에서 설계를 close해 주세요.

설계가 close되면, 태스크 분해 (Task Decomposition)로 진행합니다.

close된 설계를 바탕으로, $agent-workbench 에서 구현 태스크와 체크리스트로 분해해 주세요.
각 태스크가 어떤 요구사항에 대응하는지, 어떤 검증 게이트에서 확인하는지도 연결해 주세요.
아직 구현 단계로 넘어가지는 마세요.

태스크 분해 리뷰를 수행하게 합니다.

$agent-workbench 를 사용하여 태스크 분해 리뷰를 실행해 주세요.
설계 요구사항이 태스크와 체크리스트에 누락 없이 반영되었는지,
검증 게이트와의 대응이 이루어지고 있는지,
...

구현을 진행할 수 있는지 확인합니다.

$agent-workbench 의 implementation-ready 상태를 확인해 주세요.
구현을 진행할 수 없는 경우에는 블로커와 필요한 대응을 보고해 주세요.
구현을 진행할 수 있는 경우에는 구현 대상 태스크, 검증 방법, 주의해야 할 설계 판단을 정리한 후 구현을 시작해 주세요.

구현 중에는 검증 커맨드(Command)나 변경 내용을 기록하게 합니다.

$agent-workbench 의 현재 태스크에 따라 구현해 주세요.
실행한 커맨드, 검증 결과, 변경한 파일, 설계 요구사항과의 대응을 대장에 기록해 주세요.
테스트 커맨드는 추측하지 말고, 등록된 command profile을 확인한 후 실행해 주세요.

구현 중 주의했던 점이나, 동일한 지적을 반복하지 않았으면 하는 내용이 발생했을 경우에는 사용자 수정 (User Correction) 또는 KPT로서 기록하게 합니다.

지금의 지적 사항을 $agent-workbench 에 사용자 수정으로서 기록해 주세요.
향후 동일한 지적을 반복하지 않도록 적용 범위, 피해야 할 행동, 다음에 확인해야 할 내용을 정리해 주세요.
필요하다면 KPT에도 반영해 주세요.

완료 전에는 close-ready 상태를 확인하게 합니다.

구현이 완료되었다고 생각되더라도, 아직 작업을 close하지 마세요.
$agent-workbench 의 close-ready 상태를 확인하여,
미완료 태스크, 미결된 리뷰 지적 사항, 검증 부족, 변경 파일, Git 상태, 블로커, 기록해야 할 사용자 수정 또는 KPT가 남아 있지 않은지 보고해 주세요.
...

기존 프로젝트에 도입하는 경우

기존 프로젝트에 도입하는 경우에는 먼저 현재 상태를 점검(Inventory)합니다.

이미 코드, 설계 메모, Issue, README, 테스트, CI 등이 존재하기 때문에, 갑자기 새로운 설계를 만드는 것이 아니라 현재 프로젝트 상태를 대장에 입력하는 것부터 시작합니다.

흐름은 다음과 같습니다.

1. agent-workbench를 초기화한다
2. 기존의 설계·README·Issue·테스트·CI를 조사한다
3. 현재 상태를 Design Package 또는 work unit로서 정리한다
...

가장 먼저, 에이전트에게 다음과 같이 지시합니다.

가장 먼저, 에이전트에게 다음과 같이 지시합니다.

이 기존 프로젝트에 $agent-workbench 를 도입해 주세요.
먼저 대장(Ledger)을 초기화하고, 현재 리포지토리 상태, 기존 문서, 테스트 방법, CI, 미완료 작업의 유무를 조사해 주세요.
아직 구현이나 수정에는 들어가지 마세요.

기존 상태를 조사하게 합니다.

$agent-workbench 를 사용하여, 이 프로젝트의 현재 상태를 정리(Inventory)해 주세요.
README, docs, Issue에 해당하는 메모, 테스트 명령, CI 설정, 기존의 설계 판단, 미완료로 보이는 작업을 확인하고,
대장에 등록해야 할 항목을 정리해 주세요.

검증 명령을 등록하게 합니다.

이 프로젝트에서 사용해야 할 검증 명령을 조사하여, $agent-workbench 의 command profile에 등록해 주세요.
권장 명령, 피해야 할 명령, 용도별 검증 명령을 구분해 주세요.
추측으로 등록하지 말고, README, CI 설정, package 설정, 기존 스크립트를 확인해 주세요.

기존의 주의사항이나 반복하고 싶지 않은 지적 사항을 등록하게 합니다.

이 프로젝트에서 향후 반복하고 싶지 않은 지적 사항이나, 준수해야 할 주의사항을 정리하여,
$agent-workbench 에 사용자 수정(User Correction) 또는 KPT로서 등록해 주세요.
대상 범위, 피해야 할 행동, 향후 확인해야 할 내용을 구분해 주세요.

기존 설계를 Design Package화하게 합니다.

기존의 설계 정보를 정리하고, 필요하다면 $agent-workbench 의 Design Package로 가져와 주세요.
요구사항, 제약 조건, 설계 판단, 검증 게이트(Verification Gate)를 구분하여 정리해 주세요.
불명확한 점이나 설계가 모호한 부분은 임의로 보완하지 말고 확인 사항으로서 보고해 주세요.

기존의 미완료 작업을 work unit으로 만듭니다.

현재 프로젝트에서 미완료되었거나 진행 중으로 보이는 작업을 나열하고,
$agent-workbench 의 work unit으로 등록해 주세요.
각 work unit에 대해 목적, 현재 상태, 블로커(Blocker), 다음에 필요한 작업을 기록해 주세요.

기존 프로젝트에서 작업을 재개하는 경우에는, 가장 먼저 상태를 보고하게 합니다.

$agent-workbench 를 사용하여, 현재 상태를 확인해 주세요.
active한 work unit, suspended한 work unit, 미해결 리뷰 지적 사항, 등록된 command profile,
사용자 수정, KPT, 현재 Git 상태, 다음에 취해야 할 작업을 보고해 주세요.
...

구현으로 나아가기 전에는, implementation-ready를 확인하게 합니다.

이 작업을 구현으로 진행해도 될지, $agent-workbench 의 implementation-ready를 확인해 주세요.
부족한 설계, 미해결된 지적 사항, 검증 명령 미등록, 리포지토리 상태의 문제가 있다면 보고해 주세요.
문제가 없다면, 대상 태스크와 검증 방법을 명시한 후 구현으로 진행해 주세요.

완료 전에는, 반드시 close-ready를 거칩니다.

작업을 완료 처리하기 전에, $agent-workbench 의 close-ready를 확인해 주세요.
미완료 태스크, 미해결 리뷰 지적 사항, 검증 부족, 변경된 파일, Git 상태, 블로커,
기록해야 할 사용자 수정이나 KPT가 남아 있지 않은지 보고해 주세요.
...

주요 개념

Ledger

ledger는 프로젝트 로컬 SQLite 대장입니다.

.agent-workbench/ledger.sqlite

여기에 작업 상태, 설계, 리뷰, 검증, 증거 등을 기록합니다.

Markdown이나 채팅이 아니라, 구조화된 대장을 신뢰할 수 있는 단일 원천(Source of Truth)으로 만드는 것이 포인트입니다.

Work unit

work unit은 에이전트가 수행하는 작업 단위입니다.

예를 들어 다음과 같은 것들이 있습니다.

- release workflow를 구현한다
- public docs를 재구성한다
- 설계 패키지를 작성한다
...

work unit은 active, suspended, blocked, closed, reopened, follow-up 등의 상태를 가집니다.
이를 통해 작업이 현재 어떤 상태인지 추적할 수 있습니다.

Activation stack

activation stack은 중단과 복귀를 다루기 위한 메커니즘입니다.

예를 들어, 다음과 같은 흐름을 기록합니다.

docs work가 active
↓
release wrapper issue가 발견됨
...

resume-ready gate를 통해 설계 상태, 리뷰 상태, repository state, 전제 조건이 변경되지 않았는지 확인합니다.

Design Package

Design Package는 설계 재료를 agent-workbench가 다루기 쉬운 형태로 구조화한 것입니다.

처음부터 전용 형식으로 작성할 필요는 없습니다.

원천이 되는 것은 일반적인 설계 메모든, Markdown 설계서든, txt든, 대화하며 정리한 내용이든 상관없습니다.

중요한 것은 그 설계 재료를 그대로 거대한 메모로 취급하는 것이 아니라, agent-workbench가 추적할 수 있는 형태로 가져오는 것입니다.

Design Package로 가져오면 설계에 포함된 정보를 다음과 같이 나누어 다룰 수 있습니다.

- 요구사항 (Requirements)
- 제약 사항 (Constraints)
- 설계 결정 (Design Decisions)
...

요구사항은 REQ-001과 같은 키를 가집니다.

설계 결정은 DEC-001과 같은 키를 가집니다.

이를 통해 구현 태스크, 체크리스트, 검증 게이트, 리뷰, 구현 증거를 설계 요구사항에 연결할 수 있습니다.

단순히 "설계를 읽고 구현해"가 아니라, "이 요구사항을 이 태스크로 구현하고, 이 검증을 통해 충족했다"라고 말할 수 있는 상태로 만들기 위한 메커니즘입니다.

Readiness gate

readiness gate는 작업을 다음 단계로 진행해도 되는지 확인하기 위한 메커니즘입니다.

대표적인 gate는 다음과 같습니다.

gate는 기본적으로 read-only입니다.