Pullboard가 에이전트 협업을 위한 명세 기반 개발 도구 공개

Pullboard는 에이전트가 승인된 명세에 따라 작업하고 서로의 결과를 검증하도록 돕는 소프트웨어 개발 도구다. Git 저장소 안에서 작동하며 계정이나 별도 의존성이 필요 없고, 자체적으로 모델을 호출하지 않는다. 제작팀은 정량 시스템 개발에 Pullboard를 사용한다고 밝혔다.

Pullboard는 진행 상황 확인, 질문 답변, 변경 승인 등을 한 보드에서 처리하는 협업 대기열이다. 에이전트는 서로 다른 작업 레인에서 일하고, 다른 에이전트가 요구사항에 맞춰 결과를 확인하기 전까지 작업은 완료로 처리되지 않는다. 사람은 판단과 승인을 맡고, 에이전트는 합의한 명세에 따라 작업한다.

철학과 핵심 개념

Pullboard는 사용자가 규칙을 정하고 판단을 맡는 구조를 지향한다. 저장소의 개발 규칙인 Doctrine을 정하면 에이전트가 이를 따르고, Spec을 기준으로 코드를 만든 뒤 검증 결과를 남긴다.

Pullboard의 기본 요소는 다섯 가지다.

• Items는 작업 항목이다. 각 항목에는 검증 기준이 있으며 한 번에 한 에이전트만 맡는다.
• Shouts는 에이전트 간 의사소통 방식이다. 질문은 지휘 체계를 따라 올라가고, 사용자에게는 사용자 판단이 필요한 요청만 전달된다.
• Spec은 요구사항별 한 행으로 구성되는 계획이다. 사용자가 승인한 행만 작업 기준으로 인정된다.
• Doctrine은 저장소의 규칙이다. 각 규칙은 Git 훅이나 리뷰 등으로 적용한다.
• Activity는 작업 배정, 제출, 거부, 승인 등 모든 기록을 순서대로 남긴다.

Pullboard는 에이전트가 작업을 끝냈다고 보고했지만 실제로는 완료되지 않은 문제를 다른 에이전트의 검증으로 다루고, 결정 사항은 대화가 끝난 채팅이 아니라 명세에 보관한다. 에이전트마다 별도의 워크트리와 레인을 제공해 같은 파일을 동시에 수정하는 상황을 막는다. 작업 제출 전에는 테스트가 통과해야 한다.

작동 방식

승인된 SPEC.md 행은 에이전트가 작업을 맡는 순간 고정되는 계약이다. 저장소의 규칙은 DOCTRINE.md에 두며, 기계적으로 확인할 수 있는 규칙은 훅으로 적용한다. 각 에이전트는 자기 워크트리에서 일하고, 작업 배정은 원자적으로 처리된다. 항목은 다른 항목이 끝날 때까지 대기할 수도 있다.

작업을 제출하려면 검증 게이트를 통과해야 한다. 이후 다른 에이전트가 정확히 같은 커밋을 확인한다. Pullboard는 이 과정을 Agentic Development Lifecycle(ADLC)이라고 부른다. 사용자가 만들 대상을 정하고, 에이전트가 구현과 교차 검증을 맡는 방식이다.

에이전트가 판단할 수 없는 문제가 생기면 질문을 올린다. 조정자 에이전트가 해결할 수 있는 문제는 처리하고, 사용자의 결정이 필요한 질문만 사용자에게 전달한다. 제작팀은 조정자 역할을 맡은 에이전트 한 명과 깊이 협업하고, 그 조정자가 나머지 작업 레인에 일을 나누며 사용자의 선호를 기록하는 방식을 권장한다.

Doctrine과 Spec

Spec이 만들 대상을 정한다면 Doctrine은 만드는 방법을 정한다. 예를 들어 Doctrine에는 “필요한 데이터만 보관한다”는 규칙을, Spec에는 “구매자가 한 단계로 카드 결제를 할 수 있다”는 요구사항을 둘 수 있다. 각 저장소에는 Pullboard의 기본 Doctrine이 적용되며, 사용자는 규칙을 추가하거나 덮어쓰거나 일부를 거부할 수 있다.

