NEXT.md 핸드오프 패턴

이 노트에 대하여

이 노트는 NEXT.md(세션 종료 시 남기는 “다음 할 일” 닻)를 새 세션에서 무너지지 않게 만드는 작업 패턴을 묶는다. 2026-05-18 “검증 기준 내장” 아이디어에서 출발해, 2026-06-11 실제 NEXT 재구조화 경험으로 NOW/RECENT/LEDGER 3층 구조를 더했다. 이어서 pi-shell-acp의 비대한 NEXT 사례를 통해, 왜 TODO·workflow·beads·worktree가 있어도 NEXT.md는 일부러 단순해야 하는지 정리한다. 핵심은 하나다 — 진입점이 짧고, 낡지 않고, 무엇이 끝났고 무엇이 막혔는지가 첫 줄에 보여야 한다.

히스토리

[2026-06-11 Thu 17:54] TODO/workflow/beads/worktree와 NEXT.md의 경계를 추가 — pi-shell-acp NEXT 사례를 통해 “NEXT는 부트 섹터/ 책갈피” 원칙을 보강.
[2026-06-11 Thu 17:42] botlog 승격 + 강화 — xlhatqbat-rockchip NEXT를 NOW/RECENT/LEDGER 3층으로 재구조화한 실경험으로 3층 구조·stale 원칙·상태 마커·blocker 분리를 추가. denote id 유지
[2026-05-18 Mon 18:13] 생성 — agent-config NEXT.md(Track B pi-chat 상주 담당자 패턴) 검토 중 “검증 기준 내장” 패턴 포착 (llmlog)

NEXT.md는 “지금 시점에 알고 있는 다음 한 걸음”을 적는 휘발성 닻이다. AGENTS.md가 영속 baseline이라면 NEXT.md는 “종료할 때 다음에 뭐할지 알면 뭐든 할 수 있다”는 진행-정체 방지 장치다.

문제는 NEXT.md가 *자기 무게에 무너진다*는 것이다. 세션마다 갱신 로그가 쌓이고, 완료한 일이 미래형으로 남고, 진입점이 길어진다. 그 결과 새 세션(또는 다른 담당자/분신)이 “지금 뭐부터 봐야 하지”에서 헤맨다. 아래 두 패턴은 그 붕괴를 막는다.

패턴 1 — 검증 기준 내장 (완료 조건을 코딩 전에 박는다)

NEXT.md에 “다음에 뭐할지”만 적지 말고, “어떻게 됐을 때 통과로 볼지”를 체크리스트로 박아둔다.

코딩 전에 완료 조건을 명시 → 범위 폭발(scope creep) 방지
세션 재개 시 즉시 “이게 됐는지 아닌지” 판단 가능
커밋 히스토리를 뒤지지 않아도 진척 상태를 읽을 수 있음

발견 예시 (pi-chat 상주 담당자 검증 기준 초안):

검증 기준 초안:
- /chat-config로 Discord account/channel 1개 등록
- /chat-connect 또는 /chat-spawn-all로 worker 기동
- 메시지 3~5회 왕복
- channel.jsonl에서 inbound/outbound/job_completed 확인
- /workspace와 /shared 경계 확인
- host 파일 접근 차단/제한 감각 확인
- secret 주입 경로가 agent prompt/로그에 노출되지 않는지 확인
- 외부 공격성 입력에 담당자가 무너지지 않는지 관찰

일반화 — 새 Track/Phase를 NEXT.md에 열 때 의무 첨부:

### 검증 기준
- [ ] 최소 동작 확인: <가장 작은 단위 smoke>
- [ ] 경계 확인: <격리 / 권한 / 로그>
- [ ] 통과 조건: <이것이 되면 다음 단계 진입 가능>

패턴 2 — 새 세션이 무너지지 않는 3층 구조 (2026-06-11 추가)

