← today i learned

Backlog.md 도입 검토

2026-07-13 · 검토 대상: MrLesk/Backlog.md v1.48.0 · 비교 기준: 현행 PLAN.md + 플랜 스킬 8개 체계 · 같은 날 후속 검토(§10)로 결론 갱신

"태스크를 마크다운 파일로 관리하는 전용 도구를 쓰면 어떨까"의 두 번째 검토다. 첫 번째(beads 반려)가 "마크다운을 버리고 DB 로 갈 이유가 없다"였다면, 이번 후보는 마크다운을 버리지 않는다. 그래서 질문이 한 단계 어려워진다: 진실원본이 똑같이 git 안의 마크다운이라면, 지금의 수제 PLAN.md 체계를 기성 도구로 바꿀 이유가 있는가.

1Backlog.md 는 무엇인가

Backlog.md 는 git 저장소 안에서 사람과 AI 에이전트가 협업하기 위한 마크다운 네이티브 태스크 매니저다. 태스크 하나가 backlog/tasks/ 아래 마크다운 파일 하나가 되고, CLI·터미널 칸반 보드·웹 UI·MCP 서버가 같은 파일들을 읽고 쓴다. 서버도 텔레메트리도 없는 로컬 우선 도구다.

디렉터리 구조와 태스크 파일은 이렇게 생겼다.

backlog/
├── tasks/          # 태스크 1건 = 파일 1개 ("task-12 - 제목.md")
├── drafts/         # 착수 전 보류 항목
├── docs/           # 프로젝트 문서
├── decisions/      # 설계 결정 기록 (ADR)
├── archive/        # 완료·취소 태스크 보관
└── config.yml      # statuses, autoCommit, zeroPaddedIds 등

---
id: task-12
status: In Progress
priority: high
milestone: MVP
dependencies: [task-5, task-8]
created: 2026-07-13
---
## Description        (배경·목표)
## Acceptance Criteria (체크박스 완료 조건)
## Implementation Plan (구현 전 승인용 계획)
## Implementation Notes(진행 기록)