SPEC.md의 요구사항은 다음 형식으로 한 행씩 작성한다.

- <id> [<status>, <priority>] <what must be true> | gate: <what proves it>

예시는 다음과 같다.

- G1 [approved, must] A shopper can pay by card in one step. | gate: test/checkout.test.js

ID는 섹션 문자와 숫자로 구성된다. 행은 사용자가 승인하기 전까지 초안이며, 승인된 행만 유효한 기준으로 취급한다.

작업 기록과 보드

Pullboard 제작팀은 이 방식으로 제품을 만들며, 작업 항목 3개 중 거의 1개가 되돌아간다고 밝혔다. 다음은 거부와 재제출, 승인 기록의 한 예다.

#13  worktree prints a subagent's opening lines      REJECT  BEHAVIOR_MISMATCH  by tests-2              "the printed cd line double-quoted the token without escaping it;               copying it expanded the token away and exited 1"      resubmitted 85f0f5d      ACCEPT  CRITERION_MET  by tests-2              "runs the printed cd line with a conflicting value and reaches the               real target; removing either escape makes the test fail"

에이전트는 터미널에서 작업하고 사용자는 Pullboard View에서 진행 상황을 확인한다. 한 페이지에서 이 컴퓨터의 모든 프로젝트를 실시간으로 볼 수 있다. 보드에는 사용자 판단이 필요한 결정과 승인 대기 행, 멈춘 레인이 표시된다. 각 항목의 배정·제출·판정과 거부 사유를 타임라인에서 확인하고, 항목 추가나 질문 답변, 레인에 메시지 보내기, 레인 보류 등을 할 수 있다. 로컬 API v1을 제공하며 view --export 명령으로 다시 재생할 수 있는 정적 스냅샷을 내보낸다.

pullboard view

시작하기

사용하려면 Git과 Node 22.13 이상이 필요하다. 설치 후 체험 명령을 실행할 수 있다.

npm i -g pullboard
pullboard tour

체험은 임시 저장소에서 진행된다. 사용자가 빈 이름을 world로 인사하는 규칙을 승인하면 조정자 에이전트가 항목을 등록하고, 구현 에이전트가 기능을 만든다. 검증 에이전트는 빈 이름을 입력해 문제를 찾아 거부한다. 구현 에이전트가 수정과 테스트를 추가한 뒤, 검증 에이전트는 의도적으로 수정 사항이 실패하는지 확인하고 승인한다. 마지막으로 조정자 에이전트가 기록을 남기며 변경 사항을 병합한다.

저장소 초기화는 한 번만 하면 된다. init은 명세와 Doctrine, 에이전트 지침을 작성하고 훅과 보드를 설치한다. 생성된 파일을 커밋한 뒤 저장소에서 Claude Code를 열고 만들 대상을 말하면 해당 에이전트가 조정자 역할을 맡는다.

pullboard init
git add -A && git commit -m "chore(repo): set up pullboard"

수동 작업 흐름

조정자가 수행하는 각 단계는 저장소의 기본 체크아웃에서 직접 진행할 수도 있다. 먼저 SPEC.md에 요구사항을 적는다.

## G · Goals: what the client asked for
- G1 [approved, must] A shopper can pay by card in one step. | gate: test/checkout.test.js
- G2 [draft, aim] Saved carts follow a shopper across devices. | serves: G1

그다음 설정을 참고해 pullboard.json에서 검증 게이트와 레인을 정한다. 아래 명령은 G1을 기준으로 웹 체크아웃 작업을 등록한다.

pullboard add web "Checkout" --specs G1 --criterion "card payment takes one step"

항목을 등록한 뒤 에이전트가 맡으면 검증 기준이 고정된다. 다음 명령으로 웹 레인의 워크트리를 만들고 다음 작업을 맡은 뒤 제출할 수 있다.

pullboard worktree web
cd ../myapp-web-1
pullboard next
pullboard submit 1

