방금 두 번째 Claude Code 에이전트를 실행했다. 이제 문제가 생겼다.

첫 번째 에이전트는 리팩토링 중이다. 두 번째는 같은 파일 일부를 건드리는 기능을 만들어야 한다. 서로의 존재를 모른다. 당신은 라우터이자 상태 저장소이자 충돌 해결자이고, 유일한 도구는 터미널 창 사이에서 컨텍스트를 복사-붙여넣기하는 것뿐이다.

대부분의 개발자가 Claude Code에서 벽에 부딪히는 지점이 바로 여기다. 에이전트의 코딩 능력이 부족해서가 아니다. 무엇을 작업할지 알려주는 시스템이 없기 때문이다.

복사-붙여넣기 문제

대부분의 Claude Code 워크플로우는 같은 방식으로 시작된다. 머릿속에 (혹은 Jira나 GitHub issue에) 태스크가 있고, 에이전트 프롬프트에 설명을 붙여넣는다. "인증 플로우 만들어." "페이지네이션 버그 고쳐." "다크 모드 지원 추가해."

에이전트 하나로는 잘 작동한다. 에이전트가 전체 컨텍스트를 갖고 있고, 출력을 감시할 수 있으며, 화면을 보고 있으니 완료 시점도 안다.

두 번째 에이전트를 추가하면 균열이 즉시 나타난다.

에이전트 A가 API 레이어를 리팩토링하고 있다. 에이전트 B가 새 엔드포인트를 만들고 있다. 둘 다 server/routes.ts를 건드린다. 서로의 변경사항을 모른다. 한쪽이 push하고 다른 쪽의 작업이 깨질 때 충돌을 발견한다. 더 나쁜 경우, 둘 다 로컬에서는 성공하지만 머지 결과가 어떤 diff에도 나타나지 않는 방식으로 깨진다.

근본 원인은 에이전트가 대충 일해서가 아니다. 공유 상태가 없기 때문이다. "에이전트 A가 API 리팩토링을 담당한다"가 기록된 곳이 없다. "라우트 파일이 수정 중이니 순서를 기다려라"는 상태도 없다. 에이전트들은 전체 그림에 대한 인식 없이 개별 프롬프트로 작동한다.

세 번째 에이전트를 추가하면 코딩보다 조율에 더 많은 시간을 쓰게 된다.

에이전트가 태스크 시스템에 실제로 필요한 것

도구를 찾기 전에 물어볼 가치가 있다: Claude Code 에이전트가 좋은 작업을 하려면 실제로 무엇이 필요한가?

놀라울 정도로 적다.

고유 식별자. 커밋과 코멘트에서 참조할 수 있는 것. "버그 수정함"은 멀티 에이전트 로그에서 쓸모없다. "PROJ-47 완료: 필터 뷰에서 페이지네이션이 잘못된 카운트 반환"은 추적 가능하다.

명확한 범위. 제목, 설명, 수락 기준. 소설이 아닌, 페르소나가 있는 유저 스토리가 아닌, "완료"가 어떤 모습인지에 대한 구체적 진술. "/users 엔드포인트는 페이지네이션된 결과를 반환한다. 페이지 크기 기본값은 25. next_cursor 필드는 마지막 페이지에서 null."

업데이트할 수 있는 상태. 에이전트는 자신이 어디에 있는지 신호를 보낼 수 있어야 한다: 클레임됨, 진행 중, 완료. 이것 없이는 터미널 창을 들여다보며 추측하는 것으로 되돌아간다.

의존성 인식. "PROJ-46이 머지될 때까지 이것을 시작하지 마라"는 가장 흔한 멀티 에이전트 실패를 방지한다: 아직 존재하지 않는 코드 위에 구축하는 것.

이 리스트에 없는 것을 주목하라. 스프린트 계획. 벨로시티 추적. 칸반 보드. 스토리 포인트. 색깔별 라벨이 있는 에픽. 에이전트에게 프로젝트 관리 극장은 필요 없다. 태스크, 상태, "완료"라고 말하는 방법이면 된다.

CLAUDE.md 계약

태스크 시스템은 에이전트에게 무엇을 할지 알려준다. CLAUDE.md 파일은 어떻게 할지 알려준다.

여러 Claude Code 에이전트를 실행하고 있다면, 각각 정체성과 경계를 정의하는 CLAUDE.md가 있어야 한다. 이것은 선택적 설정이 아니다. 협조하는 에이전트와 서로 밟는 에이전트의 차이 그 자체다.