설계 철학이 뚜렷하다: 에이전트 시대의 병목은 코드 작성이 아니라 사람의 주의(attention)이므로, 스펙 리뷰 → 구현 계획 승인 → 태스크별 코드 리뷰라는 체크포인트를 강제하고, 태스크 1건 = 컨텍스트 윈도 1개 = PR 1개로 diff 를 사람이 읽을 수 있는 크기로 유지한다. backlog init 은 CLAUDE.md / AGENTS.md 에 에이전트용 작업 지침을 주입해 주고, --plain 플래그와 MCP 리소스(backlog://workflow/*)로 에이전트가 태스크를 직접 조회·조작한다.

2비교 기준: 현행 PLAN.md 체계

비교 대상이 "맨손 마크다운"이 아니라는 점이 이 검토의 핵심 전제다. 현행 체계는 저장소마다 PLAN.md(또는 PLAN_*.md) 하나를 진실원본으로 두고, 그 위에 생산자·소비자로 분리된 스킬 8개가 수명주기 전체를 돌린다. 상세는 두 세션 플랜 파이프라인 페이지에 있고, 요약하면:

• 생산자 · /make-a-plan(문서 신규 작성), /add-plan(태스크 T-N 추가·아이디어 승격), /add-idea(보류 아이디어 I-N 기록)
• 소비자 · /next-plan(다음 착수 후보 보고), /follow-plan(순차: 구현 → 검증 → 커밋), /sub-follow-plan(워커 서브에이전트 위임), /parallel-plan(worktree 병렬 + ff-merge)
• 유지보수 · /cleanup-plan(완료 태스크를 ID + 한 줄 요약으로 압축, 완료 5건 이상이면 소비자 스킬이 자동 호출)

태스크에는 표준 필드(완료 조건 · 의존 · 범위 힌트 · 단독실행 · 접수일)와 상태 4종([ ] TODO / [→] IN_PROGRESS / [x] DONE / [!] BLOCKED)이 강제되고, T-N 은 플랜 전역에서 유일하게 증가하는 카운터다. 이 머신의 작업 디렉터리에만 PLAN 파일 16개가 이 규약으로 운영되고 있다.

3기능 대응 매핑

현행 체계의 요소를 하나씩 Backlog.md 로 옮겨 보면, 대부분이 1:1 로 대응된다. 이 대응표 자체가 이번 검토의 첫 발견이다: 현행 표준 필드 체계는 사실상 Backlog.md 의 frontmatter 를 산문형 마크다운으로 구현한 것이다. 완료 조건은 Acceptance Criteria, 의존은 dependencies, 접수일은 created, 아이디어 보류는 drafts 에 해당한다.

4도입하면 얻는 것

4-1. 병렬 편집 충돌의 구조적 해소

현행 체계의 가장 실재하는 마찰이다. /parallel-plan 은 여러 워커가 PLAN.md 를 동시에 못 건드리게 하려고 "워커는 메타 파일 수정 금지, 리드가 머지 단계에서 일괄 갱신, 충돌 시 append-only 해소" 규칙을 유지하고 있다. 태스크가 파일 하나씩이면 이 규칙 자체가 필요 없어진다. 각 워커가 자기 태스크 파일만 만지면 충돌 면적이 0 이고, checkActiveBranches 는 다른 worktree 브랜치에서 진행 중인 태스크의 상태까지 읽어 "이미 다른 브랜치에서 Done" 같은 오판을 막는다. 병렬 에이전트 운용에 정확히 맞춘 설계다.

4-2. 부분 조회로 컨텍스트 절약

현행은 소비자 스킬이 PLAN.md 전체를 읽는다. 완료 이력과 서사가 함께 읽히므로 파일이 크면 낭비가 생기고, 그래서 /cleanup-plan 압축이 존재한다. Backlog.md 는 task view --plain 이나 MCP 로 필요한 태스크만 가져온다. 다만 대칭 비용이 있다: 전체 그림이 필요할 때는 여러 번 질의해야 하고, 태스크 수십 건 규모에서는 파일 하나를 통째로 읽는 쪽이 오히려 싸다. 이 이득은 백로그가 수백 건으로 커질 때 실효가 생긴다.

4-3. 시각화가 공짜

칸반 TUI 와 웹 UI(드래그 앤 드롭, AC 체크박스 편집)가 그냥 따라온다. 현행에는 대응물이 없고 /next-plan 의 텍스트 보고가 전부다. 솔로 운용에서 필수는 아니지만, 진행 중 태스크가 여러 브랜치에 걸쳐 늘어나면 보드의 가치가 커진다.

4-4. 생태계 표준과의 호환

Claude Code 전용이 아니라 codex 등 다른 에이전트도 같은 MCP·CLI 로 붙는다. 지금은 플랜 규약이 스킬 프롬프트 안에만 존재해서, 다른 도구를 쓰는 순간 규약을 다시 가르쳐야 한다. 도구 중립적 태스크 계층이 생기는 셈이다.

4-5. 완료 이력의 보존 품질

/cleanup-plan 은 완료 태스크를 한 줄로 압축하면서 세부(검증 로그, 구현 노트)를 버린다. Backlog.md 는 완료 태스크 파일을 Implementation Notes 째로 archive/ 에 보관하므로, 압축과 보존이 양자택일이 아니게 된다.

5잃는 것과 리스크

5-1. 산문성의 상실 (가장 본질적)

PLAN.md 는 태스크 큐이기만 한 것이 아니다. "현재 상태" 단락의 산문 서사, 태스크 사이에 흐르는 맥락, 디자인 결정의 배경이 한 문서에 있고, 세션이 리셋된 에이전트가 파일 하나를 읽으면 프로젝트 전체의 서사를 복원한다. 이 저장소의 PLAN.md 가 좋은 예다: 27개 태스크의 이력이 "왜 SSG 를 안 쓰는지, 왜 리네임을 했는지"라는 이야기로 압축돼 있다. Backlog.md 로 가면 이것이 파일 30여 개로 흩어지고, 서사는 docs/ 에 따로 쓰지 않는 한 사라진다. 태스크 파편의 합은 이야기가 아니다.

5-2. 런타임 의존과 전 머신 전파

지금은 git 과 텍스트 에디터면 끝이다. 도입하면 모든 작업 머신에 Node/Bun 런타임과 backlog 바이너리가 필요하고, 부트스트랩 스크립트에 설치·버전 고정을 추가해 유지해야 한다. 이 머신에는 Node v22 가 있어 npm i -g backlog.md 한 줄이지만, 머신이 늘 때마다 이 한 줄도 같이 는다. MCP 로 쓰면 세션마다 상주 프로세스도 하나 더 생긴다.

5-3. 스킬 8개의 재작성

플랜 계열 스킬 전부가 "PLAN.md 를 읽고 쓴다"를 전제한다. 헬퍼 스크립트(plan-context.sh)의 번호 계산, 상태 표기 규칙, cleanup 압축 로직, parallel-plan 의 충돌 해소 규칙이 모두 도구 호출로 대체되거나 폐기돼야 한다. 없어지는 코드가 많다는 건 좋은 신호이기도 하지만(cleanup-plan 폐기, 충돌 규칙 폐기), 전환기의 재작성·재검증 비용은 실제로 크다.

5-4. 이중 체계 과도기

PLAN 파일 16개를 한 번에 옮길 수는 없으므로, 상당 기간 "backlog 저장소"와 "PLAN.md 저장소"가 공존한다. 스킬은 backlog/ 존재 여부로 자동 분기해야 하고(퍼블리시 스킬의 사내/사외 디스패처와 같은 패턴이라 선례는 있다), 그동안 두 규약의 미묘한 차이가 혼선을 만든다.

5-5. 전체 조망의 간접화

GitHub 웹에서 PLAN.md 는 문서 하나로 전체가 읽히고 diff 하나로 변경이 리뷰된다. Backlog.md 도 파일 단위 열람은 되지만, 전체 조망은 board export 산출물(사본)이나 로컬 보드를 거쳐야 한다. beads 의 "열람에 도구가 한 겹 낀다" 문제의 약한 버전이 남는 셈이다.

5-6. 도구 수명 리스크 (낮음)

개인 계정 소유 프로젝트라는 점은 beads 와 같지만, exit cost 가 다르다. 데이터가 순수 마크다운이므로 도구가 버려져도 파일은 그대로 남고, 스크립트로 언제든 PLAN.md 로 되돌릴 수 있다. 락인이 얕다는 것이 이 도구의 가장 좋은 안전 속성이다.

6전환 과정에서 예상되는 문제

실제로 도입한다고 가정했을 때 걸릴 지점들이다. 파일럿 전에 답을 정해 두어야 한다.

7beads 반려 논리와의 정합

plan-pipeline §9 에서 beads 를 반려한 근거가 이 후보에는 얼마나 적용되는지 대조하면, 이 검토의 위치가 정확해진다.

정리하면 Backlog.md 는 beads 반려 사유 넷 중 도구 쪽 결함 둘을 지웠고, 우리 쪽 사정 둘(규모, 전환 비용)은 도구가 지울 수 없는 것이다. 그래서 결론은 "반려"가 아니라 "대기"가 된다: 규모 사유가 사라지는 순간 남는 장애물은 전환 비용뿐이고, 그건 일회성이다.

8시나리오 비교와 권고

→ 이 섹션의 권고(D)는 §10 후속 검토에서 B(파일럿)로 갱신되었다.

권고: D 를 기본으로, 트리거가 오면 B 로. 판단의 축은 도구의 품질이 아니라(품질은 충분하다) 페인포인트의 실재다. 현행 체계에서 실제로 아픈 곳은 parallel-plan 의 PLAN 충돌 관리 하나인데, 이미 규칙으로 관리되고 있고 병렬 실행 자체가 아직 상시 운용이 아니다. 도구가 주는 나머지 구조화 이득은 표준 필드 체계로 이미 흡수했다(시나리오 C 가 완료 상태라는 것, 이것이 이번 검토의 두 번째 발견이다).

9재평가 트리거

다음 중 하나가 현실이 되면 이 결론을 다시 연다. beads 검토 때의 트리거와 같은 축이되, 이번에는 갈 곳이 정해져 있다.

• 병렬 상시화 · /parallel-plan 급 병렬 실행이 예외가 아니라 기본 운용이 되어, append-only 충돌 해소 규칙이 실제로 자주 발동할 때
• 규모 · 단일 저장소의 활성 백로그가 수백 건에 이르러 "다음 착수 가능"이 파일 훑기로 안 나올 때
• 도구 혼용 · Claude Code 외의 에이전트(codex 등)가 같은 백로그를 상시로 읽고 써야 할 때 (스킬 프롬프트 규약은 도구 경계를 못 넘는다)

트리거가 오면: 신규 저장소 1곳에 backlog init --task-prefix T 로 파일럿을 열고, /sub-follow-plan 하나만 backlog CLI 기반으로 개조해 한 사이클을 돌려 본 뒤 확대를 결정한다. 되돌리기는 쉽다. 파일은 어차피 마크다운이다.

한 줄로 줄이면: Backlog.md 는 "우리가 손으로 만든 것의 기성품"이라 언젠가 갈아탈 수 있는 좋은 후보지만, 기성품이 이기는 조건(병렬 상시화·수백 건 규모)이 아직 오지 않았다. 그 조건이 오면 이번에는 마크다운을 버릴 필요가 없다.

10후속 검토: 결론을 B(파일럿)로 옮긴다

2026-07-13 · 발행 직후 실사용자 리뷰와 추가 조사(스킬 본문 정독, CLI 문서 재확인, 운영 형태·멀티 repo 조사)를 반영한 후속 기록. §1-9 는 원형대로 두었다.

10-1. 트리거 목록이 놓친 진짜 트리거

§5-1 은 산문성 상실을 "가장 본질적" 손실로 놓았고, D(현상 유지) 권고는 그 위에 서 있었다. 그런데 실사용 관찰은 반대였다: 인간이 PLAN.md 를 실제로 읽지 않는다. 마크다운 파일을 뒤적이는 일은 인간에게 생각보다 크고, 산문 서사의 독자는 사실상 세션 리셋 후의 에이전트뿐이었다. 아무도 읽지 않는 산문은 §5-1 이 매긴 무게만큼 지킬 가치가 없다. 반대로 칸반 보드는 인간이 실제로 소비할 수 있는 형태의 전체 조망이다. "인간이 진실원본을 소비하지 못하고 있다"는 §9 의 세 트리거(병렬 상시화·규모·도구 혼용)보다 본질적인 트리거인데, 목록에 없었다.

10-2. 스킬 = 프론트엔드 유지, Backlog.md = 백엔드 교체

전환의 형태도 §5-3 이 가정한 "재작성"과 다르다는 것이 확인됐다. 사용자는 PLAN.md 를 직접 편집하지 않고 스킬을 통해서만 만진다. 즉 스킬 계층이 이미 저장소 추상화이고, 백엔드만 갈아끼우면 사용 패턴은 그대로다. 갈아끼울 지점도 정확히 한 곳이다: 생산자 스킬들이 "플랜 파일 탐색 + 다음 번호 계산"을 plan-context.sh 헬퍼 1회 호출로 해결하는데, 그 자리가 backlog CLI 호출로 치환되는 유일한 심(seam)이다.

CLI 문서(CLI-INSTRUCTIONS.md · ADVANCED-CONFIG.md) 기준으로 §3 매핑을 구체화하면:

더 중요한 발견은 스킬 쪽에 있다. 플랜 스킬 8종 본문(합계 443줄)의 상당 부분이 채번 규칙, 상태 표준, ID 표기 보존 같은 "도구 부재를 프롬프트로 보완하던 규칙"이다. 도구가 이를 구조적으로 보장하면 스킬은 재작성이 아니라 다이어트가 된다. 최대 수혜자는 /parallel-plan 이다: §4-1 이 최대 이득으로 꼽은 append-only 충돌 해소 규칙과 "워커의 메타 파일 수정 금지" 규칙이 통째로 사라진다.

10-3. 옮기는 김에 좋아지는 것들

• 검증의 기계화 · "AC 전 항목 체크 완료 = 커밋 가능"으로 follow-plan 의 검증 게이트를 기계적으로 정의할 수 있다.
• 워커 보고의 영속화 · 서브에이전트의 RESULT 블록(현행은 대화에서 휘발)을 태스크 파일의 Implementation Notes 에 남긴다.
• 우선순위 명시화 · 현행 PLAN 은 우선순위가 서술 순서에 암묵적으로만 있다. priority 필드로 next-plan 의 후보 산출이 추론이 아니라 조회가 된다.
• 서브태스크 · -p 로 부모 아래 분해. 현행은 T 번호 폭증이 무서워 큰 태스크를 안 쪼갰다.
• 다중 플랜 파일 정리 · PLAN_*.md 여러 개 + "최근 수정본" 휴리스틱이 단일 백로그 + 마일스톤/라벨로 정리된다.
• 미러 드리프트 감소 · 스킬이 CLI 기반이 되면 codex/gemini 미러에서 도구명 치환이 필요한 면적이 줄어든다.
• 인간 개입 채널 · 웹 보드에서 카드를 옮기는 것이 곧 파일 변경이라, 사람의 우선순위 조정이 에이전트에게 그대로 전달된다.

10-4. 운영 형태: tailnet 안에서, 인스턴스는 저장소당 하나

상시 보드 운영을 조사한 결과 세 가지가 확정됐다.

• Tailscale funnel(공개 노출)은 부적합. 메인테이너가 reverse-proxy base-path 요청을 거부하며 밝혔듯, backlog browser 는 의도적으로 무인증·로컬 단일 사용자 도구다(접속 가능 = 파일시스템 접근 권한자 전제). tailnet 내부 한정 tailscale serve 는 이 보안 모델과 어긋나지 않는다.
• 멀티 repo 단일 웹 UI 는 없다. 인스턴스 1개 = 프로젝트 1개. "backlog of backlogs" 는 요청은 있었으나 미구현이고, v1.38.0 의 BACKLOG_CWD 는 인스턴스가 바라볼 폴더를 바꿀 뿐이다. 우회는 저장소별 포트 + 링크 index 페이지. path-prefix 프록시는 #716 거부로 SPA 라우팅이 깨져 불가.
• 중앙 상시 보드는 "어느 클론을 보느냐" 문제가 있다. autoCommit 이 false 라 웹에서의 편집은 커밋·푸시 없이는 다른 머신에 전달되지 않는다. read-only 조망용으로 한정하거나, 보드 전용 클론에 pull 주기 + 자동 커밋을 붙이거나를 파일럿에서 정해야 한다.

10-5. 갱신된 권고

D(현상 유지)에서 B(파일럿)로 옮긴다. 도구가 이기는 조건은 이미 충족돼 있었고, §9 의 트리거 정의가 그것을 담지 못했을 뿐이다. 파일럿은 신규 또는 백로그가 얕은 저장소 1곳에서 열고(§6 의 ID 연속성 문제 회피), 스킬은 backlog/ 디렉터리 감지 dual-mode 로 개조한다. 산문 서사는 docs/ 문서로 분리 존치를 시도하되, 파일럿의 핵심 검증 질문은 "세션 리셋 후 docs 문서 + 태스크 frontmatter 만으로 재개가 되는가"다.

§8 의 한 줄을 갱신하면: 기성품이 이기는 조건은 이미 와 있었다. 다만 그 조건은 병렬도 규모도 아니라, 인간이 읽지 않는 진실원본이었다.