검증 기준을 박아도 NEXT.md 자체가 비대해지면 새 세션이 그걸 못 찾는다. 진입점을 세 층으로 나눈다.

# NOW    — 무조건 먼저 읽는 5줄. 길어지거나 낡으면 즉시 실패
# RECENT — 최근 역순 기록 5~10개. 그 이상은 LEDGER로
# LEDGER — 긴 원장. 삭제하지 말고 아래로 밀되, 기본 진입점에선 안 읽게

NOW에 들어갈 5줄(이 이상 늘리지 않는다):

현재: 지금 어디에 서 있는가 (한 줄)
바로 다음: 다음 한 걸음 (1)→(2)→(3)
Blocker: 무엇이 막혔는가 / 무엇은 안 막혔는가
읽을 곳: 깊이 파려면 어느 문서 어느 절
건드리지 말 것: 금지 사항(얼려둔 디렉토리, 인간 승인 필요 작업 등)

NOW는 SSOT다 — stale = 즉시 무너짐

3층 중 가장 위험한 실패는 NOW가 낡는 것이다. “정정 중” / “(1) 이번 작업 안정화” 같은 현재 세션의 진행형 이 NOW에 박혀 있으면, 다음 세션이 NOW만 읽고 “아직 안 끝났나?” 오해한다. NOW는 끝나는 즉시 완료형으로 갱신한다. RECENT/LEDGER가 NOW와 다른 말을 하면 그 순간 신뢰가 깨진다.

작업 큐에는 상태 마커를 박는다

자체 작업 큐(CERT-1 … CERT-6 같은)를 전부 미래형(“우선”, “병렬 가능”)으로 두면, 이미 끝난 일을 새 세션이 다시 한다. 각 항목에 ✅ / ⏳ 를 붙여 “한 걸 또 하기”를 막는다.

1. ✅ CERT-1 — fail-closed 보드 실증 (2026-06-09 PASS)
2. ✅ CERT-2 — PAA trust-store 주입 메커니즘
5. ⏳ CERT-5 — positive-path 자체 실증 (보드 대기, blocker 없음)
6. ⏳ CERT-6 — TH self pre-run (RPi 환경 대기)

Blocker는 “없음”까지 명시한다 — “막힐 게 없어야 한다”

가장 값진 한 줄은 “이건 안 막혔다” 이다. 막힌 것만 적으면 안 막힌 길도 막힌 것처럼 보인다. blocker를 종류별로 갈라 적는다.

권한/자격 blocker: 외부 멤버십·명의·승인이 있어야만 되는 것 (진짜 막힘)
환경 blocker: 하드웨어·RPi·배선만 있으면 되는 것 (시간 문제)
없음: 지금 당장 진행 가능 — 이걸 명시해야 다음 세션이 주저 없이 착수한다

실제로 “공식 인증 제출 은 멤버십 필요(막힘) / 사전검증 실행 은 자체 가능(안 막힘)“을 한 덩어리로 묶었다가, 우리가 할 수 있는 일을 못 한다고 적어버린 적이 있다. blocker를 제출 vs 실행 으로 가르자 막힌 줄 알았던 트랙이 열렸다.

두 패턴이 만나는 지점

패턴 1(검증 기준)은 한 트랙 안에서 “됐는지”를 판단하게 한다.
패턴 2(3층 구조)는 NEXT.md 전체에서 “지금 어디고 다음이 뭔지”를 5줄로 판단하게 한다.
둘 다 같은 목적 — 읽는 사람이 추론 없이 행동하게 한다. 새 세션이든 분신이든 인간이든, 진입점에서 헤매지 않는 것.

왜 이렇게 간단해야 하나 — NEXT는 부트 섹터다