엔지니어링 에이전트를 위한 간략화된 예시:

## Identity

Engineer for the project. You implement features, fix bugs,
and write tests. You own implementation quality.

## What You Own

- All files under `components/` and `lib/`
- Unit tests in `__tests__/`
- You may read but not modify files under `server/`

## What You Don't Own

- Deployment configuration (that's ops)
- Issue triage and prioritization (that's the coordinator)
- QA validation (QA tests your work independently)

## Completion Protocol

Before marking any task done:
1. Run the full test suite: `pnpm test`
2. Verify your change works manually
3. Comment what you did with the commit hash
4. Push before reporting completion

경계 섹션이 하중을 견디는 부분이다. 명시적 파일 소유권 없이는 에이전트가 이탈한다. 엔지니어링 에이전트가 "도움이 되려고" 배포 설정을 리팩토링한다. QA 에이전트가 테스트 대신 테스트 대상 코드를 변경해서 테스트를 "수정"한다. 명시적 경계가 이런 실패 모드를 방지한다.

완료 프로토콜도 똑같이 중요하다. 가장 흔한 에이전트 실패를 방지한다: 단지 컴파일만 되는데 완료를 선언하는 것. "전체 테스트 스위트 실행"과 "수동 검증"은 구체적인 게이트다. 이 프로토콜을 따르는 에이전트는 사람이 신뢰할 수 있는 결과물을 만든다. 없는 에이전트는 한 줄 한 줄 재확인해야 하는 결과물을 만든다.

이것을 여러 에이전트에 걸쳐 확장하면 각 멤버가 자기 레인, 인수인계 프로토콜, "완료"의 의미를 아는 플릿을 얻는다.

CLI-first 태스크 관리

워크플로우에 관한 관찰인데, 내재화하는 데 생각보다 오래 걸렸다: Claude Code 에이전트는 GUI 인터페이스보다 CLI 도구와 함께 극적으로 더 잘 작동한다.

생각해보면 당연하다. Claude Code 에이전트는 터미널에 산다. 명령을 실행하고, 출력을 읽고, 결과에 따라 행동을 취할 수 있다. 웹 UI를 탐색하고, 버튼을 클릭하고, 렌더링된 페이지를 해석하라고 요구하는 것은 에이전트의 자연스러운 인터페이스에 역행하는 것이다.

CLI 기반 태스크 시스템은 에이전트가 단일 흐름으로 이것을 수행할 수 있음을 의미한다:

# Read the task
task show PROJ-47

# Claim it
task update PROJ-47 --status in_progress --assignee agent-1

# Do the work...

# Report completion
task comment PROJ-47 "DONE: Fixed pagination. Commit: abc1234"
task update PROJ-47 --status done

컨텍스트 전환 없음. 브라우저 창 없음. 칸반 보드 스크린샷 없음. 에이전트가 태스크를 읽고, 작업하고, 상태를 업데이트한다. 모두 작업 환경을 벗어나지 않고.

출력도 기계 판독 가능하다. 에이전트 전체에서 무슨 일이 일어나고 있는지 확인해야 할 때 쿼리할 수 있다:

task list --status in_progress    # What's being worked on?
task list --assignee agent-2      # What is agent-2 doing?
task list --blocked               # What's stuck?

이것이 작동하는 도구의 형태다. 에이전트의 언어를 말하는 CLI.

Beads: 에이전트를 위한 로컬 퍼스트 이슈 트래킹

위에서 설명한 워크플로우는 가설이 아니다. beads를 사용해서 매일 실행하고 있는 것이다. beads는 정확히 이런 종류의 에이전트 주도 개발을 위해 만들어진 오픈소스 로컬 퍼스트 이슈 트래커다.

beads는 이슈("beads"라 불림)를 코드베이스와 함께 로컬 Dolt 데이터베이스에 저장한다. 각 bead에는 ID, 제목, 설명, 상태, 우선순위, 의존성, 코멘트 스레드가 있다. CLI는 bd라 불리며, 에이전트가 태스크를 읽고, 상태를 업데이트하고, 구조화된 코멘트를 남기기 위해 사용하는 인터페이스다.

실제 워크플로우다. 태스크를 생성한다:

bd create --title "Fix pagination on filtered views" \
  --description "The /users endpoint returns wrong count when filters are applied. Page size defaults to 25. next_cursor should be null on the last page." \
  --priority p2

에이전트가 클레임한다:

bd update bb-r3k2 --claim --actor eng1
bd update bb-r3k2 --status in_progress

코드를 작성하기 전에, 에이전트가 계획을 코멘트한다:

bd comments add bb-r3k2 --author eng1 "PLAN:
1. Fix count query in /users to apply filters before COUNT()
2. Add cursor boundary check for last page
3. Add test cases for filtered pagination

Files:
- server/routes/users.ts - fix count query
- server/routes/users.test.ts - add filtered pagination tests"

이것은 체크포인트다. 계획이 잘못되었으면 45분 후 나쁜 구현을 발견하는 대신 30초 만에 잡을 수 있다.

에이전트가 작업하고, 테스트를 실행하고, 완료를 코멘트한다:

bd comments add bb-r3k2 --author eng1 "DONE: Fixed filtered pagination count.

- COUNT() now applies the same WHERE clause as the data query
- next_cursor returns null when offset + page_size >= total_count
- Added 4 test cases covering filtered + unfiltered pagination

Commit: a1b2c3d"

bd update bb-r3k2 --status ready_for_qa

태스크에는 이제 완전한 감사 추적이 있다: 무엇이 요청되었는지, 에이전트가 무엇을 계획했는지, 실제로 무엇을 했는지, 리뷰할 커밋 해시. QA를 실행하는 두 번째 에이전트가 이를 가져가서 독립적으로 검증할 수 있다.

이것이 작동하는 이유는 beads가 에이전트와 같은 언어를 말하기 때문이다. 모든 것이 CLI 명령이다. 모든 것이 구조화된 출력을 생성한다. 도구와 에이전트 사이에 임피던스 불일치가 없다.

전체 그림 보기

CLI 워크플로우는 에이전트 3~4개까지 확장되고, 거기서 새로운 천장에 도달한다. 도구의 천장이 아니라 인지적 천장이다.

에이전트 5개에서 bd list를 실행하고 프로젝트 상태를 머릿속으로 조립하는 것은 스프레드시트를 읽으며 의존성 그래프를 머릿속에 유지하려는 것과 같다. 어떤 태스크가 블로킹되어 있나? 어떤 에이전트가 20분간 상태를 업데이트하지 않았나? 기능 에픽이 60% 완료인가 80% 완료인가? 정보는 모두 CLI 출력에 있지만, 조립하는 데 필요한 노력이 에이전트가 추가될 때마다 누적된다.

여기에 Beadbox가 들어맞는다. beads 위에 위치하는 실시간 대시보드로, 전체 에이전트 플릿의 상태를 보여준다. 시각적으로 렌더링된 의존성 트리. 에픽 진행률 바. 다섯 개의 bd show 명령을 실행하지 않고도 스캔할 수 있는 에이전트 코멘트 스레드.

Beadbox는 CLI를 대체하지 않는다. 에이전트들은 여전히 모든 것에 bd를 사용한다. Beadbox는 전체 그림이 필요할 때 여는 레이어다: 어떤 워크스트림이 움직이고, 어떤 것이 멈춰있고, 병목은 어디인지. beads 데이터베이스의 변경을 감시하고 실시간으로 업데이트되므로, 오래된 데이터를 볼 일이 없다.

베타 기간 동안 무료이며 완전히 로컬 머신에서 실행된다. 계정 없음, 클라우드 없음, 데이터는 로컬에 유지된다.

시작하기

구조화된 태스크 관리에서 가치를 얻기 위해 에이전트 13개가 필요하지 않다. Claude Code 에이전트 2개와 규칙 하나로 시작하라: 모든 태스크에 bead를 만들고, 모든 에이전트는 코딩 전에 계획을 코멘트하고, 모든 완료에 검증 단계를 포함한다.

이 패턴은 복리로 작용한다. 에이전트에 공유 태스크 시스템이 갖춰지면, 작업을 독립적으로 검증하는 QA 에이전트를 추가할 수 있다. 우선순위 큐에서 태스크를 디스패치하는 코디네이터를 추가할 수 있다. 조율 오버헤드가 선형으로 증가하지 않으면서 5, 10, 15 에이전트로 확장할 수 있다. 이전에는 수동 컨텍스트 전환이었던 것을 프로토콜이 처리하기 때문이다.

도구:

beads 로컬 퍼스트 태스크 관리. 오픈 소스.
Claude Code 에이전트 런타임.
Beadbox 플릿이 커질 때 시각적 감시.

이런 워크플로우를 구축하고 있다면, GitHub에서 Beadbox에 스타를 달아주세요.

Claude Code Agent 태스크 관리 방법