구현 에이전트는 G1을 인용하는 feat(web): pay by card [G1] 형식으로 커밋하고, 게이트를 통과한 결과를 제출한다. 검증 레인에서도 워크트리를 만들고 검증 작업을 맡는다.

pullboard worktree review
cd ../myapp-review-1
pullboard next --verify
pullboard verify 1 accept --note "paid in one step; without the fix the test fails"

검증 에이전트는 해당 커밋을 체크아웃해 확인한 뒤 근거를 붙여 승인하거나 사유와 함께 거부한다.

에이전트 작업과 아키텍처

pullboard worktree는 레인용 워크트리를 만들고 하위 에이전트가 시작할 때 필요한 지침을 출력한다. pullboard resume은 재시작 후 에이전트가 맡은 항목과 메시지, 다음 단계를 이어가게 한다. pullboard next는 다른 에이전트가 맡지 않은 다음 항목을 가져온다. pullboard run은 가벼운 모델이 간단한 항목을 감독 없이 처리하게 한다. Claude Code에는 스킬을 제공하고, Codex 등 다른 도구는 AGENTS.md 또는 pullboard prompt <role>을 읽는다.

보드 전체는 사용자의 컴퓨터에 있는 .git 내부 파일 하나로 구성된다. 모든 상태 변경은 수명 주기 선언을 따른다. 항목은 상태 기계로 관리된다. 항목은 열린 상태에서 시작해 에이전트가 맡으면 진행 중이 된다. 에이전트가 응답하지 않으면 다시 열린다. 제출된 항목은 검증자가 승인해 검증 완료로 바꾸거나, 거부해 열린 상태로 되돌릴 때까지 제출 상태를 유지한다. 항목을 취소할 수 있는 사람은 조정자뿐이다. 선언에서 허용하지 않는 상태 변경은 보드가 거부한다.

상태 기계는 src/machine.js에 선언되어 있으며 명령어와 보기 화면, 문서가 모두 이 선언을 공유한다.

데이터와 저장소

데이터는 호스팅되지 않고 저장소 안에 보관된다. Spec, Doctrine, 설정은 코드와 함께 커밋하는 일반 파일이다. 보드는 .git 안의 SQLite 파일 하나로 저장되며 모든 워크트리가 공유하지만 커밋하지 않는다. 제출된 작업은 Git에 고정되므로 워크트리를 삭제해도 유지된다. pullboard export로 보드 전체를 백업할 수 있다.

pullboard.json에서 검증 게이트와 레인을 설정한다.

{
 "gate": "npm test",
 "lanes": {
 "web": { "owns": ["apps/web/"], "specs": ["G"] },
 "review": { "owns": [] }
 }
}

검증 게이트에는 npm test나 pytest처럼 코드의 유효성을 확인하는 명령을 지정한다. 게이트는 제출과 푸시 전에 실행된다. 각 레인은 경로와 Spec 섹션을 맡으며, 담당 레인 밖의 파일을 포함하는 커밋은 거부된다.

언어별로 적합한 게이트를 설정할 수 있다. &&로 여러 검사를 연결할 수도 있다.

목적과 한계

Pullboard는 장기간 진행되는 개발에서 여러 에이전트가 일관성을 유지하도록 만드는 도구다. 다만 워크트리 식별은 한 컴퓨터 안에서만 의미가 있으며 보안 경계가 아니다. --no-verify로 훅을 건너뛸 수 있지만, 푸시 전 게이트와 검증자가 보완 장치로 작동한다. CI는 Linux와 macOS에서 실행되며 Windows는 아직 테스트되지 않았다.

계획 중인 기능으로는 여러 기기와 휴대전화에서 보드를 실시간으로 보는 릴레이가 있다. 이 기능은 코드가 아니라 봉인된 기록을 전달할 예정이다. Pullboard View에 마일스톤과 남은 작업을 한눈에 보여주는 로드맵도 계획되어 있다.

문서에는 수명 주기, CLI JSON API, 저장 형식, RFC가 있다. Pullboard는 MIT License로 배포된다.