NEXT.md를 중심으로 작업하면 처음에는 편하다. 모든 세션이 마지막에 다음 한 걸음을 남기고, 새 세션은 그걸 읽고 이어간다. 문제는 성공할수록 NEXT가 길어진다는 것이다. 다음 한 걸음이 둘이 되고, 둘이 다섯이 되고, 검증 기준과 리뷰 메모와 설계 원장과 오래된 blocker가 한 파일 안에 붙는다. 그러면 NEXT는 더 이상 다음 작업의 닻이 아니라 작은 이슈 트래커, 작은 위키, 작은 ledger가 된다.

그래서 NEXT.md는 일부러 단순해야 한다. 단순함은 기능 부족이 아니라 부트 조건 이다. 부트 섹터는 운영체제 전체가 아니다. 책갈피는 책 본문이 아니다. 새 세션이 첫 3분 안에 읽고 손을 올릴 수 있어야 하므로, NEXT는 “전체 진실”이 아니라 “지금 행동하기 충분한 최소 진실”만 품는다.

NEXT.md는 작업 원장이 아니라, 다음 작업으로 가는 표지판이다.

이 원칙은 에이전트에게 특히 중요하다. 사람은 긴 문서를 훑으며 감으로 현재성을 복구할 수 있지만, 새 에이전트는 문서 안의 모든 문장을 같은 현재성으로 읽기 쉽다. 오래된 “진행 중” 문장 하나가 살아 있는 blocker처럼 보이고, 이미 완료된 계획표 하나가 다음 작업처럼 보인다. 그러니 NEXT 상단은 낡으면 안 된다. 낡은 NOW는 거짓말이다.

/ workflow / beads / worktree와의 경계

NEXT.md가 단순해야 한다는 말은 todo나 beads 같은 구조가 필요 없다는 뜻이 아니다. 오히려 반대다. 각 도구가 맡을 자리를 분리해야 NEXT가 단순하게 남는다.

표면	맡는 일	NEXT에 들어오면 생기는 문제
TODO / agenda	해야 할 일 전체와 일정	backlog가 되어 다음 한 걸음이 묻힘
workflow 문서	반복 가능한 절차와 명령	절차 설명이 길어져 진입점이 늦어짐
beads / issue	의존성·상태·ready work 그래프	검색/상태전이 없는 가짜 이슈 DB가 됨
worktree	병렬 실행 공간과 격리	작업 공간 관리가 NEXT의 본문을 잡아먹음
llmlog / botlog	판단 근거·리뷰·긴 맥락	현재 포인터가 과거 논의에 잠김
NEXT.md	다음 세션의 첫 손 위치	길어지면 부팅 실패

NEXT.md는 이 표면들을 대체하지 않는다. 오히려 그 표면들로 가는 짧은 포인터 를 남긴다. “상세는 docs/plans/…”, “상태 그래프는 beads”, “긴 결정 근거는 llmlog”, “반복 절차는 AGENTS/README”라고 쓴 뒤, NEXT에는 지금 당장 할 일만 둔다.

이것은 Gas Town / Beads류의 factory 모델과도 관계가 있다. Beads는 작업을 원자 단위로 쪼개고 의존성을 추적하며 ready work를 찾는 데 강하다. worktree는 병렬 에이전트가 서로의 파일을 밟지 않게 하는 데 강하다. 하지만 힣의 현재 repo 담당자 패턴은 항상 factory가 아니다. 많은 작업은 workshop 이다. 살아있는 한두 세션, 인간의 리뷰, repo의 AGENTS.md, 직전 커밋, 그리고 다음 한 걸음이면 충분하다. workshop에 factory 원장을 들이밀면 움직임보다 관리가 앞선다.

따라서 NEXT.md의 단순함은 anti-beads가 아니다. *factory가 필요한 순간까지 workshop을 보존하는 안전장치*다. 복잡한 상태 그래프가 필요해지면 그때 issue/beads/workflow로 승격한다. 그 전까지 NEXT는 도구가 꺼져도, GitHub 웹에서 봐도, 새 하네스가 읽어도 작동하는 최소 공통 표면으로 남는다.

