baton: at a glance

baton은 거대한 소프트웨어가 아니라 약속된 폴더 구조와 컨벤션이다. Markdown은 사람이 Claude에게 건네는 짧은 지시에 쓰고, HTML은 Claude가 사람에게 돌려주는 산출물에 쓴다. 이 한 페이지는 그 구조를 한 화면에 모아둔 시각 요약이다.

Read along · prd.md/ design.md/ cli-spec.md
§ 01
Concept · Three Lanes

세 개의 레인

Human → Claude SHORT MARKDOWN · OFTEN UPDATED inbox/task.md inbox/context/ inbox/.archive/ Shared BIDIRECTIONAL · APPEND-ONLY CLAUDE.md memory/decisions.md memory/open-questions.md Claude → Human SINGLE-FILE HTML · KEPT outbox/001-…html outbox/002-…html outbox/NNN-…html Human → Claude SHORT MARKDOWN · OFTEN UPDATED inbox/task.md inbox/context/ inbox/.archive/ Shared BIDIRECTIONAL · APPEND-ONLY CLAUDE.md memory/decisions.md memory/open-questions.md Claude → Human SINGLE-FILE HTML · KEPT outbox/001-…html outbox/002-…html outbox/NNN-…html
Human lane Shared Claude lane
§ 02
Topology · Directory Tree

폴더 트리

# baton init 직후
project-root/
├── CLAUDE.md                    < 150줄, 항상 자동 로드
├── baton.json                   name, createdAt, batonVersion
├── inbox/
│   ├── task.md                "지금" 할 일. 한 화면 분량.
│   ├── .archive/              과거 task의 ISO-timestamp 백업
│   └── context/               참조 자료. 명시 요청 시 로드.
├── outbox/
│   ├── 001-initial-spec.html
│   ├── 002-data-flow.html
│   └── NNN-<slug>.html        3자리 일련번호 + kebab slug
└── memory/
    ├── decisions.md           한 결정 한 줄, append-only
    └── open-questions.md      미결 질문, 해결 시 [resolved] 추가
§ 03
Sequence · One Cycle

한 사이클의 흐름

Human Filesystem Claude ① baton new "..." → inbox/task.md 갱신 ② 새 세션: CLAUDE.md + task.md 자동 로드 ③ 작업 ④ outbox/NNN-slug.html 작성 (single-file) ⑤ memory/decisions.md ◂ append ⑥ baton open → 최신 outbox html ⑦ 피드백 ↻ ① 로

세션 간 컨텍스트는 memory/decisions.md 한 파일로 누적된다. 새 Claude 세션은 항상 CLAUDE.md → inbox/task.md → memory/decisions.md 순으로 읽는다.

§ 04
Surface · Four Commands

CLI 한눈에

baton init [name]

현재 디렉토리에 폴더 트리 + 템플릿 생성. idempotent.

side effectcreates 5 dirs

baton new "<task>"

inbox/task.md를 새 task로 초기화. 이전 본은 inbox/.archive/ 로 mv.

requires rootarchives prior

baton open

outbox/*.html 중 mtime 최신을 OS 기본 브라우저로 오픈.

darwin: openwin: startlinux: xdg-open

baton status

현재 task 한 줄, outbox 개수, 미해결 open-questions 수.

version warnno spinner
§ 05
Rationale · Why This Split

형식 분리의 근거

Markdown — 사람 → Claude

장점Claude가 정확히 편집·치환 가능. diff 명확. 자동화 쉬움.
단점다이어그램·색·인터랙션 표현 빈약. 100줄 넘으면 잘 안 읽힘.
활용task.md, CLAUDE.md, memory/*.md (모두 짧게)

HTML — Claude → 사람

장점정보 밀도. SVG/CSS/JS 인라인. 더블클릭 공유.
단점생성 2–4× 느림. git diff 지저분. 다시 편집 부담.
활용outbox/NNN-slug.html (single-file, self-contained)
§ 06
Discipline · Six Tenets

설계 원칙 여섯

i.
컨벤션 > 코드먼저 컨벤션으로 풀 수 있는지 묻는다.
ii.
Zero deps외부 npm 금지. Node 내장만 쓴다.
iii.
SSOT per concern한 정보는 한 파일에만 둔다.
iv.
Fail loud자동 복구하지 않는다. 사람이 즉시 인지.
v.
Append > overwritememory는 누적. task는 archive 후 덮어씀.
vi.
Idempotent같은 명령 두 번 호출해도 안전.