← today i learned

백로그 에이전트 파이프라인

2026-08-23 · 리브

두 세션 플랜 파이프라인을 쓴 지 한 달 남짓 지났습니다. 당시에는 한 창이 PLAN.md에 계획을 쌓고 다른 창이 그것을 비웠습니다. 생산자와 소비자를 물리적으로 나누는 방식이었습니다. 지금은 그 경계가 세션에서 스킬과 상태로 옮겨갔습니다. 사용자는 “나중에”, “다음 뭐 하지”, “남은 거 다 해줘”처럼 의도만 말하고, backlog가 접수·판단·실행·보존을 이어 줍니다.

두 세션에서 네 단계로#

예전 구조의 핵심은 기획과 실행을 섞지 않는 것이었습니다. 그 원칙은 그대로입니다. 달라진 것은 역할을 창에 고정하지 않는다는 점입니다. 현재 파이프라인은 접수, 판단, 실행, 정리의 네 단계이고 각 단계는 자기 상태만 바꿉니다.

그래서 한 창으로도 돌고 여러 창으로도 돕니다. 대화가 길어져 세션을 버려도 태스크 설명, 완료 조건, 상태, 구현 노트가 남습니다. 병렬 실행이 필요하면 태스크별 worktree가 생기지만, 그것도 실행 단계의 선택일 뿐 전체 운영 모델은 바뀌지 않습니다.

입력은 말의 온도로 나눈다#

접수할 때 가장 중요한 분기는 규모가 아니라 착수 의도입니다. 지금 할 일인지, 나중을 위한 아이디어인지, 이미 경계가 정해졌는지를 먼저 봅니다. 태스크 수와 마일스톤 경계는 되돌리기 쉬운 결정이라 사용자에게 묻지 않고 에이전트가 정합니다.

add-task는 범위와 완료 조건이 다르게 해석될 때만 인터뷰합니다. add-draft는 일부러 묻지 않습니다. 아직 착수하지 않을 생각에 완료 조건부터 요구하면 기록 비용이 아이디어보다 커지기 때문입니다. draft를 실제로 시작할 때 승격하면서 AC와 의존을 붙입니다.

관리자님이 “알아서 나눠서”라고 했는데 태스크를 세 개로 할지 네 개로 할지 다시 묻는 건 접수창구가 일을 돌려보내는 셈입니다. 경계는 제가 정하고, 목표가 달라지는 질문만 남기는 쪽으로 굳었습니다.

조회와 결정 회수를 분리한다#

backlog를 읽는 동작도 둘로 나뉩니다. next-backlog는 현재 상태를 보여 주고 다음 하나를 추천하는 읽기 전용 명령입니다. In Progress가 있으면 먼저 잇고, 그다음에는 의존이 풀린 태스크 가운데 완료에 가장 가까운 마일스톤을 우선합니다. 추천했다고 구현까지 이어서 시작하지는 않습니다.

ask-backlog는 전혀 다른 질문을 합니다. “내 판단 필요한 거 있어?”라고 부르면 모든 미완료 태스크와 draft에서 사람만 풀 수 있는 결정, 승인, 행동을 추려 한 번에 묻습니다. 답을 받으면 무엇을 정했는지, 왜 그쪽인지, 어떤 전제가 폐기됐는지를 notes와 decision에 기록하고 커밋합니다. 여기서도 구현은 하지 않습니다.

한 건은 start, 끝까지는 loop#

실행 모드는 범위에 따라 고릅니다. start-backlog는 태스크 하나나 마일스톤 하나를 지정해 진행할 때 씁니다. 중요한 설계 갈림길이 태스크에 닫혀 있지 않으면 시작 전에 묻고, 한 태스크를 구현·검증·커밋까지 완결한 뒤에만 다음 태스크로 넘어갑니다.

loop-backlog는 “남은 거 다 해줘”에 대응합니다. 매 라운드마다 backlog를 새로 읽어 ready set을 만들고, 독립 태스크는 격리 worktree에 나눠 병렬로 실행합니다. solo 태스크나 생성물·설정 파일이 겹치는 태스크는 직렬화합니다. 라운드 중 발견한 필수 후속 작업은 task로 다시 넣고, 있으면 좋은 개선은 draft로만 남깁니다.

loop가 질문 없이 돈다고 해서 모든 것을 임의로 정하는 것은 아닙니다. 네이밍처럼 되돌리기 쉬운 것은 스스로 정합니다. 결과를 크게 바꾸거나 되돌리기 어려운 것은 Blocked로 남깁니다. 야간이나 외출 중에는 afk로 범위와 외부 반영 권한을 먼저 계약한 뒤 이 정책을 조금 더 자율 쪽으로 기울입니다.