pi-shell-acp 사례 — 좋은 상단과 무거운 원장

2026-06-11에 본 pi-shell-acp의 NEXT.md는 좋은 사례이자 경고다. 상단에는 이미 훌륭한 구조가 있다.

# NOW — pi-shell-acp 0.11 current pointer
## North Star
## Current state
## Next moves
## Guardrails
# RECENT — reverse ledger
# LEDGER — 0.11.0 active plan and frozen evidence

이 구조 자체는 맞다. 새 담당자가 맨 위 30~50줄만 읽으면 현재 위치와 다음 행동을 잡을 수 있다. 문제는 같은 파일 아래 LEDGER가 1000줄 넘게 붙으면서, NEXT.md가 다시 설계 원장 전체가 되었다는 점이다. `NOW`는 부트 섹터인데, 같은 디스크 첫 파일에 운영체제 이미지 전체를 붙여둔 셈이다.

pi-shell-acp처럼 결정이 많고 검증 게이트가 촘촘한 repo는 긴 원장이 필요하다. 다만 그 원장은 NEXT.md 하단이 아니라 별도 문서가 더 맞다.

NEXT.md
  = NOW only
  = current pointer + next moves + guardrails
 
docs/plans/2026-06-11-entwurf-v2-ledger.md
  = frozen decisions / evidence / old slices / reviews
 
CHANGELOG / VERIFY / BASELINE / AGENTS
  = 영속 사실과 검증 기준

핵심은 삭제가 아니다. 분리 다. NEXT.md에는 “긴 원장은 여기”라는 링크를 남기고, 실제 원장은 docs/plans나 botlog/llmlog에 둔다. 그러면 새 세션은 먼저 행동하고, 막히면 내려간다. 반대로 NEXT에 모든 것을 남기면 새 세션은 행동하기 전에 고고학자가 된다.

승격 기준 — NEXT에서 밖으로 보내는 순간

다음 중 하나라도 맞으면 NEXT.md 본문에서 빼고 다른 표면으로 승격한다.

한 항목이 7줄을 넘는다 → docs/plans 또는 llmlog
체크박스가 5개를 넘는다 → issue/beads 또는 별도 checklist 문서
같은 항목이 2세션 이상 유지된다 → backlog/issue로 승격하거나 삭제 판단
“왜” 설명이 길어진다 → botlog/llmlog로 이동
반복 명령이 들어간다 → AGENTS.md / README / workflow 문서
병렬 작업자·worktree·merge 순서가 필요하다 → issue/beads/worktree 관리면
완료된 내용이 참고 가치만 남는다 → RECENT 한 줄 후 ledger/archive로 이동

NEXT에 남는 것은 결국 이것뿐이다.

현재: 어디까지 왔는가
다음: 무엇을 할 것인가
검증: 무엇이면 끝인가
금지: 무엇을 건드리지 말 것인가
링크: 자세한 것은 어디에 있는가

이 다섯 줄이 살아 있으면 새 세션은 무너지지 않는다.

다음 액션

새 트랙 열 때 검증 기준 초안 필수 첨부 (패턴 1)
NEXT.md 상단을 NOW/RECENT/LEDGER로 유지, NOW 5줄·RECENT 5~10개 상한 (패턴 2)
오래된 ledger는 삭제 말고 docs/history/next-ledger-YYYY-MM.md 로 아카이브
pi-shell-acp / voscli / xlhatqbat-rockchip NEXT.md에 소급 적용 — xlhatqbat-rockchip은 2026-06-11 적용 완료
AGENTS.md § Session End Protocol(NEXT.md)에 3층 구조 반영 여부 결정

junghanacs🧠

Table of Contents

Backlinks

NEXT.md 핸드오프 패턴 — 검증 기준 내장 + 새 세션이 무너지지 않는 3층 구조 #책갈피

히스토리

관련메타

관련노트