subagent-driven-development의 ledger는 플랜별 작업 디렉토리인 .superpowers/sdd/<플랜명>/에 위치하는 progress.md라는 진행 대장입니다. 어떤 태스크가 끝났고, 어느 커밋 범위가 이에 대응하는지를 한 줄씩 기록해 나갑니다. 이 파일은 컨텍스트의 컴팩션 후에 컨트롤러가 현재 위치를 잃어버리고 완료된 태스크 목록 전체를 다시 실행하는 사고를 방지하기 위한 파일입니다.
이 글은 Skillselion(Claude Code, Codex, Cursor용 확장 기능을 실제 설치 수로 나열한 독립 디렉토리)이 obra/superpowers에서 공개된 SKILL.md (568행, 2026-10-12 조회), 포함 스크립트, v7.0.0의 릴리스 노트를 읽고 정리한 것입니다. 실제로 스킬을 구동하여 검증한 글은 아닙니다. 스킬 전체 흐름은 subagent-driven-development 스킬 설명 가이드에 정리되어 있으므로, 여기서는 ledger만 다룹니다.
얼마나 사용되는 스킬인가
skills.sh의 표시 기준, 2026-10-12 시점의 설치 수는 223,979건입니다. 같은 Superpowers에 포함된 executing-plans는 당일 기준으로 230,946건이었습니다. 리포지토리 obra/superpowers의 스타는 297,886개(GitHub API, 2026-10-12)이지만, 이는 리포지토리 전체의 수치이며 스킬 단독의 수치는 아닙니다. 라이선스는 MIT입니다.
게시 정보는 subagent-driven-development 스킬 게시 페이지에, 스킬 세트 전체 개요는 Superpowers 스킬 모음 가이드에 있습니다.
왜 대장이 필요한가
SKILL.md의 Setup 섹션은 이유를 한 문장으로 적고 있습니다.
Conversation memory does not survive compaction.
대화의 기억은 컴팩션을 거치며 남아있지 않습니다. 다음 문장에서는 현재 위치를 잃은 컨트롤러가 완료된 태스크 목록을 재디스패치한 실제 사례에 대해 언급하며, 관찰된 것 중 가장 큰 실패라고 말합니다. 그 위에 진행 상황은 todo뿐만 아니라 ledger 파일에도 기록하도록 지시하고 있습니다.
'대장을 기록하는 것은 번거롭다'는 변명도 스킬 후반부의 Common Rationalizations 표에서 미리 무효화하고 있습니다.
The ledger is what survives compaction.
컴팩션을 살아남는 것은 ledger 쪽이라는 내용입니다.
위치와 첫 줄 규칙
스킬 시작 시 bash scripts/sdd-workspace PLAN_FILE을 실행하면, 해당 플랜 전용 디렉토리의 절대 경로가 출력됩니다. 위치는 <repo-root>/.superpowers/sdd/ 아래에 있으며, 스크립트 주석에 따르면 플랜 파일의 베이스 이름별로 1개의 디렉토리가 있습니다. ledger, 태스크 브리프, 구현자 보고서, 검토용 패키지가 모두 여기에 들어갑니다.
.git/ 안에 두지 않는 이유도 주석에 적혀 있습니다. Claude Code는 .git/를 보호 경로로 취급하여 에이전트의 쓰기를 거부하기 때문에, 구현 서브 에이전트가 보고서를 작성할 수 없게 되기 때문입니다.
ledger의 첫 줄에는 어떤 플랜 파일의 대장인지 보여주는 식별 행을 작성합니다. 재개 시 판단은 이 행에서 시작됩니다.
- 1행이 자신의 플랜을 가리키면,
complete 행이 있는 태스크는 완료 처리하고 재디스패치하지 않습니다. complete 행이 없는 첫 번째 태스크부터 재개합니다.
- 마지막 행이 fix round의 태스크라면 수정 루프 중간이므로 다음 라운드부터 계속합니다.
- 1행이 다른 플랜을 가리키는 ledger나, 이전 경로인
.superpowers/sdd/progress.md에 남아있는 ledger는 다른 플랜의 진행 상황으로 간주하지 않고, 자신의 ledger를 새로 만듭니다.
같은 파일 이름의 플랜이 2개 있는 경우에 대비하여, 스크립트는 작업 디렉토리마다 plan-path라는 마커에 소유 플랜의 경로를 기록합니다. 충돌할 때는 부모 디렉토리 이름을 사용하고, 그래도 중복되면 순번으로 디렉토리 이름을 나눕니다.
ledger의 1행은 이렇게 보인다
작업 완료 시점과 사소한 지적 사항을 보류할 때의 형식은 다음과 같습니다.
Task <N>: complete (commits <base7>..<head7>, review clean)
Task <N>: complete (commits <base7>..<head7>, <K> parked)
Task <N>: minor (deferred): <one-liner>
SKILL.md의 Example Workflow에는 값이 채워진 예시도 실려 있습니다.
[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]
핵심은 complete 행과 fix round 행에 커밋 범위가 포함되어 있다는 것입니다(minor (deferred) 행에는 포함되지 않습니다). 컨트롤러의 기억이 사라져도, ledger에 기록된 커밋은 git 안에 남아 있습니다.
The ledger is your recovery map
trust the ledger and
git log
over your own recollection.
ledger는 복구용 지도이며, 컴팩션 후에는 자신의 기억보다 ledger와 git log를 신뢰하라는 지시입니다.
완료 행 외에도, 착수 전 플랜 충돌 스캔 표, 수정 라운드별 결과, 보류(parked)한 지적 사항, 그리고 Ruling 행이 작성됩니다. Ruling 행에는 무엇을 결정했는지, 왜 그렇게 결정했는지, 잘못되었을 경우 무엇을 잃게 되는지 세 가지를 남깁니다. 정확한 형식은 SKILL.md의 원문을 참조하십시오.
Every adjudication is a ledger entry
재정(裁定)은 반드시 ledger에 한 줄로 남습니다. 지적 사항을 조용히 버리는 것은 금지입니다.
컨트롤러가 멈춰 질문하는 네 가지 경우
이 스킬은 작업 사이에 사람에게 확인을 받지 않도록 설계되었습니다.
Do not pause to check in with your human partner between tasks.
플랜의 모순이나 모호함은 컨트롤러 자신이 재정하고, ledger에 기록하여 진행합니다. 잘못된 재정은 눈에 보이는 되돌림으로 끝날 수 있지만, 질문으로 멈춘 세션은 상대방에게 하루 전체를 잃게 할 수 있다는 것이 SKILL.md의 논리입니다.
그 위에서, 멈추는 조건은 네 가지로 한정됩니다.
Four things stop you, and only these
- 되돌릴 수 없는 작업 또는 파괴적인 작업
- 보안과 관련된 작업
- 이 worktree 외부로 미치는 부작용 중 사전에 확인하는 것이 일반적인 경우(merge, 공유 브랜치에 push, 공개)
- 어떤 진행 방식을 선택하든 추측일 수밖에 없을 정도로 망가진 플랜
멈추지 않는 설계와 함께 작동하는 것이 판단의 기록입니다. 종료 시, 컨트롤러는 ledger에서 Ruling:을 포함하는 모든 행을 모아 최종 메시지의 「Rulings I made」에 시간 순서대로 나열합니다. 개발자는 거기서 읽고 잘못된 판단만 다시 수행하면 됩니다.
git clean -fdx의 함정
Setup 절 끝에 짧은 경고가 있습니다.
git clean -fdx
will destroy the workspace (it's git-ignored scratch)
-x를 붙인 git clean은 무시된 파일도 삭제합니다. 작업 디렉토리는 .superpowers/sdd/.gitignore(기본 내용은 *)로 통째로 무시되고 있기 때문에, ledger도 브리프도 리포트도 함께 사라집니다. SKILL.md가 제시하는 복구 수단은 git log입니다.
여기부터는 SKILL.md에 쓰여 있지 않은, 필자의 해석입니다. 커밋은 git에 남아 있으므로 어느 정도까지 구현이 진행되었는지는 복원할 수 있습니다. 반면, Ruling 행이나 보류된 지적 사항은 ledger에만 기록되어 있습니다. 빌드 결과물을 정리하려는 습관으로 -fdx를 치는 개발자라면, 플랜 실행 중일 때만 -e .superpowers로 제외하는 것이 안전할 것입니다.
v7.0.0에서 ledger 커밋이 가능해지다
2026-10-10 공개된 v7.0.0의 릴리스 노트에는 Subagent-Driven Development 섹션에 다음 수정 사항이 기재되어 있습니다.
It used to overwrite the file with * on every run, reverting any version a repo committed (for example, to track progress.md ledgers).
It now writes the default only when no file exists.
이전의 sdd-workspace는 실행할 때마다 .gitignore를 *로 덮어써서, 리포지토리 측에서 커밋한 내용이 매번 되돌아가고 있었습니다. 현재는 파일이 존재하지 않을 때만 기본값을 작성합니다. 스크립트의 해당 줄은 다음과 같습니다.
[ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore"
이를 통해 리포지토리 자체의 .gitignore를 두고 ledger만 버전 관리하는 운영이 가능해졌습니다. 예를 들어 다음과 같이 작성할 수 있습니다. 이는 리포지토리에 있는 내용이 아니라 필자가 작성한 예시입니다(ignore 판정만 git check-ignore로 확인했습니다).
추적하는 경우 알아두어야 할 점이 두 가지 있습니다.
git clean이 지우는 것은 미추적 파일이므로, 커밋된 ledger는 -fdx로도 남아 있습니다. 브리프나 리포트는 ignore 상태 그대로이므로 사라집니다 - Finish 섹션은 최종 검토가 통과된 후에 rm -rf <workspace>로 플랜의 작업 디렉터리를 지우도록 지시하고 있습니다. ledger를 추적했다면, 이 삭제는 차이점(diff)으로 나타납니다.
SKILL.md 본문은 여전히 작업 디렉터리를 git-ignore 전제하에 설명하고 있습니다. ledger 추적은 리포지토리 측의 선택이며, 스킬이 권장하는 운영 방식은 아닙니다. 같은 섹션에는 Windows의 Git Bash에서 플랜 마커가 절대 경로로 되어 있던 버그 수정도 포함되어 있습니다.
어떤 경우에 사용할 스킬인가
SKILL.md의 판정 다이어그램에서는 구현 플랜이 있고, 태스크들이 대체로 독립적이며, 서브 에이전트를 사용할 수 있는 경우가 이 스킬의 사용처입니다. 인라인 실행을 선택한 경우나 서브 에이전트 도구가 없는 환경에서는 executing-plans로 분기합니다. 둘 다 같은 작업 디렉터리와 ledger를 공유한다고 명시되어 있으므로, 대장(ledger) 읽는 방식은 공통적입니다.
- 인라인으로 실행할 경우: executing-plans 스킬 게재 페이지
- 시작 전에 격리된 작업 장소를 준비할 경우: using-git-worktrees 스킬 게재 페이지
- 모든 태스크 완료 후 인계처: finishing-a-development-branch 스킬 게재 페이지
비슷한 용도의 스킬을 나란히 찾아보고 싶다면, AI 에이전트 분야의 스킬 목록이 입구가 됩니다.
출처
이 글은 Skillselion이 작성했습니다. Skillselion은 Claude Code, Codex, Cursor용 확장을 실제 설치 수로 나열하는 독립적인 디렉터리로, Anthropic, OpenAI, Cursor 어느 곳과도 제휴하고 있지 않습니다.
Discussion
