NEXT.md 핸드오프 패턴

이 노트에 대하여

이 노트는 NEXT.md(세션 종료 시 남기는 “다음 할 일” 닻)를 새 세션에서 무너지지 않게 만드는 작업 패턴을 묶는다. 2026-05-18 “검증 기준 내장” 아이디어에서 출발해, 2026-06-11 실제 NEXT 재구조화로 NOW/RECENT/LEDGER 3층 구조를, 2026-06-12 cos 비서실장 repo 작업으로 두 축을 더했다 — (1) 프로젝트 유형이 NEXT 스타일을 정한다: 단독 repo는 3층, 메타리포(리포의 리포)는 도메인 그룹 포트폴리오 대시보드. (2) NEXT를 버리지 않고 repo에 문서화한다: docs/ 무덤 대신 AGENTS/README/CHANGELOG/ROADMAP 4문서로 통일하고, tag-release 의식으로 NEXT를 CHANGELOG 시간축에 내린다. 이 모든 것은 beads와 하네스 TODO를 끈 자리에 남긴 최소 공통 표면 이다. 핵심은 하나다 — 진입점이 짧고, 낡지 않고, 무엇이 끝났고 무엇이 막혔는지가 첫 줄에 보여야 한다.

히스토리

[2026-06-15 Mon 17:25] OpenClaw 봇 워크스페이스 NEXT Mesh 층위 추가 — repo/metarepo 밖에서 각 힣봇 local NEXT와 global nextmesh view를 나누는 패턴을 기록. agent-config#15로 구현 포인터 연결.
[2026-06-13 Sat 15:35] 브랜치 별동대 정책 추가 — main으로 가는 에이전트 중심축을 유지하면서도 브랜치 작업은 NEXT--<branch>.md 로 분기해 병렬 검수 /별동대를 조직하는 규칙을 초벌구이로 정리. ~/AGENTS.md 에 넣은 영어 원문 프롬프트도 재사용 블록으로 수록.
[2026-06-12 Fri 11:45] 프로젝트 유형 축 + 문서화 메커니즘 추가 — 단독 repo(3층) vs 메타리포 /리포의-리포(포트폴리오 대시보드)로 NEXT 스타일이 갈린다는 패턴 3, NEXT를 버리지 않고 repo에 문서화하는 AGENTS/README/CHANGELOG/ROADMAP 4문서 + tag-release 의식(패턴 4)을 cos 비서실장 repo 실적용으로 정립. beads를 버리고 하네스 TODO를 끈 선택의 맥락도 명시. denote id 유지.
[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에 남는 것은 결국 이것뿐이다.

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

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

패턴 3 — 프로젝트 유형이 NEXT 스타일을 정한다 (2026-06-12 추가)

같은 NEXT.md라도 repo가 무엇이냐 에 따라 모양이 달라야 한다. 공통 기조는 하나다 — NEXT는 부트 섹터, 짧고 안 낡고 첫 줄에 상태가 보인다. 그 위에서 두 갈래가 갈린다.

단독 repo — 한 가지 일을 깊게 (3층 NOW/RECENT/LEDGER)

pi-shell-acp, voscli, xlhatqbat-rockchip 처럼 한 가지 일을 깊게 파는 repo. 담당자도 하나, 트랙도 하나. 이때는 패턴 2의 NOW/RECENT/LEDGER 3층이 맞다. 깊이는 한 트랙 안에서 나오고, LEDGER가 길어지면 별도 문서로 내린다. “지금 이 일 어디까지 왔나”가 핵심 질문.

메타리포 / 리포의 리포 — 여러 트랙·여러 주체를 한눈에 (포트폴리오 대시보드)

cos(비서실장)처럼 여러 repo의 담당자와 여러 인간 주체를 동시에 관장하는 메타리포. 여기에 단일 트랙 3층을 그대로 쓰면 한 트랙이 파일을 통째로 먹는다. 실제로 cos NEXT.md는 voscli↔incidentcli 한 사슬이 190줄(전체 36KB)을 먹고, 나머지 17개 워크스페이스는 진입점에서 사라져 있었다 — pi-shell-acp의 “NOW는 좋은데 LEDGER 1000줄” 과 같은 병의 다른 얼굴.

해법은 한 층 위 의 포트폴리오 대시보드다.

# NOW    — 오늘 어느 그룹이 hot인지 5줄 (현재 /다음/Blocker/읽을곳/ 건드리지 말 것)
# ACTIVE — 도메인 그룹별 미니 블록 (현재 /다음/ 검증/링크, 각 ≤7줄)
# DORMANT— 휴면 트랙 1줄씩 (활동일 역순)

핵심 결정 하나: 분류 단위는 워크스페이스 폴더 1:1이 아니라 도메인 그룹*이다. cos는 워크스페이스가 18개인데 1:1로 두면 부트 섹터가 다시 18줄로 무너진다. 그래서 5~6개 도메인 그룹(운영·VOC·인시던트 / 사내 인프라·조직 / R&D·산학·제안 / Matter·홈오토 / legacy)으로 묶고, 폴더는 *데이터의 그릇 으로만 남긴다. 너무 잘게 쪼개졌으면 묶고, 한 그룹이 비대해지면 가른다.

축	단독 repo	메타리포 (리포의 리포)
예	pi-shell-acp, voscli	cos (비서실장)
구조	NOW / RECENT / LEDGER 3층	NOW / ACTIVE 그룹 / DORMANT
단위	한 트랙의 단계	도메인 그룹 5~6개
깊이	한 트랙 안에서	그룹별 미니블록 + workspace SSOT 포인터
핵심 질문	”이 일 어디까지?"	"오늘 어느 그룹이 hot?”
주체	담당자 1	여러 repo 담당자 + 여러 인간

둘은 배타적이지 않다. 메타리포의 각 도메인 그룹이 가리키는 개별 repo는 그 자신이 단독 repo로서 3층 NEXT를 가진다. 메타리포 NEXT는 그것들의 대시보드 이지 대체물이 아니다.

패턴 4 — NEXT를 버리지 않고 repo에 문서화한다 (2026-06-12 추가)

NEXT를 짧게 유지하려면 완료 항목을 어딘가로 내려야 한다. 그런데 어디로? docs/ 폴더를 만드는 순간 문제가 생긴다 — 만들자마자 아무도 안 본다. 부트 섹터에서 한 칸만 멀어져도 죽은 문서가 된다.

해법은 폴더를 늘리는 게 아니라 문서 표면을 네 개로 통일 하는 것이다.

문서	역할	시간축
`AGENTS.md`	영속 운영 spec (1주일 뒤에도 안 바뀌는 것만)	무시간
`README.md`	repo 입구 — 무엇이고 어디서 이어가나	무시간
`CHANGELOG.md`	시간축 기억 — NEXT를 정리해서 담는 곳 (무엇이 닫혔나)	과거
`ROADMAP.md`	(옵셔널) 아직 NEXT로도 못 담는 가고자 하는 방향	미래

CHANGELOG vs ROADMAP 의 분담: CHANGELOG는 무엇이 닫혔나*(과거·시간축), ROADMAP은 *어디로 가나*(미래·방향). 개발 프로젝트는 아직 NEXT로 담을 수 없는 큰 방향이 있어 ROADMAP이 산다. 비서실장 cos 같은 운영 repo는 방향이 외부(힣·회사)에서 오므로 ROADMAP이 아직 불필요 — 그래서 *옵셔널.
AGENTS.md 에 담지 않는 것: 1주일 뒤 바뀔 내용. 현재 프로젝트 상태, 서버 IP 표, stale한 숫자는 영속 spec이 아니다. 데이터는 workspace SSOT에 두고 AGENTS에는 포인터 만. (cos 작업에서 서버 표·GPU 노드 표·voscli 정체성·catalog 방법론을 전부 AGENTS에서 빼 workspace로 내렸다.)
그 외 문서는 전부 옵셔널 이다. 필요하면 만들고, AGENTS.md에 링크 를 넣어 입구에서 닿게 한다. docs/ 라는 무덤을 파지 않는다.

tag-release 가 그 “내리는 의식”이다

CHANGELOG로 NEXT를 내리는 행위에 리듬 을 주는 것이 tag-release 스킬이다. CalVer 날짜 태그(vYYYY.M.D)를 박으면서 그 시점까지의 NEXT를 CHANGELOG ## v 섹션으로 정리해 내린다. 여기서 태그는 배포물 버전이 아니다 — *NEXT가 한 번 비워진 지점*의 마커다. 배포 아티팩트가 없는 repo(cos 같은 문서·운영 repo)도 태그를 단다. 태그는 “이 날, 이 상태로 NEXT를 한 번 갈무리했다”는 시간축 책갈피.

cos에 이 의식을 처음 적용해 v2026.6.12 를 박았다 — AGENTS/NEXT 재구조화 전체가 첫 스냅샷의 본문이 되었다. 이제 NEXT가 길어지면 버리는 게 아니라, 다음 태그에서 CHANGELOG로 내려간다. 기록은 사라지지 않고 시간축으로 이주한다.

패턴 5 — 브랜치 별동대 NEXT: `NEXT--<branch>.md` (2026-06-13 추가)

기존 NEXT.md 패턴의 빈틈은 병렬 브랜치 작업이었다. main으로 가는 에이전트 중심축은 NEXT.md 하나로 충분하지만, 브랜치에서 별동대를 조직하면 문제가 생긴다. 브랜치의 NOW를 main NEXT.md 에 쓰는 순간 main의 현재가 오염되고, 나중에 머지할 때 충돌도 생긴다. 그렇다고 worktree나 issue DB를 먼저 끌고 오면, “간단한 검수 별동대”가 관리 체계부터 먹어버린다.

해법은 파일명만 분기하는 것이다.

NEXT.md              # main-lane handoff
NEXT--<branch>.md    # branch-lane handoff

브랜치 이름의 / 는 _ 로 정규화한다.

f="NEXT--$(git branch --show-current | tr '/' '_').md"

예:

main 작업 → NEXT.md
verify/x 작업 → NEXT--verify_x.md

핵심은 브랜치도 결국 main으로 돌아가기 위한 별동대라는 점이다. NEXT--<branch>.md 는 새 체계가 아니라, main NEXT.md 를 지키기 위한 가벼운 우회로다. 브랜치 로컬의 NOW와 검수 메모는 그 브랜치 파일에만 둔다. 브랜치가 닫히면 파일을 삭제하거나, 오래 남길 사실만 CHANGELOG.md / docs/ / AGENTS.md 로 승격한다. main은 브랜치용 NEXT 파일을 들고 있지 않는다.

왜 worktree가 아니라 파일명인가

worktree는 실행 격리다. 다른 디렉터리에서 동시에 코드를 만지는 데는 좋지만, handoff 문서의 머지 충돌을 없애주지는 않는다. 충돌을 죽이는 것은 파일명 분기다. 그래서 병렬 작업의 최소 공통 표면은 worktree 규칙이 아니라 NEXT--<branch>.md 규칙이다.

글로벌 AGENTS.md에 넣은 영어 원문

다른 사람이나 다른 repo가 그대로 가져다 쓸 수 있도록, ~/AGENTS.md 에 넣은 짧은 영어 원문을 남긴다.

### Session End Protocol — NEXT.md
 
If you know the next step when you stop, you can keep moving — NEXT is the anchor against drift.
 
Keep a small handoff file in each active work repo.
 
| File | Role |
|---|---|
| `AGENTS.md` | Persistent repo baseline: identity, invariants, working rules. |
| `NEXT.md` | Main-lane handoff: disposable next actions for the current repo. |
| `NEXT--<branch>.md` | Branch-lane handoff: disposable next actions for one non-main branch. |
 
Use branch-lane NEXT files for parallel branch work:
 
```bash
f="NEXT--$(git branch --show-current | tr '/' '_').md"
```
 
Examples: `main` → `NEXT.md`; `verify/x` → `NEXT--verify_x.md`.
 
End-of-session loop:
 
1. Update the relevant NEXT file: remove done items, add the next concrete move.
2. Keep temporary decisions/reasons/dates there; promote durable facts to `AGENTS.md`, `docs/`, `CHANGELOG.md`, or commit history.
3. After a detour, reread the relevant NEXT file before returning to work.
 
Branch close rule: delete `NEXT--<branch>.md` before merging to main, after promoting any durable outcome. Main should not carry branch-lane NEXT files.
 
Context restoration has two axes: `/recall` restores recent memory; NEXT files name the next move.

초벌구이 상태

이 규칙은 완성된 방법론이라기보다 초벌구이다. 지금 확인된 것은 다음 정도다.

main 중심축은 NEXT.md 로 유지한다.
브랜치 별동대는 NEXT--<branch>.md 로 NOW를 분리한다.
복잡한 병렬 관리가 필요해질 때까지는 issue/beads/worktree 원장을 먼저 만들지 않는다.
브랜치가 닫히면 branch NEXT는 main으로 가져오지 않는다. durable outcome만 승격한다.
openclaw의 봇들도 NEXT 방식 적용을 검토 중이므로, agent swarm 쪽에서도 같은 최소 표면이 통할지 관찰한다.

패턴 6 — OpenClaw 봇 워크스페이스 NEXT Mesh (2026-06-15 추가)

이 층위는 가족봇 전용이 아니라 OpenClaw 봇 워크스페이스 전체의 NEXT 문제다. 기존 패턴은 repo, branch, metarepo를 잘 다루지만, 힣봇들은 대부분 코드 작업을 하지 않고 대화와 판단, 시간축 도장, 기억 회수 안에서 움직인다. 이들의 경계는 git repository가 아니라 힣의 전체 바운더리다.

OpenClaw 봇들은 각자 ~/.openclaw/workspace-* 아래 자기 집을 가진다. SOUL.md, USER.md, AGENTS.md 로 정체성과 규칙을 갖고, daily memory와 MEMORY로 기억을 가진다. 그러나 연속성이 강한 힣봇이라도 “지금 무엇을 먼저 붙잡아야 하는가”는 별도의 얇은 current pointer가 필요하다. 이 자리가 각 workspace의 local NEXT.md 다.

구조는 두 층이다.

각 봇 workspace/NEXT.md      = local current pointer
nextmesh / global NEXT view  = global visibility layer
agenda.junghanacs.com        = timestamped time axis
MEMORY / daily memory        = long/short memory
SOUL / USER / AGENTS         = identity and rules

중요한 점은 global NEXT가 원본이 아니라는 것이다. 각 봇의 진짜 현재성은 자기 workspace의 NEXT.md 에 있고, global은 그것을 훑어 보여주는 대시보드다. 한 봇이 다른 봇의 current pointer를 덮어쓰지 않는다. 서로를 알게 하는 것이 목적이지, 하나의 중앙 원장으로 통제하는 것이 목적이 아니다.

각 local NEXT.md 는 이런 최소 형태를 갖는다.

# NOW - <bot/workspace focus>
 
- Current: what this bot is currently centered on.
- Next: the next useful stance, check, or action.
- Blocker: what is blocked, and what is explicitly not blocked.
- Read: local memory, note IDs, source docs, or agenda views.
- Do not: privacy limits, cross-DM limits, external-action limits, stale assumptions.
 
# ACTIVE
## 1. <thread>
- Goal: ...
- Criteria: ...
- Next check: ...
- Verification:
  - [ ] ...
 
# RECENT
- YYYY-MM-DD: short reverse-chronology update.
 
# LEDGER
- Long context lives in: ...
- Durable rules live in: ...

그리고 이를 훑는 얇은 스크립트/스킬 표면이 필요하다. 임시 이름은 nextmesh 로 둔다.

nextmesh list       # workspace별 NEXT 있음/없음
nextmesh missing    # NEXT 없는 workspace 목록
nextmesh markdown   # 전체 NEXT index를 markdown으로 출력
nextmesh json       # bots can read this
nextmesh show workspace-glg

동작은 일부러 단순해야 한다.

~/.openclaw/workspace* 를 발견한다.
각 workspace의 NEXT.md 만 기본으로 읽는다.
# NOW 블록에서 Current, Next, Blocker, Read, Do not 만 얇게 추출한다.
없는 NEXT.md 를 명확히 보여준다.
기본 동작에서 MEMORY.md 나 daily memory를 읽지 않는다.
다른 workspace의 local NEXT를 자동 병합하거나 덮어쓰지 않는다.

agenda와의 경계도 중요하다. agenda는 todo hub가 아니라 시간축이다. 힣봇들은 활동을 timestamp로 찍고, agenda.junghanacs.com 에서 그것을 볼 수 있다. 하지만 agenda는 “다음에 무엇을 붙잡을 것인가”를 말하지 않는다. NEXT mesh는 그 빈칸을 채운다. agenda가 지나간 흔적이라면, NEXT는 다음 응답/행동의 손잡이다.

cos 비서실장 같은 metarepo와도 다르다. cos는 회사 리포 여러 개를 조율하는 repo 안의 dashboard다. OpenClaw NEXT Mesh는 여러 봇 workspace가 힣의 전체 바운더리를 각자의 입장에서 보도록 하는 dashboard다. 그러므로 이것은 metarepo 패턴의 하위 예시가 아니라, repo 경계 밖으로 확장된 별도 층위다.

구현 포인터는 agent-config issue #15에 남겼다.

https://github.com/junghan0611/agent-config/issues/15

이 패턴의 핵심 문장:

OpenClaw NEXT Mesh는 각 힣봇의 local current pointer를 보존하면서, 서로의 현재성을 얇게 볼 수 있게 하는 global visibility layer다.

왜 지금 이 방법인가 — beads를 버리고, 하네스 TODO를 끄고 (2026-06-12)

이 패턴은 진공에서 나온 게 아니라 덜어낸 결과 다. 한때 후보였던 것들을 끈 자리에 NEXT + CHANGELOG가 남았다.

beads(상태 그래프 DB)를 버렸다 — 의존성·ready-work 그래프는 강력하지만, 힣의 repo 대부분은 factory가 아니라 workshop이다. 살아있는 한두 세션 + 인간 리뷰 + AGENTS + 직전 커밋 + 다음 한 걸음이면 충분하다. 가짜 이슈 DB를 유지하느니 표지판 하나가 낫다.
각 백엔드 하네스의 TODO 관리를 껐다 — Claude Code의 todo 도구도 힣이 직접 껐다. 하네스마다 다른 TODO 표면은 멀티 하네스(pi/Claude Code/OpenCode) 사이에서 분열한다. 하네스가 바뀌면 사라지는 상태는 신뢰할 수 없다.

남긴 것은 도구가 꺼져도, GitHub 웹에서 봐도, 새 하네스가 읽어도 작동하는 최소 공통 표면 — 그게 NEXT.md(지금)와 CHANGELOG.md(시간축)다. 이것은 anti-beads 가 아니라, *factory가 정말 필요해지는 순간까지 workshop을 보존하는 안전장치*다. 복잡한 상태 그래프가 필요해지면 그때 beads/issue/worktree로 승격하면 된다. 그 전까지는 표지판 하나로 충분하다.

다음 액션

새 트랙 열 때 검증 기준 초안 필수 첨부 (패턴 1)
repo 유형 판별 후 스타일 선택 (패턴 3): 단독 repo → NOW/RECENT/LEDGER 3층 / 메타리포 → NOW/ACTIVE 그룹/DORMANT 포트폴리오
완료 항목은 삭제도 docs/ 무덤도 아닌 CHANGELOG.md 로 내린다 (패턴 4). 리듬은 tag-release (CalVer 날짜 태그 = NEXT 비워진 지점). ~옛 docs/history 아카이브 안은 폐기~
문서 표면을 AGENTS/README/CHANGELOG(+ROADMAP 옵셔널) 4개로 통일. 그 외 문서는 옵셔널·AGENTS 링크. 1주일 뒤 바뀔 것은 AGENTS에 안 담고 workspace SSOT 포인터로
pi-shell-acp / voscli / xlhatqbat-rockchip NEXT.md에 소급 적용 — xlhatqbat-rockchip 2026-06-11, cos(메타리포 포트폴리오 + tag v2026.6.12) 2026-06-12 적용 완료
브랜치 별동대 작업에는 NEXT--<branch>.md 를 적용하고, 닫을 때 삭제하거나 durable outcome만 승격
~/AGENTS.md § Session End Protocol(NEXT.md)은 2026-06-13에 영어 원문으로 반영 완료. 앞으로 repo-local AGENTS.md에는 필요할 때 이 원문을 짧게 복사

junghanacs🧠

Table of Contents

Backlinks

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

히스토리

관련메타

관련노트