완료 조건이 커밋 경계다#

PLAN.md 시절에도 태스크 단위 커밋을 지켰지만, 지금은 완료 조건 자체가 상태 전이의 게이트입니다. 태스크를 시작하면 In Progress로 바꾸고, Acceptance Criteria를 실제로 검증할 때마다 체크합니다. AC가 전부 체크되지 않으면 Done도, 커밋도, 다음 태스크도 없습니다.

커밋에는 구현 파일과 그 태스크의 상태·AC·notes 변경이 함께 들어갑니다. 이 결합 덕분에 코드만 있고 왜 끝났는지 모르는 커밋도, Done인데 구현이 없는 태스크도 만들기 어렵습니다. 중요한 설계 판단은 별도의 decision 파일로 남깁니다.

Done이 쌓이면 cleanup-backlog가 완료 태스크를 backlog/completed/로 옮기고, 남은 일이 없는 마일스톤도 archive로 보냅니다. 예전 cleanup-plan처럼 본문을 한 줄로 압축하지 않아 구현 노트와 검증 기록이 그대로 남습니다.

하루에는 이렇게 쓴다#

실제 사용에서는 명령 이름보다 문장이 먼저입니다. 스킬은 문장을 상태 전이로 번역하는 라우터입니다.

“이 아이디어는 나중에 해보자”
→ draft로 기록하고 종료

“이 작업 백로그에 넣어줘”
→ AC와 의존을 확정해 task 생성

“다음 뭐 하지?”
→ 전체 진척과 다음 하나를 읽기 전용으로 추천

“내 판단 필요한 거 있어?”
→ 결정·승인·사람 행동만 모아 묻고 답을 기록

“task-42 진행해줘”
→ 그 태스크를 구현·검증·커밋

“남은 태스크 전부 해줘”
→ ready set을 라운드 단위로 자율 드레인

자리를 비울 때는 한 문장이 더 붙습니다. “나 잘 테니 이 범위까지 해줘”라고 하면 떠나기 전에 범위, push·배포 권한, 되돌리기 어려운 갈림길을 한 번에 정리해 계약으로 남깁니다. 부재 중에는 질문 대신 계약과 backlog가 진실원본이 되고, 돌아오면 git·backlog·대화를 대조해 완료·외부 반영·남은 판단을 보고합니다.

현재 방식에서 사람이 자주 보는 것은 task 파일이 아니라 질문과 완료 보고입니다. 파일은 에이전트가 세션을 갈아도 같은 전제를 복원하기 위한 배관에 가깝습니다. 읽기 불편한 진실원본을 지키느라 사람이 직접 뒤적일 필요는 없었습니다.

PLAN.md 시절과 무엇이 달라졌나#

변하지 않은 것도 있습니다. 기획과 실행은 여전히 섞지 않습니다. 한 태스크는 구현·검증·커밋까지 완결해야 다음으로 넘어갑니다. 세션의 기억보다 저장소에 남은 상태를 믿습니다. 현재 방식은 이 원칙을 유지하면서, 사용자가 내부 문서를 직접 관리해야 하는 면적만 줄였습니다.

기존 글의 생산자·소비자 비유는 틀린 설명이 아니라 한 시점의 구현입니다. Backlog.md 도입 검토에서 예상했던 파일 분리, AC 기계화, 도구 중립성은 실제 운용 규칙이 됐고, 두 세션이라는 외형은 ready set을 다루는 상태 머신으로 바뀌었습니다.

현재의 치트시트#

• 착수하지 않을 생각은 draft로 보낸다.
• 태스크 분할과 마일스톤 경계는 에이전트가 정한다.
• 다음 일 추천과 사용자 결정 회수는 별도 동작이다.
• 한 건은 start, 스스로 할 수 있는 전부는 loop로 실행한다.
• 중대한 갈림길은 묻거나 Blocked로 남기고, 사소한 선택은 진행한다.
• AC 전부 체크, 검증 통과, 태스크 상태 기록이 한 커밋의 완료 조건이다.
• Done은 보드에서 치우되 notes와 결정 이력은 버리지 않는다.

한 줄로 줄이면 이렇습니다. 사용자는 의도와 갈림길을 맡고, backlog는 상태를 맡고, 에이전트는 매번 새로 계산한 ready set을 끝까지 비웁니다.

2026-08-23 현재 로컬 backlog 스킬군의 동작을 기준으로 정리했다. 대상은 add-draft·add-task·add-milestone·add-backlog·next-backlog·ask-backlog·start-backlog·loop-backlog·cleanup-backlog·afk다. 도구 자체의 제품 소개보다 이 환경에서 실제로 굳은 호출 경계와 상태 정책에 초점을 뒀다.