baton 사람과 Claude 사이의 폴더 기반 통신 컨벤션

핵심 아이디어

Claude와 긴 대화를 나눌수록 컨텍스트는 흘러가고 결과물은 흩어진다. baton은 이 문제를 폴더 구조로 해결한다 — 지시는 inbox/에, 결과는 outbox/에, 공유 메모리는 memory/에. 새 세션이 시작돼도 CLAUDE.md 하나만 읽으면 Claude는 컨벤션을 파악한다.

1 · 설치

$ npm install -g @zollibee/baton@latest
# 업데이트:
$ npm install -g @zollibee/baton@latest
# 또는 로컬 개발:
$ git clone https://github.com/sohee-zoe/baton.git && cd baton && npm link

2 · 프로젝트 시작

1. baton init — 폴더 스켈레톤 생성

   프로젝트 이름 지정 가능. 없으면 현재 디렉토리 이름 사용.
2. inbox/task.md 작성

   Goal / Constraints / Output 세 섹션. 40줄 이내.
3. Claude에게 작업 지시

   새 세션에서 CLAUDE.md를 읽으면 Claude가 컨벤션을 파악함.
4. baton open — 결과 확인

   최신 outbox HTML을 브라우저로 열어줌.

$ mkdir my-project && cd my-project
$ baton init "My Project"
✓ baton 프로젝트 생성: My Project
  CLAUDE.md, inbox/, outbox/, memory/ 준비됨.
# task.md 작성 후 Claude에게 지시...
$ baton status
baton: My Project
  task    : (새 작업 제목)
  outbox  : 1개 (최신: 001-slug.html)
  open Q  : 0개
$ baton open

3 · 폴더 구조

project/
├── CLAUDE.md              ← Claude 진입점. 항상 로드. <100줄.
├── baton.json             ← 프로젝트 마커 (이름·버전)
├── inbox/
│   ├── task.md            ← 현재 할 일 (사람이 씀, 40줄 이내)
│   ├── .archive/          ← 이전 task.md 자동 보관
│   └── context/           ← 참조 문서 (명시 요청 시 로드)
├── outbox/
│   └── 001-slug.html      ← Claude 산출물. 번호 prefix로 정렬.
└── memory/
    ├── decisions.md        ← 결정 누적 (한 줄씩, 덮어쓰기 금지)
    ├── open-questions.md   ← 미결 질문. 해결 시 [resolved] 추가.
    └── summary.md          ← 세션 부트스트랩 요약 (20줄 이내)

4 · CLI 명령

$ baton init "Research Notes"
✓ baton 프로젝트 생성: Research Notes
# name 생략 시 현재 디렉토리 이름 사용
# 이미 초기화된 경우 오류 없이 건너뜀 (idempotent)

$ baton new "데이터 시각화 대시보드 설계"
✓ inbox/task.md 갱신: 데이터 시각화 대시보드 설계
  이전 task → inbox/.archive/2026-05-09T02-30-00.md
# task.md를 열어 Goal / Constraints / Output 작성

$ baton open
→ outbox/003-dashboard.html
# mtime 기준 최신 파일. outbox가 비어있으면 안내 메시지.

$ baton status
baton: Research Notes
  task    : 데이터 시각화 대시보드 설계
  outbox  : 3개 (최신: 003-dashboard.html)
  open Q  : 2개
$ baton status --json
{
  "projectName": "Research Notes",
  "task": "데이터 시각화 대시보드 설계",
  "outboxCount": 3,
  "latestOutbox": "003-dashboard.html",
  "openQuestionsCount": 2,
  "batonVersion": { "file": "0.1.1", "running": "0.1.1" }
}

5 · Claude와 함께 쓰는 법

산출물 규칙 (Claude가 따라야 할 것)

Claude는 결과를 outbox/NNN-slug.html로 출력한다. 번호는 현재 최댓값 + 1을 3자리 zero-pad. 파일 첫 줄에 메타 주석 필수:

<!-- title: 제목 task: task명 created: YYYY-MM-DD -->

결정 기록

새 결정이 생기면 memory/decisions.md에 한 줄 append. 덮어쓰거나 줄 삭제 금지.

2026-05-09: Chart.js 채택 [근거: zero-dep 유지, CDN 불필요]

미결 질문

memory/open-questions.md에 한 줄씩. 해결되면 같은 줄에 [resolved: YYYY-MM-DD 내용] 추가. 줄 삭제는 금지 — 결정 히스토리 보존용.

6 · 설계 원칙