일은 AI 세션에 넘기고, 진행은 한 화면에서

설치#

설치 파일(dmg)을 받아 응용 프로그램 폴더로 옮기고 엽니다. 요구 사항·Gatekeeper 경고·데이터 위치·삭제는 설치 런북에 자세히 있습니다.

1. 배포 담당자에게 받은 Baton-x.y.z-arm64.dmg(Apple 실리콘) 또는 x64 를 엽니다.
2. Baton 을 응용 프로그램 폴더로 끌어다 놓고 실행합니다.
3. 첫 실행이면 baton 준비 화면이 뜹니다.

• 설치하는 사람용: 설치 런북 — 요구 사항 · 첫 실행 · gh 없이 쓰기 · 개인 설정 파일 · 데이터 위치
• 배포본을 만드는 사람용: 릴리스 런북 — 버전 올리기 · 서명·공증 · 배포 채널 · 롤백

첫 실행 — 원버튼 셋업#

앱이 처음 뜨면 baton 준비 화면이 필수 항목(앱 설정 · git · Claude Code CLI · Claude 로그인 · GitHub · 워크스페이스 …)을 점검합니다. 필수가 모두 통과해야 다른 화면으로 갈 수 있습니다.

1. 한 번에 설정 을 누릅니다. 앱이 설치 · 로그인 · 필수 MCP · 기본값을 순서대로 합니다.
2. 브라우저 로그인이 필요하면(GitHub 코드 · Jira) 앱이 브라우저를 엽니다. 로그인하고 돌아와 로그인했어요 를 누르면 바로 이어집니다.
3. 끝나면 요약이 뜹니다. 사람이 해야 할 것(워크스페이스 폴더 고르기 · 슬랙 토큰 등)의 버튼을 눌러 마무리합니다.

12

연동 — 같은 툴, 여러 계정#

레일 맨 아래 연동 이 툴 연동을 하는 단 한 자리입니다. 탭이 여섯입니다.

첫 실행에는 「설치·상태」 탭이 먼저 열립니다 — 앱을 막고 있는 것부터 보여야 하기 때문입니다. 필수 항목이 남아 있으면 그 탭에 빨간 숫자가 붙습니다.

어느 계정이 쓰이나 — 프로젝트에 지정한 것 → 워크스페이스에 지정한 것 → 그 툴의 기본 계정 순입니다. 프로젝트에서 「워크스페이스 따름」 을 고르면 지정이 지워져 위에서 물려받습니다(끄는 것이 아닙니다). 표에서 ↑ 가 붙은 칸이 물려받은 것입니다. 지정은 연동 › 전체 탭 과 프로젝트 탭의 「연동」 섹션 두 자리에서 모두 할 수 있습니다.

프로젝트마다 스페이스 — 일감을 만들 기본 자리

프로젝트 탭 › 연동 의 프로젝트 관리툴 줄에는 계정 칸 오른쪽에 스페이스 칸이 있습니다. 그 프로젝트의 티켓 · 일감 · 카드를 만들 때 기본으로 갈 자리입니다 — Jira 는 프로젝트, Track 은 스페이스, Trello 는 보드. 보기는 지금 그 프로젝트가 쓰는 툴의 스페이스이고, 맨 위 정하지 않음 이 맵핑을 지웁니다.

• 맵핑하면 새 작업 시작의 스페이스 칸이 그 레포의 스페이스로 미리 골라지고, Track 탭의 레포 후보에 그 레포가 섭니다. AI 의 track_create 도 그 스페이스에 만듭니다.
• 저장된 스페이스가 지금 툴에서 풀리지 않으면(툴을 바꿈 · 스페이스를 보관함 · 보드를 지움) 칸 아래에 「저장된 스페이스 ○○ 는 지금 툴(…)에 없습니다 — 다시 고르세요」 가 섭니다.
• Track 인데 스페이스가 하나도 없으면 칸 대신 일감 › Track 에서 스페이스 만들기 링크가 섭니다. 계정이 없어 툴을 모르면 칸이 잠깁니다(먼저 계정을 정하세요). 「사용 안 함」이면 칸이 없습니다.
• 연동 › 전체 표에는 프로젝트 관리툴 칸 아래에 스페이스가 흐리게 한 줄로 섭니다(TRK · 결제 / 스페이스 미지정 / ⚠ 없음). 고르는 자리는 프로젝트 탭 하나입니다.

연동 설정 — 무엇을 넣으면 무엇이 켜지나#

하나도 넣지 않아도 앱은 돕니다. worktree · 세션 · 문서 · 성과 · 위키 · 메모는 로컬 git 과 앱 DB 만으로 섭니다. 아래 값들은 넣으면 늘어나는 것이고, 비우면 그 기능과 관련 워크플로우가 목록에서 조용히 빠집니다(눌렀다가 막히는 것이 아니라 아예 보이지 않습니다).

「한 번에 설정」을 누르면 이 값들을 먼저 묻습니다. 채워 넣고 저장하고 계속을 누르면 값을 설정 파일에 써 준 뒤 이어서 설치·로그인·필수 MCP·기본값까지 순서대로 갑니다 — Jira 주소를 방금 넣었으면 그 주소로 로그인 단계가 이어집니다. 지금은 넣고 싶지 않으면 건너뛰고 계속(값을 건드리지 않습니다) 또는 취소입니다. 폼만 열고 싶으면 점검 목록 맨 위 앱 설정 파일 행의 연동 설정 버튼을 눌러도 같은 칸이 나옵니다. 그 행에는 지금 쓰는 연동이 적혀 있습니다 — 아무것도 없으면 「연동 없음(로컬 git 만)」입니다.

Jira 를 켠 뒤의 세부 조직 값(상태 전이 이름 · 커스텀 필드 id · 자동 처리 대상)은 기본값 행의 설정 에서 이어서 정합니다. 대부분은 Jira 가 붙는 순간 앱이 실측해 채웁니다.

무엇을 하는 자리인가 — 프로젝트 타입#

Baton 은 프로젝트마다 타입을 가집니다 — 개발 · 학습 · 기획 · 통합 · 심플. 타입에 따라 보드 상세의 메뉴와 쓸 수 있는 워크플로우, AI 의 역할이 달라집니다. 자세한 것은 프로젝트 타입 을 보세요.

기존 프로젝트는 전부 개발 입니다. 공부하거나 기획하는 자리는 프로젝트를 붙이는 어느 자리에서든 타입을 골라 시작합니다 — 신규 프로젝트 추가 · 폴더에서 프로젝트 추가 · 워크스페이스 추가 · 프로젝트 추가(재스캔).

화면 구성 한눈에#

창 왼쪽의 레일 이 화면을 고르고, 맨 위 상단바 가 앱 전체 상태를 보여 줍니다. 레일의 번호 키(⌘1~⌘9)는 위에서부터 차례로 붙습니다(기능을 끄면 번호가 다시 매겨집니다).

사이드 패널 숨기기#

왼쪽에 목록이 붙은 화면 — 보드(트리·작업 목록) · 실행(워크플로우 목록) · 에이전트(역할 목록) · 위키(트리) · 모니터링(대시보드 목록) — 에서 그 목록을 숨겨 오른쪽 본문을 넓게 봅니다.

1. 본문 머리 왼쪽 끝의 패널 버튼(사이드 패널 숨기기)을 누르거나 ⌃` 를 칩니다.
2. 다시 열 때는 같은 자리의 버튼(사이드 패널 보이기)이나 ⌃` 를 한 번 더.

1

링크 — 어디서나 같은 네 갈래#

앱에서 누를 수 있는 링크는 모두 같은 네 가지로 열립니다. 세션 대화의 주소, 실행 로그 · 요약 · 티켓 설명 · 리뷰 코멘트 안의 링크, 문서 · 즐겨찾기 · PR · Jira 티켓 · 위키 · 성과의 근거 · 그룹 링크 · 모니터링 대시보드 — 어디에 적혀 있든 같은 메뉴, 같은 순서, 같은 말입니다.

1. 링크를 그냥 누릅니다. 링크 이름과 주소가 머리에 적힌 메뉴가 그 자리에 섭니다(오른쪽 버튼 · 트랙패드 두 손가락 탭도 같은 메뉴입니다 — 그때는 커서 옆).
2. 브라우저로 열기 — 시스템 기본 브라우저로 보냅니다. 메뉴의 첫 줄이라 종전 동작은 한 번 더 누르는 것으로 남습니다.
3. 앱에서 열기 — 앱 창 안의 팝업 뷰어로 봅니다. 잠깐 확인하고 닫을 때 씁니다.
4. 옆에서 열기 — 화면을 좌우로 나누고 오른쪽 칸 브라우저의 새 탭으로 엽니다. 띄워 놓고 반대쪽에서 일할 때입니다(브라우저).
5. 주소 복사 — 주소를 클립보드에 넣습니다(남에게 넘길 때).

드롭다운 — 고르는 칸은 모두 같다#

앱에서 목록을 펼쳐 고르는 칸은 모두 같은 칸입니다 — 실행 폼의 레포 · 스페이스 · 대상 worktree, 실행 기록의 거르개, 연동의 계정, Track 의 스페이스, 모니터링의 범위까지. 모양은 선택지 수가 정합니다.

1. 선택지가 다섯 개 이하면 누르면 펼치는 목록입니다. 칠 칸은 없고, 펼친 채 글자를 치면 그 글자로 시작하는 항목으로 갑니다.
2. 여섯 개 이상이면 쳐서 찾는 칸입니다. 이름 · 설명의 낱말로 좁혀지고 찾은 글자가 칠해집니다.
3. 공통 키: ↓ 펼치기 · 다음, ↑ 이전, ↵ 고르기, Esc 닫기(친 말만 되돌립니다), Tab 닫고 다음 칸. 칸에 손만 들어가서는 펼쳐지지 않습니다.
4. 비울 수 있는 칸은 맨 위에 「전체」 · 「정하지 않음」 같은 항목이 있고, 고른 값 오른쪽의 ✕ 로도 비웁니다.

1

칸마다 즐겨찾기(별)

쳐서 찾는 칸(여섯 개 이상)에서는 항목 끝에 ☆ 가 섭니다. 누르면 ★ 가 되고 그 항목이 목록 맨 위 즐겨찾기 묶음으로 올라갑니다 — 다음부터는 펼치자마자 보입니다. 다시 누르면 내려갑니다. 키보드로는 항목을 짚고 ⌘D 입니다.

12

보드 화면 구성#

123456

• 필터 — 티켓 키·레포 이름으로 트리와 목록을 좁힙니다(⌘F).
• 워크스페이스 트리 — 워크스페이스 › 프로젝트(레포) › worktree(과업) › 세션 › 서브에이전트.
• 작업 목록 — 세션 카드. 탭 전체 · 주의 · 실행 중 · 만료(각 칸에 건수 숫자)으로 거르고 밀도(촘촘·보통·여유)를 고릅니다. 내가 마지막으로 연 세션이 맨 위입니다.
• 정보 칩 — 티켓 요약 · PR · 변경 · 문서 · 이력 · 성과 · 프로젝트 · 링크, 그룹 세션이면 진행상황(상세 패널).
• 대화 와 입력창 — 세션과 주고받습니다(세션 대화).

워크스페이스 트리와 행 메뉴#

행의 ⋯ 버튼이나 우클릭이 같은 메뉴를 엽니다. 메뉴는 행의 종류(워크스페이스 · 프로젝트 · worktree · 세션)마다 다릅니다.

펼치고 접기 — 행마다 따로입니다

하위가 있는 행에는 왼쪽에 꺾쇠(>)가 섭니다. 누르면 펴지고 꺾쇠는 아래를 향합니다. 펼침은 행마다 따로라 다음 세 가지가 보장됩니다.

• 고르는 일은 펼침을 건드리지 않습니다 — 다른 행을 누르거나 방향키로 훑어도, 펴 둔 가지는 그대로 있고 새로 고른 가지가 저절로 열리지도 않습니다.
• 여러 가지를 동시에 펴 둘 수 있습니다 — 한쪽을 펴는 것이 형제를 접지 않습니다.
• 층마다 따로입니다 — worktree 를 펴면 세션이, 세션을 펴면 N agents 묶음이, 그것을 펴면 개별 서브에이전트가 나옵니다.

키보드는 행에 손을 얹고 ← — 그 행의 펼침 토글입니다(펴져 있으면 접고, 접혀 있으면 폅니다). 하위가 없는 행에서 ← 는 상위 행으로 올라갑니다. → 는 접힌 행을 펴고, 이미 펴져 있으면 행 메뉴를 엽니다.

트리 머리의 도구 셋

트리 위 워크스페이스 줄 오른쪽에 버튼 셋이 고정돼 있습니다 — 트리를 아무리 스크롤해도 같은 자리입니다.

모두 펼침 과 열린 세션으로 는 트리 블록 자체가 접혀 있으면 먼저 펴 줍니다(보여 달라는 뜻이니까요). 모두 접힘 은 블록을 건드리지 않습니다.

접고 편 모양은 그대로 남습니다 — 다른 화면에 갔다 오거나 앱을 다시 켜도 접어 둔 가지는 접힌 채입니다.

123

표기명을 고칠 수 있는 행(worktree · 세션 · 그룹 · 워크스페이스 · 프로젝트)은 그 행에서 Enter 를 누르거나 더블클릭하면 메뉴를 열지 않고도 바로 이름 칸이 됩니다. Space 는 그대로 고르기와 그룹·에이전트 묶음 접기펴기입니다 — 둘이 갈라지기 전까지는 Enter 도 같은 일을 했습니다. 워크스페이스 스코프 가상 worktree(「워크스페이스 세션」) · 그룹 안의 레포 노드 · 「분류 안 됨」 · 에이전트는 이름을 고칠 수 없습니다.

1

줄기 행의 ↓N · ↑N — 눌러서 받고, 눌러서 올립니다

기본(줄기) worktree 행의 기본 딱지 옆에는 그 브랜치가 원격과 얼마나 벌어졌는지가 섭니다 — ↓N 은 받을 것(원격에만 있는 커밋), ↑N 은 올릴 것(아직 안 올린 커밋)입니다. 원격과 같거나 아직 확인 전이면 아무것도 그리지 않습니다 — 정상까지 배지로 말하면 다른 행의 진짜 신호가 묻힙니다.

둘 다 버튼입니다. 누르면 그 자리에서 pull · push 하고, 도는 동안 그 배지만 … 로 바뀝니다(그 사이 다시 눌리지 않습니다). 끝나면 배지를 즉시 다시 재서 결과를 그대로 보입니다. 행을 고르거나 끌지 않습니다 — 배지를 누른 것은 「받아라 · 올려라」이지 「이 행을 고르라」가 아닙니다.

• ↓N — fast-forward 로만 당깁니다. 양쪽에 각자의 커밋이 있으면(갈라짐) 아무것도 하지 않고 알립니다 — merge 냐 rebase 냐는 사람이 정할 일입니다.
• ↑N — fast-forward 로만 올립니다. 강제 push 는 하지 않습니다. 받을 것이 있어 그냥은 못 올리면 아직 올리지 않은 채로 「원격에 새 커밋 N개가 있습니다 — 먼저 받은 뒤에 올릴까요?」를 묻고, 당기고 올리기 를 누르면 받은 뒤에 이어서 올립니다(받는 데 실패하거나 갈라져 있으면 올리지 않고 멈춥니다).
• 레포가 거절하면 그 사유를 그대로 보입니다 — 보호 브랜치나 서버 훅이 막는 레포에서는 그 메시지가 알림에 그대로 뜹니다. 앱이 우회하지 않습니다.

세션 행에는 상태 말고도 딱지가 붙습니다: 아직 안 본 결과가 있으면 새 결과, 이 세션을 워크플로우가 열었으면 워크플로우, Claude 가 선택지 카드 없이 글로만 묻고 멈췄으면 작업 목록 과 같은 답 대기 딱지가 새 결과 바로 앞에 섭니다 — 문구·색은 작업 목록과 같고, 그 세션에 답을 보내면 함께 빠집니다. 백그라운드로 건 일의 결과를 기다리는 세션에는 결과 대기 딱지가 섭니다(둘 이상이면 결과 대기 2 처럼 수가 붙고, 일이 끝나면 빠집니다). worktree 행에는 이 딱지들을 모아 보이지 않습니다(세션 행에서만 봅니다).

worktree 그룹 — 에픽처럼 묶어 보기#

여러 레포에 걸친 worktree 를 사람이 정한 그룹으로 모읍니다. 그룹은 이름과 링크 하나(에픽 · 기획서 · 스레드 등, 선택)만 가진 앱 자체 데이터라 Jira 에 매이지 않습니다. 그룹은 워크스페이스 바로 아래, 프로젝트보다 먼저 서고, 그 안에서도 레포 › worktree 구조를 그대로 보입니다 — 그룹 안에 그 그룹의 worktree 가 있는 레포마다 레포 노드(레포 이름 · 레포 색)가 서고, worktree 는 자기 레포 노드 아래에 섭니다. 그래서 에픽 이름과 어느 레포의 worktree 인지를 트리에서 한 번에 읽습니다.

1. 워크스페이스 행의 ⋯ › 그룹 만들기 — 이름과 링크(선택)를 넣고 만들기. 링크는 http:// · https:// 주소만 받습니다.
2. 넣기 — worktree 행을 그룹 안 어디든(그룹 행 · 레포 노드 · 구성원 행) 끌어다 놓습니다. 놓을 자리에 「그룹 이름」에 넣기 가 뜹니다. 어느 레포 노드 위에 놓든 worktree 는 자기 레포 노드 아래로 갑니다(레포는 바뀌지 않습니다). 마우스 없이는 worktree 행 메뉴 › 그룹으로 이동 에서 그룹을 고릅니다(맨 끝 새 그룹 만들기… 는 만들면서 바로 넣습니다). 다른 그룹의 worktree 를 옮기는 것도 같습니다.
3. 그룹 해제 — 그룹 안의 worktree 행을 그룹 밖 프로젝트 쪽 어디든(프로젝트 행 · 줄기 · 다른 worktree 행) 끌어다 놓습니다. 놓을 자리에 그룹 해제 가 뜨고, 놓으면 원래 자기 프로젝트 아래 제자리로 돌아갑니다. 다른 레포 쪽에 놓아도 해제만 하고 자기 레포로 돌아갑니다 — 그때는 표시가 그룹 해제 → 레포 이름 으로 돌아갈 곳을 말합니다. 돌아간 행은 골라지고 보이는 자리까지 스크롤되며, 「그룹에서 뺐습니다 — 레포 이름 로 돌아갔습니다」 알림이 뜹니다. 마우스 없이는 행 메뉴 › 그룹 해제, 또는 행에서 ⌥⌫.
4. 그룹 행 · 레포 노드를 누르거나 Enter · ← → 로 접고 펼칩니다. 그룹 행 오른쪽의 링크 버튼이 그룹의 링크를 브라우저로 엽니다.
5. 그룹 문서 — 그룹 행 메뉴 › 문서 추가 로 묶음 전체의 문서(에픽 기획서 · 설계서 · 스레드 · 로컬 HTML · Markdown · PDF)를 붙입니다. 구성원 worktree 가 아니라 그룹에 붙습니다 — 그래서 구성원 하나를 닫아도 남습니다. 붙인 문서는 그룹 행 아래 그룹 세션 줄을 골라 문서 칩에서 보고 · 열고 · 고치고 · 뗍니다. ⌘⇧F 통합 검색에서도 제목 · 주소로 찾을 수 있고, 목록에는 레포 대신 그룹 · 이름이 소속으로 섭니다 — 고르면 그 그룹의 문서 자리로 갑니다. 그룹 행에는 worktree 2 · 문서 1 처럼 몇 건인지 섭니다. 구성원 worktree 의 문서는 종전대로 각 worktree 자리에 있습니다(섞이지 않습니다).
6. 구성원 세션에 일괄 요청 — 그룹 행 메뉴에서, 이 그룹의 worktree 에 열려 있는 세션들에 같은 요청을 한 번에 넣습니다(다른 세션에 요청 보내기). 열린 세션이 없으면 항목이 서지 않습니다.
7. worktree 모두 닫기 — 그룹에 든 worktree 를 한 번에 기록으로 옮깁니다(그룹 닫기). 구성원이 없으면 항목이 서지 않습니다. 그룹 삭제 와 다릅니다 — 저건 묶음만 풀고 worktree 는 그대로 둡니다.
8. 그룹 삭제 는 묶음만 풀고 안에 있던 것은 제자리로 돌려보냅니다: worktree 는 자기 프로젝트 아래로, 그룹 문서·링크는 워크스페이스 자리로 옮겨져 거기서 계속 열립니다(사라지지 않습니다 — 종전에는 그룹과 함께 지워졌습니다). 그룹 세션은 닫힙니다 — 돌던 프로세스가 내려가고, 대화는 기록 › 닫힌 세션에 그룹 이름과 함께 남아 되살릴 수 있습니다.
9. 그룹 세션 — 그룹 행의 +(또는 행 메뉴 › 세션 추가)로 묶음 전체를 보는 세션을 엽니다. 이 세션은 구성원 worktree 하나(줄기 우선)의 폴더에서 뜨지만 어느 한 과업에 매이지 않고, 시작할 때 구성원마다 티켓 · PR · 체크 · 미해결 코멘트 · 변경 요약을 갱신해 맥락으로 받습니다. 구성원이 많으면 앞의 12개까지 싣고 몇 개를 싣지 않았는지 적습니다. 위에서 붙인 그룹 문서 도 구성원보다 먼저 맥락에 실리고, 이 세션에게 「이 링크 문서에 등록해줘」라고 말하면 그 그룹에 붙습니다(성과 · 티켓 연결과 이 worktree 자신의 표기명은 과업 하나에 붙는 기록이라 그 worktree 세션에서 말해야 합니다 — 세션이 그렇게 답합니다). 세션 · 그룹 · 프로젝트 · 워크스페이스의 표기명을 바꾸는 것은 이 세션에서도 됩니다 — 「이 그룹 세션들 이름을 순서 맞춰 바꿔줘」처럼 말하면 구성원 세션들을 한 번에 바꿉니다(AI 에게 baton 기능 시키기). 열린 세션은 그룹 행 바로 아래 그룹 세션 줄에 모입니다. 구성원이 하나도 없는 그룹은 뜰 폴더가 없어 + 와 행 메뉴 › 세션 추가 가 눌리지 않습니다 — 그 자리 툴팁(메뉴는 오른쪽 캡션)이 「worktree 를 먼저 넣으세요」라고 적습니다. ⌘N 으로 눌렀으면 같은 말을 알림으로 받습니다. worktree 행을 이 그룹에 끌어다 놓으면 바로 눌립니다.

123

1

그룹 안의 레포 노드는 그 레포의 프로젝트 행과 같은 대상입니다 — ⋯ 메뉴(worktree 만들기 · 열린 PR 보기 · 버전 히스토리 …)와 ⌘N 이 그 레포에 그대로 동작하고(다만 여기서 worktree 만들기 를 하면 만든 자리가 그 그룹 안에 섭니다), 메뉴 맨 끝 프로젝트 행으로 가기 가 그룹 밖의 원래 프로젝트 행(줄기와 그룹에 안 든 worktree 가 선 자리)으로 손을 옮깁니다. 레포 노드를 고르면(클릭 · 키보드 포커스) ⌘P 는 곧바로 그 레포를 대상으로 삼습니다 — 다만 상세 패널의 선택(worktree · 세션)은 바뀌지 않습니다. 그룹 안의 worktree · 세션을 고르면 그 worktree 의 레포가 그대로 대상이 됩니다 — 그룹은 트리가 보여 주는 자리만 바꿀 뿐입니다.

Jira 와 이어진 워크플로우는 그룹을 알아서 채웁니다

에픽 분해(일감 쪼개기(분해) 의 「일감마다 worktree 준비」) · 새 작업 시작(상위 티켓을 고른 경우) · worktree 만들기(티켓을 넣은 경우)가 worktree 를 만들고 티켓과 이으면, 그 티켓의 상위 에픽으로 그룹을 만들어 넣습니다. 이름은 에픽 키 + 제목(예: REPORT-4100 캠페인 브랜드 랭킹), 링크는 에픽 주소이고 행에 자동 딱지가 붙습니다. 같은 에픽이면 새로 만들지 않고 같은 링크의 그룹에 넣습니다 — 이름을 바꿨거나 그 링크로 직접 만든 그룹이어도 그렇습니다.

기획 프로젝트 — 대화로 정하고, 「구현」으로 넘기기#

기획 타입 프로젝트의 상세에는 기획 칩이 섭니다. 여섯 단계가 총론 → 경계 → 각론 순서로 서고, AI 와 대화하며 정한 것이 저절로 그 단계에 쓰입니다. 앞 다섯 단계를 정했음 으로 굳히면 디자인/설계 진행 이 디자인 · 설계를 채우고, 사람이 그 둘을 승인 하면 구현 이 열려 개발 레포의 main 머지까지 알아서 갑니다(아래 디자인 · 설계 승인 · 자율 구현). 이 흐름 전에 만든 기획은 확인 한 번으로 승인 없이도 구현합니다.

1. 대화하면 칩이 채워집니다 — 기획 프로젝트의 세션에서 이야기하다 한 단계가 모양을 갖추면, AI 가 그 단계를 초안 으로 씁니다(「등록해줘」라고 하지 않아도 됩니다). AI 가 쓴 단계에는 AI 딱지가 붙고, 칩을 열어 두었으면 그 자리에서 바뀝니다.
2. 「정했음」은 사람이 정합니다 — 대화에서 「이걸로 확정」처럼 말하면 AI 가 그 말을 근거로 정했음 을 올립니다. 앱이 그 말이 실제로 그 대화에 있었는지 확인하고, 없으면 올리지 않습니다 — AI 가 스스로 「정해졌다」고 판단해 올릴 수는 없습니다. 칩에서 직접 정했음 을 눌러도 됩니다. 고칠 것이 생기면 다시 초안.
3. 정한 것을 읽습니다 — 단계 행의 글 미리보기(두 줄)를 누르면 그 단계가, 칩 머리의 기획서 보기 를 누르면 여섯 단계 전체가 문서를 열 때와 같은 자리 · 같은 종이에 펼쳐집니다. 단계마다 번호 · 상태(정했음 · 초안 · 없음) · 누가 언제 썼는지가 서고, 글은 제목 · 목록 · 표가 그려진 문서로 보입니다. 아직 쓰지 않은 단계는 「아직 쓰지 않았습니다」로 섭니다. 머리의 단계 줄에서 전체 와 단계를 오가고, 대화로 돌아가기 로 닫습니다. 보는 사이 AI 가 단계를 고치면 그 자리에서 바뀝니다.
4. 그림판(HTML)으로 읽습니다 — 기획서 보기는 단계 글을 AI 가 그림 · 표 · 흐름도(사용자 여정 · 하는 것/안 하는 것 표 · 기능 지도 · 지표 그래프 · 사용자 카드)로 다시 그린 그림판을 먼저 엽니다. 정본은 여전히 단계 글(원문)입니다 — 그림판은 그 글을 다시 말할 뿐 새 내용을 더하지 않고, AI 도 원문을 읽습니다. 머리의 그림으로 · 원문(MD) 으로 바꿔 봅니다. 단계가 바뀌면 조금 뒤(기본 60초 — 저장이 몰려 와도 한 번) 앱이 기획서 그림판 그리기 를 스스로 돌려 다시 그립니다. 그동안은 이전 판이 그대로 보이고 머리에 갱신 중 — 이전 판(아직 시작 전이면 글이 바뀌었습니다 — 이전 판)이 섭니다. 지금 다시 그리려면 다시 그리기 — 기다리지 않아도 됩니다. 그림판이 아직 없으면 원문으로 열리고 그렇다고 알려 줍니다. 그림판은 스크립트를 끈 격리 창에 그려집니다.
5. 피드백을 모아 보내 반영합니다 — 칩 머리의 피드백(또는 기획서 보기의 읽기 · 피드백 중 피드백)을 누르면 git diff 에 리뷰 코멘트를 달듯 기획서에 피드백을 남깁니다. 자리는 셋입니다.
   • 기획서 총괄 — 맨 위 총괄 피드백. 여섯 단계 전체에 대한 말입니다.
   • 단계 전체 — 단계 머리의 이 단계에.
   • 줄 — 블록(문단 · 목록 항목 · 표 · 코드)에 마우스를 올리면 왼쪽에 + 가 섭니다. Shift 를 누른 채 다른 블록의 + 를 누르면 범위가 됩니다. 옆의 숫자는 그 단계 글의 줄 번호입니다.
   • 그림판에서 — 그림으로 보는 중이면 그림판의 블록(문단 · 항목 · 표 · 그림)을 누르면 그 자리가 골라지고, Shift 를 누른 채 같은 단계의 다른 블록을 누르면 범위가 됩니다. 오른쪽 칸에 원문 4~5줄 처럼 그 블록이 그린 단계 글의 줄과 글이 서고, 거기 쓴 피드백은 원문의 그 줄에 달립니다 — 원문(MD) 으로 바꿔도 같은 자리에 섭니다. 스레드는 오른쪽 칸에 단계별로 서고, 줄 단추(4~5줄)를 누르면 그림판의 그 자리로 갑니다. 그림판이 지금 글보다 앞선 판이면 고른 글로 지금 글의 자리를 찾고, 못 찾으면 그 단계 전체에 고른 글을 인용해 남깁니다.
   남긴 피드백은 보내기 전 상태로 모여 있고, 그동안은 고치거나 지울 수 있습니다. 다 남기면 머리의 피드백 N건 보내기 — 그 자리의 최근 세션(없으면 새로 엽니다)이 피드백마다 타당한지 판단해 단계를 고쳐 초안으로 다시 쓰고, 반영됨 또는 기각됨으로 답합니다. 보내고 기다리지 않아도 됩니다 — 답이 오면 그 자리에 붙습니다. 기각된 것은 다시 요청 하거나 기각 수용 으로 닫습니다. 피드백은 기록으로 남고, 칩의 단계 옆에 피드백 2 · 반영됨 1 처럼 섭니다 — 누르면 그 단계의 피드백으로 갑니다. 단계 글이 바뀌어 자리를 찾지 못한 피드백은 그 단계 머리 아래 지난 글에 단 피드백 으로 인용과 함께 섭니다.
6. 손으로 쓰고 고칩니다 — 단계 행의 쓰기 · 고치기(마크다운). 고치는 사이 AI 가 그 단계를 바꾸면 「그사이 이 단계가 바뀌었습니다」 띠가 서고 저장이 잠깁니다 — 지금 글 불러오기 로 새 글을 받거나 내 글 유지 로 내 글을 지킵니다. 모르고 덮는 일은 없습니다. 글을 비우면 상태가 없음 으로 돌아갑니다.
7. 이력 — 행 끝의 시계 단추가 그 단계의 이력(누가 · 초안/정했음 · 첫 줄)을 펴고, 이 글로 되돌리기 로 앞 글을 다시 씁니다. 되돌린 것도 이력에 남습니다(단계마다 최근 50개).
8. 구현 프로젝트 — 칩 머리의 구현 프로젝트 줄에서 연결 로 같은 워크스페이스의 개발 프로젝트를 잇고, 이름 옆 × 로 끊습니다. 기획이 프로젝트 그룹에 있으면 고르는 목록에는 그 그룹의 개발 프로젝트만 나옵니다(그룹에 고를 것이 없을 때만 그룹 없는 개발 프로젝트가 함께 나옵니다 — 다른 그룹의 것은 어차피 이을 수 없어 빼 둡니다). 같은 구현 프로젝트를 디자인 칩의 디자인 반영도 씁니다. 서비스 개발 시작으로 만든 개발 레포는 처음부터 구현 프로젝트로 이어져 있습니다. 이으면 두 프로젝트가 프로젝트 그룹으로 묶입니다(없으면 기획 이름으로 새로 · 한쪽만 그룹에 있으면 그 그룹으로). 서로 다른 그룹에 있거나 다른 워크스페이스면 잇지 않습니다.
9. 플랫폼 — 한 서비스가 iOS · Android · 웹 · macOS · Windows · iPad 처럼 여러 곳에 나갈 때 씁니다. 구현 프로젝트 줄 아래 플랫폼 줄의 플랫폼 더하기 로 미리 준비한 이름을 고르거나 직접 적고(한글만인 이름은 디자인 · 설계 폴더에 쓸 영문 키를 함께 적습니다), 그 플랫폼을 만드는 구현 프로젝트를 고릅니다. 줄에는 iOS → snap-ios 처럼 플랫폼마다 담당 구현 프로젝트가 서고, 담당이 없으면 구현 프로젝트 없음으로 섭니다.
   • 플랫폼 현황 — 플랫폼이 있으면 플랫폼 줄 아래에 표가 섭니다. 행은 공통과 플랫폼마다, 열은 기획 → 디자인 → 설계 → 승인 → 구현 → 출시 순서입니다. 「iOS 는 구현 중, Android 는 디자인 승인 필요, 웹은 구현 프로젝트 없음」을 한 장에서 읽습니다. 점선의 공통 그대로 는 일을 안 한 것이 아니라 다를 것이 없다는 뜻입니다. 디자인 칸을 누르면 그 플랫폼으로 걸러진 디자인 칩이, 구현 칸을 누르면 그 실행이 열리고, 출시 칸을 누르면 출시 표시를 켜고 끕니다.
   • 서비스 개발 시작 에서 대상 플랫폼을 둘 이상 고르면(예: 크로스플랫폼 모바일 → iOS · Android) 기획에 처음부터 플랫폼이 서고, 처음 만든 개발 레포가 공통과 그 플랫폼 전부를 담당합니다. 나중에 플랫폼별 레포를 이으면 담당을 나눕니다.
   • 담당 플랫폼 — 구현 프로젝트마다 무엇을 만드는지 정합니다. 서버 · API 레포는 공통, 한 레포가 iOS · Android 를 함께 만들면(Flutter 등) 둘 다 고릅니다. 플랫폼이 하나라도 있는데 담당을 정하지 않은 구현 프로젝트가 있으면 줄에 경고가 섭니다.
   • 플랫폼 칩을 누르면 — 이름 바꾸기 · 출시로 표시(다시 누르면 지웁니다) · 플랫폼 빼기. 빼도 그 플랫폼의 내용은 지우지 않아 같은 키로 다시 더하면 돌아옵니다. 키는 폴더 이름이라 바꾸지 않습니다.
   • 플랫폼 차이 — 플랫폼이 있으면 공통 글이 있는 단계 행에 플랫폼 차이 단추가 섭니다. 플랫폼을 고르면 그 플랫폼에서만 공통 글과 다른 것만 씁니다(예: iOS — 다시 열 때 Face ID 로 잠금 해제). 공통 글을 복사하지 않습니다 — 비어 있는 플랫폼은 「공통 그대로」입니다. 차이도 공통 단계처럼 초안 · 정했음 · 이력이 있고, 기획 대화의 AI 도 「iOS 에서만」 같은 말을 들으면 그 플랫폼의 차이 칸에 씁니다. 「구현」은 구현 프로젝트가 담당하는 플랫폼의 차이만 함께 넘깁니다.
   • 플랫폼 시안 · 플로우맵 · 설계 — 플랫폼이 있으면 디자인 칩 맨 위에 플랫폼 줄(전체 · 공통 · 플랫폼마다)이 섭니다. 플랫폼을 고르면 그 플랫폼에서 보이는 목록 — 그 플랫폼의 파일과, 그것이 덮지 않은 공통 파일 — 입니다. 플랫폼 파일 행에는 플랫폼 딱지와 공통을 덮음이, 공통 파일을 복사해 시작한 뒤 공통이 다시 바뀌었으면 공통이 바뀜 · 공통 v4 가 섭니다(조용히 낡지 않게). 공통 파일 행에는 따로 그린 플랫폼이 iOS 는 따로 그림 처럼 적힙니다. 플로우맵은 플랫폼마다 그리고, 로고 · BI 는 공통에만 둡니다. 설계는 인프라 · HLD · 결정 · 검증 기준이 공통에 하나이고, 플랫폼마다 다른 기술 스펙 · LLD · 컴포넌트 스펙만 플랫폼 딱지를 달고 섭니다. 공통 승인은 공통 파일만 셉니다.
   • 플랫폼마다 승인 — 디자인 · 설계 승인 띠 아래에 플랫폼마다 한 줄이 섭니다. 그 플랫폼에서만 다른 파일이 없으면 공통을 따름(누를 것이 없습니다), 있으면 승인 필요 와 승인 단추가 섭니다. 승인한 뒤 그 플랫폼 파일이 바뀌거나 새로 생기면 승인 뒤 바뀜, 그 플랫폼의 기획 차이가 바뀌면 기획 차이가 바뀜 으로 풀립니다. 구현 창에서는 담당 플랫폼이 아직 승인되지 않은 구현 프로젝트가 이유와 함께 잠긴 줄로 섭니다 — iOS 만 승인되면 iOS 를 담당하는 구현 프로젝트만 갑니다.
   • 공통 먼저 — 공통(서버 · API)을 담당하는 구현 프로젝트와 플랫폼 구현 프로젝트를 함께 구현하면, 공통 구현이 main 에 머지된 뒤 플랫폼 구현이 시작합니다(창을 닫아도 그대로 갑니다). 기다리지 않으려면 구현 창의 공통을 기다리지 않고 함께 시작 을 켭니다 — API 가 없는 동안 앱은 임시 대체품으로 짓습니다.
   • 디자인 반영 · 준비물 — 플랫폼 시안의 디자인 반영은 그 플랫폼을 담당하는 구현 프로젝트로만 갑니다. 공통 시안은 화면을 따로 그린 플랫폼과 공통만 담당하는 구현 프로젝트를 이유와 함께 뺍니다. 연결이 없을 때 기존 프로젝트 고르기 · 신규 프로젝트 만들기 에는 담당 플랫폼 칸이 섭니다. 설계의 준비물은 적힌 플랫폼을 담당하는 구현 프로젝트의 .env.local 로 갑니다(비우면 공통 담당).
   • 플랫폼은 워크트리가 아닙니다 — 「다음 달에 결제를 더한다」는 신규 기능(워크트리), 「iOS 에서만 다르게」는 플랫폼입니다. 플랫폼이 없는 기획은 지금처럼 하나의 플랫폼으로 돕니다.
10. 구현 — 디자인 · 설계 두 승인이 서야 켜집니다(아래 디자인 · 설계 승인). 꺼져 있으면 단추에 자물쇠가 서고, 그 아래 단계 띠가 이유를 적습니다. 확인 창이 먼저 아직 쓰지 않은 단계 · 초안인 단계와 임시 대체품으로 갈 준비물을 알려 줍니다.
    • 구현 프로젝트가 있으면 — 대상(기본 전부)을 확인하고 구현 시작. 대상마다 자율 구현이 시작됩니다 — 일감으로 나눠 하나씩 구현 · 검증 · 리뷰하고 그 레포의 main 에 머지합니다. 대상이 여럿이면 각 실행이 자기 레포의 몫만 합니다.
    • 구현 프로젝트가 없으면 — 기존 프로젝트 고르기 또는 신규 프로젝트 만들기(저장할 위치 · 이름 · 무엇을 만드나). 고른 프로젝트는 구현 프로젝트로 연결되고 그룹에 묶여 다음부터는 묻지 않습니다. 신규는 뼈대를 만든 뒤 구현이 시작됩니다 — 창을 닫아도 계속됩니다.
    • 다시 누르면 — 지난 구현이 끝까지 갔으면 그 뒤 바뀐 것만(승인한 디자인 · 설계 문서의 판 · 기획 단계) 일감으로 만들어 이어 갑니다. 바뀐 것이 없으면 아무것도 시작하지 않습니다. 지난 구현이 중간에 끊겼으면 처음부터 계획하되 이미 머지된 일감은 다시 만들지 않습니다. 아직 도는 중이면 끝난 뒤 다시 누르라고 알려 줍니다.
    창은 기다리지 않습니다 — 시작하면 바로 닫히고, 끝나면 알림이 옵니다. 진행은 실행 화면과 Track 의 일감에서 봅니다.

1

12

12

12

12

12

12

1

디자인 · 설계 승인 — 「구현」을 여는 두 승인

기획은 기획 → 디자인 · 설계 → 승인 → 구현 순서로 갑니다. 기획 칩 머리에 디자인/설계 진행 과 구현 이 나란히 서고, 그 아래 단계 띠가 디자인 ✓/✗ · 설계 ✓/✗ 와 이유를 적습니다. 디자인 칩 옆에는 설계 칩이 섭니다(기획 · 통합 프로젝트).

1. 디자인/설계 진행 — 앞 다섯 단계(배경 · 목표 · 사용자 · 범위 · 기능 명세)가 모두 정했음 이어야 켜집니다. 누르면 디자인 세션(기준 · 가이드 · 지면별 시안 · 프로토타입 · 플로우맵)과 설계 세션(인프라 · 기술 스펙 · HLD · 컴포넌트 스펙 · LLD · 결정 · 준비물)이 함께 돕니다. 창을 잡지 않습니다 — 끝나면 알림이 옵니다. 도는 동안 단추는 디자인/설계 진행 중… 으로 잠기고 옆에 실행 보기 가 섭니다(같은 자리에서 두 번 띄우지 않습니다). 반쯤 쓴 문서라 그동안은 승인 과 구현 도 잠깁니다. 다시 누르면 빠진 칸만 채웁니다.
2. 설계 칩 — 타입 일곱 칸(인프라 아키텍처 · 기술 스펙 · HLD · LLD · 컴포넌트 스펙 · 검증 기준 · 결정 · 준비물)이 늘 섭니다. 빈 칸은 점선 자리로 남아 무엇이 빠졌는지 말합니다. 문서는 그림(SVG) · 표가 든 HTML 한 장씩이고, 행의 열기 로 앱 안 · 옆에서 · 브라우저 중에 골라 엽니다. 행의 ⋯ › Baton Drive 에 올리기 로 다른 사람에게 보일 자리(Baton Drive 의 워크스페이스 › 프로젝트 › 설계)에 올립니다. 판(v3 · 이전 판 2)을 누르면 이전 판이 펼쳐집니다. 결정 · 준비물 행 아래에는 결정마다 정함 / 열림 이 섭니다. 문서마다 AI 가 읽고 고치는 원문(MD) 이 짝으로 있습니다 — 사람은 그림(HTML)을 보고, AI 는 원문을 먼저 고친 뒤 그림을 다시 그립니다. 행의 원문(MD) 열기 로 원문을 보고, 원문이 그림보다 새로우면 그림이 원문보다 오래됨 이 섭니다(수정 요청 으로 다시 그리게 합니다). 원문이 없거나 결정 표가 그림과 어긋나면 칩 머리 아래 경고 줄이 적습니다 — 승인을 막지는 않지만, 승인 뒤 원문만 고쳐도 승인이 풀립니다.
3. 검증 기준 — 「구현이 끝났다」를 기술 관점에서 판정하는 표입니다(Oracle). 기준마다 갈래(기능 · API 계약 · 데이터 불변식 · 비기능 · 흐름) · 가리키는 것(기능 명세의 수용 기준 · LLD 절 · 플로우맵 경로) · 확인 방법(명령 · 테스트 · 측정) · 통과 조건(종료 코드 0 · p95 < 300ms · 0건)이 한 줄로 섭니다. 디자인/설계 진행 이 LLD 뒤에 채웁니다. 기준이 하나도 없거나 확인 방법 · 통과 조건이 빈 기준이 있으면 승인 띠에 검증 기준 N 줄이 서고 승인 이 잠깁니다 — 「잘 동작한다」처럼 확인할 수 없는 기준으로는 구현이 끝났는지 말할 수 없기 때문입니다. 근거 없는 수치 목표는 지어내지 않고 결정 · 준비물 의 열린 결정으로 올라갑니다.
4. 문서 고치기 — 행의 수정 요청 을 누르면 창이 열립니다. 무엇을 고칠지 적고(절 · 그림 번호로 짚으면 한 번에 갑니다) 수정 맡기기 — 이 기획 자리에 설계 수정 세션이 열려 같은 파일을 고치고 판을 올립니다. 문서 안의 안 고친 코멘트도 함께 반영하고, 새 결정이 생기거나 열린 결정에 답이 되면 결정 · 준비물 문서도 같이 고칩니다. 창은 바로 닫히고, 고친 결과는 이 목록의 판으로 보입니다. 코멘트는 글머리표 줄(- §3.2 · 그림 4: 캐시 경계를 그려 주세요)로 적어 복사한 뒤 행의 클립보드의 코멘트를 문서에 적기 로 문서에 넣습니다 — 코멘트만 반영하려면 수정 요청 창을 비워 둔 채 맡깁니다. 판 · 코멘트를 적을 자리가 없는 문서(코멘트 못 닮)에는 코멘트 달 수 있게 고치기 가 먼저 섭니다. 설계가 승인돼 있으면 창이 먼저 알려 줍니다 — 문서가 바뀌면 승인이 풀리고(승인 뒤 바뀜) 구현 이 다시 잠기니, 고친 뒤 다시 승인 합니다.
5. 승인 띠 — 디자인 칩(기획 · 통합 프로젝트)과 설계 칩 머리에 섭니다. 상태는 넷입니다: 승인 안 됨 · 승인됨(시각) · 승인 뒤 바뀜(승인한 파일이 바뀌거나 사라짐 — 바뀐 파일) · 기획이 바뀜(앞 다섯 단계가 바뀜 — 바뀐 단계). 필수 칸이 빠졌거나 열린 결정이 남았으면 승인 이 잠기고 그 이유를 띠가 적습니다. 풀리면 다시 승인, 거두려면 승인 거두기. 승인은 사람이 이 띠에서 누른 것만 셉니다 — AI 가 승인할 수는 없습니다.
6. 준비물 — 설계 띠의 준비물 3 · 채움 1 · 임시 대체품 2 를 누르면 API 키 · 계정처럼 사람만 준비할 수 있는 것이 펼쳐집니다. 값 칸(가려진 칸)에 넣고 저장 하면 연결된 개발 레포의 .env.local 에만 쓰고 칸을 비웁니다 — 앱 · 대화 · 기록 어디에도 값이 남지 않습니다. 채우지 않은 것은 승인을 막지 않고, 구현이 없으면: 에 적힌 임시 대체품(mock · stub)으로 돌립니다. 구현이 끝난 뒤 키를 채우면 준비물 줄 아래 임시 키 → 실제 키 교체 가 켜집니다(SEARCH_API_KEY — 임시 대체품 2곳) — 누르면 그 자리를 실제 키를 쓰는 구현으로 바꿉니다(임시 키 → 실제 키 교체). 키를 아직 채우지 않았으면 단추는 꺼진 채 … 를 채우면 켜집니다 를 적습니다.
7. 구현 — 두 승인이 서면 켜집니다. 승인한 파일이나 앞 다섯 단계가 바뀌면 승인이 풀려 다시 잠깁니다.
8. 기존 기획 — 이 흐름 전에 만든 기획은 잠그지 않습니다. 단계 띠가 기존 기획이라 잠그지 않습니다 를 적고, 구현 을 누르면 디자인 · 설계 승인 없이 구현합니다 확인을 한 번 거칩니다. 띠의 새 흐름으로 를 누르면 그때부터 두 승인 뒤에만 열립니다(되돌리지 않습니다). 기획의 시안을 개발 레포로 옮기는 디자인 반영도 같은 규칙입니다 — 새 흐름이면 디자인 승인 뒤에 열립니다.

123

123

1

1

12

12

1

1

12

자율 구현 — 「구현」을 누르면 main 머지까지

구현 은 사람이 옆에 붙어 있지 않아도 개발 레포의 main 에 머지하는 데까지 갑니다(원격 push · 배포는 하지 않습니다). 실행 화면에는 자율 구현, 일감마다 자율 구현 — 일감 실행이 섭니다.

1. 구현 준비 — 승인한 디자인 · 설계 문서(판까지) · 결정 · 준비물(채움 / 대체품 — 값은 싣지 않습니다)을 모읍니다. 서비스 개발 시작으로 만든 개발 레포의 첫 구현이면 먼저 기술 스펙대로 뼈대를 세우고 디자인 기준을 옮겨 main 에 커밋한 뒤 맵 · 하네스를 셋팅합니다.
2. 일감 나누기 — LLD · 컴포넌트 스펙 · 플로우맵을 읽어 일감 목록을 만들고, 일감마다 그 일감이 채우는 검증 기준을 묶습니다(일감 글의 채우는 검증 기준: O1 · O3) Track 에 목표 하나와 일감으로 그대로 세웁니다(승인 카드 없음). 일감마다 완료 기준(검증 명령)과 먼저 끝나야 하는 일감이 적힙니다.
3. 일감 구현 · 머지 — 일감을 하나씩 차례로: 자기 자리(build/<일감 키>)에서 구현 → 완료 기준 · 레포 테스트 → 다른 세션의 리뷰 → 지적이 있으면 고침. 통과하면 main 을 먼저 얹어 검증을 다시 돌리고 main 에 머지합니다. 충돌이나 실패면 main 은 그대로 두고 그 일감만 보류합니다.
4. 통합 검증 · 결과 보고 — main 에서 전체 검증을 돌리고 앱 안 브라우저로 플로우맵의 화면을 시안과 대조한 뒤, 검증 기준을 하나씩 돌려 통과 · 실패 · 미확인을 판정합니다(돌려 보지 않은 기준은 통과로 치지 않습니다). 보고서 맨 위에 검증 기준 5 — 통과 4 · 실패 1 · 미확인 0, 아래에 기준별 표(실패 · 미확인 먼저)가 섭니다. 신규 기능의 구현은 기준이 하나라도 통과하지 못하면 자동 통합을 하지 않습니다. 마지막 스텝에 머지된 일감 · 보류 일감(이유) · 결정 기록 · 대체품 목록 · 걸린 시간이 섭니다.

• 묻지 않습니다 — 구현 세션은 끝까지 자동 승인으로 열리고 질문 창을 띄우지 않습니다. 작은 결정은 설계 · 결정 문서 기준으로 정해 결정 기록(설계 자리의 build-log.html)에 남깁니다.
• 큰 결정은 그 일감만 멈춥니다 — 데이터 모델 변경 · 외부 서비스 추가 · 비용이 드는 선택이 필요하면 그 일감이 보류(사람 결정 필요)로 서고 알림이 갑니다 — 앱 안에는 토스트(사람 결정 필요 — 서비스 이름 · 일감 키 · 제목 · 이유 · 실행으로 가기), 앱 창을 보고 있지 않으면 macOS 알림 센터로도(창을 닫아 두었어도 옵니다 · 누르면 그 일감의 실행 화면으로). 끄려면 설정 › OS 알림 의 워크플로우 실행 결과. 나머지 일감은 계속 갑니다. Track 에서 이유를 보고 정한 뒤 구현 을 다시 누르면 이어 갑니다.
• 준비물이 비었으면 임시 대체품으로 — 채우지 않은 API 키 · 계정은 임시 대체품(mock · stub)으로 구현하고 코드에 BATON-FALLBACK(키 이름) 표시를 남깁니다. 보고서가 그 표시를 모아 보여 줍니다. 나중에 키를 채우면 임시 키 → 실제 키 교체 가 그 표시를 따라 실제 키를 쓰는 구현으로 바꿉니다 — 설계 칩의 준비물 줄이나 개발 레포의 프로젝트 칩에서 누릅니다.
• 상한 — 일감 하나의 고침은 최대 5번, 같은 실패가 3번 나오면 그 일감은 보류됩니다. 전체가 8시간을 넘기면 새 일감을 시작하지 않고(도는 것은 마칩니다) 남은 일감은 시간 상한으로 보류됩니다. 설정 파일의 workflows.autoBuildMaxHours · autoBuildMaxFix · autoBuildSameFail 로 바꿉니다.
• 머지된 일감의 자리는 닫히고, 보류된 일감의 자리는 남겨 사람이 이어서 볼 수 있습니다.

고도화 · 기능 추가 — 기능 워크트리

1차 구현이 끝난 기획은 main(기본 워크트리)이 실제로 구현된 서비스의 정본 기획이 됩니다. 고도화나 기능 추가는 main 을 직접 고치지 않고, 기획 프로젝트에 기능 워크트리를 하나 파서 그 안에서 기획합니다. 워크트리를 파는 순간 그때의 main 을 복사한 신규 기능이 서고, 그 기능의 기획 · 디자인 · 설계 · 승인은 그 신규 기능에만 쌓입니다. 신규 기능의 구현이 개발 레포 main 에 다 머지되면 신규 기능이 main 으로 통합됩니다.

1. 기능 워크트리 만들기 — main 의 기획 칩 머리에 1차 구현 완료 — 고치려면 기능 워크트리 띠가 서고, 단계의 고치기 · 정했음 · 디자인/설계 진행 · 디자인 · 설계 칩의 승인 · 수정 요청 이 잠깁니다(단추에 마우스를 올리면 이유가 섭니다). 띠의 기능 워크트리 만들기 를 누르면 트리의 worktree 만들기 와 같은 창이 이 프로젝트로 채워져 열립니다 — 브랜치 이름(예: feature/CPN-210)을 적고 실행. 디자인 · 설계 칩에도 같은 띠가 섭니다. main 의 구현 은 남은(보류) 일감을 이어 갈 때만 씁니다.
2. 그 워크트리에서 기획합니다 — 트리에서 기능 워크트리를 고르면 기획 · 디자인 · 설계 칩과 기획서 보기 가 모두 그 신규 기능을 봅니다. 기획 칩 머리에 신규 기능 — 브랜치 딱지 · 상태(열림 · 통합됨 · 버림) · main 대비 바뀐 단계 N 이 섭니다. 단계를 고치는 법은 main 과 같습니다(대화 · 피드백 · 손).
3. 디자인/설계 진행(바뀐 것만) — 신규 기능의 디자인/설계 진행 은 빈 칸을 채우는 대신 main 대비 바뀐 기획 단계를 받아 영향받는 시안 · 문서만 고칩니다. 디자인 · 설계 칩의 행에는 이 신규 기능(여기서 고친 사본 · 새 문서)와 main 본(main 의 것을 그대로 보는 중)이 섭니다. main 본 에 수정 요청 을 보내면 앱이 먼저 신규 기능 자리로 복사한 뒤 그 사본을 고칩니다 — main 은 통합 때만 바뀝니다.
4. 두 승인 — 신규 기능의 디자인 · 설계를 승인 합니다. 승인도 신규 기능마다 따로입니다.
5. 구현(차이만) — 신규 기능의 구현 은 main 과 다른 것(바뀐 단계 · 바뀐/새 문서)만 일감으로 만듭니다. 한 기획에서 자율 구현은 하나씩 돕니다 — 다른 신규 기능의 구현이 도는 중이면 끝난 뒤 다시 누르라고 알려 줍니다.
6. 보류 없이 끝나면 저절로 통합 — 일감이 모두 머지되면 신규 기능이 main 으로 통합됩니다(기획 단계 · 여기서 고친 시안 · 문서가 main 에 새 판으로 올라가고 이전 판은 남습니다). 보류가 남았거나 먼저 보내려면 신규 기능 띠의 기획 통합 — 확인 창이 main 으로 가는 것(기획 단계 · 디자인 · 설계)을 읊고 main 으로 통합 으로 보냅니다. 기획 통합 이 잠겨 있으면 마우스를 올려 이유(반영 필요 · 승인 필요)를 봅니다. 통합한 신규 기능의 워크트리는 닫아도 됩니다.
7. 다른 신규 기능은 반영 — 다른 신규 기능이 먼저 통합하면 남은 신규 기능에 main 이 바뀌었습니다 — 반영 필요 띠가 서고 바뀐 단계 · 디자인 · 설계가 적힙니다. 반영 을 누르면 기획 반영 실행이 갈라질 때 main · 이 신규 기능 · 지금 main 세 쪽을 견줘 합칩니다 — 한쪽만 바뀐 것은 앱이, 둘 다 바뀐 것은 AI 가 합쳐 초안으로 씁니다. 합친 것은 승인이 다시 필요하고, 합치지 못한 것은 설계의 열린 결정으로 올라가 사람이 정합니다. 창을 닫아도 계속되고 끝나면 알림이 옵니다. 통합은 반영한 뒤에 됩니다.

• 통합 밖에서 바뀐 파일 — 잠긴 main 의 시안 · 설계 파일을 누군가 직접 고쳤으면 잠금 띠 아래 통합 밖에서 바뀐 파일: 경고가 섭니다. 기능 워크트리에서 고쳐 통합하세요.
• 기존 기획(새 흐름으로 옮기지 않은 기획)의 워크트리는 신규 기능이 아니라 종전처럼 main 을 고칩니다.
• 신규 기능으로 전환 — 새 흐름으로 옮기기 전에 판 워크트리는 신규 기능이 서지 않아 main 을 직접 고칩니다(이대로 구현 하면 이 기능의 차이가 아니라 기획 전체가 일감으로 갑니다). 그 워크트리를 고르면 기획 칩에 신규 기능이 아닙니다 띠가 서고, 신규 기능으로 전환 을 누르면 확인 창이 워크트리를 판 때 뒤에 main 에 쓰인 기획 단계 · 디자인 · 설계와, 되돌릴 판이 없어 main 에 남는 것(설계 원문 MD 등)을 읊습니다. 전환하면 그것들이 이 워크트리(신규 기능)로 옮겨지고 main 은 판 때로 돌아갑니다 — 단계는 이력에 남아 되돌릴 수 있고, 파일은 판 때의 판 사본으로 돌아가거나(그 뒤에 생긴 파일이면) main 에서 빠집니다. 이 기획에서 디자인/설계 진행 · 구현 · 반영 이 돌고 있거나, 판 뒤에 다른 신규 기능이 main 으로 통합됐거나 main 으로 구현이 돌았거나, 다른 자리의 세션이 main 단계를 고쳤으면 단추가 잠기고 이유가 섭니다 — main 을 되돌리면 남의 결과가 사라지기 때문입니다. 그때는 새 기능 워크트리를 파서 옮겨 씁니다.

123

123

123

12

1

학습 프로젝트 — 커리큘럼으로 공부하기#

학습 타입 프로젝트의 상세에는 커리큘럼 칩이 섭니다. 무엇을 어떤 순서로 공부하는지, 어디까지 왔는지, 다음 장을 시작하는 버튼이 한 자리에 있습니다.

맨 위에 지금 할 일 한 줄이 섭니다 — 「무엇을 눌러야 하나」에 화면이 먼저 답합니다. 커리큘럼이 없으면 짜기, 진행 중인 장이 있으면 그 장을 이어서, 없으면 다음 장을 시작, 장을 다 끝냈으면 남은 복습입니다. 옆의 버튼은 그 일을 바로 합니다 — 차례에서 그 장을 다시 찾아 누르지 않아도 됩니다. 오늘 볼 복습이 있으면 한 줄 더 붙지만, 공부하던 장이 먼저입니다(벌여 둔 자리를 두고 다른 것을 권하면 공부가 흩어집니다).

1. 커리큘럼은 저절로 짜입니다 — 학습 타입으로 프로젝트를 붙이는 어느 자리에서든 커리큘럼 짜기가 바로 돕니다: 신규 프로젝트 추가 · 폴더에서 프로젝트 추가 · 워크스페이스 추가 · 프로젝트 추가(재스캔). 따로 누를 것도, 저장 전에 확인할 것도 없습니다 — 끝나면 차례가 서 있습니다. 과목은 적어 준 글(「무엇을 공부하나」 · 역할 코멘트)의 첫 줄이고, 비웠으면 프로젝트 이름입니다.
2. 직접 짜거나 다시 짜려면 칩을 눌러 커리큘럼 짜기. 무엇을 공부하나 에 「일본어 N2」·「Kafka 운영」처럼 적습니다(종류를 고르는 칸은 없습니다 — 적은 말이 그대로 과목명입니다). 지금 수준·목표, 쓸 수 있는 시간, 참고 자료는 선택입니다. 차례가 마음에 안 들면 다시 돌리면 됩니다 — 시작한 장은 지우지 않습니다.
3. AI 가 그 과목의 선생도 함께 만듭니다 — 어떤 사람으로 가르칠지(「JLPT 를 10년 가르쳐 온 강사」), 내 수준에 맞춘 방식, 그 과목에서 자주 막히는 자리를 들고 있는 선생입니다. 그 선생이 에이전트 목록에 서고, 챕터를 시작하면 그가 붙습니다. 범용 선생과 가장 크게 갈리는 것이 「자주 막히는 자리」입니다 — 묻기 전에 먼저 짚어 줍니다.
4. AI 가 챕터 차례(4~12장)와 학습 방식을 정해 옵니다. 학습 방식은 네 가지입니다 — 실습 코드(산출물이 코드인가) · 복습(잊는 것이 문제인가) · 평가(시험으로 넘어가는가) · 리듬(매일·주 단위·비정기). 이 값이 화면에 무엇을 보여 줄지 정합니다. 장마다 목표 학습 시간과 통과 기준도 함께 옵니다.
5. 확인 창에서 차례를 고쳐서 저장할 수 있습니다. 저장해도 폴더는 아직 만들지 않습니다 — 차례는 기록일 뿐입니다.
6. 챕터 시작 — 그 장의 시작 을 누르면 chapter/<번호>-<제목> worktree 가 그때 생기고, 트리에 그 자리가 서고, 선생이 붙은 세션이 열립니다. 20장 커리큘럼이 폴더 20개를 미리 차지하지 않습니다.
7. 이어서 하기 — 진행 중인 장에는 세션 버튼이 있고, 맨 위 지금 할 일 의 이어서 하기 도 같은 자리로 갑니다. 새로 열린 세션도 지난번까지 쓴 노트를 읽고 뜨므로, 선생이 1강부터 다시 시작하지 않습니다 — 마지막으로 하던 자리를 짧게 되짚고 이어서 갑니다.
8. 끝냄 / 다시 열기 — 끝내는 것은 사람이 누릅니다(선생이 스스로 끝내지 않습니다). 누르면 그 장의 통과 기준과 선생이 올린 증거를 읽어 주고 한 번 더 묻습니다(바로 아래 목표 달성도). 기준이 없는 옛 커리큘럼이면 목표 한 줄을 읽어 줍니다 — 목표는 「…을 할 수 있다」로 적히므로 그것이 곧 기준입니다. 진도(3/8 · 38%)는 끝낸 장의 비율로 셉니다. 끝낸 장도 다시 열기 로 돌아갈 수 있습니다 — 복습하러 들어간 자리입니다.
9. 다시 짜기 — 차례는 공부하는 동안 바뀝니다. 다시 짜도 이미 시작한 장은 남습니다(그 자리에 worktree·세션·커밋이 붙어 있습니다).

1

수업은 정해진 차례로 갑니다 — 지금 어디쯤인지 보입니다

한 장은 늘 같은 차례를 지납니다: 되짚기 → 오늘 할 것 → 개념 → 확인 → 실습 → 정리 → 마무리. 선생이 단계를 옮길 때마다 올리고, 커리큘럼의 그 장에 「수업 3/7 · 개념」 으로 섭니다 — 설명이 언제 끝나는지, 실습은 하는지, 지금 어디까지 왔는지를 물어보지 않아도 됩니다.

• 개념과 확인은 여러 번 오갑니다 — 한 조각 설명하고 되묻고, 또 한 조각. 막히면 앞 단계로 돌아갑니다.
• 실습 은 실습 코드 공부에만 섭니다. 어학·독서는 여섯 단계이고 「하지 않아도 되는 일」이 남은 것처럼 보이지 않습니다.
• 마무리 에서 선생이 무엇이 채워지고 무엇이 남았는지를 말합니다 — 「넘어가셔도 됩니다」는 선생이 아니라 화면이 말합니다(바로 아래).

목표 학습 시간 — 이 장은 몇 시간쯤 쓰는 게 합리적인가

장마다 목표 시간이 적힙니다(「1시간 30분」). 커리큘럼을 짤 때 AI 가 쓸 수 있는 시간을 근거로 정하고, 한 장은 보통 1~3시간입니다 — 그보다 길어지는 주제는 장을 둘로 쪼갭니다.

• 어디에 보이나 — 차례의 그 장 제목 옆 · 지금 할 일 줄(「… 를 시작하세요 · 예상 1시간 30분」) · 커리큘럼 머리의 남은 N시간. 머리의 수는 아직 끝내지 않은 장의 합이라 「오늘 어디까지 할까」에 바로 답합니다. 일부 장만 시간이 정해져 있으면 그 사실이 툴팁에 적힙니다.
• 선생이 그 시간에 분량을 맞춥니다 — 이게 이 기능의 핵심입니다. 챕터를 시작하면 선생도 목표 시간을 받고, 시작할 때 「오늘 1시간 반 정도로 봅니다」라고 말한 뒤 설명의 깊이와 실습의 크기를 거기에 맞춥니다. 넘칠 것 같으면 곁가지를 덜고, 남으면 더 깊이 들어갑니다.
• 안 정한 장에는 아무것도 서지 않습니다 — AI 가 값을 못 냈거나 옛 커리큘럼이면 그 장만 빈 채로 둡니다(「예상 0분」을 그리지 않습니다). 합계에서도 빠집니다.

목표 달성도 — 무엇을 보고 다음 장으로 넘어가나

장마다 통과 기준이 항목으로 2~4개 적혀 있습니다(「…을 할 수 있다」). 커리큘럼을 짤 때 AI 가 함께 정하고, 차례의 그 장에 「목표 3/4」 로 섭니다 — 진도(장 단위)와 달리 한 장 안에서 얼마나 왔는지를 이 수가 말합니다.

중요한 것은 누가 판정하는가입니다. 선생에게 「이 사람이 넘어갈 만한가?」를 물으면 거의 항상 그렇다고 답합니다 — 격려하는 쪽으로 기울고, 자기가 설명한 것을 상대가 이해한 것으로 셉니다. 그래서 선생은 판정하지 않습니다: 항목에 증거만 올리고, 「넘어갈 만한가」는 앱이 규칙으로 계산합니다.

• 항목마다 받을 증거가 정해져 있습니다 — 설명은 내가 자기 말로 설명한 발언(짧은 동의는 설명이 아닙니다), 적용은 내가 직접 돌려 통과한 명령이나 내가 쓴 파일(실제로 있어야 합니다), 암기는 복습 큐에서 내가 맞힌 기록입니다. 선생이 설명한 것 · 선생이 돌린 것은 증거가 아니고 앱이 거절합니다.
• 실습 전에는 「적용」이 채워지지 않습니다 — 설명을 듣고 끄덕인 것이 적용의 증거로 통과하지 않습니다. 그리고 수업이 정리(6) 에 닿기 전에는 「넘어갈 만합니다」를 아예 계산하지 않습니다.
• 끝냄 창이 평가표입니다 — 항목 · 선생이 올린 증거 원문 · 그 옆에 내가 고르는 「할 수 있다 / 아직」. 근거가 「제가 설명해 드렸습니다」 수준이면 읽고 바로 압니다.
• 내 답이 선생보다 셉니다 — 선생이 「됐다」고 올린 항목에 내가 아직 을 고르면 그 항목은 미달로 돌아가고 「넘어갈 만합니다」가 내려갑니다. 같은 버튼을 다시 누르면 「아직 안 고름」으로 되돌아갑니다.
• 두 갈래로 고릅니다 — 정리하고 넘어가기(이 장을 끝내고 다음 장까지 바로 시작합니다) · 좀 더 공부하기(수업을 개념 으로 되돌리고 남은 항목만 선생에게 넘깁니다 — 채워진 항목을 다시 듣지 않습니다).
• 그래도 끝낼 수 있습니다 — 기준을 다 못 채워도 그래도 끝냄 이 열려 있습니다(끝내는 것은 사람입니다). 그때 남은 항목은 커리큘럼 머리의 보완할 것 N 에 모이고, 다음 장 선생도 그 목록을 받습니다 — 걸리는 자리에서 한 번 짚습니다. 복습 큐와 다른 자리입니다: 복습은 외울 조각이고 이건 목표 미달입니다.

통과 기준이 없는 장(S481 이전에 짠 커리큘럼)에는 아무것도 늘지 않습니다 — 종전처럼 목표 한 줄로 묻습니다. 다시 짜기 를 하면 기준이 서고, 이미 쌓인 증거는 항목의 글이 같으면 그대로 남습니다.

끝내면 학습 문서가 남습니다 — 몇 달 뒤에 다시 볼 한 장

챕터를 끝냄 하면 그 장의 노트를 한 장짜리 HTML 학습 문서로 정리해 그 챕터의 문서로 등록합니다(워크플로우 study-note). 노트 md 는 공부하는 동안 쌓이는 시간순 기록이라 다시 읽기 힘든데, 이 문서는 정리된 지식입니다.

• 무엇이 들어가나 — 맨 앞에 이 장에서 할 수 있게 된 것(통과 기준 체크 목록) · 한눈에 보는 표 · 흐름과 구조를 그린 다이어그램 · 맞는 예와 틀린 예 · 자주 틀리는 자리 · 되짚기 질문(답은 접혀 있습니다) · 맨 뒤에 접어 둔 원문 노트.
• 자기 완결입니다 — CSS 가 파일 안에 들어 있어 네트워크 없이 열리고, 밝은 화면·어두운 화면 둘 다 읽힙니다. 몇 년 뒤에 열어도 깨지지 않습니다.
• 어디에 남나 — 레포에는 notes/<번호>-<제목>.html 로(커밋됩니다), 앱에는 그 챕터 상세의 문서 칩에. 앱 쪽은 사본이라 나중에 그 챕터 worktree 를 닫아도 남습니다.
• 위키에도 자동으로 들어갑니다 — 등록한 문서는 위키 트리에 맞춰 서고, HTML 은 본문까지 검색에 걸립니다. 따로 할 일은 없습니다.
• 붙들지 않습니다 — 「끝냄」을 누르면 그 자리에서 다음 일로 넘어가도 됩니다. 다 되면 우하단에서 알려 줍니다.
• 노트도 통과 기준도 비어 있으면 만들지 않습니다 — 꾸미기만 한 빈 문서는 다시 볼 가치가 없습니다.

노트 — 선생이 쓰고 사람이 읽는 파일

챕터를 시작하면 notes/<번호>-<제목>.md 가 함께 만들어집니다. 선생이 그 장에서 다룬 것·막힌 자리·복습할 것을 거기 적고, 사람이 쓴 말은 고치지 않고 아래에 덧붙입니다.

차례의 각 장에는 노트가 몇 줄 쌓였고 마지막으로 언제 손댔는지가 함께 섭니다 — 진도는 장 단위라 한 장(1~3시간)을 한참 공부해도 숫자가 꿈쩍하지 않는데, 이 줄이 「지난번에 어디까지 했나」를 화면에서 바로 말해 줍니다.

커리큘럼의 챕터 행에서 노트 를 누르면 그 파일이 코드 보기로 열립니다 — 앱이 사본을 들지 않으므로 늘 지금 내용입니다. 노트는 레포 파일이라 커밋으로 남고, 다른 기기에서도 그 브랜치를 받으면 그대로 읽힙니다.

복습 — 잊는 것이 문제인 공부

커리큘럼의 학습 방식에 복습 이 켜져 있으면 상세에 복습 칩이 하나 더 섭니다. 선생이 가르치면서 외울 것을 자동으로 큐에 넣습니다 — 사람이 카드를 적지 않습니다.

1. 앞면만 보입니다. 떠올린 뒤 뒷면 보기 를 누르면 뒷면과 판정 버튼이 섭니다 — 순서가 뒤바뀌면 복습이 아니라 읽기가 됩니다.
2. 기억남 이면 다음 차례가 멀어집니다 — 1 → 3 → 7 → 14 → 30일. 모름 이면 내일 다시 봅니다(처음으로 돌아갑니다). 간격이 고정이라 「왜 오늘 이게 떴지」에 답할 수 있습니다.
3. 오늘 볼 것이 없으면 다음에 볼 것 N건 만 셉니다 — 아직 때가 아닌 것은 보여 주지 않습니다(그러면 복습이 전체 훑기가 됩니다).
4. 이미 아는 것은 빼기 로 큐에서 없앱니다.

공부는 화면에서 시작합니다 — 문서를 열어 복사하지 않습니다

커리큘럼 · 차례 · 진도 · 복습은 앱이 들고 있는 데이터입니다. 공부를 시작하려고 레포 안의 .md 를 열거나, 프롬프트를 복사해 대화창에 붙이거나, 진도를 손으로 적을 필요가 없습니다 — 커리큘럼 칩의 「시작」 하나가 그 일을 합니다. 레포 파일로 가는 것은 노트와 실습 결과뿐입니다.

그래서 학습·통합 프로젝트의 세션은 커리큘럼을 알고 뜹니다 — 과목 · 진도 · 차례 · 학습 방식 · 이 자리가 몇 장인지 · 노트 경로 · 복습 큐 수가 받은 컨텍스트 에 실립니다. 커리큘럼이 아직 없으면 「커리큘럼은 저절로 짜이니 레포에 만들지 말라」고 적힙니다. 세션이 레포에 커리큘럼 문서를 또 만들면 같은 것이 두 벌이 되고, 내가 보는 화면은 앱 쪽입니다.

프로젝트 그룹 — 기획·학습과 개발을 한 자리에#

레포(프로젝트) 자체를 사람이 정한 프로젝트 그룹으로 묶습니다. worktree 그룹과 담는 것이 다릅니다 — 저건 과업(worktree)을 모으고, 이건 레포를 모읍니다. 기획 프로젝트와 그 결과를 구현하는 개발 프로젝트처럼 이어지는 일을 한 자리에서 보려고 씁니다(프로젝트 타입).

1. 워크스페이스 행의 ⋯ › 프로젝트 그룹 만들기 — 이름을 넣고 만들기. 링크 칸은 없습니다(그건 에픽에서 온 worktree 그룹의 칸입니다).
2. 넣기 — 프로젝트 행을 그룹 행 위로 끌어다 놓습니다(그룹 안의 아무 행이어도 됩니다). 놓기 전에 「그룹 이름」에 넣기 딱지가 그 행에 서니 그 말을 보고 손을 떼면 됩니다. 행 ⋯ › 프로젝트 그룹으로 이동 도 같은 일을 하고, 맨 끝 새 프로젝트 그룹 만들기… 는 만들면서 바로 넣습니다. 같은 워크스페이스의 그룹만 — 묶여도 어느 워크스페이스의 레포인지는 트리 구조로 남습니다.
3. 빼기 — 그룹 밖(묶이지 않은 프로젝트 행 · 워크스페이스 행)에 끌어다 놓거나 ⌥⌫, 또는 행 메뉴의 프로젝트 그룹에서 빼기. 워크스페이스 아래 제자리로 돌아갑니다. 기획 연결(구현 프로젝트)이 있는 프로젝트는 그룹을 옮길 수 없습니다 — 연결된 프로젝트는 한 그룹에 있어야 하므로, 연결을 먼저 끊습니다. 그룹을 지우면 그 안의 연결은 함께 풀립니다.
4. 그룹에 든 프로젝트는 그룹 안에만 섭니다(워크스페이스 바로 아래에는 다시 그리지 않습니다). 프로젝트 수(프로젝트 N)는 묶여도 그대로 셉니다.
5. 그룹 세션 — 그룹 행의 +(또는 행 메뉴 › 세션 추가)로 묶음 전체를 보는 세션을 엽니다. 구성원이 하나도 없어도 열립니다 — 그룹부터 만들고 세션에서 무엇을 묶을지 정하는 순서도 됩니다.
6. 어디서 도나 — 이 세션은 구성원 레포가 아니라 그룹 전용의 빈 작업 폴더에서 뜹니다(~/.baton/work/groups/<그룹id>). 묶음을 보는 자리가 한 구성원 안에 갇히지 않게, 그리고 거기서 실수로 코드를 고치는 일이 없게 하기 위함입니다. 구성원 레포는 절대 경로로 읽습니다(맥락에 경로가 실립니다 · git -C <경로>).
7. 무엇을 맥락으로 받나 — 구성원 레포의 맵: 이름 · 타입 · 경로 · base 브랜치 · 맵 한 줄 · 역할 코멘트 · 테스트/빌드 명령, 그리고 이 그룹에 붙인 문서. 맵이 아직 돌지 않은 레포는 그렇다고 적힙니다(빈 것과 안 실린 것은 다릅니다).
8. 일은 각 레포의 세션이 합니다 — 「이 기획대로 구현은 저쪽 개발 프로젝트에서 해줘」처럼 말하면 그 프로젝트의 세션에 요청을 보냅니다. 그룹 세션은 조회하고 파악해 통합해서 알려 주고, 고치는 일을 넘기는 자리입니다.
9. 문서·링크를 이 자리에 붙입니다 — 행 메뉴 › 문서 추가, 또는 그룹 세션 상세의 문서 칩. 묶음 전체의 글(1-1 기획서 · 설계서)이 여기 옵니다. 구성원 프로젝트의 문서는 각 프로젝트 자리에 그대로 있습니다. 성과는 과업(worktree) 단위라 이 자리에 서지 않습니다.
10. 진행상황으로 묶음 전체를 한 장에 봅니다 — 그룹 행 ⋯(또는 우클릭) › 진행상황, 또는 그룹 세션 상세의 진행상황 칩. 세션을 열지 않아도 행 메뉴에서 바로 볼 수 있습니다. 거의 화면 가득 찬 팝업으로 열리고, 그림은 기본이 맞춤(자리에 꼭 맞게 키우거나 줄임)입니다 — 위의 − / + / 맞춤 / 100% 로 배율을 바꿉니다. 구성원 worktree 가 단계(대기 · 파악 · 구현 · 리뷰 · 반영 · 완료)와 의존 관계로 그려집니다. 보기는 둘입니다: 의존(무엇이 무엇을 막고 있나)과 단계(지금 무엇이 어디까지 왔나 · 빈 단계는 좁은 띠로 줄어듭니다).
    • 선 읽는 법 — 그림 위 범례에 늘 적혀 있습니다. 점이 찍힌 끝이 선행(먼저 끝나야 하는 쪽), 화살촉이 후행(기다리는 쪽)입니다. 실선 = 확정된 의존(사람이 긋거나 Jira 에서 왔거나 승인한 것), 주황 점선 = AI 추천안(승인 대기), 빨간 점선 = 순환(서로를 기다림 — 하나를 지워야 풀림). 카드 왼쪽 띠 색은 단계, 테두리 색은 상태(승인 기다림 · 검사 실패 · 차단 · 다음 차례 · 움직임)입니다.
    • 어느 노드에 붙은 선인지 — 노드나 선에 포인터를 올리면 거기 이어진 선과 노드만 남고 나머지는 흐려집니다. 선은 카드 테두리에 붙고, 한 카드에 여럿이 붙으면 세로로 펼쳐져 따로 나갑니다.
    • 선을 누르면 그림 위 막대에 양 끝 이름(「A → B」)과 어디서 온 것인지(사람 · Jira · AI) · 사유가 보입니다. 추천안이면 승인 · 거절, 그 밖이면 지우기를 거기서 누릅니다(빈 자리를 누르거나 ✕ 로 풉니다).
    • 노드를 끌어 다른 노드에 놓으면 선행·후행 간선을 긋고, 노드의 ↗ 로 그 worktree 로 갑니다.
    창을 열면 저장해 둔 상태로 먼저 그린 뒤 곧바로 각 worktree 의 git 을 다시 읽어 고칩니다. 열어 둔 동안 보드가 바뀌면 그림도 따라 바뀝니다. ↻ 새로 읽기 는 그 다시 읽기를 지금 한 번 더 하며 토큰을 쓰지 않습니다. PR 없이 base 에 머지 커밋으로 머지한 worktree 는 완료 · 머지됨 (로컬) 로 섭니다(fast-forward 머지는 가려낼 수 없어 여기 들지 않습니다). 의존 관계를 모르겠으면 의존성 재추론(AI)을 누릅니다 — 구성원 요약만 읽어 추론하고, 결과는 점선 추천안으로 올라와 승인해야 그림에 섭니다. 도는 동안 버튼은 추론 중… 으로 막히고(창을 닫아도 계속 돕니다), 끝나면 알림이 새 추천안 몇 건 인지, 이미 있는 간선과 같아 그대로 둔 것이 몇 건인지 알려 줍니다 — 같은 추천을 다시 냈으면 새로 찾은 의존이 없습니다 가 정상입니다. 손으로 그은 간선과 한 번 거절한 간선은 재추론이 덮지 않습니다.
11. 이름 변경 은 행에서 바로(Enter), 그룹 편집 은 창에서.
12. 그룹 삭제 는 묶음만 풀고 안에 있던 것은 제자리로 돌려보냅니다: 프로젝트는 워크스페이스 아래로, 문서·링크는 워크스페이스 자리로 옮겨져 거기서 계속 열립니다(사라지지 않습니다). 그룹 세션은 닫힙니다 — 돌던 프로세스가 내려가고, 대화는 기록 › 닫힌 세션에 그룹 이름과 함께 남아 되살릴 수 있습니다.

서비스 개발 그룹 — 기획 → 디자인 · 설계 → 구현 → 마감을 상태로#

프로젝트 그룹을 서비스 개발 그룹으로 지정하면, 기획 · 디자인 · 설계 · 구현이 칩마다 상태 하나로 섭니다 — 문서 칩은 대기 → 작성 → 검토 → 승인, 구현은 대기 → 구현중 → 구현완료, 모두 끝나면 마감. 중간에 세션이 멈춰도 어디서 멈췄는지 · 무엇을 이어서 하면 되는지가 칩과 그룹 보드에 남습니다. 지정하지 않은 그룹 · 단독 프로젝트는 지금 모습 그대로입니다.

1. 지정 — 그룹 행 ⋯(또는 우클릭) › 서비스 개발 그룹으로 지정. 확인 창이 지금 상태로 계산한 칩 머리(예: 기획 작성 · 디자인 대기)와 함께 바뀌는 것을 보여 줍니다 — 기존 기획은 새 흐름(디자인 · 설계 승인 뒤 구현)으로 올라가고, 「승인 없이 반영/구현」이 사라집니다. 그룹에 기획(또는 통합) 프로젝트가 정확히 하나 있어야 누를 수 있습니다. 서비스 개발 시작으로 만든 그룹은 처음부터 서비스 개발 그룹입니다.
2. 칩에는 지금 상태의 버튼만 섭니다 — 작성: 검토 요청(task 가 덜 끝났거나 필수 칸이 비면 잠기고 이유를 말합니다) · AI로 다시 작성 · 실패한 task 가 있으면 재시도. 검토: 승인 · 고치기. 승인: 승인 거두기. 대기: 버튼 없이 막힌 이유 한 줄(「기획 승인을 기다립니다」). 「디자인/설계 진행」 · 「구현」 · 「다시 승인」 · 「다시 그리기」 · 「코멘트 달 수 있게 고치기」는 서비스 개발 그룹 칩에 서지 않습니다.
3. ⋯ 더 보기 — 상태 띠 머리의 ⋯(칩마다 하나)에 상태와 따로 하는 일이 모입니다: 수정 요청…(파일 고르기 → 수정 요청 창) · 판 목록 · 되돌리기…(파일 → 판 고르기 · 설계는 판 목록… 열기만) · 디자인 칩이면 기준 정하기 · 시안 그리기 · 플로우맵 그리기 · 시안 검사 · 내보내기. 행에는 이 버튼들이 서지 않습니다. 승인된 칩의 파일을 고치거나 되돌리려 하면 「승인이 풀립니다 — 검토로 내려가고 아래 칩은 대기로 돌아갑니다」를 먼저 묻습니다.
4. 흐름 — 기획을 승인하면 디자인 · 설계의 대기가 풀리고, 빈 칸이 있으면 디자인 · 설계 진행이 저절로 돕니다. 디자인 · 설계를 모두 승인하면 구현이 열립니다. 승인 뒤 파일이나 기획 단계가 바뀌면 그 칩은 검토로 내려오고 아래 칩은 대기로 돌아갑니다(승인 뒤 새로 생긴 파일은 내리지 않습니다).
5. task — 칸을 펼치면 칩 안의 진행 단위가 섭니다(기획 단계 · 시안 · 설계 문서 · 구현 일감). 승인은 칩 단위이고 task 는 진행 · 재개의 단위입니다 — 빈칸 · 진행중 · 완료 · 실패, 승인 뒤 바뀐 것에는 승인 뒤 바뀜. 맡은 세션이 끝났는데 끝나지 않은 task 는 실패로 서고 재시도가 켜집니다 — 누르면 그 세션이 살아 있으면 그 세션에, 아니면 새 세션에 이어서 할 일(재개 brief)을 보냅니다.
6. 그룹 보드 — 그룹 세션 상세의 흐름 칩: 지금 자리 한 줄 · 플랫폼별 지금 · 멈춘 곳(이어서 하기) · 기획 → 디자인 ∥ 설계 → 구현 → 마감 · 플랫폼마다 마감 줄. 구현 칩: 플랫폼마다 일감 표(레포 · 상태 · 세션/브랜치 · 검증 기준)와 구현 시작 · 검증 실행 · 구현 다시 시작.
7. 개발 레포에서 — 서비스 그룹에 이은 개발 레포의 상세에도 구현 칩이 섭니다. 그 레포가 맡은 칸과 그 레포의 일감만 보이고, 지금 보는 워크트리가 그 일감의 브랜치면 이 워크트리 딱지가 붙습니다. 여기서는 검증 실행 · 재시도만 하고, 구현 시작 · 다시 시작은 그룹 보드의 구현 칩에서 합니다. 개발 레포의 디자인 칩은 지금 모습 그대로입니다.
8. 구현은 저절로 움직입니다 — 일감이 집히면 구현중, 일감 PR 이 머지되면 완료, 세션이 끝났는데 남은 일감은 실패. 일감이 전부 완료되는 순간 통합 검증이 저절로 한 번 돕니다 — 끝나면 알림이 오고, 통과면 구현완료입니다(일감 하나 머지될 때마다 돌지 않습니다 · 자율 구현이 이미 검증했거나 같은 일감 묶음으로 이미 돌았으면 다시 돌지 않습니다 · 일감이 다시 열렸다 또 끝나면 한 번 더). 검증 실행(service-verify)은 손으로 다시 돌릴 때 씁니다 — 일감을 다시 구현하지 않고 검증 기준만 판정합니다 — 기준이 전부 통과하면 구현완료, 실패한 기준을 채우는 일감은 실패로 섭니다. 자율 구현이 끝날 때의 통합 검증도 같은 판정을 남깁니다.
9. 마감 — 한 플랫폼의 모든 칩이 승인 · 구현완료면 「웹 마감」처럼 플랫폼마다 마감할 수 있고, 전부 끝나면 서비스 마감. 마감한 뒤 공통이 바뀌어도 다시 열리지 않고 「마감 · 영향 있음」만 섭니다 — 다시 여는 것은 마감 해제.
10. 멀티 플랫폼 — 상태는 공통 칸 + 플랫폼 칸입니다. 플랫폼에 따로 그린 것이 없으면 공통 그대로(버튼은 공통 칸에). 칩 머리는 가장 늦은 플랫폼의 상태와 「웹 승인 · iOS 검토」 같은 요약을 말합니다. 공통이 바뀌면 모든 플랫폼이, 플랫폼 칸만 바뀌면 그 플랫폼만 내려갑니다.
11. 해제 — 그룹 행 › 서비스 개발 그룹 해제. 칩이 지금 모습으로 돌아가고, 기록(원장)은 지우지 않아 다시 지정하면 이어집니다.

1

1

1

1

123

1

1

worktree 만들기#

레포에 브랜치를 파고 worktree(과업 단위 작업 폴더)를 만듭니다. 티켓을 넣으면 그 내용을 읽은 세션까지 열립니다.

1. 트리에서 프로젝트 행의 ⋯ › worktree 만들기.
2. 브랜치 이름과(선택) Jira 티켓 키를 넣습니다. 그룹 칸을 고르면 worktree 가 처음부터 그 worktree 그룹 안에 생깁니다(비우면 프로젝트 아래).
3. 확인하면 worktree 가 생기고 트리에 나타납니다. 티켓을 넣었다면 세션이 그 티켓을 읽고 기다립니다.
4. 만드는 데 시간이 걸리므로 다른 일을 계속하면 됩니다 — 다 되면 보던 화면은 그대로 둔 채 우하단 토스트(워크트리로 이동 · 세션으로)와 상단바 답 대기 배지 가 길을 내밉니다.

작업 목록(세션 카드)#

세션마다 카드 한 장입니다. 카드에는 세션 이름 · 프로젝트 · 티켓 · 상태(승인 필요 · 실행 중 · 응답 없음 · 대기) · 서브에이전트가 보입니다.

• 탭 주의 는 내가 손을 대야 하는 카드만 모읍니다 — 승인 필요 · 응답 없음 · 강제 멈춤됨 · 답 대기 · 아직 안 본 새 결과 · 쓰다 만 작성 중.
• 탭 실행 중 은 지금 일하는 세션을 모읍니다 — 답을 쓰고 있는 세션에 더해, 답은 끝났지만 백그라운드로 건 일의 결과를 기다리는 세션(아래 결과 대기)도 여기 섭니다.
• 탭 만료 는 48시간 동안 아무 일이 없어 앱이 프로세스를 내린 세션만 모읍니다. 닫힌 것이 아니라 대화와 자리는 그대로이고, 말을 걸거나 「이어가기」를 누르면 이어서 진행하며 이 탭에서 빠집니다.
• 탭마다 그 칸에 몇 개가 있는지 숫자 가 함께 붙습니다. 0이면 숫자가 서지 않습니다. 전체 의 숫자는 지금 목록에 보이는 세션 수입니다(기본 포함 을 끄면 줄기 세션을 뺍니다). 주의 · 실행 중 · 만료 는 기본 포함 을 꺼 둬도 그 세션들까지 세므로, 가려 둔 줄기 세션이 승인을 기다리는 것도 숫자로 보입니다.
• 기본 포함 을 켜면 base worktree(main 등)의 세션도 보입니다. 숫자는 서 있는데 목록이 비었다면 그 세션이 가려 둔 base 에 있는 것이라, 빈 자리가 「기본 포함」을 켜면 보입니다 라고 알려 줍니다.
• 목록은 어떤 세션도 빠뜨리지 않습니다 — worktree 세션이 먼저 서고, 그 아래로 그룹 세션(그룹 안 worktree 를 아우르는 자리) · 프로젝트 그룹 세션(그룹 안 프로젝트를 아우르는 자리) · 워크스페이스 세션 · 분류 안 됨 묶음이 차례로 섭니다. 그룹 세션 카드의 둘째 줄에는 경로 대신 그 그룹의 이름이 섭니다.
• 선택 으로 여러 카드를 골라 한 번에 닫거나(정리), 고른 세션 전부에 같은 요청을 한 번에 넣습니다(요청 보내기 — 다른 세션에 요청 보내기).
• 목록은 열려 있는 세션 전부입니다 — 위 트리에서 행을 옮기거나 눌러도 목록은 바뀌지 않습니다.
• 세션 탭 · ⌘K · 알림 · 트리에서 세션을 고르면 목록이 그 카드가 보이는 자리로 스크롤됩니다. 이미 보이면 움직이지 않고, 키보드 포커스는 쓰던 자리에 그대로 둡니다.
• 한 레포만 보려면 ⌘K 에서 프로젝트를 고릅니다. 목록 머리에 그 레포 칩이 서고, 칩 옆 ✕ 로 풉니다.
• 작성 중 딱지 — 입력창에 아직 보내지 않은 글이 남아 있는 세션에 붙습니다(공백만 있으면 붙지 않습니다). 보내거나 지워서 칸이 비면 딱지는 곧바로 사라집니다. 다른 화면에 다녀와도 초안은 남아 있습니다.
• 새 결과 딱지 — 아직 보지 않은 세션 결과가 있으면 붙습니다. 그 세션을 열어 결과를 보면 사라집니다.
• 강제 멈춤됨 딱지 — 세션이 내 뜻과 무관하게 멈췄을 때 붙습니다: 응답 도중 앱이 꺼짐 · API 오류(사용량 한도 · 인증 · 서버 과부하) · 인터넷 끊김 · 30분 넘게 소식 없음 · 세션 엔진이 도중에 멈춤. 딱지에 마우스를 올리면 사유와 시각이 보입니다. 내가 ⌃C 로 끊었거나, 정상으로 끝났거나, 내 답(승인 · 질문)을 기다리는 세션에는 붙지 않습니다.
• 실행 중 의 점 색 — 그 일을 누가 시켰는지를 말합니다. 파랑은 내가 보낸 말, 초록은 다른 세션이 넘긴 요청, 보라는 워크플로우가 보낸 프롬프트입니다 — 대화창 말풍선과 같은 색입니다. 일하는 중에 다른 쪽의 요청이 줄 서 있으면 점이 여럿 섭니다(예: 파랑 · 초록). 상태 표시에 마우스를 올리면 시킨 쪽과 그 세션 · 실행 이름이 글로 보입니다.
• 결과 대기 — 세션이 오래 걸리는 일(테스트 · 실험 스크립트 · 빌드)을 백그라운드로 걸어 두고 답을 끝냈을 때입니다. 답은 끝났지만 일은 뒤에서 돌고 있고, 세션은 그 결과를 기다립니다. 상태 자리에 대기 대신 결과 대기(실행 중과 같은 색)가 서고, 옆에 백그라운드 N 딱지가 몇 개가 도는지 셉니다.
  • 카드 아래에 도는 일이 한 줄씩 펴집니다 — 종류(셸 · 감시 · 서브에이전트) · 무엇을 걸었는지 · 걸린 지 얼마나 됐는지.
  • 이 세션은 실행 중 탭에 함께 서고, 탭의 숫자에도 셉니다. 일이 끝나면 세션이 그 결과를 받아 이어서 일하고, 딱지는 저절로 빠집니다.
  • 답을 쓰는 중에 걸어 둔 일이 있으면 상태는 실행 중 그대로 두고 백그라운드 N 딱지만 붙습니다.
  • 뒤에서 일하는 세션은 48시간이 지나도 내리지 않습니다(만료로 가지 않습니다) — 내리면 그 일도 함께 끝나기 때문입니다.
  • 앱이 직접 연 세션만 압니다. 앱을 다시 켜면 그 전에 걸려 있던 일은 보이지 않습니다(세션 프로세스가 앱과 함께 내려가기 때문입니다).
• 위임 중 딱지 — 이 세션이 다른 세션에 요청을 넘기고 그 답을 기다릴 때 붙습니다. 맡긴 곳이 둘 이상이면 위임 중 2 처럼 수가 붙고, 딱지에 마우스를 올리면 맡긴 세션 이름이 보입니다.
  • 이 세션은 답을 다 쓰고 대기 상태여도 실행 중 탭에 함께 서고, 탭의 숫자에도 셉니다 — 일은 받은 세션에서 돌고 있기 때문입니다.
  • 받은 세션이 그 요청에 답하고 턴을 마치면(또는 다른 일로 넘어가거나 닫히면) 딱지가 곧바로 빠집니다. 받은 세션이 승인 카드를 붙들고 멈춰 있는 동안은 아직 하는 중으로 셉니다.
  • 판정은 요청한 세션이 session_replies 로 답을 되읽을 때의 하는 중과 같습니다. 워크플로우로 넘긴 일은 여기 들지 않습니다.
• 승인 필요 세션은 카드 셋째 줄의 승인 필요 표시(주황색)로 알 수 있어 따로 딱지를 더하지 않았습니다. 도구 승인과 모델이 내민 질문 카드가 모두 여기 듭니다.
• 답 대기 딱지 — Claude 가 선택지 카드 없이 글로만 묻고 멈춘 세션에 붙습니다(예: 「고쳐도 될까요?」로 답이 끝남). 상태는 대기 그대로지만 나를 기다리는 세션이라 주의 탭에 함께 섭니다. 상단바 답을 기다리는 세션 목록의 「답을 기다리는 대화」와 같은 세션입니다.
  • 그 세션에 한 번 답을 보내면 딱지가 곧바로 빠집니다 — Claude 의 답이 끝날 때까지 기다리지 않습니다. 다른 기기(원격 제어)에서 보낸 답도 같습니다.
  • 세션을 열어 읽기만 해서는 빠지지 않습니다. 질문이 아니었으면 상단바 목록의 숨기기 로도 뺄 수 있습니다.
  • 워크플로우가 그 세션에 넣은 말은 내 답으로 치지 않습니다 — 딱지가 남습니다.
  • Claude 가 다음 답에서 또 글로 물으면 새 질문이라 딱지가 다시 붙습니다.

카드가 서는 순서

내가 마지막으로 연 세션이 맨 위입니다. 그 아래로 그전에 열었던 순서대로 내려갑니다 — 오늘 손댄 세션들이 자연히 위쪽에 모입니다. 아직 한 번도 열지 않은 세션은 마지막 대화가 최근인 것부터 섭니다.

• 딱지는 자리를 바꾸지 않습니다. 「작성 중」·「강제 멈춤됨」·「승인 필요」·「답 대기」·「새 결과」가 붙어도 카드는 있던 자리에 그대로 있습니다. 그런 세션을 한자리에 모아 보려면 주의 탭을 누르세요 — 그것이 이 탭의 일입니다.
• 보는 동안 목록은 움직이지 않습니다. 카드를 누르거나 ↑↓ 로 훑는 동안 줄이 다시 서면 방금 누른 카드가 눈앞에서 사라지므로, 순서는 그 자리에 머무는 동안 고정됩니다. 내가 옮겨 다닌 자취는 세션을 열거나 닫을 때 · 탭이나 검색어를 바꿀 때 · 다른 화면에 다녀왔을 때 반영됩니다.

1

1

1

12

강제 멈춤된 세션 처리하기

1. 「강제 멈춤됨」 카드를 눌러 세션을 엽니다. 입력창 위에 강제 멈춤됨 · 사유 · 시각 배너가 서고, 대화 끝에는 무엇이 끊겼는지 적힌 카드가 있습니다.
2. 다시 시도(API 오류 · 인터넷 끊김) 또는 이어가기(앱 종료 · 엔진 멈춤 · 소식 없음) — 대화를 되찾아 세션을 다시 띄웁니다. 아무 일도 하기 전에 멈춘 턴이면 방금 보낸 말을 다시 보내고, 일을 하던 중이었으면 「끊긴 곳부터 이어서」를 보냅니다.
3. 따로 처리했거나 이어갈 필요가 없으면 확인 — 딱지만 내립니다. 새로 말을 걸거나 세션을 닫아도 딱지는 내려갑니다. 30분 넘게 소식이 없던 세션은 소식이 오면 저절로 풀립니다.
4. 인증 실패로 멈춘 것이면 배너에 「Claude 로그인」 이 하나 더 섭니다 — 눌러서 앱 안에서 다시 로그인 한 뒤 다시 시도 하면 이어집니다. 사용량 한도 · 서버 과부하에는 이 버튼이 서지 않습니다(로그인으로 풀리는 일이 아닙니다).

1

1

이름 고치기

1. 카드를 더블클릭합니다(키보드로는 카드에서 F2). 세션 이름 자리가 입력칸이 되고, 자리가 좁아 … 로 줄어 보이던 이름도 입력칸에는 전체가 들어 있습니다.
2. 새 이름을 치고 Enter — 탭 · 트리 · 목록이 한꺼번에 새 이름을 씁니다. Esc 는 저장하지 않고, 다른 곳을 누르면 저장합니다.

키보드와 행 메뉴

⌥2 로 목록을 잡은 뒤 ↑↓ 로 카드를 옮기면 그 세션이 바로 열립니다. Enter 는 손이 선 카드를 엽니다. →(또는 카드 오른쪽 위의 ⋯ 버튼 · ⇧F10)는 그 카드의 메뉴를 엽니다. 메뉴 머리에 세션 이름이 끝까지 보이고, ← 나 Esc 로 닫으면 손은 그 카드로 돌아옵니다.

이틀 쉬면 프로세스만 내려갑니다 — 「만료」

세션 하나가 Claude 프로세스 하나입니다(한 개에 400MB 쯤). 열어 두고 안 쓰는 세션이 쌓이면 이 컴퓨터가 먼저 느려지므로, 48시간 동안 아무 말도 오가지 않은 세션은 앱이 프로세스를 내립니다. 딱지는 「만료」 가 됩니다 — 목록 머리의 만료 탭이 모으는 세션과 같은 말입니다.

• 닫는 것이 아닙니다. 트리와 작업 목록에 그 자리에 그대로 있고, 대화도 전부 남아 있습니다 — 사라지는 것은 메모리 위의 프로세스뿐입니다.
• 그냥 말을 걸면 이어집니다. 입력창에 쓰고 보내면 세션이 다시 뜨면서 그 대화를 되찾아(resume) 이어서 답합니다. 대화 끝의 「이어가기」 를 눌러도 같습니다(말을 걸 것이 아직 없을 때 쓰세요).
• 일하는 중 · 승인 대기 세션은 내려가지 않습니다. 워크플로우가 몰고 있는 세션도 그대로 둡니다. 「만료」가 되는 것은 이틀 내내 아무 일도 없던 자리뿐입니다.
• 경고가 아닙니다. 「만료」 카드는 「강제 멈춤됨」과 달리 평상색으로 섭니다 — 고칠 것이 없다는 뜻입니다.

티켓·레포 필터 (⌘F)#

트리와 작업 목록을 티켓 키·레포 이름으로 좁힙니다.

1. 손이 트리·목록에 있을 때 ⌘F(또는 필터 칸을 누릅니다).
2. 티켓 키나 레포 이름 일부를 칩니다 — 트리가 즉시 좁혀집니다.
3. 칸을 비우면 전체가 돌아옵니다 — Esc 로도 한 번에 지웁니다(손은 칸에 남습니다).

1

워크스페이스 전환 · 추가#

상단바 왼쪽의 워크스페이스 이름을 누르면 전환 메뉴가 뜹니다.

• 재스캔 — 워크스페이스 폴더에서 새 레포를 감지해 「프로젝트 나중에 추가」 팝업을 엽니다.
• 워크스페이스 추가 — 폴더를 고르면 하위 git 레포를 찾아 프로젝트로 등록하고 프로젝트 맵을 만듭니다.
• 신규 프로젝트 추가 — 레포를 새로 만듭니다. 아래 절을 보세요.
• 폴더에서 프로젝트 추가 — 워크스페이스 밖의 폴더 하나를 프로젝트로 붙입니다(이미 있는 폴더).
• git 레포가 아닌 폴더도 됩니다 — 목록에 git 없음 딱지로 뜨고 꺼진 채입니다. 켜서 추가하면 앱이 그 자리에서 git init 합니다(빈 첫 커밋까지). 터미널을 따로 열 필요가 없습니다.
• 체크한 폴더는 타입도 함께 정합니다 — 체크를 켜면 그 행 아래로 개발 · 학습 · 기획 · 통합 고르개가 펴집니다(기본 개발). 타입에 따라 보드 상세의 메뉴가 달라지고, 등록한 뒤에는 바꿀 수 없습니다 — 체크하는 그때가 유일한 기회입니다. 이미 등록된 행에는 그 타입이 딱지로 서 있습니다.
• 삭제 — 앱 DB 에서만 지웁니다. 디스크의 레포는 그대로입니다.

프로젝트 타입 — 개발 · 학습 · 기획 · 통합 · 심플#

프로젝트를 만들거나 붙일 때 무엇을 하는 자리인가 를 고릅니다. 타입에 따라 보드 상세의 메뉴(칩 줄) 와 쓸 수 있는 워크플로우, 그리고 AI 의 역할 이 달라집니다. 대화하고 일을 시키는 방식은 어느 타입이든 같습니다.

어느 타입이든 요약 · 문서 · 이력 · 링크 · 프로젝트 는 늘 섭니다.

칩 줄은 가로로 스크롤합니다 — 창이 좁으면 밀어서 봅니다. 칩을 끌어 놓으면 순서가 바뀌고 그대로 기억됩니다(대화창 아래 워크플로우 칩과 같습니다). ⌘⌃1~⌘⌃9 는 늘 보이는 순서를 따릅니다.

타입은 프로젝트가 들어오는 모든 자리에서 고릅니다 — 신규 프로젝트 추가 · 폴더에서 프로젝트 추가 · 워크스페이스 추가 · 프로젝트 추가(재스캔). 뒤의 두 자리는 한 번에 여러 개를 붙이므로 체크를 켠 폴더마다 고르개가 그 아래 펴집니다. 기본은 개발 이고, 이미 등록된 행에는 그 프로젝트의 타입이 딱지로 서 있습니다(읽기 전용).

심플 프로젝트 — 폴더 하나에서 묻고 답하기#

git · worktree · PM(Jira · Track) 없이 폴더 하나를 두고 AI 에게 묻는 자리입니다. 답의 근거는 그 폴더의 파일과, 그 폴더에서 AI 가 읽는 기본 맥락 — 폴더의 CLAUDE.md(행동 지침)와 AI 메모리 — 입니다.

1. 프로젝트를 붙이는 어느 자리에서든 타입을 심플 로 고릅니다 — 신규 프로젝트 추가 · 폴더에서 프로젝트 추가 · 워크스페이스 추가 · 프로젝트 추가(재스캔).
2. 폴더는 그대로 붙습니다 — git init 을 하지 않고, 프로젝트 맵 · 하네스도 돌지 않습니다. 신규로 만들면 빈 폴더만 생깁니다(무엇을 묻는 자리인가 는 이름 추천에만 씁니다).
3. 트리의 프로젝트 행에서 세션 열기(⌘N) — 세션이 그 폴더에서 뜹니다. 여러 번 열면 탭이 나란히 섭니다.
4. 물어봅니다. 메모 · 정리 파일이 필요하면 「정리해서 파일로 남겨줘」라고 하면 세션이 그 폴더에 씁니다.

1

• 행 메뉴 에는 세션 열기 · 터미널 열기 · Finder 에서 보기 · 프로젝트 원격 세션 · 링크 모듬 · 이름 변경 · 색 바꾸기 · 프로젝트 그룹 이동만 섭니다. worktree 만들기 · PR · 버전 히스토리 · 맵 · 배포는 없습니다.
• 상세 › 프로젝트 에는 폴더 · 답의 근거 · 쓰지 않는 것이 한 장으로 섭니다. 칩 줄에는 늘 서는 것(요약 · 문서 · 이력 · 링크 · 프로젝트)만 있습니다.
• 워크플로우 는 정의에 audience: [simple] 을 적은 것만 보입니다 — 레포를 전제한 워크플로우는 이 자리에서 돌면 중간에 실패하기 때문입니다.

신규 프로젝트 추가#

아직 폴더도 없는 프로젝트를 여기서 시작합니다(폴더만 있는 경우는 프로젝트 추가에서 그대로 고르면 됩니다 — git init 은 앱이 합니다). 상단바 워크스페이스 이름 › 신규 프로젝트 추가(트리 맨 아래 프로젝트 그룹의 ⋯ 에도 있습니다).

1. 프로젝트 타입 을 고릅니다 — 개발 · 학습 · 기획 · 통합. 타입에 따라 보드 상세의 메뉴가 달라집니다. 등록한 뒤에는 바꿀 수 없습니다.
2. 저장할 위치 를 고릅니다. 고른 위치가 소속을 정합니다 — 워크스페이스 폴더를 고르면 그 워크스페이스에, 그 밖이면 트리 맨 아래 프로젝트 그룹에 붙습니다.
3. 이름 은 비워 둘 수 있습니다. 비운 채 누르면 아래 내용으로 이름을 제안해 칸에 채우고 멈춥니다 — 폴더 이름이 되는 값이라 한 번 보고 누르게 합니다. AI 추천 으로 먼저 받아 볼 수도 있고, 받은 이름은 고쳐도 됩니다.
4. 무엇을 만드나 에 적은 글대로 만든 뒤 레포를 채웁니다(README 만 둘지, 언어별 최소 뼈대까지 세울지는 내용에 따라 정합니다). 비우면 폴더와 git init 까지만 합니다.
5. 학습 타입을 골랐으면 이 칸은 「무엇을 공부하나」 입니다 — 적은 글로 커리큘럼을 저절로 짭니다(첫 줄이 과목명이고, 전문은 수준·목표로 함께 들어갑니다). 레포에는 아무것도 채우지 않습니다 — 커리큘럼은 앱의 데이터이고, 레포로 가는 것은 챕터의 노트·실습뿐입니다. 비워도 됩니다(프로젝트 이름으로 짭니다).
6. 만들고 맵 생성 — 폴더 · git init · 등록은 누르는 즉시 끝나고 트리에 올라옵니다. 뼈대와 프로젝트 맵은 그 뒤 실행으로 이어지며, 이 창을 닫아도 계속됩니다. 학습 프로젝트면 이 자리에 커리큘럼 짜기 진행이 섭니다 — 끝나면 상세의 커리큘럼 에 챕터 차례가 서 있습니다.

하네스 셋팅 을 켜 두면 뼈대와 맵이 끝난 뒤 이어서 하네스를 깝니다.

하네스 셋팅 — AI 가 일할 틀을 레포에 깔기#

프로젝트를 붙이는 어느 자리에서든 하네스 셋팅 을 켤 수 있습니다 — 신규 프로젝트 추가 · 폴더에서 프로젝트 추가 · 워크스페이스 추가 · 프로젝트 추가(재스캔). 켜고 추가하면 등록이 끝난 뒤 하네스 전문 에이전트가 그 레포를 조사해 작업 방침과 문서 구조를 깝니다. 기본은 꺼져 있습니다 — 레포에 파일을 쓰는 일이라 사람이 고릅니다.

1

• 어느 AI 로 열어도 같은 규칙 — 정본은 AGENTS.md 하나입니다(Codex · Cursor · Copilot 등이 그대로 읽는 공통 파일). CLAUDE.md 는 첫 줄 @AGENTS.md 로 그것을 불러오고, Gemini 는 .gemini/settings.json 으로 같은 파일을 읽습니다. 이미 있는 도구 파일(Cursor 규칙 · Copilot 지시)은 정본을 가리키게 줄입니다. 같은 규칙을 도구마다 복사하지 않습니다.
• 무엇을 적나 — 레포가 무엇인가 두세 줄 · 실제로 돌려 본 빌드 · 테스트 · 린트 명령 · 끝내기 전에 통과해야 할 검사 · 코드만 봐서는 모르는 관례와 그 이유 · 문서 지도. 루트 파일은 짧게(200줄 미만) 둡니다 — 길수록 AI 가 덜 지킵니다.
• 문서 구조 — 이미 docs/ 가 있으면 그 구조를 따르고, 없으면 쓸 내용이 있는 자리만 만듭니다(docs/ARCHITECTURE.md · docs/decisions/).
• 기존 파일은 덮어쓰지 않습니다 — 있던 CLAUDE.md 의 공통 내용은 AGENTS.md 로 옮기고, 옮기거나 뺀 문장은 이유와 함께 보고합니다.
• 커밋하지 않습니다 — 바뀐 파일은 작업 트리에 남습니다. 그 레포에 열린 하네스 셋팅 세션의 마지막 답(바뀐 파일 · 확인한 명령 · 확인 필요)을 보고 git diff 로 검토한 뒤 커밋하세요. 그 세션에 「이 규칙은 빼 줘」처럼 이어서 말할 수 있습니다.
• 창을 닫아도 계속됩니다 — 등록은 먼저 끝나고 하네스는 뒤에서 돕니다. 신규 프로젝트는 뼈대 · 맵이 끝난 뒤에 깝니다(적을 명령이 생긴 다음).

서비스 개발 시작 — 기획 · 개발 레포와 그룹을 한 번에#

새 서비스를 기획 레포 · 개발 레포 · 그 둘을 묶은 프로젝트 그룹으로 시작합니다. 상단바 워크스페이스 이름 › 서비스 개발 시작(트리의 워크스페이스 행 ⋯ 에도 있습니다). 두 번 누릅니다 — 처음 정할 수 있는 만큼 적어 초안 제출, 기획 세션과 보강한 뒤 기획 칩에서 서비스 개발 시작.

1. 서비스 — 서비스 이름(그룹 이름이 됩니다) · 폴더 이름(비운 채 누르면 추천받아 채우고 멈춥니다 · AI 추천) · 한 줄 설명 · 만들고 싶은 서비스 · 주요 사용자 · 핵심 기능 · 레퍼런스. 기획 레포는 <폴더 이름>-plan, 개발 레포는 <폴더 이름> 으로 섭니다.
2. 디자인 — 원하는 느낌을 열 가지(미니멀 · 클린 / 모던 SaaS / 따뜻 · 친근 / 프리미엄 · 럭셔리 / 볼드 · 비비드 / 내추럴 · 오가닉 / 테크 · 퓨처리스틱 / 에디토리얼 · 매거진 / 플레이풀 · 일러스트 / 뉴브루탈리즘) 중에서 고르거나 직접 적기. 색(메인 · 글자 · 포인트 · 배경)과 다크 모드. 색은 칸마다 자동 을 켜고 끕니다 — 자동으로 둔 칸은 AI 가 정하고 무엇을 왜 골랐는지 결과에 적습니다. 전부 자동으로 하기 는 디자인 · 플랫폼 · 스택을 한 번에 맡깁니다.
3. 플랫폼 · 스택 — 대상 플랫폼을 여럿 고를 수 있습니다(안 고르면 AI 가 정합니다). 개발 스택은 비우면 AI 가 플랫폼과 기능을 보고 제안하고, 플랫폼을 고르면 아래에 서는 제안을 눌러 채울 수도 있습니다. 서버(로그인 · 데이터 저장) 필요 여부와 언어도 고릅니다.
4. 위치 — 기본은 그 워크스페이스 폴더입니다. 다른 폴더를 고르면 트리 맨 아래 프로젝트 그룹에 붙습니다.
5. 초안 제출 — 기획 레포와 프로젝트 그룹이 누르는 즉시 서고, 그 레포에 기획 세션이 열립니다. 세션이 받은 내용을 분석해 기획 칩 여섯 단계를 초안으로 채우고, 보강할 것을 다섯 개 이내로 묻습니다(실행 화면에는 서비스 초안 기획 으로 섭니다). 그 세션에 답하며 기획을 굳힙니다 — 며칠 걸려도 됩니다.
6. 서비스 개발 시작 — 기획 칩 머리의 띠에 있습니다. 기획 칩의 앞 다섯 단계(배경 · 목표 · 사용자 · 범위 · 기능 명세)가 모두 정했음이어야 시작됩니다. 누르면 초안 때 값이 채워진 같은 창이 열립니다 — 이야기하다 바뀐 컨셉 · 색 · 플랫폼 · 스택을 고치고 누릅니다. 개발 레포를 만들어 기획에 잇고(같은 그룹 · 구현 프로젝트), 디자인 · 설계 진행 실행이 두 세션에서 정해 둔 담당을 차례로 부릅니다.
   • 디자인 기준 · 로고(service-brand-designer) — 기획의 디자인 자리(Baton 사용자 폴더)에 tokens.html, 디자인 가이드(guides/), 로고 SVG 셋(brand/logo.svg · logo-mark.svg · logo-mono.svg), 브랜드 시안 한 장.
   • 시안 · 프로토타입 · 플로우맵(service-prototyper) — 지면별 시안 · 눌러서 이동되는 프로토타입 · 플로우맵을 그리고, 기획 칩의 프로토타입 단계를 초안으로 갱신합니다. 상세의 디자인 칩에서 봅니다.
   • 기술 스펙 · 인프라 · HLD(arch-lead) — 스택(버전까지)과 선택 이유 비교표, 인프라 구성도, 구성요소 · 흐름. 연결된 개발 레포가 있으면 그 코드를 읽기만 합니다. 마지막에 결정 · 준비물(decisions.html) — 정한 것과 근거, 사람만 정할 수 있어 대화로 물은 결정, 구현에 필요한 API 키 · 외부 계정(발급 방법 · 없을 때의 대체품)을 한 장에 모읍니다. 열린 결정이 남으면 설계를 승인할 수 없고, 키의 값은 문서에 적지 않습니다(개발 레포의 .env.local 에만 들어갑니다).
   • 컴포넌트 스펙(component-spec-writer) · LLD(lld-writer — 디자인의 시안 · 플로우맵이 선 뒤 화면마다 API 를 잇습니다) · 설계 검사(arch-critic — 이름 일치 · 그림 렌더 확인).
   • 마지막 결과 · 링크 — 무엇이 섰고, 디자인 · 설계 승인에 무엇이 빠졌는지.
   개발 뼈대 · 디자인 기준 옮기기 · 맵 · 하네스는 여기서 돌지 않습니다 — 설계가 스택을 정한 뒤 기획 칩의 구현 첫 실행이 맡습니다.
7. 진행과 결과 — 실행 › 실행 상세에서 단계마다 담당 에이전트(누르면 그 세션) · 결과 글을 봅니다. 마지막 결과 · 링크 단계의 링크를 누르면 기획 칩 · 디자인 칩 · 개발 레포로 바로 갑니다. 기획 칩의 띠도 실행 보기 로 바뀝니다.

AI 는 할 수 있는 일을 직접 합니다. 서비스를 만드는 세션(기획 레포 · 기획에 연결된 개발 레포 · 위 담당들)은 사람에게 묻거나 부탁하기 전에 그 일을 스스로 할 수 있는지 먼저 확인합니다. 명령 실행 · 설치 · 파일 만들기 · 설정 · 조사는 직접 하고 한 일을 알립니다. 사람에게 넘기는 것은 사람만 정할 수 있는 결정(방향 · 우선순위 · 예산 · 브랜드 · 확정 · 승인)과 본인이어야 하는 일(로그인 · 가입 · 결제 · 인증 · API 키 발급), 그리고 해 보고 권한 밖이었던 일뿐입니다. 넘길 때는 개발을 몰라도 따라 할 수 있게 — 왜 직접 못 하는지, 어느 화면에서 무엇을 누르는지 번호 붙인 단계로, 끝나면 무엇을 알려 주면 되는지 — 적습니다. 그래도 부탁을 받았는데 AI 가 할 수 있는 일 같으면 「그냥 해 줘」라고 답하면 됩니다.

12

worktree 닫기 — 기록으로 옮기기#

과업이 끝난 worktree 는 지우지 않고 기록 으로 옮깁니다. 대화·문서·산출물·성과는 기록에 남고 디스크의 worktree 폴더만 정리됩니다.

1. 트리 worktree 행 ⋯ 또는 상세 머리의 ⋯ › worktree 닫기.
2. 창이 열리면 닫을 수 있는지 먼저 확인합니다. 막히면 상자에 이유와 파일이 뜨고 닫고 보관이 잠깁니다 — 아직 아무것도 닫지 않았습니다.
3. 커밋하지 않은 변경 때문에 막혔으면 그 상자에서 강제로 닫기 를 고를 수 있습니다(아래).
4. 그 밖의 이유(레포의 기본 체크아웃 · 이미 기록으로 옮긴 자리 · 어느 레포인지 모르는 자리)로 막혔으면 넘길 길이 없습니다. 창을 닫고 그 worktree 에서 정리한 뒤(⋯ › git 상태) 다시 열거나 다시 확인을 누릅니다.
5. 요약을 만들지 고르고 확인합니다. 요약은 뒤에서 만들어지므로 창을 닫아도 됩니다.

「남는 것」 목록 맨 끝에 사용 토큰 한 줄이 섭니다 — 이 과업에 든 토큰과 추정 비용입니다. 창이 열리는 순간 이 worktree 세션들의 대화 기록을 읽어 합계를 확정하므로, 닫은 뒤 세션이 정리되어도 토큰 통계에 그대로 남습니다.

닫는 동안 트리의 그 worktree 행에는 제거중 딱지가 붙습니다(요약을 만드는 동안 포함). 창을 닫아도 딱지는 남아 있어 어느 자리가 지워지고 있는지 보입니다. 닫기가 끝나면 행이 기록으로 옮겨지고, 실패하거나 중단하면 딱지가 사라집니다.

커밋하지 않은 변경이 막을 때 — 강제로 닫기

정리하지 못한 파일이 남아 worktree 가 걷히지 않을 때, 그 상자에서 무엇을 할지 골라 그대로 닫을 수 있습니다. 고를 것은 셋이고 기본은 닫지 않는 쪽입니다 — 고르기 전에는 닫고 보관이 잠겨 있습니다.

버튼의 문구가 고른 것을 그대로 말합니다(남기고 강제로 닫기 · 버리고 강제로 닫기) — 무엇을 누르는지 버튼에서 읽힙니다. 삭제된 파일은 남길 내용이 없어 목록에만 적히고, 아주 큰 파일(5MB 넘음 · 합계 50MB 넘음)도 기록이 부풀지 않게 목록에만 적힙니다.

세션에 말로 시킬 때도 같습니다 — 워크플로우 의 worktree 닫기 에 커밋하지 않은 변경이 있어도 닫기 · 버리는 변경을 기록에 남기기 두 칸이 있습니다.

닫는 도중 폴더를 지우지 못하면(잠긴 worktree 등) 보관을 되돌립니다. worktree 는 목록에 그대로 남아 있으니 알림의 사유를 확인하고 다시 닫으면 됩니다. 앱이 남긴 .baton/ 파일(요약 등)은 막는 이유가 아닙니다 — 기록으로 옮긴 뒤 함께 정리됩니다. 폴더가 이미 없는 worktree 는 기록만 남깁니다.

폴더 없는 worktree 를 한 번에 정리하기

터미널에서 폴더를 지웠거나 다른 도구가 걷어 간 worktree 는 앱이 말없이 보관하지 않습니다 — 트리에 폴더 없음 딱지를 달고 그대로 세워 둡니다(지운 것이 기록으로 넘어가 버리면 왜 사라졌는지 알 수 없기 때문입니다). 그래서 그런 자리가 쌓입니다. 한 번에 걷는 길이 둘 있습니다.

• 프로젝트 행 ⋯ › 폴더 없는 worktree 정리 — 그 레포의 자리만. 정리할 것이 없으면 항목이 아예 없고, 있으면 옆에 그 수가 적힙니다.
• 동기화 알림의 「정리」 — 세션 목록 머리의 새로고침 을 누르면(동기화가 함께 돕니다) 「폴더가 없는 worktree N개」 알림이 뜨고, 거기 정리 버튼이 붙습니다. 이쪽은 모든 레포가 대상입니다.
• 세션에 말로 — 「폴더 없는 워크트리 정리해줘」. 세션이 먼저 대상을 세어 보여 주고, 치우는 것은 실행 카드 로 승인을 받습니다(AI 에게 시키기). 원격에서도 같습니다 — 워크플로우 목록의 폴더 없는 worktree 정리 가 같은 일입니다.

창이 열리면 무엇을 닫는지 다시 세어 보여 줍니다 — 자리 목록과, 기록에 남을 대화 · 링크·문서 수입니다. 지울 폴더는 없습니다(이미 사라졌습니다). 브랜치는 그대로 남아 같은 브랜치로 언제든 다시 만들 수 있습니다.

정리 를 누르면 창은 바로 닫히고 일은 뒤에서 계속됩니다 — 자리마다 닫기 와 똑같은 경로를 타므로(보관 · 사용 토큰 확정) 자리 수만큼 시간이 걸립니다. 끝나면 알림이 몇 개를 옮겼는지 말합니다. 어떤 자리가 막히면 그 자리만 트리에 그대로 남고 나머지는 옮겨집니다 — 알림에 사유가 뜹니다.

그룹 닫기 — 묶음째 기록으로#

에픽 하나가 끝나면 그 그룹의 worktree 를 하나씩 닫지 않고 한 번에 옮깁니다. 그룹 행 ⋯ › worktree 모두 닫기.

창이 열리면 무엇을 닫는지 세어 보여 줍니다 — 자리 목록(폴더 없음 · 변경 N개 표시), 기록에 남을 대화 수, 그리고 고를 것 셋입니다.

버튼에 실제로 닫히는 수가 적힙니다(변경이 남은 자리를 넘기지 않으면 그 수만큼 줄어듭니다). 누르면 창은 바로 닫히고 일은 뒤에서 계속됩니다 — 자리를 차례로 닫습니다.

진행은 트리가 말합니다: 대상 자리 전부에 제거중 딱지가 한 번에 붙고, 닫힌 자리가 기록으로 빠지면서 남은 수가 줄어듭니다. 딱지에 마우스를 올리면 아직 몇 자리가 남았는지 뜹니다. 아직 차례가 오지 않은 자리도 제거중 입니다 — 그 자리를 따로 닫으려 하면 「다른 닫기가 이 자리를 처리하는 중입니다」로 거절합니다(같은 자리를 두 번 닫아 한쪽이 실패하는 것을 막습니다).

세션에 말로 시킬 수도 있습니다 — 워크플로우 의 그룹 닫기 가 같은 일입니다(실행 카드 로 승인을 받습니다).

머리 · 세션 탭 · 정보 칩#

12

정보 칩은 누르면 아래로 서랍이 열립니다. 화면에 보이는 순서대로 ⌘⌃1~⌘⌃9 가 붙습니다.

머리 오른쪽 ⋯ 는 worktree 동작 메뉴입니다.

• git 상태 — 이 worktree 폴더의 브랜치·변경 파일을 팝업으로 봅니다(폴더가 없으면 「폴더 없음」).
• 세션 탭: ⌘T 새 세션 · ⌘⇧T 새 터미널(아래 참고) · ⌘W 탭 닫기 · ⌃[ 이전 탭 · ⌃] 다음 탭(줄의 위치 순서 — 끌어 옮긴 순서 그대로, 끝에서는 반대쪽 끝으로) · ⌃Tab/⌃⇧Tab 왼쪽 / 오른쪽 탭 · ⌃⇧[/⌃⇧] 탭 히스토리(전에 골랐던 탭으로). 입력창에 쓰는 중에도 됩니다. 터미널 탭도 같은 줄의 같은 탭이라 이 키들이 그대로 듣습니다.
• 탭 줄 오른쪽 + 의 세 갈래 — 그냥 누르면 세션(그 worktree 의 티켓 · PR · 변경 · 문서 · 성과 · 링크를 갱신해 맥락으로 안고 시작합니다), ⌥와 함께 누르면 맥락 없는 세션, ⌘와 함께 누르면 터미널입니다(터미널 탭). 버튼에 마우스를 올리면 이 셋이 툴팁에 적혀 있고, 같은 갈래가 worktree 동작 메뉴에도 눌리는 항목으로 있습니다(세션 추가 · 세션 추가 · 맥락 없이 · 터미널 열기) — 누르는 손잡이를 모르고도 찾을 수 있게 둔 것입니다. 폴더가 사라진 worktree 에서는 세 갈래 모두 꺼져 있습니다.
• 엔진을 골라 세션 추가 — 연동에 Codex 계정이 하나라도 있으면 worktree 동작 메뉴에 세션 추가 · Codex 로 · 세션 추가 · Claude 로 가 더 섭니다. 그냥 세션 추가 는 그 프로젝트에 지정된 AI 계정의 엔진으로 엽니다(Codex 계정이면 Codex) — 이 두 항목은 그 지정과 다른 엔진으로 한 세션만 열 때 씁니다. 세션이 열린 뒤에는 엔진이 바뀌지 않습니다. Codex 계정이 없으면 이 두 항목은 보이지 않습니다.
• 새 세션 탭의 자리 — 지금 선택된 탭 바로 뒤에 섭니다(⌘T · + · 트리에서 지금 보고 있는 worktree 에 추가). 선택된 탭 없이 추가하면(다른 worktree 의 트리 행 · 기록 › 닫힌 세션의 되살리기) 그 줄의 맨 뒤에 섭니다. 탭 순서는 답이 와도 바뀌지 않고, 앱을 다시 띄워도 그대로입니다.
• 보던 세션으로 돌아오기 — 트리에서 worktree 행을 고르면(클릭 · ↑↓) 그 worktree 에서 마지막으로 보던 세션 탭이 열립니다. 다른 worktree 를 보고 와도, 앱을 다시 띄워도 그대로입니다. 그 세션을 닫았거나 아직 고른 적이 없으면 줄의 첫 탭이 열립니다. 알림의 「세션 열기」 · 명령 팔레트의 세션처럼 세션을 집어 가는 길은 기억과 상관없이 그 세션으로 갑니다.
• 탭 순서 바꾸기 — 탭을 끌어서 다른 탭의 앞(왼쪽 절반)이나 뒤(오른쪽 절반)에 놓습니다. 놓일 자리에 세로 막대가 섭니다. 키보드로는 탭에 포커스를 두고 ⌥←/⌥→ 로 한 칸씩 옮깁니다(끝에서는 더 가지 않습니다). 바꾼 순서는 worktree 마다 저장되어 화면을 옮기거나 앱을 다시 띄워도 그대로이고, 보고 있던 탭은 옮긴 뒤에도 그대로 선택돼 있습니다.
• 터미널 탭 — 세션 탭과 같은 줄에 같은 탭으로 섭니다. ⌘⇧T, 탭 줄 오른쪽 + 를 ⌘와 함께 클릭, worktree 동작 메뉴의 터미널 열기, 트리의 워크스페이스 · 프로젝트 · worktree · 세션 행 메뉴에서 엽니다. 앱을 떠나지 않고 npm run dev · npm test · git status 를 돌리는 자리입니다.
  • 그룹 세션 자리에서도 열립니다 — 그룹은 자기 폴더가 없으므로, 터미널은 그 그룹 세션이 실제로 뜬 폴더(구성원 worktree 중 줄기 우선)에서 뜹니다. 구성원이 하나도 없는 그룹과 프로젝트 묶음에는 빌릴 폴더가 없어 터미널 열기 항목이 아예 보이지 않습니다 — 구성원 프로젝트 · worktree 에서 여세요.
  • 세션 탭과 똑같이 다룹니다 — 새 터미널은 지금 선택된 탭 바로 뒤에 서고, 끌어서 순서를 바꾸거나 ⌥←/⌥→ 로 한 칸씩 옮길 수 있으며, ⌃Tab · ⌃[/⌃] 가 세션 탭과 터미널 탭을 가리지 않고 지납니다. 세션 탭을 누르면 대화로, 터미널 탭을 누르면 셸로 곧바로 돌아옵니다. 다른 것은 탭 안에 든 것뿐입니다.
  • 탭 이동 키는 셸 안에서 쳐도 듣습니다 — 커서가 터미널 안에 있어 명령을 치는 중이어도 ⌃Tab · ⌃[/⌃] · ⌃⇧[/⌃⇧] 는 앱이 먼저 받아 탭을 옮깁니다(셸로는 가지 않습니다). 그 대신 터미널에서 ⌃[ 로 ESC 를 보낼 수는 없습니다 — Esc 키를 쓰면 됩니다(vim 도 그것으로 나옵니다). ⌃C 중단 · ⌃D · ⌃R 이력 검색처럼 나머지 Ctrl 조합은 모두 셸의 것입니다.
  • 어디서 열리나 — 셸은 그 행이 가리키는 폴더에서 뜹니다: 워크스페이스 행은 워크스페이스 폴더, 프로젝트 행은 그 레포의 줄기, worktree · 세션 행은 그 worktree 입니다. 폴더가 사라진 worktree 에서는 「폴더 없음」으로 열리지 않습니다.
  • 진짜 터미널입니다 — vim · top · less · ssh 처럼 화면을 통째로 쓰는 프로그램이 그대로 돌고, Ctrl+C · Tab 완성 · 방향키 · 색이 평소 터미널과 같습니다. 창 크기를 바꾸면 그 크기가 셸까지 전해집니다.
  • 프롬프트의 특수문자도 그대로 보입니다 — agnoster · powerlevel10k 처럼 Powerline · Nerd Font 글자를 쓰는 셸 프롬프트가 네모(□)로 깨지지 않도록, 터미널은 한글 등폭 + Nerd 글리프를 가진 글꼴을 먼저 찾아 씁니다(D2Coding · MesloLGS NF · Hack Nerd Font 등 — 기계에 깔려 있는 것을 씁니다). 그런 글꼴이 하나도 없으면 앱의 기본 등폭으로 그리며, 이때 Powerline 글자는 그 글꼴에 없어 네모로 보일 수 있습니다. 한글도 같은 이유로 정확히 두 칸에 맞아 표·눈금이 어긋나지 않습니다.
  • 터미널마다 셸이 따로입니다 — 한쪽에서 cd 해도 다른 터미널은 그대로고, npm run dev 를 켜 둔 채 다른 탭에서 git status 를 칠 수 있습니다. 탭 이름은 더블클릭으로 고칩니다.
  • 닫으면 돌던 명령도 끝납니다 — 탭의 ✕ 나 ⌘W 는 그 셸과 거기서 돌던 것(개발 서버 등)을 함께 끝냅니다. 누르는 즉시 탭이 사라집니다 — 세션 탭과 달리 확인을 묻지 않습니다(되살릴 기록이 없는 셸 한 장이기 때문입니다). 그냥 다른 탭으로 옮기는 것은 끝내는 것이 아닙니다 — 출력은 돌아와도 그대로 남아 있습니다. 앱을 끄면 열려 있던 터미널은 모두 정리됩니다.
  • 복사 · 붙여넣기 는 ⌘C · ⌘V 입니다. 고른 글자가 없을 때의 ⌃C 는 평소처럼 실행 중단입니다. 지난 출력은 위로 스크롤해서 봅니다(터미널당 5000줄까지).
  • 셸은 로그인 셸로 뜹니다 — 평소 터미널과 같은 PATH 라 node · npm · git 이 그대로 잡힙니다. macOS 에서는 계정에 설정된 셸(보통 zsh)을 씁니다.
• 탭이 많아지면 — 탭은 칸 폭에 맞춰 조금씩 좁아지고, 그래도 넘치면 줄이 가로로 흐릅니다(트랙패드 · 마우스 휠 · 탭에 포커스를 두고 ←→). 넘친 쪽 끝은 흐려져 「더 있다」를 알려 줍니다. 고른 세션의 탭은 언제나 보이는 자리로 따라옵니다. +(세션 추가)와 오른쪽 스코프 글은 줄과 함께 흐르지 않고 제자리에 남으므로, 탭이 몇 개든 세션을 더 열 수 있습니다. 끌어서 옮기는 중에 줄 끝에 손을 대면 줄이 따라 흘러 화면 밖 자리로도 옮길 수 있습니다.

세션 대화#

입력창에 쓰고 ⌘Enter 로 보냅니다. 세션이 도구(명령 실행·파일 쓰기)를 쓰려 하면 승인 카드 가 뜹니다.

1. 보드에서 worktree 를 고르고 세션 탭을 누릅니다(⇧Enter 는 어디서든 입력창으로 점프).
2. 입력창에 지시를 쓰고 ⌘Enter.
3. 응답 중에는 응답 중 · n초 가 보입니다. 멈추려면 ⌃C 또는 그 줄의 중단 (⌃C)(세션은 살아 있습니다). 한글 입력 상태 그대로 눌러도 되고, 손이 입력창이 아니라 대화 쪽에 있어도 됩니다. 복사는 종전대로 ⌘C 입니다.
4. 응답이 끝나기를 기다리지 않고 이어서 보내도 됩니다. 그 말 아래에 대기 중 이 서고, 세션이 지금 하던 단계(명령 실행 · 파일 읽기 같은 도구 호출 하나)를 끝내는 자리에서 그 말을 읽으면 반영됨 · 14:18 로 바뀝니다 — 끝까지 다 하고 나서가 아니라 하던 일 도중에 반영됩니다. 세션이 그 말을 읽기 전에 멈추면 읽히지 않음 이 서니 다시 보내세요.
5. 승인 카드가 뜨면 승인 또는 거부. 놓친 승인은 상단바 답 대기 배지 에 모입니다.
6. 세션이 고르라고 물으면 답을 기다립니다 카드가 뜹니다. 질문마다 선택지를 고르고(여러 개 고르는 질문은 체크박스), 맞는 것이 없으면 기타 칸에 직접 씁니다. 모든 질문에 답하면 답 보내기 — 세션이 그 답을 받아 이어갑니다. 넘기려면 답하지 않기.
7. 보낸 뒤에는 대화에 질문에 답함 줄이 남습니다 — 물음 과 내 답 이 쌍으로 갈려 한 쌍씩 서므로, 나중에 내가 뭐라고 답했는지 를 그 자리에서 그대로 읽을 수 있습니다. 답에 쓴 줄바꿈·목록·코드는 쓴 그대로 보입니다.

12

1

원격 제어 — 폰에서 이어 쓰기#

앱에서 돌리던 세션을 claude.ai/code 나 Claude 앱(폰)에서 이어 씁니다. 세션은 계속 이 기계에서 돌고, 파일·도구도 이 기계의 것을 씁니다.

1. 입력창 위 표시줄의 원격 을 누르고 원격 제어 켜기. 쉬던 세션이면 몇 초 동안 원격 연결 중… 이 보입니다.
2. 원격 연결됨 이 되면 다시 눌러 claude.ai 에서 열기 · QR — 폰으로 열기 · 링크 복사. Claude 앱의 코드 세션 목록에는 baton · 워크스페이스 › 프로젝트 › 워크트리 · 세션 으로 뜹니다 — 이름만 보고 어느 작업의 세션인지 알아볼 수 있게 자리가 함께 붙습니다(이름은 트리에 보이는 표기명 그대로이고, 없는 마디는 빠집니다).
3. 폰으로 옮길 때는 QR 이 가장 빠릅니다 — 주소를 카메라로 찍으면 됩니다. 주소는 원격을 켤 때마다 새로 발급되므로, 껐다 켜면 먼저 띄운 QR 은 더 이상 열리지 않습니다.
4. 폰에서 보낸 말은 대화에 나 · 원격 으로 남고, 답과 도구 진행도 그대로 쌓입니다.
5. 폰에서 승인하면 앱의 승인 카드는 다른 기기에서 답함 으로 접힙니다.
6. 그만두려면 원격 제어 끄기. 앱을 끄거나 세션을 닫아도 끊깁니다.

12

대화 안 찾기 (돋보기 · ⌘F)#

지금 세션의 대화에서 말을 찾습니다. 매치 수와 지금 위치(2/8)가 보이고 이전·다음으로 옮겨 다닙니다.

1. 대화 로그 오른쪽 위 돋보기 를 누르거나, 손이 대화·입력창·세션 탭 에 있을 때 ⌘F.
2. 찾을 말을 칩니다 — 대화 속 일치하는 곳이 칠해집니다.
3. Enter 다음 · ⇧Enter 이전(⌘G / ⌘⇧G 도 같습니다). 끝에서 처음으로 돕니다.
4. Esc 로 닫으면 손이 원래 자리로 돌아갑니다.

1

코드 보기 (파일 트리 · 파일 탭)#

고른 과업(또는 프로젝트)의 폴더를 그대로 열어 파일을 읽습니다. 파일은 탭으로 뜨고, 확장자에 맞춰 색이 칠해집니다. 고치지는 않습니다 — 고치는 일은 세션에게 맡기고, 여기서는 읽고 줄에 코멘트를 달아 넘깁니다.

1. 보드에서 worktree 나 프로젝트 행을 고릅니다.
2. 창 오른쪽 위 코드 보기(</>) 를 누르면 오른쪽에 파일 트리 가 섭니다. 폴더가 없는 자리(워크스페이스 행 · 그룹 행)에서는 이 아이콘이 아예 뜨지 않습니다.
3. 폴더를 누르면 그 한 겹만 읽습니다 — 레포가 몇 만 개든 여는 속도가 같습니다.
4. 파일을 더블클릭하면 세션 탭과 같은 줄에 파일 탭이 섭니다(Enter 도 같습니다). 한 번 누르면 고르기만 합니다 — 훑어보다가 탭이 잔뜩 쌓이지 않게. 폴더는 종전대로 한 번에 접히고 펼쳐집니다.
5. 탭 옮기기(⌥← ⌥→ · 드래그) · ⌘W 닫기가 세션 탭과 똑같습니다.
6. 파일 안에서 말을 찾으려면 ⌘F — 찾은 줄이 칠해지고 Enter / ⇧Enter 로 옮겨 다닙니다.

1. 줄에 코멘트 — 줄 번호 옆 + 를 누르고 남길 말을 씁니다(⌘Enter 로 추가). 코멘트가 있는 줄은 말풍선이 늘 보입니다.
2. 다 썼으면 아래 줄의 AI 에게 보내기 — 그 과업의 세션이 받아 고치고, 반영 또는 기각 으로 답합니다. git 상태 창의 리뷰 와 같은 흐름이고 같은 목록에 쌓입니다.

컨텍스트 잔량 · 압축#

입력창 위 표시줄 오른쪽 끝에 컨텍스트 n% 남음 이 보입니다. 25% 아래는 주의색, 10% 아래는 위험색입니다. 누르면 대화를 압축할지 묻습니다.

1. 입력창 위 컨텍스트 n% 남음 을 누릅니다.
2. 대화를 압축할까요? 에서 압축. 이전 대화가 요약으로 바뀌어 남은 컨텍스트가 늘어납니다.
3. 압축은 뒤에서 돕니다. 끝나면 대화에 표식이 남습니다.

12

받은 컨텍스트#

이 세션이 안고 시작한 것 — 작업 폴더 · 프로젝트 지침(CLAUDE.md) · 사용자 지침 · 앱이 붙인 안내 · baton 도구 · 시작 맥락(PR·변경 요약)을 보여 줍니다.

학습·통합 프로젝트에서는 커리큘럼도 함께 실립니다 — 과목 · 진도 · 차례 · 학습 방식 · 이 자리가 몇 장인지 · 노트 경로 · 복습 큐 수. 그래서 세션은 공부가 앱의 커리큘럼으로 돌아간다는 것을 알고 뜨고, 레포에 커리큘럼 문서를 따로 만들지 않습니다(학습 프로젝트).

/clear 로 대화를 비워도 시작 맥락은 남습니다. 시작 맥락은 대화의 첫 말로 들어가서 /clear 가 함께 지우는데, 앱이 그 자리에서 같은 글을 마지막으로 확인한 캐시로 다시 넣습니다 — 그룹 세션은 비운 뒤에도 자기 묶음과 구성원을 압니다. 대화에 「/clear 뒤 이 자리의 시작 맥락을 다시 넣었습니다」 한 줄이 서고, 받은 컨텍스트에도 다시 실립니다. 맥락 없이 연 세션에는 비운 뒤에도 넣지 않습니다.

1. 대화 로그 위 도구줄에서 받은 컨텍스트.
2. 항목의 전체 보기 로 원문을 펼칩니다. 오른쪽 위 새로고침으로 다시 읽습니다.

세션 가져오기 — 다른 세션에서 알아낸 것#

다른 세션의 대화를 다섯 항목(무엇을 하려던 세션인가 · 확정된 사실 · 결정과 이유 · 만진 파일·명령 · 미해결) 한 장으로 줄여 입력창에 넣습니다. 전송은 하지 않습니다. 앱에서 연 세션뿐 아니라 앱 밖에서 연 Claude 세션(터미널의 claude · IDE · 다른 Agent SDK 앱)도 가져옵니다.

1. 입력창 아래 세션 가져오기.
2. 목록에서 세션을 고릅니다. 찾기 상자(이름 · 세션 ID · 장소 · 폴더)와 장소 · 출처 · 기간 칩으로 좁힙니다. 앱 밖 세션만 보려면 출처 앱 밖.
3. 목록에 없는 세션은 Claude 세션 ID(5b3f7c1d-8e2a-… 모양)를 찾기 상자에 붙여 넣고 ID 로 가져오기 를 누릅니다.
4. 압축본과 출처를 읽고, 필요하면 아래 글상자에서 고친 뒤 입력창에 넣기.

다른 세션에 요청 보내기 — 옆 자리에 일을 넘긴다#

세션 가져오기가 다른 세션에서 가져오는 길이라면, 이것은 다른 세션에 보내는 길입니다. 내가 지금 알아낸 것이 옆 worktree 의 세션이 깔고 있는 전제를 무너뜨릴 때, 그 세션으로 찾아가 같은 설명을 다시 쓰지 않아도 됩니다.

보내는 것은 언제나 나입니다. AI 가 대상과 글을 준비할 수는 있지만, 한 글자도 내 승인 없이는 나가지 않습니다 — 설정의 모든 권한 자동 승인 을 켜 두었어도 이것만은 매번 묻습니다(그 설정은 도구 승인, 즉 명령 실행·파일 쓰기에만 듣습니다). 남의 작업 자리를 움직이는 일이기 때문입니다. 자리를 비운 사이에도 이어지게 하려면 카드의 끝까지 자동 승인 을 켭니다 — 그 세션 하나에만, 끌 때까지입니다.

AI 에게 시키는 길

1. 대화에서 말합니다 — 「이거 저쪽 세션에도 알려줘」 · 「의존하는 세션에 이걸 시켜줘」 · 「이 그룹 세션들에 일괄로 요청해줘」.
2. 대화에 다른 세션에 요청 카드가 서고 세션은 거기서 멈춥니다(상단바 답을 기다리는 세션 에도 다른 세션에 보낼 요청 으로 오릅니다).
3. 카드에서 대상을 빼고(체크 끄기) 글을 고칩니다. 고치면 모델이 내민 원안 보기 가 나와 견줄 수 있습니다.
4. 답을 어떻게 정리해 달라고 할까요 에 원하는 형식을 적습니다(비워 두면 「무엇을 했는지 · 남은 것 · 막힌 것」으로 나갑니다). 이 말은 요청문 꼬리에 따로 붙어, 시키는 일과 섞이지 않습니다.
5. 답이 다 오면 이 세션이 모아서 알리기 — 켜 두면 보낸 세션이 모두 답한 뒤 이 세션이 스스로 깨어나 읽고 정리해서 알려 줍니다. 알린 뒤에 그 세션이 이어서 답하면(백그라운드 검사가 끝난 뒤 등) 다시 깨어납니다. 끄면 결과는 각 세션에서 직접 봐야 합니다.
6. 이 세션의 요청·실행은 끝까지 자동 승인 — 자리를 비울 거라면 여기서 켭니다(아래). 켜면 버튼이 보내고 · 끝까지 자동 승인 으로 바뀝니다.
7. N개 세션에 보내기 — 고른 수가 버튼에 적혀 있습니다. 보내지 않으려면 보내지 않기.

1234

내가 직접 보내는 길

• 고른 세션 여러 개에 — 작업 목록 머리의 선택 을 켜고 세션을 고른 뒤 요청 보내기.
• 그룹 구성원 전체에 — 그룹 행 메뉴 › 구성원 세션에 일괄 요청. 그 그룹의 worktree 에 열려 있는 세션이 대상으로 채워집니다(그룹 세션 자신은 빠집니다).

세션 간 대화 — 목표를 두고 서로 요청을 주고받는다#

다른 세션에 요청 이 한 번 물어 한 번 답받는 길이라면, 이것은 끝날 때까지 양쪽이 번갈아 손을 보는 길입니다. 받은 세션은 답에 「그쪽에서 이것을 확인해 주세요」를 함께 적고, 그 답을 읽은 세션이 처리한 뒤 다시 요청합니다 — 조사 → 반영 → 재확인처럼 한 번으로 끝나지 않는 일에 씁니다.

한 번 승인하면 20턴까지 묻지 않습니다. 그 대신 승인하는 내용이 달라집니다 — 「이 글을 한 번 보낼까」가 아니라 「이 목표로 20턴까지 주고받을까」 입니다. 20턴을 다 쓰면 멈추고 다시 묻습니다(승인하면 20턴이 더 붙습니다). 턴은 오간 메시지 한 건이 1턴이라, 20턴이면 두 세션이 각자 열 번쯤 말합니다.

여는 길

1. 대화에서 말합니다 — 「저 세션과 번갈아 확인하면서 이거 끝까지 맞춰줘」 · 「이 목표로 저쪽과 주고받으면서 해결해줘」.
2. 대화에 다른 세션과 대화 시작 카드가 섭니다. 보통 요청 카드와 다른 점은 목표 칸이 맨 위에 서는 것입니다 — 이 문장이 턴마다 상대에게 함께 가고, 승인하는 대상도 이것입니다.
3. 목표와 보낼 글을 손봅니다. 목표가 비어 있으면 보낼 수 없습니다.
4. 대화 시작 · 20턴까지 — 누르면 첫 요청이 가고, 그 뒤의 왕복은 승인 카드가 서지 않습니다. 나간 것은 모두 대화에 대화 n/20턴 · 보냈음 으로 남아 되짚을 수 있습니다.
5. 상대는 하나만 고를 수 있습니다 — 대화는 두 세션 사이의 것입니다. 여러 곳에 같은 일을 뿌리는 것은 일괄 요청 입니다.

12

20턴을 다 썼을 때

1. 다음 요청은 한 글자도 나가지 않고 대화를 20턴 더 이어갈까요? 카드가 섭니다 — 지금까지 몇 턴을 주고받았는지와 목표를 함께 보여 줍니다.
2. 20턴 더 주고 보내기 — 예산이 20턴 늘고, 들고 있던 글이 그대로 나갑니다(승인 뒤에 AI 가 다시 글을 짜내지 않습니다).
3. 여기서 그만하기 — 대화가 닫힙니다. 보낸 세션은 그것을 실패로 읽지 않고 지금까지 오간 것을 정리해서 알려 줍니다.

1

대화 흐름 — 주고받은 것을 한 장으로#

세션 간 대화 를 한 세션에서, 그 세션이 누구에게 무엇을 몇 번 묻고 답했는지를 한 장으로 봅니다. 그림에는 고른 세션에서 이어진 대화 체인만 섭니다 — 고른 세션에게 시킨 쪽, 고른 세션이 넘긴 쪽, 그 쪽이 또 넘긴 쪽까지 따라갑니다. 같은 worktree 에 있어도 이 체인에 이어지지 않은 세션은 끼지 않습니다. 세션 패널을 옮겨 다니지 않고 일이 끝난 뒤 무슨 일들을 했는지 되짚는 자리입니다.

그림에 서는 오감은 두 가지입니다. 세션이 다른 세션에 직접 요청한 것, 그리고 세션이 워크플로우를 돌려 다른 세션에 일을 넘긴 것(예: 「새 작업 시작」이 연 리드 세션)입니다. 둘은 선의 모양으로 갈리고, 그림 위 범례 한 줄이 그 뜻을 말합니다.

체인은 고른 세션에서 3 단계 · 세션 20개까지 펼칩니다. 그 너머에도 주고받은 세션이 있으면 끝 노드에 +n 더 가 붙습니다 — 그 세션으로 가서(↗) 「대화 흐름」을 다시 열면 거기서부터 이어 볼 수 있습니다.

AI 를 부르지 않습니다. 노드의 글도 배선의 숫자도 이미 대화에 적힌 것을 잘라 온 것이라, 열어도 토큰이 들지 않습니다. 「↻ 다시 읽기」도 마찬가지입니다.

여는 길

1. 워크스페이스 트리 에서 대화중 · 대화 승인 대기 라벨이 붙은 세션을 누릅니다(또는 상세에서 그 세션 탭을 고릅니다).
2. 세션 줄의 + 옆에 대화 흐름 버튼이 서 있습니다. 고른 세션이 아무와도 주고받지 않았으면 버튼이 서지 않습니다 — 탭을 옮기면 그 세션 기준으로 다시 정해집니다.
3. 누르면 화면을 거의 채우는 창이 열립니다.

12345

읽는 법

끝까지 자동 승인 — 자리를 비워도 이어지게#

요청을 넣고 자리를 뜨면, 중간에 뜬 승인 카드에서 세션이 멈춰 섭니다. 그 세션 하나에 한해 승인을 묻지 않게 하는 스위치입니다.

켜는 곳 · 끄는 곳

• 요청 · 실행 카드에서 — 이 세션의 요청·실행은 끝까지 자동 승인 체크를 켜고 보냅니다. 자리를 비우기 직전에 누르는 마지막 카드가 여기라, 켜는 자리는 이곳이 먼저입니다.
• 끄기 — 대화 상태 줄의 자동 승인 중 배지 옆 지금 끄기. 배지에는 그 스위치로 나간 건수가 함께 섭니다.

문서#

과업에 붙은 설계 문서·링크입니다. 워크플로우와 세션이 이 문서를 컨텍스트로 씁니다. 여러 레포에 걸친 그룹에도 같은 방식으로 붙일 수 있습니다 — 그 경우 문서는 구성원 worktree 가 아니라 묶음에 붙습니다.

1. 정보 칩 문서 n 을 누릅니다.
2. 문서 추가 에 링크(또는 로컬 HTML · Markdown · PDF)를 넣으면 제목이 자동으로 채워집니다. HTML · Markdown 은 대화 자리에서, PDF 는 PDF 창에서 열립니다.
3. 앱에서 열면 글만 앱 서식(테마 · 글꼴 · 표)으로 다시 그립니다 — 문서가 들고 온 색·글꼴·레이아웃은 쓰지 않습니다. 로컬 HTML 은 표가 많아 패널 폭을 그대로 쓰고, Markdown 은 읽기 좋은 폭을 지킵니다. 원본 모습 그대로 보려면 머리의 원본 그대로 열기 로 기본 브라우저에서 엽니다.
4. 행의 ▥ 는 옆에서 열기 입니다 — 화면을 좌우로 나누고 오른쪽 칸 브라우저의 새 탭에서 봅니다. 문서를 띄워 놓고 반대쪽에서 일할 때 씁니다(브라우저).
5. 앱에서 여는 문서는 행에 앱 열기 · 브라우저 열기 가 나란히 섭니다 — 열어 보지 않고도 바로 기본 브라우저로 보낼 수 있습니다. 로컬 파일(HTML · Markdown · PDF)뿐 아니라 주소 문서(링크 · 슬랙)도 같습니다: 그 문서들도 대화 자리에서 열리기 때문입니다. ⌥ 나 ⌘ 를 누른 채 문서를 누르면 메뉴를 건너뛰고 바로 브라우저로 열립니다.
6. 링크인 문서(링크 · 슬랙)는 행에 복사 아이콘이 섭니다 — 누르면 그 주소가 클립보드에 들어갑니다(행 ⋯ › 링크 복사 도 같습니다). 로컬 파일(HTML · Markdown · PDF)에는 서지 않습니다: 이 기기의 파일 경로라 복사해 붙일 곳이 없습니다 — 그 자리의 답은 Finder 에서 보기 입니다.
7. 행의 ⋯ 로 수정 · 삭제합니다.
8. 행을 누르면 앱 어디서나 같은 링크 네 갈래 메뉴가 섭니다(브라우저 · 앱에서 · 옆에서 · 주소 복사). 앱에서 열기 는 위에 적은 그 자리(뷰어 · 팝업 · PDF 창 · 웹 뷰)를 엽니다.

성과#

「그래서 무엇이 좋아졌나」를 과업마다 남깁니다. 지표 · 근거 · 신뢰도가 카드로 섭니다.

1. 정보 칩 성과 n.
2. 성과 추가 에서 직접 적거나, 성과 측정 워크플로우로 지표를 조회해 채웁니다.
3. 연결 티켓이 있으면 성과를 Jira 에 반영 으로 티켓 설명 아래 「성과」 절을 씁니다.

PR 개발자#

worktree 브랜치의 PR 상태 · checks · 미해결 리뷰 스레드를 봅니다. GitHub 기능이 켜져 있어야 보입니다.

1. 정보 칩 PR #번호(없으면 PR 없음). 칩을 눌러 열 때마다 그 PR 을 다시 읽어옵니다 — 상태 · checks · 미해결 코멘트가 지금 값으로 바뀝니다.
2. 서랍을 열어 둔 채 기다릴 때는 지금 갱신 을 누릅니다(칩을 열 때 도는 것과 같은 일입니다).
3. 머지 는 체크가 모두 통과 · 기준 승인 도달 · 미해결 코멘트 0 일 때만 눌립니다. 조건이 덜 찼으면 버튼이 꺼져 있고, 버튼에 마우스를 올리면 무엇이 남았는지 를 알려 줍니다.
4. PR 이 자동으로 안 잡히면 다른 PR 확인 또는 ⌘⇧P 로 링크를 붙여 직접 연결합니다.
5. 리뷰 요청 은 슬랙 리뷰 채널에 PR 을 남기고, 배포 준비 실행 은 커밋→리뷰 루프→PR→checks 를 돌립니다.

구독 한도 · 새로고침#

5h: 5% (3h12m) 는 5시간 창 사용률과 초기화까지 남은 시간, wk: 85% (2d9h) 는 주간 창입니다. 옆의 「n초 전」 은 마지막으로 읽은 시각입니다.

창이 좁으면 상단바가 한 줄을 지키려고 곁말을 이 순서로 하나씩 내립니다 — 워크스페이스 이름이 다 보이는 데까지만 내리므로, 창을 넓히는 동안 이름이 오히려 짧아지는 일은 없습니다.

1. 괄호 안의 남은 시간과 「n초 전」 — 퍼센트와 색은 그대로이고, 칸에 마우스를 올리면 남은 시간이 보입니다.
2. 「동기화 정상」 글자(초록 점은 남습니다)와 명령 버튼의 「명령」 글자(⌘K 키캡은 남습니다).
3. MCP 배지가 「MCP 2」 처럼 짧아집니다 — 마우스를 올리면 전체 문구가 보이고, 누르면 진단으로 가는 것은 같습니다.

그래도 모자라면 워크스페이스 이름이 … 로 줄어듭니다(마우스를 올리면 전체 이름). 가장 좁은 창에서도 「orc…」 처럼 앞 글자는 남습니다.

모델 하나에만 걸린 주간 한도가 있으면 주간 칸 뒤에 그 모델 이름으로 한 칸 더 섭니다 — 예: Fable: 12% (2d9h). 이름은 계정에 내려온 표기명 그대로입니다. 계정에 그런 한도가 없으면 칸도 없지만, 한 번 선 칸은 그 뒤로 사라지지 않습니다 — 값을 못 읽은 때에는 Fable: - 로 자리를 지킵니다.

1. 「n초 전」 옆 새로고침 아이콘을 누르면 지금 다시 읽습니다.
2. 열린 세션이 하나도 없으면 새로 읽지 못했다는 안내가 뜹니다 — 세션을 하나 열고 다시 누릅니다.

답을 기다리는 세션#

세션이 사람의 확인·승인·선택을 기다리면 상단바에 손 아이콘 + 숫자 배지가 뜹니다. 0 이면 보이지 않습니다. 내가 열지 않은 세션(워크트리 생성 · 워크플로우가 연 것)도 같은 배지에 섭니다.

1. 배지를 누르면 기다리는 것이 세션별로 묶여 뜹니다 — 묶음 이름이 워크트리명 - 세션명 이고, 오래 기다린 세션이 위입니다. 한 세션 안에서는 그 자리에서 끝낼 수 있는 도구 승인 이 먼저 옵니다.
2. 세션을 닫으면 그 세션이 기다리던 승인·질문도 함께 사라집니다 — 답할 세션이 없는 질문은 배지에 남지 않습니다.
3. 도구 승인 은 그 자리에서 승인 / 거절.
4. 고르라는 질문 은 선택지를 미리 보여 줍니다. 세션으로 가면 대화의 답을 기다립니다 카드에서 골라 답 보내기.
5. 답을 기다리는 대화 는 세션으로 또는 숨기기, 워크플로우 확인 은 답하기 · 실행으로.
6. 다른 세션에 보낼 요청 은 세션으로 만 있습니다 — 여기서 보내지 않습니다. 대상을 빼고 글을 고치는 것이 그 승인의 실질이라, 대화의 요청 카드 에서 합니다.
7. 뗄지 정할 문서 는 그 자리에서 떼기 / 떼지 않기 — 묻는 것이 「이 한 건을 뗄까」 하나뿐이고, 무엇을 어디에서 떼는지(자리 · 제목 · 주소)가 행에 다 적혀 있습니다. 자세한 것은 말로 문서 떼기.
8. 새로 열린 세션 은 세션으로 또는 지우기(목록에서만 뺍니다 — 세션은 그대로 열려 있습니다).

⌘K 명령 팔레트#

어디로 갈지·무엇을 할지 한 번에 찾습니다. 세션 · 워크트리 · 프로젝트 · 티켓 · 즐겨찾기 · 문서 · 워크플로우 · 에이전트 · 성과 · 위키가 종류별로 묶여 나옵니다.

1. ⌘K 또는 상단바 명령. 팔레트를 연 채 그 위에 다른 창(링크 팝업 등)이 떠서 가려졌으면 ⌘K 를 한 번 더 누르면 팔레트가 맨 위로 올라옵니다 — 치던 검색어는 그대로이고, Esc 로 닫으면 아래 창으로 돌아갑니다.
2. 검색어를 치고 ↑↓ 로 고른 뒤 Enter — 그 자리로 가거나, 워크플로우를 실행하거나, 에이전트에게 일을 맡깁니다.
3. 종류를 알면 @ 로 범위를 잡습니다: @즐겨찾기 배포 · @에이전트 시안 · @위키 롤백. Tab 으로 자동완성, 빈 입력에서 ⌫ 로 풉니다.
4. ⌥1~⌥9 로 종류 필터를 켜고 끄고, ⌥0 으로 초기화합니다.

⌘⇧F 통합 검색#

앱의 거의 모든 것을 찾습니다 — Jira 티켓 · 활성/보관 과업 · 세션 · 대화 · 문서 · 산출물 · 성과 · 메모 · 즐겨찾기 · PR · 레포.

문서는 어디에 붙였든 찾힙니다. 소속 칸이 어디 것인지 말합니다 — worktree 에 붙인 문서는 그 레포 이름, 그룹에 붙인 문서는 그룹 · 이름. 그룹은 레포가 아니므로 기록 화면의 필터(보관 · 성과 있음 · 자동 처리 · 레포 한정)를 걸면 그룹 문서는 목록에서 빠집니다.

1. 어느 화면에서든 ⌘⇧F.
2. 검색어를 칩니다. 결과를 누르면 그 자리로 갑니다.
3. 더 보려면 전체 보기 — 기록 화면에서 필터와 함께 봅니다.

화면 분할 · 테마 · 상태 표시#

• 화면 분할 (⌘⇧S) — 오른쪽에 화면을 하나 더 엽니다. 오른쪽 칸에도 레일이 서고, 번호 키는 손이 있는 칸으로 갑니다. 가운데 선을 끌어 폭을 바꿉니다. 버튼과 ⌘⇧S 는 같은 일을 하고, 다시 누르면 한 칸으로 돌아옵니다 — 접으면 손도 왼쪽 칸으로 돌아옵니다.
• 테마 전환 — 다크 → 라이트 → 시스템 순으로 바뀝니다.
• MCP 배지 — MCP 서버가 인증 필요·연결 실패면 빨갛게 뜹니다. 누르면 진단에서 재인증합니다.
• 동기화 정상 · 오른쪽 끝 바통 마크 — 무언가 도는 동안 바통이 색을 띠고 돕니다.

새로고침#

⌘R 은 새로고침 (고른 과업) — 그 worktree 의 티켓·PR·checks 를 다시 가져옵니다. ⌘⇧R 는 전체 새로고침(최대 25건)입니다. 앱 메뉴 보기 에도 있습니다.

보드 세션 목록 머리 오른쪽의 새로고침 버튼은 여기에 동기화를 더합니다 — 터미널·gh 로 밖에서 만든 worktree 를 앱에 비추고, 폴더가 사라진 worktree 를 표시합니다. 새로 찾았거나 폴더가 없는 것이 있을 때만 알림이 뜹니다. ⇧클릭은 ⌘⇧R 처럼 전체입니다. (예전에는 동기화 버튼이 따로 있었습니다.)

Jira — 내 티켓#

1. 위쪽 검색(⌘F)으로 ID·제목을 찾고, 칩으로 거릅니다: 전체 · 담당 · 보고 · 에픽 · task · 새 댓글 · 수정필요 · 상태(진행 중 · 검토 중 · 할 일 · 보류 · 완료).
2. 목록 / 트리 로 보기를 바꿉니다(트리는 에픽·이니셔티브 아래로 묶음). 내 목록에 없는 상위(이니셔티브·에픽)는 묶음 줄로 서는데, 그 줄에도 보통 행과 같이 티켓 ID · 바로가기 · ID 복사 · 링크 복사 가 있습니다 — 키보드는 o(Jira 에서 열기) · c(ID 복사) · ⇧C(링크 복사). 상위를 이름으로만 아는 묶음(예전 방식으로 연결된 티켓)은 키가 없어 이름만 섭니다.
3. 행의 상태 pill 에서 상태를 바로 바꾸고, 오른쪽 아이콘으로 worktree 를 열거나 작업을 시작합니다.

티켓 ID 복사 · 링크 복사#

행마다 복사 단추가 둘입니다. 브라우저에서 티켓을 열어 주소창을 긁어 올 일이 없습니다.

• 담기는 것은 주소 한 줄입니다 — 제목을 붙이거나 마크다운 링크([키](주소))로 만들지 않습니다. 어디에 붙여 넣어도 깨지지 않는 쪽을 골랐습니다.
• 행 메뉴(⋮)에도 티켓 ID 복사 아래에 링크 복사 가 있습니다.
• 묶음 줄(내 목록에 없는 에픽·이니셔티브)에서도 똑같이 됩니다. 주소를 알 수 없는 묶음 줄(이름으로만 연결된 상위)에는 단추도 메뉴 항목도 서지 않습니다 — 눌러서 「주소가 없습니다」를 읽게 하지 않습니다.
• 복사에 성공하면 그 단추가 1.4초 동안 ✓ 로 바뀝니다. 실패하면(창이 포커스를 잃었거나 클립보드 권한이 거부됨) 성공한 척하지 않고 알림으로 말합니다.

관리 필드 · ⚠ 수정필요 배지#

앱이 「비면 ⚠」로 보는 필드는 그 Jira 에 실제로 있는 것만입니다. 없는 값을 「누락」이라고 말하지 않습니다.

자동 처리 일감 (예전 이름 「자동 사냥」)#

앱이 네 시간마다 툴마다 훑어 할 수 있는 것 을 골라 둡니다 — Jira 는 최근 7일 안에 들어온 내 task, Track 은 최근 7일 안에 생긴 할 일 일감과 에이전트에게 맡긴 할 일 일감(날짜와 무관). 코드 작업은 승인해야 자리가 열리고, 답변으로 끝나는 일은 승인해야 댓글이 나갑니다(Track 이면 Track 댓글).

툴을 가로지르는 한 목록입니다 — 행마다 출처 배지(Jira · Track · Trello)가 붙고, 머리의 출처 칩으로 한 툴만 남길 수 있습니다. Jira 를 못 읽어도(로그인이 풀림) Track 은 계속 훑습니다.

1. 일감 › 자동 처리 일감 탭(숫자는 내가 확인 안 한 제안 수).
2. 확인 필요 무리의 행을 펼쳐 계획·판정·레포를 봅니다. 레포가 틀렸으면 바꾸고 다시 판정합니다.
3. 승인 하면 worktree·세션이 열리고 작업이 시작됩니다(답변 유형은 댓글).
4. 지금 훑기 는 바로 한 번 더 훑고, 확인 필요 다시 검사 는 판정을 다시 씁니다.

티켓 이름 밑에는 상위 로 시작하는 작은 줄이 붙습니다 — 그 티켓이 속한 상위 티켓(에픽) 의 이름이고, 누르면 그 에픽이 Jira 에서 열립니다. 상위 티켓이 없는 티켓에는 이 줄이 없습니다.

목록은 상위 에픽으로 먼저 묶여 섭니다(에픽 키 오름차순). 같은 에픽 안에서는 종전대로 티켓이 생긴 최신 순 이고, 상위 에픽이 없는 티켓은 맨 아래 에 모입니다.

맡길 역할이 있는 Track 일감(에이전트 담당)은 판정 카드에 그 역할이 적히고, 승인하면 그 역할로 구현합니다(작업 시작의 「구현 역할」 칸).

Trello#

일감 › Trello 탭은 Trello 보드의 카드를 Jira 티켓처럼 다룹니다. 보드가 티켓 키의 앞자리, 리스트가 상태, 카드가 티켓입니다 — 카드 키는 WL-12 처럼 보드 접두-카드 번호입니다. Jira 와 나란히 둘 수 있고, 키의 앞자리가 어느 툴로 갈지 고릅니다.

1. 연결 — 연동 › 프로젝트 관리툴 › Trello 의 계정 추가. trello.com/power-ups/admin 에서 Power-Up 을 하나 만들면 API 키가 나오고, 그 화면의 토큰 링크로 이 계정의 읽기 · 쓰기 토큰을 발급합니다. 둘을 넣고 확인을 누르면 계정 칩이 확인됨 으로 바뀝니다 — 칩에 마우스를 올리면 「이름 · 보드 N개 (접두들)」로 무엇이 붙었는지 보입니다(실패하면 칩에 그 이유가 같은 자리에 뜹니다).
2. 보드 칸(선택) — 비우면 내가 속한 열린 보드 전부입니다. 접두는 보드 이름에서 만듭니다(Web Launch → WL, 영문이 없는 이름은 TB+보드 주소 앞 네 글자). 직접 정하려면 WEB=abc123, OPS=https://trello.com/b/def456 처럼 접두=보드 로 적습니다 — 적은 보드만 다룹니다.
3. Trello 탭을 엽니다. 완료 리스트(Done · 완료)의 카드는 빼고 섭니다. 검색 · 보드 칩 · 내 카드(내가 멤버로 달린 것)로 거릅니다.
4. 상태(리스트) 칸을 열면 같은 보드의 다른 리스트가 나옵니다. 고르면 카드가 그 리스트로 옮겨집니다.
5. 행을 누르거나 Trello 에서 열기 로 카드를 브라우저에서 엽니다.

12

Trello 만 연결했다면 — 레일의 일감 화면은 서고 Trello 탭으로 열립니다. Jira 셋업 · 티켓 폴링 · 자동 처리의 Jira 훑기는 켜지지 않고, Jira 탭은 「Jira 가 연결되지 않았습니다」 안내만 냅니다.

Track — 앱 안의 프로젝트 관리툴#

Track 은 앱 안에 일감을 두는 프로젝트 관리툴입니다. 설치나 로그인이 필요 없고, 일감은 이 맥의 앱 DB 에 저장됩니다. 위계는 목표 › 일감 › 세부 일감, 상태는 할 일 · 진행 중 · 리뷰 · 완료 · 보류 다섯입니다. 키는 TRK-12 처럼 스페이스 접두-번호라 브랜치 이름 · 커밋 · 대화에서 Jira 키와 똑같이 씁니다.

1. 켜기 — 스페이스 만들기 — 일감 › Track 탭의 스페이스 만들기. 이름(필수 · 1~40자)과 접두(선택 · 영문 대문자로 시작하는 2~6자)를 적고 만들기. 접두를 비우면 이름의 영문에서 만듭니다(영문이 없으면 TRK). 접두는 첫 일감을 만들기 전까지만 바꿀 수 있고, 다른 스페이스 · Jira 프로젝트 키 · Trello 보드 접두와 겹치면 받지 않습니다. 처음 만들 때 연동 › 프로젝트 관리툴에 Track 계정도 함께 생깁니다.
2. 스페이스 고르기 — 툴바 첫 칸이 스페이스 고르개입니다(이름 · 접두 · 오른쪽에 맵핑된 레포 수). 고른 스페이스의 일감만 보이고, 다음에 열 때도 그 스페이스로 엽니다. 스페이스는 워크스페이스와 무관하게 여러 개 둘 수 있습니다 — 옆의 ＋ 스페이스 로 더 만듭니다.
3. 보기 — 목록 · 트리(목표 › 일감 › 세부 일감) · 칸반(다섯 열). 상태 · 단계 칩, 목표 고르개, 검색(키 · 제목)으로 거릅니다.
4. 새 일감(n) — 단계를 고르고 내용을 적습니다(첫 줄이 제목, 나머지가 본문). 상위 · 레포 · 기한 · 맡길 역할(에이전트 이름)을 정하고 만들기, 또는 만들고 시작(바로 worktree · 세션을 엽니다). 일감은 지금 고른 스페이스에 만들어집니다.
5. 다음 걸음 — 행 오른쪽의 버튼은 Jira 와 같은 워크플로우입니다: 목표는 일감 쪼개기(분해), 일감은 작업 시작 · 세부 일감 쪼개기, worktree 가 있으면 워크트리로 이동.
6. 칸반에서는 카드를 끌어 열을 옮기거나, 카드에 포커스를 두고 ⇧← ⇧→ 로 옮깁니다. Enter 는 상세입니다.

123

1

레포 후보 — Track 을 쓰기로 한 프로젝트만

새 일감 창의 레포 칸에는 이 스페이스에 맵핑된 프로젝트가 먼저, 그다음 Track 을 쓰지만 스페이스를 아직 정하지 않은 프로젝트(뒤에 「스페이스 미지정」)가 섭니다. 다른 스페이스에 맵핑된 프로젝트와 Jira · Trello 를 쓰는 프로젝트는 나오지 않습니다. 「스페이스 미지정」 레포로 일감을 만들어도 맵핑은 바뀌지 않습니다 — 맵핑은 프로젝트 탭 › 연동에서 합니다. 창이 열린 사이 그 레포의 맵핑이 다른 스페이스로 바뀌면 칸 아래에 「이 레포는 ○○ 스페이스에 맵핑돼 있습니다」가 섭니다(만들기는 막지 않습니다).

스페이스 설정 · 보관

고르개 옆 ⚙(스페이스 설정)에서 이름 · 접두 · 상태 자동 진행을 바꾸고, 이 스페이스에 맵핑된 프로젝트 목록에서 프로젝트 탭 으로 갑니다. 접두는 첫 일감이 생기기 전까지만 바뀝니다 — 일감이 있으면 칸이 잠기고 그 이유가 적힙니다.

보관은 지우기가 아닙니다. 보관한 스페이스는 목록 · 자동 처리에서 빠지고 새 일감을 만들 수 없지만, 일감 · 키 · 맵핑은 그대로 남습니다. 고르개 끝 「보관됨」에서 고르면 맨 위에 「보관된 스페이스입니다」 배너가 서고 새 일감이 잠깁니다. 배너나 설정 창의 되살리기로 돌아옵니다.

1

12

담당은 사람이 아니라 세션 · 에이전트입니다

Track 은 쓰는 사람이 한 명이라 사람 담당 대신 누가(어느 AI 가) 이 일을 들고 있나를 담당으로 둡니다.

• 세션 — 일감을 worktree 에 이으면(작업 시작 · 티켓 연결) 그 자리의 세션이 담당이 됩니다. 칩을 누르면 그 세션으로 갑니다.
• 에이전트 — 상세의 역할 맡기기나 새 일감 창의 맡길 역할로 정합니다. 그 일감으로 작업을 시작하면(또는 자동 처리를 승인하면) 그 역할이 구현을 맡습니다. 세션이 담당이 된 뒤에도 맡긴 역할은 남습니다.

상태는 스스로 앞으로 갑니다 — 언제든 되돌립니다

담당 세션이 일을 시작하면 할 일 → 진행 중, 그 브랜치에 PR 이 서면 → 리뷰, 머지되면 → 완료 로 앱이 옮깁니다. 앞으로만 가고, 보류는 건드리지 않습니다. 옮길 때마다 댓글에 「자동으로 옮김」이 남고, 상세의 기록 탭에서 되돌리기를 누르면 돌아갑니다 — 한 번 되돌린 신호로는 다시 옮기지 않습니다(다음 폴링이 사람의 손을 덮지 않게). 스페이스마다 끌 수 있습니다(⚙ 스페이스 설정).

이어서 하기#

내가 이미 손대던 티켓(worktree·세션이 있는 티켓)도 사냥에 올라옵니다. 이런 행에는 진행 중 · 이어서 딱지가 붙고, 승인하면 새 자리를 열지 않고 하던 자리에서 이어서 합니다.

1. 진행 중 · 이어서 행을 펼치면 이어서 할 자리(worktree·세션·어디까지 했는지)가 한 줄로 보입니다.
2. 승인하고 이어서 — 워크플로우가 먼저 진행 상황(커밋·문서·PR·대화)을 파악하고, 애매한 것은 묻고, 남은 단계만 진행합니다.
3. 실행이 끝났거나 멈췄는데 자리가 살아 있으면 이어서 진행 이 다시 섭니다.

실행 화면#

• 워크플로우 이름을 누르면 설명과 단계가 펼쳐집니다. ⌥1 목록 · ⌥2 실행 기록.
• 워크플로우 검색 — 목록 위 검색칸에 id · 제목 · 설명 · 전용 이름을 칩니다(띄어 쓴 말은 모두 들어간 것만). 찾은 말은 목록에서 색으로 칠해집니다. 손이 목록에 있을 때 ⌘F 로도 잡힙니다. 칸에서 ↓(또는 Enter) 첫 행으로 · 맨 위 행의 ↑ 칸으로 · Esc 또는 칸 오른쪽 ✕ 로 검색어 지우기. 칸의 Enter 는 실행하지 않습니다 — 행에서 Enter 를 한 번 더 누르면 실행입니다.

안 보이는 워크플로우 — 꺼 둔 기능

워크플로우마다 어떤 연동이 있어야 도는지가 정의에 적혀 있습니다(Jira · 슬랙 · GitHub). 설정 › 기능 에서 그중 하나를 끄면 그 워크플로우는 목록에서 사라집니다 — 실행 목록뿐 아니라 ⌘K 팔레트 · 대화 입력창 위의 칩 · 트리와 Jira 의 버튼 · 세션이 말로 돌리는 길(실행 카드) · 예약 까지 함께입니다. 켜 두지 않은 연동으로 인증을 요구하는 화면을 보지 않게 하려는 것입니다.

다만 있으면 더 쓰는 연동은 숨기는 근거가 되지 않습니다. 예를 들어 worktree 만들기 는 티켓을 넣었을 때만 Jira 를 읽고, 비우면 브랜치와 세션만 만듭니다 — 그래서 Jira 를 꺼도 목록에 그대로 남습니다. 대신 실행 전 입력 창에 「꺼진 연동: Jira — 그 단계는 건너뛰고 나머지는 그대로 실행됩니다」 가 한 줄 섭니다. 아래 표의 필요 칸에 (선택) 이 붙은 것이 그런 연동입니다.

세션이 MCP 로 하는 일은 앱 연동과 다른 길입니다. 세션의 Atlassian MCP 가 티켓을 만드는 워크플로우는 앱 Jira 연동을 꺼 두어도 목록에 남고 끝까지 돕니다 — 앱 Jira 는 만든 티켓의 요약·상태를 캐시에 채우는 데만 쓰이고, 없으면 키만 남기고 지나갑니다(요약은 나중에 채워집니다). 대신 MCP 인증이 만료돼 있으면 실행 첫 걸음에서 「atlassian 인증 필요 — 재인증하고 계속 / 취소」 로 멈춥니다. 세션도 티켓도 만들어지지 않습니다.

줄어든 목록 위에는 왜 줄었는지가 한 줄로 섭니다 — 꺼진 기능 수와 숨긴 워크플로우 수, 걸어 둔 예약이 있으면 몇 개가 서 있는지, 그리고 설정에서 켜기. 마우스를 올리면 숨긴 워크플로우 이름이 보입니다. 다시 켜면 그대로 돌아옵니다.

이름으로 못 찾으면 — AI 추천 · 새로 만들기

• AI 로 찾기 → 없으면 새로 만들기 — 검색어를 치면 목록 아래에 칸이 하나 섭니다. 이름으로 못 찾았거나 찾은 것이 원하는 게 아니면 AI 로 찾기 를 누르세요. 검색어를 「하려는 일」로 읽고 이미 있는 워크플로우 중 맞는 것을 최대 3개 권합니다(왜 맞는지 한 줄과 함께). 권한 것마다 실행 · 보기(검색어를 지우고 그 행을 펼칩니다).
• 권한 것이 없거나 맞지 않으면 「검색어」로 새로 만들기 — 워크플로우 추가 창이 검색어를 채운 채 열립니다. 모델을 쓰지 못하면 낱말로 고르고 그 사실을 칸에 적습니다. 기다리는 동안에도 새로 만들기는 누를 수 있습니다.

12

실행 기록 거르기

• 실행 기록은 워크플로우 · 트리거(수동 실행 / 예약 실행) · 기간 · 워크트리로 거릅니다. 행의 상세 · 중단 · 다시 실행 — 실패 지점부터 이을 수 있는 실패에는 다시 실행 대신 이어서 실행 이 섭니다(이어서 실행). 예약이 돌린 행에는 예약 과 반복 시각이 붙습니다(워크플로우 예약).
• 이 워크플로우 실행만 — 왼쪽 목록 행의 기록 버튼(실행 왼쪽의 두루마리 아이콘)을 누르면 오른쪽 실행 기록에 그 워크플로우의 실행만 남습니다. 버튼이 색으로 켜지고 그 행 왼쪽에 테가 서며, 워크플로우 칸에 이름이 들어갑니다. 다시 누르거나 워크플로우 칸의 ✕, 필터 해제 로 풉니다. 다른 행의 기록 버튼을 누르면 필터가 그 워크플로우로 옮겨 갑니다.
• 대화창 칩 노출 — 기록 버튼 옆의 눈 아이콘은 이 워크플로우를 보드 › AI 대화창 위 워크플로우 바로 실행 칩으로 노출할지 정합니다. 기본은 비노출(빗금 친 눈)이고, 누르면 노출(뜬 눈)로 바뀝니다. 새로 만들거나 들인 워크플로우도 비노출로 시작합니다 — 대화창의 워크플로우 칩 고르기와 같은 값입니다(자세히).
• 워크플로우 칸은 자동완성입니다 — 누르거나 ↓ 로 펼치면 기록에 있는 워크플로우가 제목 · 건수와 함께 뜨고, id 나 제목 일부를 치면 좁혀집니다. ↑ ↓ 로 옮기고 Enter 로 고릅니다. Esc 는 친 말을 되돌립니다(고른 값은 그대로). 맨 위 워크플로우 전체 를 고르거나 칸 오른쪽 ✕ 를 누르면 풀립니다.
• 기간 은 전체 · 오늘 · 어제 · 7일 · 30일 을 눌러 고릅니다(7일 · 30일은 오늘을 넣어 셉니다). 옆의 달력 칩에 지금 걸린 실제 날짜가 적힙니다. 달력 칩을 누르면 달력에서 시작일과 끝날을 찍어 아무 범위나 고릅니다 — 기록이 있는 날에는 점이 찍혀 있습니다.

123

기본으로 들어 있는 워크플로우(설치본 기준 — 데모 그림에는 일부만 보입니다):

필수 워크플로우 · 사용자 워크플로우#

앱 안에 든 정의로만 도는 워크플로우가 필수 입니다 — 사용자 폴더(~/.baton/workflows)에 같은 이름 파일을 두어도 읽지 않습니다. 그래서 설치 직후 그 폴더가 비어 있어도 앱의 버튼이 그대로 동작합니다. 목록에서 필수에는 필수, 내가 만들거나 가져온 것에는 사용자 가 붙습니다.

버튼이 있다고 필수인 것은 아닙니다. 버튼은 그 이름의 정의가 있으면 서고, 그 정의가 앱에 든 것인지 사용자 폴더의 것인지는 가리지 않습니다. 그래서 조직마다 값이 다른 워크플로우는 버튼이 있어도 필수에서 내려 둡니다 — 리뷰 요청이 그렇습니다(리뷰 채널과 부를 봇). 고치지 못해서 아무 일도 안 일어나는 쪽이, 고쳐서 반쯤 도는 쪽보다 나쁘기 때문입니다.

• 필수 — worktree 닫기 · worktree 만들기 · 새 작업 시작 · 작업 시작 · 워크스페이스 추가 · 신규 프로젝트 추가 · 하네스 셋팅 · 일감 쪼개기(분해) · 성과 측정 · 레포 테스트 · 배포 준비. 앱의 버튼이 이름으로 부르고 조직마다 다를 것이 없는 것들입니다.
• 필수가 아닌 것 — 리뷰 반영 · 환경 테스트 · 리뷰 요청. 조직마다 전제가 달라(리뷰봇 문구 · 테스트 정의 · 리뷰 채널과 부를 봇) 사본으로 고쳐 쓸 수 있게 두었습니다. 다른 워크플로우가 이들에게 일을 넘길 때는 입력 이름만 지키면 됩니다.
• 사용자 — 사용자 폴더에 있는 정의. 지금처럼 그 폴더에서 돌고, 고치고 지울 수 있습니다.
• 표시가 없는 것 — 앱에 들어 있지만 앱이 이름으로 부르지 않는 것. 종전처럼 고치면 사용자 폴더에 수정본이 생기고 기본값으로 되돌리기 로 돌아갑니다.

같은 이름의 사본은 등록할 수 없습니다

필수 워크플로우와 id(파일 이름)가 같거나 표시 이름(title)이 같은 워크플로우는 만들기 · 정의 저장 · 가져오기에서 거절되고 사유가 그 자리에 뜹니다. 표시 이름은 대소문자와 앞뒤 · 연속 공백을 무시하고 비교합니다(「 Worktree 닫기」 도 「worktree 닫기」 와 같은 이름). 사본은 다른 이름으로 만드세요 — 사본 만들기 는 자동으로 「… (사본)」 이름을 붙입니다.

작동 불가 사본 — 파일을 직접 넣은 경우

~/.baton/workflows 에 필수와 같은 id 나 같은 표시 이름의 파일을 직접 넣었거나 예전에 고쳐 둔 파일이 남아 있으면, 앱은 원본만 씁니다. 그 파일은 실행 목록에 서지 않고 실행할 수도 없으며, 목록 위 작동 불가 사본 칸에 작동 불가 표시와 이유 · 파일 경로와 함께 섭니다.

1. 이름 바꾸기 — 새 id(파일 이름)와 새 표시 이름을 적고 바꾸기. 파일 이름과 정의의 id · title 이 함께 바뀌고, 곧바로 사용자 워크플로우로 목록에 섭니다. 다른 워크플로우와 겹치거나 필수와 같은 이름이면 사유가 폼에 남습니다.
2. 원본과 비교 — 사본과 앱 기본 정의를 나란히 봅니다. 무엇을 고쳐 두었는지 보고 고르세요.
3. 삭제 — 한 번 더 지웁니다 를 눌러야 지워집니다. 사본 파일만 지우고 원본은 그대로입니다.

12

워크플로우 실행하기#

1. 목록 행의 실행(또는 ⌘K 에서 워크플로우 이름, 입력창의 워크플로우 칩).
2. 입력 팝업에서 대상·옵션을 채웁니다. 지금 보고 있는 worktree 는 미리 채워집니다.
3. 시작. 팝업은 바로 닫혀도 됩니다 — 실행은 뒤에서 계속되고 끝나면 알림이 뜹니다.

새 작업 시작의 입력 — 요약 · 상위 티켓

• 요약 은 여러 줄입니다. 첫 줄이 Jira 이슈 제목과 세션 제목이 되고, 둘째 줄부터는 이슈 설명으로 들어갑니다. ↵ 는 줄바꿈, ⌘↵ 가 실행입니다.
• 상위 티켓 은 이 작업을 둘 상위 묶음(Jira 의 에픽 · Track 의 목표 등)입니다. 칸을 누르면 고른 프로젝트의 진행 중 티켓이 뜨고, 키나 제목 일부를 치면 찾아 줍니다(묶음 — 에픽 · 이니셔티브 · 목표 — 이 위에 섭니다). ↓ 로 후보에 내려가 ↵ 로 고르거나 눌러 고릅니다.
• 상위 티켓은 비워 둘 수 있습니다 — 비우면 상위 없이 만듭니다. 고른 뒤에는 비우기 로 되돌립니다.
• 스페이스 는 일감을 만들 자리입니다(Jira 프로젝트 · Track 스페이스 · Trello 보드). 레포를 고르면 그 레포에 맵핑된 스페이스가 미리 골라지고(프로젝트마다 스페이스), 후보도 그 레포가 쓰는 툴의 스페이스만 섭니다. 레포를 바꾸면 스페이스도 따라 바뀌지만, 스페이스를 직접 고른 뒤에는 레포를 바꿔도 덮지 않습니다.
• 이슈 타입 은 고른 Jira 프로젝트에서 실제로 만들 수 있는 타입 만 후보로 뜹니다. 설정의 기본 타입(보통 Task)이 미리 골라지되, 그 프로젝트에 없는 타입이면 목록에 나오지 않습니다 — 요청 접수용 프로젝트처럼 Task 가 아예 없는 곳이 있습니다.
• 스페이스를 바꾸면 이슈 타입 · 상위 티켓 후보도 그 스페이스의 것으로 다시 뜹니다.

1

시작 알림 · 실행으로 가기

어디서 시작하든 — 입력창의 워크플로우 칩(⌘⌥1~⌘⌥9) · ⌘K · 실행 목록의 실행 · 다시 실행 · 프로젝트 메뉴 · 일감의 다음 걸음 · 환경 테스트 · worktree 닫기 · 워크스페이스/프로젝트 추가 · 성과 측정 · 자동 처리 일감 승인 — 누르는 즉시 화면 오른쪽 아래에 「○○ 실행을 시작했습니다」 알림이 5초 동안 뜹니다. 알림의 실행으로 가기 를 누르면 방금 시작한 그 실행의 상세로 갑니다.

• 알림은 입력 중인 칸의 포커스를 가져가지 않습니다. 계속 치면 됩니다.
• Tab 으로 알림의 버튼에 닿고, 거기서 Esc 를 누르면 그 알림만 닫히고 치던 자리로 돌아갑니다.
• 실행이 끝나면 같은 자리에 결말(끝남 · 실패)이 다시 뜹니다 — 화면을 옮겼거나 창을 닫았어도 뜹니다.
• 시작하지 못했으면(이미 같은 자리에서 돌고 있음 · 설정 필요 등) 이유를 담은 알림이 닫을 때까지 남습니다.

실행 상세 · 응답하기#

실행 기록 행의 상세 는 단계 흐름과 진행 로그를 보여 줍니다. 사용자 응답 대기 인 단계는 거기서 답하거나 대화에서 응답 으로 세션에 갑니다.

맨 위 요청 칸에는 시작할 때 채운 입력 그대로 가 폼과 같은 순서·이름으로 섭니다 — 무엇을 요청해서 돈 실행인지 여기서 확인합니다. 비워서 보낸 칸은 — 로 남습니다(비운 것도 고른 값입니다). 그 아래가 대상(작업 폴더)입니다.

워크플로우가 확인을 기다리기 시작하면 어느 화면에 있든 확인 팝업 이 뜹니다. 에이전트가 쓴 본문(분해안 · 리뷰 요약 등)은 마크다운 문서 로 그려집니다 — 제목 · 목록 · 굵게 · 코드 · 표가 대화의 답과 같은 모양입니다.

• 본문 상자 오른쪽 위 원문 은 같은 자리에서 글자 그대로(마크다운 기호 포함) 보여 줍니다. 다시 누르면 문서로 돌아옵니다.
• 원문 복사 는 그려진 글이 아니라 마크다운 원문 을 넣습니다 — Jira · 슬랙 · 대화에 붙여도 다시 문서가 됩니다.
• 나중에 로 닫아도 실행은 그대로 기다립니다.

실패 지점부터 이어서 실행 · 앱 종료로 끊긴 일#

실패한 실행은 처음부터 다시 돌리지 않고 실패한 단계부터 이어서 돌릴 수 있습니다. 앞 단계의 결과(만든 worktree · 세션 · 조회한 값)는 그대로 씁니다.

1. 실행 기록에서 실패한 행의 이어서 실행 을 누르거나, 상세 를 열어 위쪽 이어서 실행 칸의 버튼을 누릅니다.
2. 칸의 한 줄이 어디서부터 도는지 알려 줍니다. 에이전트의 답을 기다리다 실패했으면 그 요청을 보낸 단계부터 다시 보냅니다 — 기다리던 답은 이미 사라졌기 때문입니다.
3. 같은 실행이 그 자리부터 다시 돕니다. 상세 머리에 이어서 실행 N번 이 붙습니다.

1

앱 종료로 끊긴 일 골라서 잇기 — 앱을 완전히 종료하면 돌던 워크플로우와 답을 쓰던 세션이 끊깁니다. 다시 켜면 저절로 이어 돌리지 않고, 끊긴 것만 모아 줄마다 버튼으로 고르게 합니다.

• 켰을 때 이번에 끊긴 일이 있으면 앱이 꺼지며 끊긴 일이 N건 있습니다 토스트가 뜹니다. 골라서 이어가기 로 창을 엽니다.
• 실행 화면 머리의 앱 종료로 끊긴 일 버튼도 같은 창을 엽니다(끊긴 일이 있을 때만 보입니다 — 배지 숫자는 아직 처리하지 않은 것만 셉니다).
• 이을 수 있는 실행 줄에는 재시작 과 필요없음 두 버튼이 있습니다. 재시작 은 그 자리에서 곧바로 이어서 실행을 시작하고, 필요없음 은 잇지 않고 처리됨으로 표시합니다.
• 이을 수 없는 실행 줄에는 확인 한 버튼뿐입니다 — 왜 이을 수 없는지 사유가 바로 위 줄에 적혀 있습니다. 눌러도 실행은 그대로 실패한 채로 두고 알림 목록에서만 뺍니다.
• 세션 줄은 이어가기(대화를 되찾아 잇는다) 와 필요없음(카드만 닫는다 — 대화는 남습니다) 두 버튼입니다.
• 같은 갈래에 2건 이상 있으면 절 머리에 모두 필요없음·모두 확인 이 함께 서 한 번에 치울 수 있습니다.
• 어느 버튼이든 누르면 창을 열어 둔 채로 곧바로 처리됩니다 — 재시작·이어가기는 뒤에서 돌고(세션은 다시 띄우는 데 몇 초씩 걸립니다), 처리된 줄은 목록에서 빠집니다. 창을 닫아도 결과는 토스트가 알려 줍니다.

확인 창에서 더 논의하기#

일부 확인 창(예: 일감 쪼개기(분해) 의 분해안 확인)은 제안 아래에 피드백 칸이 있습니다. 적은 말로 제안을 다시 받거나, 결정하면서 추가 지시로 함께 보냅니다.

1. 제안을 읽고 아래 피드백 칸에 고칠 점을 적습니다. 칸이 비어 있으면 더 논의한다 는 누를 수 없습니다.
2. 더 논의한다 를 누르면 창이 닫히지 않고 피드백을 반영해 다시 제안 받는 중 으로 바뀝니다. 보낸 피드백, 경과 시간, 세션이 지금 하는 일이 보입니다. 이때 이대로 만든다 는 잠깁니다.
3. 새 제안이 오면 같은 창에 바뀌어 섭니다. 앞 제안과 피드백은 지난 제안 · 피드백 에 접혀 남습니다. 필요한 만큼 되풀이합니다.
4. 마음에 들면 이대로 만든다. 칸이 비어 있으면 마지막 제안 그대로, 적혀 있으면 마지막 제안 + 그 글 을 토대로 만듭니다.

12

결과 형식 — 결과를 표 · 키-값 · 마크다운으로 보기#

워크플로우 정의(YAML)에 output: 을 적으면 그 단계의 결과를 정한 모양으로 보여 줍니다. 형식은 표(table) · 키-값(keyvalue) · 마크다운(markdown) · JSON(json) · 평문(text) 다섯 가지입니다. 정의 맨 위에 적은 output: 은 실행 상세 맨 위의 최종 결과 가 됩니다.

1. 워크플로우 행의 정의 편집 에서 결과를 받는 단계(보통 에이전트의 대기 단계)에 output: { format: table } 처럼 적습니다. 모양을 확인하려면 schema(필수 칸 required · 칸의 종류 type)를, 열 순서와 제목은 fields 를 함께 적습니다.
2. 실행 전체의 결과는 맨 위에 output: { from: 단계의 as 이름, format: keyvalue } 로 적습니다.
3. 실행 기록 행의 상세 를 열면 최종 결과 가 단계보다 먼저 서고, 형식이 정해진 단계는 결과 보기 로 펼칩니다.

• 다음 단계에는 늘 구조 값(JSON)이 그대로 넘어갑니다. 에이전트 답에서 꺼낸 값이 $이름.data 로 실리고, 전과 같은 $이름.text 도 남습니다. 화면의 모양은 보여 주는 방식일 뿐입니다.
• 에이전트에게는 형식이 자동으로 지시됩니다. 답이 형식과 맞지 않으면 같은 세션에 한 번 더 고쳐 달라고 요청합니다(횟수는 retry, 0~3).
• 그래도 맞지 않으면 형식 불일치 경고와 어긋난 자리를 보이고, 받은 원문을 그대로 남긴 채 계속합니다. 그 자리에서 멈추게 하려면 onInvalid: fail.
• 원본 보기 는 다음 단계로 넘어간 JSON 과 에이전트 원문을 펼칩니다. 복사 는 붙여 넣기 좋은 모양(표 · 키-값은 JSON, 마크다운은 본문)을 넣습니다.
• 표시만 바꾸고 싶으면 template 에 마크다운 틀을 적습니다 — {{항목}} 은 값, {{#data}}…{{/data}} 는 줄마다 반복입니다. 넘어가는 값은 바뀌지 않습니다.

API 호출 — 워크플로우에서 외부 API 부르기#

정의(YAML)에 http.request 단계를 적으면 앱이 그 주소로 요청을 보내고, 응답 JSON 을 뜯어 다음 단계의 인자로 넘깁니다. 앱이 미리 아는 Jira · GitHub · 슬랙 말고 사내 API · 사외 서비스 · 웹훅 을 부르는 자리입니다.

1. 워크플로우 행의 정의 편집 에서 단계를 더하고 주소를 적습니다. as 로 이름을 붙이면 뒤 단계가 그 이름으로 응답을 읽습니다.
2. 응답 값은 ${이름.json.…} 으로 꺼냅니다 — 점으로 내려가고 목록은 번호(0 부터)로 짚습니다.
3. 보내는 값(body)에는 입력칸 값과 앞 단계 결과를 그대로 섞어 적습니다. 객체로 적으면 JSON 으로 보냅니다.

steps:
  - http.request: { url: "https://api.example.com/items" }
    as: list
    label: 목록 조회
  - http.request:
      url: "https://api.example.com/items/${list.json.data.items.0.id}/sync"
      method: POST
      headers: { authorization: "Bearer secret:API_TOKEN" }
      body: { picked: "${list.json.data.items.0.id}", memo: $memo }
    as: synced
    label: 동기화

• 토큰은 정의에 적지 않습니다. secret:키이름 으로 적어 두고 값은 ~/.baton/secrets.json 의 testSecrets 에 둡니다(테스트 방식과 같은 자리 · 같은 규칙). 글 안에 섞어 써도 됩니다 — "Bearer secret:API_TOKEN". 값이 없으면 요청을 보내지 않고 어느 키가 비었는지 말합니다. 푼 값이 응답·기록에 찍히면 *** 로 가립니다.
• 응답이 2xx 가 아니면 그 단계에서 멈춥니다(상태코드와 본문 앞부분이 사유에 남습니다). 404 를 「없음」으로 받아 갈래를 타려면 allowStatus: [404], 어떤 코드도 멈추지 않게 하려면 failOnStatus: false 로 적고 ${이름.ok} · ${이름.status} 로 판단합니다.
• 쓸 수 있는 값: status · ok · json(파싱된 응답) · text(원문) · headers · contentType · durationMs. JSON 이 아닌 응답은 text 로 받습니다(parse: json 으로 「반드시 JSON」을 요구할 수도 있습니다).
• 기본 제한 시간은 30초(timeoutSec 으로 최대 600초). 넘으면 몇 초 기다렸는지 말하고 멈춥니다 — 실행이 앱을 붙잡지 않습니다.

워크플로우 예약 — 정해 둔 시각에 실행#

워크플로우를 매일 · 평일 · 매주 · 매시간 · 몇 분마다(또는 크론 식) 저절로 돌립니다. 기본은 수동입니다 — 예약을 등록한 워크플로우만 저절로 돌고, 나머지는 지금처럼 실행 을 눌러야 돕니다.

1. 실행 화면 왼쪽 목록에서 워크플로우 이름을 눌러 펼치고, 예약 칸의 + 예약 을 누릅니다.
2. 반복 · 요일 · 시각 을 고릅니다. 바로 아래 줄에 다음 실행 시각 세 번이 보입니다. 원하는 모양이 없으면 직접 입력(크론 식) 에 분 시 일 월 요일 을 적습니다(예: 0 9 * * 1-5 는 평일 09:00).
3. 앱이 꺼져 있던 동안 놓친 실행 을 고릅니다 — 켜지면 한 번 실행 또는 건너뛰기.
4. 아래의 실행 입력(대상 · 옵션)을 실행할 때처럼 채우고 예약 저장.

앱이 꺼져 있거나 맥이 잠자기였을 때

Baton 은 이 컴퓨터에서 돌기 때문에 앱이 꺼져 있거나 맥이 잠든 동안에는 예약이 돌 수 없습니다. 그 사이의 예정 시각은 예약마다 고른 대로 합니다.

• 켜지면 한 번 실행 — 앱을 켜거나 맥이 깨어나면 곧 가장 최근 예정분을 한 번만 실행합니다. 사흘 꺼져 있었어도 몰아 돌리지 않습니다. 따라잡는 한도(기본 24시간)보다 오래 지난 예정분은 건너뜁니다.
• 건너뛰기 — 놓친 예정분은 실행하지 않고 「건너뛰었습니다」만 남깁니다.
• 예정 시각에서 5분 안에 확인되면 놓친 것이 아니라 제시간 실행입니다.
• 같은 예약의 앞선 실행이 아직 끝나지 않았으면(답을 기다리는 중 등) 다음 예정분은 겹쳐 돌리지 않고 건너뜁니다.
• 예약을 만들거나, 반복을 바꾸거나, 꺼 둔 예약을 다시 켜면 그때부터 셉니다 — 그 전의 예정분을 따라잡지 않습니다.

예약 관리 · 기록

• 예약이 켜진 워크플로우에는 목록에 예약 표시가 붙습니다(마우스를 올리면 다음 실행 시각).
• 펼친 안의 예약 칸에서 끄기 · 고치기 · 지우기. 마지막 줄이 최근 예정분을 실행했는지 · 건너뛰었는지 · 시작하지 못했는지를 말합니다.
• 그 워크플로우가 기대는 기능 을 끄면 예약은 돌지 않습니다 — 그 줄이 꺼진 기능 때문에 돌지 않습니다 와 어느 기능인지를 말합니다. 예약을 지우지는 않으므로 기능을 다시 켜면 예정대로 돕니다.
• 실행 기록의 트리거 필터에서 예약 실행 만 · 수동 실행 만 봅니다. 시작하지 못한 예약도 실패한 예약 실행으로 기록에 남습니다. 예약을 지워도 그 예약으로 돈 기록은 남습니다.
• 예약 실행이 끝나거나 실패하면 알림이 뜹니다(창을 보고 있지 않으면 OS 알림).

12

워크플로우 가져오기#

다른 사람이 만든 워크플로우(.yaml) · 에이전트(.md) 파일을 검사한 뒤 들입니다. 여러 파일을 한 번에 올릴 수 있습니다.

1. 실행 화면 툴바 가져오기 — 또는 파일을 실행 화면 아무 데나 끌어다 놓습니다.
2. 창 위의 탭에서 길을 고릅니다 — 파일에서(내가 받은 파일) 또는 카탈로그에서(공개 스토어).
3. 파일마다 판정(통과 · 경고 n · 오류 n)이 뜹니다. 문법 · 액션 입력 · 이름 겹침을 저장 전에 봅니다.
4. 다른 워크플로우·에이전트에 기대는데 빠진 파일이 있으면 함께 올려야 할 파일 칸에 그 파일을 더 놓습니다.
5. 이름이 겹치면 덮어쓰기 또는 이름 바꾸기 를 고릅니다. 오류가 0 이면 가져오기 가 켜집니다.

카탈로그에서 골라 받기

카탈로그에서 탭은 공개 스토어의 목록을 받아 보여 줍니다. 묶음을 체크해 고르면 그 자리에서 내려받아 파일에서 올린 것과 똑같은 검사를 받습니다 — 문법 · 액션 입력 · 의존 · 이름 겹침 · 밖으로 나가는 동작.

• 목록 위에 보고 있는 주소가 그대로 적힙니다. 어느 카탈로그를 믿고 고르는지가 출처의 반입니다.
• 묶음을 고르면 부르는 에이전트·자식 워크플로우가 함께 들어옵니다 — 「함께 올려야 할 파일」을 사람이 찾아다닐 일이 없습니다.
• 행의 배지는 올린 사람의 신고입니다. 그 아래 위험 칸은 앱이 받아 온 정의를 직접 읽어 센 값이라, 둘이 다를 수 있습니다 — 다르면 그 사실 자체가 정보입니다.
• 받는 파일은 목록에 적힌 sha256 과 맞춰 봅니다. 다르면 가져오지 않고 그 사실을 말합니다.
• 등급이 높음 이면 파일 경로와 똑같이 동의를 켜야 가져오기가 켜집니다. 길이 다르다고 관문이 느슨해지지 않습니다.

밖으로 나가는 동작 — 위험 요약과 동의

남의 정의는 내 기기에서 돕니다. 그래서 가져오기 창은 그 정의가 어디로 무엇을 보내는지 를 먼저 정리해 보여 줍니다.

• 위험 등급과 점수(밖으로 나가지 않음 · 낮음 · 주의 · 높음)가 서고, 점수가 왜 그렇게 됐는지 줄마다 적힙니다.
• 단계마다 호스트(api.example.com) · 주소 원문 · shell 이면 명령 원문 을 보입니다.
• 그 요청에 무엇이 실리는지 를 자리와 함께 적습니다 — header:authorization ← 저장된 비밀값 API_TOKEN 처럼. 비밀값이 나가는 줄은 붉게 섭니다.
• 값이 실행 중에 정해지면 그 값이 어디서 오는지 를 말합니다(입력 「대상 서버」 · 3번 「조회」 결과). 정의가 선언하지 않은 이름이면 「알 수 없음」 이라고 적습니다.
• 등급이 높음 이면 목록을 읽고 동의 를 켜야 가져오기 가 켜집니다. 파일이나 선택을 바꾸면 동의는 풀립니다.

워크플로우 추가(말로 만들기)#

1. 목록 머리 + 추가(또는 목록 검색의 「검색어」로 새로 만들기 — 검색어가 채워진 채 열립니다).
2. 하고 싶은 일을 말로 적고 초안 만들기.
3. 비슷한 워크플로우가 이미 있으면 먼저 보여 줍니다. 그걸 쓰려면 실행 또는 보기(창을 닫고 목록에서 펼칩니다), 하려는 일과 다르면 무시하고 초안 만들기. 비슷한 것이 없으면 곧장 초안을 만듭니다.
4. 앱이 정의(YAML) 초안을 채웁니다. 읽고 고친 뒤 추가 는 사람이 누릅니다. 행의 메뉴에서 정의를 다시 편집할 수 있습니다.

1

이미 있는 워크플로우 고치기(말로 고치기)#

워크플로우 행을 펼쳐 정의 편집 을 누르면 정의(YAML)를 손으로 고치거나 말로 고칠 수 있습니다.

1. 어떻게 고칠지 말로 적어도 됩니다 칸에 바꾸고 싶은 것을 적습니다. 여러 줄로 적을 수 있고(Enter 는 줄바꿈), 조건이 여럿이면 줄을 나눠 적는 편이 잘 전달됩니다.
2. 고쳐 보기(또는 ⌘Enter)를 누릅니다. 아래 편집 상자가 고친 초안 으로 채워집니다 — 저장은 사람이 누릅니다.
3. 모델이 엉뚱하게 고쳤으면 내 편집으로 되돌리기 로 누르기 직전의 내 글로 돌아갑니다.
4. 저장 은 YAML · 액션 이름을 검사합니다. 걸리면 사유가 폼 안에 남고 쓰던 초안은 지워지지 않습니다.

일괄 변경 — 여러 레포에 같은 지시 개발자#

일괄 변경 요청 은 고른 프로젝트 모두에 같은 지시를 적용하고 레포마다 PR 을 만듭니다. 프로젝트마다 변경 적용 실행이 따로 돌며 worktree → 세션 → PR → 리뷰 요청까지 이어 갑니다.

1. 실행 화면에서 일괄 변경 요청 › 실행.
2. 대상 프로젝트 칸 머리의 전체 선택 으로 모두 고르거나, 하나씩 켭니다. 전체 해제 로 한 번에 비웁니다.
3. 프로젝트가 8개 이상이면 이름으로 좁히기 칸이 뜹니다. 좁힌 동안 버튼은 보이는 것만 고르고(「보이는 3개 선택」), 좁히기 밖에서 이미 고른 것은 「숨은 선택 N」 으로 남습니다.
4. 요청 내용을 적고 실행 → 확인 단계에서 대상·요청을 다시 보고 승인합니다. 실행 기록에 「batch-change 에서 위임」 으로 레포마다 한 줄씩 섭니다.

스킬 · 플러그인 · 마켓플레이스 보기#

나머지 세 탭은 Claude Code 가 파일로 들고 있는 것을 보여 줍니다. 터미널에서 /plugin 으로 깐 것도, 세션이 깐 것도 같은 목록에 섭니다.

• 대상 고르개로 전역만 볼지 전역 + 그 프로젝트를 함께 볼지 정합니다. 프로젝트 자리는 두 갈래입니다 — 이 프로젝트 · 공유(레포에 커밋되어 팀원에게도 깔립니다) · 이 프로젝트 · 나만(커밋되지 않습니다).
• 검색은 탭을 가로지릅니다. 경로로 좁히고(team-skills/dbkit/sql) 갈래로도 좁힙니다(skill: · plugin: · market:). 고르면 그 탭으로 가서 상세가 열립니다.
• 항목을 고르면 오른쪽에 어디서 왔는지 · 실제 파일 경로 · 지시문이 보입니다. 플러그인은 무엇을 나르는지(스킬 · 에이전트 · 훅)와 모든 세션에 더해지는 토큰까지 봅니다 — 「세션이 왜 무거운가」의 답이 이 숫자입니다.

설치 · 제거 · 켜기/끄기

• 마켓플레이스 탭 에서 마켓을 고르면 그 마켓이 품은 플러그인이 보이고, 각 줄의 설치 로 깝니다. 마켓 자체는 머리의 + 마켓 등록(주소·경로·owner/repo)과 갱신 으로 다룹니다.
• 프로젝트에 설치할 때는 어디에 쓸지 묻습니다 — 나만(기본 · 커밋되지 않음) · 팀 공유(커밋되어 팀원에게도 깔림) · 전역. 「팀 공유」는 레포에 파일이 남는다는 뜻이라 그 사실을 고르는 자리에 적어 둡니다.
• 켜고 끄기 는 플러그인 상세에서 바로 합니다(설정 한 줄이라 묻지 않습니다). 제거 는 디스크를 지우므로 확인 창을 거칩니다 — 그 플러그인이 나르던 스킬·에이전트도 함께 사라집니다.

「이미 켜져 있습니다」처럼 바뀐 것이 없을 때는 실패가 아니라 그 사실을 그대로 알립니다 — 두 번 누르지 않아도 됩니다.

최근 사용

스킬 상세에 최근 사용 이 함께 섭니다 — 몇 번 썼는지, 마지막이 언제인지, 무슨 요청으로 불렀는지(사람이 친 말 그대로). AI 를 부르지 않습니다 — 앱이 남긴 기록과 Claude Code 의 입력 기록을 읽어 셉니다.

remote 설정 · 변경 개발자#

GitHub 기능이 켜져 있는데 레포에 원격이 없으면 remote 설정, 있으면 remote 변경(힌트에 지금 주소)이 보입니다.

1. 프로젝트 행 ⋯ › remote 설정(또는 remote 변경).
2. GitHub 주소(https://github.com/org/repo 또는 git@github.com:org/repo.git)를 넣고 저장합니다.

버전 히스토리(배포 이력) 모두#

「이 레포에 언제 무엇이 나갔나」 를 날짜순으로 봅니다. 릴리스 노트를 쓰는 레포는 릴리스로, 아니면 base 브랜치의 머지 기록(커밋 제목·내용)으로 보여 줍니다. 원격이 있으면 원격 기준, 없으면 로컬 기준입니다.

1. 프로젝트 행 ⋯ › 버전 히스토리 보기.
2. 행을 펼치면 본문(릴리스 노트·커밋 내용)이 보입니다. PR·릴리스는 브라우저로 엽니다.
3. 머리 오른쪽에서 머지 기록으로 보기 / 릴리스 노트로 보기 를 바꾸고, 머지 기록이면 원격 새로 받기.
4. 아래 더 불러오기 로 이전 이력을 봅니다.

레포마다 무엇으로 볼지는 상세 패널 프로젝트 칩의 배포 이력 에서 정합니다 — 스위치 「릴리스 노트로 배포 이력 보기」 와 다시 감지. 같은 칩에 프로젝트 맵(맵 다시 생성) · 테스트 방식 · 연동 · 배포 환경 도 있습니다.

열린 PR 보기 개발자#

이 레포에 지금 열려 있는 PR 을 내 것부터 보여 줍니다. 누르면 브라우저로 엽니다.

⌘P 는 보드 화면 어디서든 같은 목록을 바로 엽니다 — 트리 · 상세 패널 · 세션 목록 · 대화 입력창 · 드로어, 손이 어디에 있어도 됩니다. 대상은 마지막으로 클릭하거나 키보드로 고른 트리 항목입니다: 프로젝트 행 · 그룹 안 레포 노드를 골랐으면 그 레포 그대로, worktree · 세션을 골랐으면 그 상위 레포(세션은 속한 worktree 를 거쳐), 이 화면을 켠 뒤로 트리를 아직 안 건드렸으면 목록에 걸어 둔 프로젝트 필터를 그 레포로 봅니다. 한글 입력 상태 그대로 눌러도 되고, 이미 뜬 팝업 위에서는 다시 열지 않습니다.

프로젝트 원격 세션#

이 레포의 맥락을 폰·claude.ai 에서 쓰는 전용 세션입니다. 프로젝트마다 하나이고, 앱 안에서는 어디에도 보이지 않습니다 — 트리에도, 세션 목록에도, 상세의 탭 줄에도 서지 않습니다. 여는 길은 프로젝트 행의 ⋯ › 프로젝트 원격 세션 뿐입니다.

• 켜기 — 세션을 만들고 원격을 붙입니다. 쉬던 세션이면 프로세스가 뜨는 데 7~8초가 걸리므로, 주소는 조금 뒤에 생깁니다(그동안 메뉴는 원격 연결 중… 을 보여 줍니다).
• 세션 열기 — 그동안 오간 기록을 팝업으로 봅니다. 읽기만 하는 자리입니다 — 입력칸이 없고, 말과 승인은 claude.ai · Claude 앱에서 합니다. 탭으로 열리지 않으므로 닫아도 세션은 그대로 돕니다.
• QR — 폰으로 열기 — 주소를 QR 한 장으로 띄웁니다. 폰 카메라로 찍으면 그 자리에서 이어 씁니다.
• 링크 복사 — 같은 주소를 클립보드로.
• 재연결 — 세션이 떠 있지 않을 때만 섭니다(앱을 껐다 켠 뒤). 이 세션과 대화를 그대로 두고 원격만 다시 붙입니다 — 「끄기 → 켜기」와 달리 대화가 기록으로 넘어가지 않습니다. 주소는 새로 발급됩니다.
• 끄기 — 이 세션을 닫습니다. 원격만 떼지 않습니다 — 원격으로만 쓰는 자리라 원격 없이 남으면 쓸 수 없기 때문입니다. 대화는 기록 › 닫힌 세션에 남습니다.

표기명 변경 · 색 바꾸기 · 프로젝트 맵 다시 생성 · 기본 worktree 세션 · 폴더 없는 worktree 정리#

• 표기명 변경 — 폴더·레포 이름은 그대로 두고 트리·카드에 보이는 이름만 바꿉니다(행 더블클릭·Enter 와 같음). 비우고 저장하면 폴더 이름으로 돌아갑니다 — worktree 표기명과 같은 규약입니다. 바꾼 이름은 그 아래 worktree 행 앞에 붙는 레포 이름과 카드 · 기록 · 워크플로우 「대상」 고르는 칸까지 모두 따라옵니다(예전에는 프로젝트 행만 바뀌고 나머지는 폴더 이름으로 남아 같은 자리가 두 이름으로 불렸습니다).
• 색 바꾸기 — 트리·카드·팔레트에서 이 레포를 알아볼 색을 고릅니다. 옆 프로젝트 색을 보면서 고르세요.
• 프로젝트 맵 다시 생성 — 언어·빌드·테스트 명령·주요 디렉터리를 다시 조사합니다. 워크플로우 프롬프트에 컨텍스트로 들어갑니다.
• 기본 worktree 에서 세션 열기 — 티켓을 만들기 전에 main 에서 확인·질문할 세션을 엽니다.
• 폴더 없는 worktree 정리 — 이 레포에서 폴더가 밖에서 지워진 worktree 를 한 번에 기록으로 옮깁니다. 정리할 것이 없으면 이 항목은 보이지 않고, 있으면 옆에 그 수가 적힙니다(닫기).

배포 현황 (ArgoCD) 개발자#

레포의 환경(개발 · 스테이징 · QA · 운영)별 ArgoCD 배포 상태를 한 창에서 보고, 앱을 동기화하거나 멈춘 롤아웃을 재개 · 프로모트합니다. 배포 기능이 켜져 있어야 보입니다. MCP 는 필요 없습니다(ArgoCD API 를 직접 읽습니다).

1. 환경 등록 — 상세 프로젝트 칩 › 배포 환경 에서 환경 줄의 추가: 모듈 이름 (선택) · ArgoCD 주소 · 앱 이름 · 앱 namespace (선택) · ArgoCD project (선택)를 넣고 연결 확인 후 저장. 환경은 0~4개, 필요한 것만 둡니다.
2. 한 환경에 앱 여럿(멀티 모듈) — 한 레포에 모듈이 여럿이라 ArgoCD 앱이 모듈마다 따로면, 앱이 이미 있는 환경에서도 추가 를 눌러 둘째 앱을 넣습니다. 이때는 모듈 이름(예: api · worker · batch)이 필수입니다 — 같은 환경에 같은 이름은 둘 둘 수 없습니다. 앱 줄마다 편집 · 삭제 가 따로 있고, 배포 현황 창에서도 같은 환경 칸(머리의 추가) 안에서 넣을 수 있습니다. 앱이 하나뿐인 환경은 이름을 비워 둬도 됩니다.
3. 프로젝트 행 ⋯ › 배포 현황. 환경 칸마다 등록한 앱이 카드로 서고(모듈이 여럿이면 한 칸에 여러 장 · 카드 머리에 모듈 이름), 카드마다 sync/health 알약 · 리비전 · 이미지 · 마지막 동작이 보입니다. 창이 열린 동안 10초마다 갱신됩니다.
4. 카나리면 단계 눈금(i/n)과 가중치 막대가 서고, 멈춰 있으면 프로모트 필요 상자가 뜹니다(블루그린은 preview 대기).
5. 재개(멈춘 단계를 풀고 다음 단계로 · resume) 또는 전체 프로모트(남은 단계를 건너뛰고 끝까지)를 누르면 확인 창이 앱 · 환경 · 롤아웃 · 지금 단계를 보여 줍니다. 되돌릴 수 없으니 확인하고 진행합니다. 사람이 일부러 멈춘 롤아웃(프로모트 대기가 아닌 멈춤)에도 재개 가 뜹니다. 중단(abort)된 롤아웃은 재개로 풀리지 않아 버튼 대신 「ArgoCD 에서 retry 하세요」 안내와 ArgoCD 열기 가 섭니다.
6. Suspended 상자 — ArgoCD 에서 앱이 Suspended 인데 위의 롤아웃 상자가 서지 않는 멈춤(롤아웃 없이 멈춘 Deployment 등)이면 카드에 「Suspended — Deployment/이름」 상자가 섭니다. ArgoCD 가 그 리소스에 지금 허락하는 동작만 버튼으로 나오고(보통 재개), 버튼마다 무엇을 하는지 한 줄이 붙습니다. 허락하는 동작이 없거나 볼 권한이 없으면 버튼 대신 까닭과 ArgoCD 열기 가 섭니다.
7. 재개 · 전체 프로모트 · 동기화의 확인 창은 취소 에 손이 먼저 가 있고, Enter 로는 실행되지 않습니다 — 확인 버튼을 눌러야 보냅니다. 실패하면(권한 없음 등) ArgoCD 가 준 까닭이 알림으로 옵니다.
8. 모든 환경 카드에 동기화 가 있습니다 — 카나리가 없는 일반 Deployment 앱도 됩니다. OutOfSync 면 강조돼 보이고, 확인 창이 지금 sync 상태 · 리비전과 대상 리비전(앱이 따라가는 브랜치·태그)을 보여 줍니다. prune 없이 동기화합니다(삭제된 리소스는 지우지 않음). 운영 환경이면 경고 한 줄이 더 붙습니다. 이미 동기화가 도는 중이면 버튼이 잠기고 보내지 않습니다.
9. Pod — 카드 끝의 Pod N 줄이 떠 있는 Pod 수와 비정상(CrashLoopBackOff · ImagePullBackOff · OOMKilled 등) · 준비 중 · 재시작 수, 그리고 상태별 개수를 보여 줍니다. 누르면 펼쳐져 ReplicaSet(리비전)별로 Pod 가 서고 — 카나리면 canary · stable, 블루그린이면 active · preview — 비정상 Pod 는 붉게 강조됩니다. Pod 줄을 누르면 Pod 상세 창이 열려 노드 · 생성 시각 · 컨테이너별 상태 · 재시작 · 직전 종료 사유(예: OOMKilled (exit 137)) · 최근 이벤트를 보여 줍니다. 로그는 로그 불러오기 를 눌러야 읽고, 컨테이너 · 끝에서 몇 줄 · 직전 컨테이너(재시작 전) 를 고를 수 있습니다. 목록은 창이 이미 받는 정보로 그려서 서버에 요청이 더 가지 않습니다.
10. 보낸 뒤 창을 닫아도 됩니다 — 결과는 앱 어디서든 알림으로 옵니다. 동기화·재개·프로모트는 누른 카드의 앱에만 가고, 확인 창과 알림이 「개발 · worker」 처럼 모듈까지 적습니다.

테스트 방식 — 레포 × 환경 모두#

레포마다, 환경(local · dev · staging · qa · prod — 레포마다 다르게)마다 「어디서 무엇을 어떻게 판정할지」 를 적어 둡니다. 명령으로 도는 테스트(e2e·회귀)와, 에이전트에게 절차를 맡기는 테스트(예: 데이터브릭스 잡을 돌리고 결과 테이블 검증)를 둘 다 둘 수 있습니다.

1. 상세 프로젝트 칩 › 테스트 방식. 위의 환경 탭(local 1 · dev 2 …)에서 환경을 고르거나 + 환경 추가(권장값 제안). 이름 변경 · 환경 삭제 도 여기서.
2. + 테스트 추가 — 테스트 이름 · 종류(명령 / 에이전트)를 고릅니다. 명령이면 명령 · 작업 디렉터리 · 타임아웃 (초) · 판정 기준(종료 코드 0 / 출력에 문자열 포함). 에이전트면 절차 · 검증 기준 · 필요 MCP(실행 전에 인증 확인). 공통으로 대상 URL · 변수(KEY=값 — 비밀은 값 대신 secret:키). 저장은 앱에 됩니다.
3. 이 환경 테스트 실행 — 레포 테스트 워크플로우가 그 환경의 테스트를 돌리고 통과/실패와 근거를 남깁니다. 창을 떠나도 계속되고 결말은 알림으로 옵니다.
4. 레포에 .baton/test-plans.yaml 을 두고 팀과 나누려면 레포로 내보내기, 받은 파일은 레포에서 불러오기(누를 때만 읽고 씁니다 · 비밀 값은 쓰지 않습니다).

실행 화면에서 레포 테스트 를 돌릴 때 환경 을 고르면 그 환경의 테스트가, 비워 두면 종전대로 기본 레시피(local · default)가 돕니다. 테스트 를 비우면 그 환경의 테스트 전부입니다.

임시 키 → 실제 키 교체 개발자#

자율 구현은 API 키 · 계정이 없으면 임시 대체품(mock · stub)으로 구현하고 그 자리 코드에 BATON-FALLBACK(키 이름) 표시를 남깁니다. 나중에 실제 키를 채우면 이 실행이 표시를 따라 그 자리를 실제 키를 쓰는 구현으로 바꾸고 개발 레포의 main 에 머지합니다. 기획에 연결된 레포에서도, 기획 없이 만든 개발 레포에서도 같습니다 — 표시만 있으면 됩니다.

1. 어디서 — 두 자리 중 편한 곳에서 엽니다.
   • 기획에서: 설계 칩 승인 띠의 준비물 줄(디자인 · 설계 승인). 이 기획의 준비물 중 채운 키가 연결된 개발 레포에 임시 대체품으로 남아 있으면 임시 키 → 실제 키 교체 가 켜집니다.
   • 어느 개발 레포에서든: 상세 패널 프로젝트 칩의 임시 키 → 실제 키 교체 절(개발 · 통합 프로젝트에만 섭니다). 실행 화면 · ⌘K 의 임시 키 → 실제 키 교체 워크플로우로도 같은 실행을 돌립니다(개발 프로젝트를 고르고, 바꿀 키를 비우면 채운 것 전부).
2. 키 넣기 — 프로젝트 칩의 절은 키마다 임시 대체품 N곳 · 파일 N 과 상태를 적습니다. ✓ 실제 키 는 이미 채운 것, 임시 대체품 은 아직 없는 것입니다. 없는 키는 가려진 칸에 값을 넣고 저장 — 그 레포의 .env.local 에만 쓰고 칸을 비웁니다(.gitignore 가 거르지 않으면 먼저 더합니다). 앱 · 대화 · 기록 어디에도 값이 남지 않습니다. 받는 이름은 이 레포의 표시에 있거나 연결된 기획의 준비물에 있는 것뿐입니다.
3. 임시 키 → 실제 키 교체 — 단추 옆에 바꿀 것이 적힙니다(PAYMENT_KEY 외 1 — 임시 대체품 3곳). 누르면 확인 창이 바꿀 키 · 자리(파일:줄)를 읊습니다. 교체 시작 을 누르면 창은 바로 닫히고 실행이 뒤에서 돕니다 — 끝나면 알림이 옵니다.
4. 무엇이 도나 — 키마다 일감 하나가 Track 에 서고, 자율 구현의 일감과 같은 길을 갑니다: 자기 자리에서 고침 → 그 키의 표시가 사라졌는지 · 레포 테스트 → 다른 세션의 리뷰 → main 에 머지. 고치는 AI 는 연결된 기획의 컴포넌트 스펙 · LLD 가 있으면 그 계약대로, 없으면 코드의 맥락대로 실제 연동을 붙이고, 키가 틀렸을 때 알아볼 수 있는 오류를 남기고, 설정(키) 뒤에서 실제 클라이언트를 쓰는 테스트를 더합니다.
5. 결과 — 실행의 마지막 스텝 결과 보고 에 바꾼 키 · 보류(이유) · 아직 남은 임시 대체품 이 섭니다. 바뀐 키의 표시는 프로젝트 칩의 목록에서 사라집니다.

12

1

• 꺼져 있으면 — 단추 옆에 이유가 적힙니다: 표시가 없음(… 에 이 기획 준비물의 임시 대체품이 없습니다) · 키를 아직 채우지 않음(… 를 채우면 켜집니다).
• 한 레포에 하나씩 — 같은 개발 레포에서 자율 구현이나 다른 교체가 돌고 있으면 시작하지 않고 끝난 뒤 다시 누르라고 알려 줍니다(같은 레포에 두 실행이 머지하면 서로를 깹니다). 교체가 도는 동안에는 그 레포로 가는 구현 도 같은 이유로 기다립니다.
• 큰 결정은 그 일감만 멈춥니다 — 키만으로 안 되고 계정 설정 · 요금제 선택 같은 사람의 결정이 필요하면 그 키의 일감만 보류(사람 결정 필요)로 서고 알림이 옵니다(사람 결정 필요 — 레포 이름). 나머지 키는 계속 갑니다.
• 표시는 레포의 파일에서 찾습니다(git 이 무시하는 파일 · node_modules · 빌드 폴더 · .env 파일은 보지 않습니다). 무시된 파일에만 있는 표시는 찾지 못합니다.

Wiki 모두#

어떤 통로로든 등록한 문서 · 링크 · 메모 · 상용구를 한 자리에 모아 보고, 여기서 새 글도 씁니다. 왼쪽이 트리, 오른쪽이 문서입니다(⌃` 로 트리를 접습니다).

위키 화면 머리에는 위키 │ Baton Drive 탭이 있습니다. 두 번째 탭은 Google Drive 의 HTML 문서함입니다 — Baton Drive 를 보세요.

1. 새 페이지 — 트리 위 ＋. 줄에 커서를 올리면 나오는 ＋ 는 그 안에 만듭니다. 깊이 제한은 없고 어느 줄이든 부모가 됩니다.
2. 편집 · 발행 — 오른쪽 편집 을 누르고 마크다운으로 씁니다. 쓰는 내용은 자동으로 저장되고(아래 「쓰던 글은 저절로 남습니다」), 다 썼으면 발행 을 눌러 본문으로 올립니다.
3. 원천 걸기 — 트리 위 📎. 메모 · 상용구처럼 보드에 자리가 없는 것을 고른 자리 아래에 겁니다. 문서 · 링크는 걸 필요가 없습니다 — 아래의 「문서는 제자리에 섭니다」를 보세요.
4. 옮기기 — 줄을 끌어 놓습니다. 줄의 위·아래 끝에 놓으면 형제로 끼고, 가운데에 놓으면 그 안에 들어갑니다. 키보드로는 ⌥↑ · ⌥↓ 입니다.
5. 검색 — 트리 위 검색창. 제목 · 라벨 · 내용 · 주소를 찾고 한국어 부분일치가 됩니다(「위키」로 「개인위키」가 걸립니다). 같은 결과가 ⌘K · ⌘⇧F 에도 나옵니다.
6. 접기 · 펴기 — 줄의 꺾쇠로 가지를 접습니다. 트리 위 줄의 모두 펼침 · 모두 접힘 은 한 번에 다 펴거나 맨 위 층만 남기고 접습니다. 접어 둔 모양은 다른 화면을 다녀와도 · 앱을 다시 켜도 그대로입니다(Baton Drive 트리도 같습니다).
7. 내보내기 — 페이지를 .md 파일로 꺼냅니다(기본 자리는 다운로드 폴더).

12

12

Baton Drive 모두#

내 Google Drive 의 .baton 폴더에 HTML 문서를 올려 두고, baton 안에서 찾아 읽는 자리입니다. 위키 화면 머리의 위키 │ Baton Drive 탭에 있습니다. 보고서 · 대시보드 · 회의록처럼 한 장짜리 HTML 을 팀 문서함처럼 쌓아 두고 싶을 때 씁니다.

처음 연결

1. Google 로그인 — Baton Drive 탭을 처음 열면 Google 로그인 버튼이 서 있습니다. 누르면 시스템 브라우저에 동의 화면이 열리고, 계정을 고르면 끝납니다. 기다리는 동안에도 다른 화면을 쓸 수 있고, 끝나면 알림으로 알려 줍니다. 마음이 바뀌면 취소 합니다.
2. 셋업에서 미리 — 처음 실행할 때의 셋업 에도 Google 로그인 줄이 선택 으로 서 있습니다. 필수가 아니라 「앱 시작」을 막지 않고, 지금 하기 싫으면 다음에 하기 를 누릅니다(로그인 길은 Baton Drive 탭에 그대로 남습니다).
3. Drive 권한 추가 — 계정은 연결됐는데 Drive 권한을 주지 않았다면 Drive 권한 추가 가 서 있습니다. 한 번 더 동의하면 됩니다(이미 준 권한은 그대로입니다). 요청하는 권한은 이 앱이 올린 파일만 다루는 범위(drive.file)입니다.

연결되면 왼쪽 위에 계정 이메일과 연결 해제 가 섭니다. 해제하면 이 기기의 캐시를 비웁니다 — Drive 의 파일은 그대로입니다.

올리기

1. 끌어다 놓기 — HTML 파일을 탭 위로 끌어다 놓으면 올라갑니다. 폴더 줄 위 에 놓으면 그 폴더 안으로, 빈 자리에 놓으면 맨 위로 들어갑니다(끄는 동안 놓일 폴더 이름이 보입니다).
2. 파일 올리기 — 트리 위 버튼으로 파일을 골라도 같습니다. 폴더를 골라 둔 상태면 그 폴더 안에 올라갑니다.
3. 다시 올리면 묻습니다 — 이 기기에서 이미 올린 파일이거나 같은 폴더에 같은 이름이 있으면 덮어쓰기 · 새로 올리기 · 건너뛰기 를 묻습니다. 덮어쓰면 Drive 에서의 위치 · 공유 · 링크가 그대로이고, Drive 가 이전 판을 남깁니다.

보기 · 찾기

왼쪽은 폴더 트리(폴더가 먼저, 이름순)이고 줄을 누르면 오른쪽에 문서가 열립니다. 위키 트리와 같은 키로 움직입니다(↑ ↓ · ← → 접기 · ⇧F10 메뉴). 트리 위 줄의 모두 펼침 · 모두 접힘 으로 폴더를 한 번에 펴고 접으며, 접어 둔 폴더는 다른 화면을 다녀와도 접혀 있습니다. 위 Baton Drive 검색 칸은 제목과 본문을 함께 찾고, 본문에 걸린 것은 걸린 대목을 보여 줍니다. 목록과 본문은 이 기기에 캐시해 두어 탭이 바로 열리고, 뒤에서 Drive 와 맞춥니다(받는 중 표시). 문서 위의 새로 받기 는 그 파일만 Drive 에서 다시 받습니다.

123

문서만 크게 보기 — 문서 위 줄 오른쪽 끝의 − · 문서 100% · ＋ 로, 또는 Baton Drive 화면 안(문서 · 트리 · 머리 버튼 어디든)에 손이 있을 때 ⌘+ / ⌘− 로 앱 화면은 그대로 두고 문서만 커지고 작아집니다(50%~200%). 브라우저 확대처럼 글자를 다시 그리므로 흐려지지 않습니다. 가운데 문서 N% 를 누르거나 ⌘0 을 누르면 100% 로 돌아옵니다. 고른 배율은 다른 문서를 열어도 · 다음 실행에도 남습니다. 위키 탭 · 옆 칸 · 다른 화면에 손이 있으면 ⌘+ 는 종전대로 앱 배율입니다.

정리하기

1. 이름 바꾸기 — 줄의 ⋯ 메뉴 › 이름 바꾸기. Drive 의 이름이 바뀝니다(공유 링크 · 이전 판 기록은 그대로입니다).
2. 옮기기 — 줄을 폴더 위로 끌어 놓거나, 메뉴 › 옮기기… 에서 폴더를 고릅니다. 폴더를 자기 아래로는 옮길 수 없습니다.
3. 새 폴더 — 트리 위 새 폴더 버튼(고른 폴더 안에, 없으면 맨 위) 또는 폴더 줄 메뉴 › 이 안에 새 폴더.
4. 휴지통 — 메뉴 › 휴지통으로(문서 위의 버튼도 같습니다). Drive 휴지통으로 가고 30일 안에 Drive 에서 되돌릴 수 있습니다. 폴더는 안의 파일째 갑니다.

메뉴에는 열기 · Drive 에서 열기 · 위치 복사 · 세션에 맡기기… · 경로 복사 도 있습니다.

코멘트 달기

문서를 고치기 전에 어디를 어떻게 바꾸고 싶은지 문서 위에 적어 둡니다. 코멘트는 문서와 함께 내 Google Drive 에 저장되어 다른 기기의 baton 에서도 같은 코멘트가 보입니다. 어떤 Drive 문서에나 답니다.

1. 문서 머리의 코멘트 를 누르면 오른쪽에 코멘트 패널이 열립니다. 단추의 숫자는 아직 처리하지 않은(열림) 코멘트 수입니다.
2. 자리 찍어 달기 를 켜고 문서의 문단 · 표 칸 · 화면 요소를 누르면 그 자리에 다는 입력칸이 열립니다(켜 둔 동안 가리키는 요소에 테두리가 둘립니다). 쓰고 달기(⌘↵).
3. 자리 없이 문서 전체에 하는 말은 문서 전체 로 답니다.
4. 단 코멘트는 문서 위에 번호 점으로 서고(열림 파랑 · 반영됨 초록 · 보류 회색), 패널에도 같은 번호로 섭니다. 패널의 인용을 누르면 문서의 그 자리로, 문서의 점을 누르면 패널의 그 코멘트로 갑니다.
5. 코멘트마다 반영됨 · 보류 · 다시 열기 · 지우기. 처리 메모(무엇을 바꿨는지 · 왜 보류했는지)가 있으면 글 아래에 섭니다.

12

• 문서가 바뀌어 자리를 못 찾으면 그 코멘트에 자리 잃음 딱지가 붙고 패널에만 섭니다(지워지지 않습니다).
• 코멘트를 문서에 반영하는 일은 세션이 합니다. 세션은 drive_comments 로 코멘트를 읽고, 문서를 고쳐 덮어쓴 뒤 drive_comment_resolve 로 코멘트마다 반영됨 · 보류(이유)를 적습니다. 코멘트를 달거나 지우는 것은 사람만 합니다.

워크플로우로…

입력 칸 이름이 drive_doc 인 워크플로우가 있으면 문서 머리와 줄의 ⋯ 메뉴에 워크플로우로… 가 섭니다. 고르면 그 문서의 주소(baton://drive/…)가 채워진 실행 창이 열립니다 — 남은 칸만 채우고 실행합니다. 내가 만든 워크플로우(~/.baton/workflows)도 칸 이름만 맞추면 여기 섭니다. 앱은 문서의 종류를 가리지 않습니다 — 어떤 문서를 받을지는 그 워크플로우가 정합니다.

고치기는 AI 에게

세션에 「Baton Drive 의 ‘주간 지표 대시보드’ 문서 이렇게 고쳐줘 …」 라고 말하면, 세션이 그 문서를 받아 고친 뒤 같은 파일에 덮어씁니다(새 문서가 하나 더 생기지 않습니다). Drive 가 이전 판을 남기니 잘못 고쳐졌으면 Drive 의 버전 기록에서 되돌릴 수 있습니다. 예문은 AI 에게 baton 기능 시키기 의 표에 있습니다. 세션이 쓰는 도구는 drive_list(찾기) · drive_read(받기) · drive_upload(올리기·덮어쓰기)이고, 지우기 · 이름 바꾸기 · 옮기기는 사람이 이 화면에서 합니다. 연결이 안 돼 있으면 세션이 「위키 › Baton Drive 탭에서 Google 로그인」을 부탁합니다. 세션이 올릴 수 있는 파일은 그 세션의 작업 폴더 아래와 drive_read 가 받아 둔 파일 · 보드 문서뿐입니다 — 다른 곳의 파일이면 작업 폴더로 복사해 올립니다.

다른 화면에서 올리기

Baton Drive 탭을 열지 않아도 앱 곳곳에서 바로 올립니다 — 보드 › 문서 행의 ⋯ 메뉴(로컬 HTML 문서만)와 디자인 칩의 ⋯ 메뉴(html 파일만), 설계 칩 행의 ⋯ 메뉴에 Baton Drive 에 올리기 가 있습니다. 덮어쓰기 질문 · 경고 · 결말 알림이 탭에서와 같습니다. 연결 전이면 올리지 않고 로그인 안내와 Baton Drive 열기 를 줍니다.

• 문서 제목이 파일 이름입니다 — 보드 문서는 보관 사본의 이름(0b76…e9.html 같은 긴 글자)이 아니라 문서 제목으로 올라갑니다. 디자인 칩의 파일은 시안 제목으로, 설계 칩의 파일은 문서 제목으로 올라갑니다. 파일 이름에 못 쓰는 글자(/ : ? 등)는 공백으로 바뀝니다.
• 보드 자리대로 폴더에 놓입니다 — 워크스페이스 › 프로젝트 › 워크트리 폴더가 없으면 만들어 그 안에 넣습니다(프로젝트 그룹 · 그룹 자리의 문서는 그 이름의 폴더). 디자인 칩의 파일은 그 아래 디자인 폴더에 들어갑니다. 설계는 기획 프로젝트에 한 벌이라 워크스페이스 › 프로젝트 › 설계 폴더에 들어갑니다. 폴더 이름은 보드의 표기명입니다(워크트리는 브랜치를 붙이지 않은 이름 · 줄기 워크트리는 브랜치 이름). 보드에서 보던 이름 그대로라 Drive 에서도 같은 길로 찾습니다.
• 로컬 스타일시트는 문서 안에 넣어 올립니다 — <link rel="stylesheet"> 가 내 컴퓨터의 .css 파일을 가리키면, 올리기 직전에 그 내용을 문서 안 <style> 로 옮깁니다. 다른 기기 · Drive 에서도 모양이 깨지지 않습니다. 내 컴퓨터의 원본 파일은 고치지 않습니다. 찾지 못한 시트는 그대로 두고 경고로 알려 줍니다.
• 그림 · 글꼴도 문서 안에 넣어 올립니다 — <img src="shot.png"> 처럼 내 컴퓨터의 그림을 가리키면, 올리기 직전에 그 그림을 문서 안(data:)으로 옮깁니다. srcset · style="background:url(…)" · <style> 안의 url(), 스타일시트 안의 그림 · 글꼴(시트가 있는 폴더 기준)도 같습니다. https:// 로 가리킨 원격 그림도 받아서 넣습니다 — Drive 뷰어는 문서 밖 그림을 열지 않기 때문입니다. 그래서 어느 기기에서 열어도 같은 그림이 나옵니다. 그림이 커도 됩니다: 넣은 뒤 5MB 를 넘는 문서는 큰 파일 올리기 방식으로 올리고, 문서 하나는 50MB(그림 한 장은 20MB)까지 받습니다. 넘으면 올리지 않고 「그림을 줄이거나 문서를 나눠 주세요」라고 알려 줍니다. 내 컴퓨터의 원본 파일은 고치지 않습니다.
• 다 올리면 바로 열 수 있습니다 — 알림에 올라간 위치(/워크스페이스/프로젝트/워크트리/제목.html)와 문서 안에 넣은 스타일시트 · 그림 수가 나오고, 버튼이 둘 있습니다. 바로가기 는 지금 보던 칸을 위키 › Baton Drive 로 바꿔 그 문서를 엽니다. 사이드로 열기 는 화면을 둘로 나눠(2분할) 옆 칸에 열어, 보던 화면은 그대로 둡니다.
• Google 쪽 일시 오류면 「재시도」 — Drive 가 잠시 응답하지 못한 실패(HTTP 500 · 503 · 요청이 너무 잦음 · 네트워크 끊김)는 실패 알림에 재시도 버튼이 섭니다. 누르면 같은 자리 · 같은 이름으로 다시 올립니다. 권한 · 파일 문제처럼 다시 해도 같은 실패에는 버튼이 없습니다.

공유하기

특정 사람에게만 보여 주려면 문서 위의 Drive 에서 열기 로 Drive 웹을 연 뒤 Drive 의 공유 창에서 사람을 더하세요. 공유는 Drive 의 것이라 덮어써도 유지됩니다.

웹에 공개하기

로그인 없이 링크만으로 누구나 보게 하려면 웹에 공개합니다. 받는 사람은 baton 도 Google 계정도 필요 없습니다 — 브라우저에서 https://baton-view.drive-viewer.workers.dev/d/… 주소를 열면 됩니다.

1. 트리에서 문서의 ⋯(또는 우클릭) › 웹에 공개… 를 고릅니다. Baton Drive 웹 공개 워크플로우가 시작됩니다 — 창을 닫고 다른 일을 해도 됩니다.
2. 워크플로우가 보안 검수를 합니다: ① 기계 검사(토큰 · API 키 · 비밀번호 · 접속 문자열 · 사설망/사내 주소 · 이메일 · 전화번호 · 주민등록번호 · 카드 번호) ② AI 검토(문맥상 공개되면 안 되는 고객 정보 · 미공개 지표 · 내부 계획). 화면에 안 보이는 주석 · 스크립트도 봅니다.
3. 실행 화면에 웹 공개 — 문서 이름 승인 카드가 섭니다. 걸린 것이 없으면 공개한다, 확인할 것이 있으면 확인했고 공개한다, 비밀 · 개인정보가 걸렸으면 공개하지 않는다 하나만 있습니다 — 원본에서 지우고 다시 돌리세요.
4. 공개하면 결과에 공개 주소가 남고, 트리의 원본 줄에 공개 딱지가 섭니다. ⋯ › 공개 링크 복사 로 주소를 복사합니다.

• 공개하는 것은 사본입니다. 검수를 통과한 본문이 .baton/공개/ 에 사본으로 놓이고, 그 사본에만 「링크가 있는 모든 사용자」 권한이 붙습니다. 원본을 고쳐도 링크 너머는 그대로입니다 — 바뀐 내용을 내보내려면 웹에 다시 공개… 로 검수를 다시 거칩니다(주소는 같습니다).
• 사본은 직접 고칠 수 없습니다. AI 의 덮어쓰기도 거절됩니다 — 검수 없이 링크 너머가 바뀌지 않게.
• 공개 내리기는 검수 없이 바로입니다. 내리는 순간 링크가 열리지 않고, 사본은 남아 다시 공개하면 같은 주소로 열립니다.
• 트리 머리의 웹 공개 버튼은 공개한 문서 전체를 보여 줍니다 — 링크 복사 · 다시 공개… · 내리기, 그리고 모두 내리기.
• AI 에게 「이 문서 웹에 공개해줘」라고 해도 같은 워크플로우가 돕니다 — 실행 카드와 승인 카드는 사람이 누릅니다.

자기 뷰어를 쓰려면 레포의 web/drive-viewer/ 를 자기 Cloudflare 계정에 올리고(자기 Google API 키로), 설정 google.publicViewerUrl 을 그 주소로 바꿉니다.

기록 모두#

닫거나 삭제된 worktree 의 요약 · 대화 · 링크 · 산출물을 검색합니다. 디렉터리는 없어도 기록은 남습니다(⌘3).

1. 검색창(⌘F)에 티켓 키 · 제목 · 대화 · 문서 · 산출물 파일명을 칩니다.
2. 필터: 전체 · 보관됨 · 활성 · 성과 있음 · 자동 처리 · 기간 · 프로젝트별.
3. 보관 과업 목록은 한 쪽에 3일치씩 날짜별로 묶여 보입니다. 아래 이전 · 다음 · 쪽 번호로 더 지난 날을 보고, 기간이나 필터를 바꾸면 첫 쪽으로 돌아갑니다.
4. 보관된 과업을 누르면 상세(요약 · 대화 · 문서 · 산출물)가 열립니다.
5. 오른쪽 위에서 보관 과업 / 닫힌 세션, 과업 / 성과 모아보기 / 토큰 을 바꿉니다.
6. 닫힌 세션 은 한 쪽에 3일치씩 날짜별로 보입니다. 아래 이전 · 다음 · 쪽 번호로 더 지난 날을 봅니다.

토큰 사용량 모두#

세션과 과업이 쓴 토큰을 봅니다. 자리는 셋이고 숫자는 모두 같은 장부에서 옵니다 — 트리 의 세션 행 · worktree 행 ⋯ › 사용 토큰 보기, 그리고 기록(⌘3) › 토큰 의 기간별 통계입니다.

한 세션 · 한 과업이 쓴 토큰

1. 트리에서 세션 행이나 worktree 행의 ⋯ › 사용 토큰 보기(작업 목록 카드 메뉴에도 같은 항목이 있습니다).
2. 입력 · 출력 · 캐시 쓰기 · 캐시 읽기 네 칸이 따로 섭니다 — 캐시 읽기는 입력의 1/10 값이라 한 숫자로 합치면 무엇이 비쌌는지 읽을 수 없습니다.
3. 아래에 합계 · 추정 비용 · 캐시 적중률 · 응답 수 · 기간. 모델을 섞어 쓴 자리는 모델별 표가 한 겹 더 섭니다(모델마다 단가가 달라 따로 계산합니다).
4. worktree 행에서 열면 그 아래 세션별 표가 함께 섭니다. 이미 닫히고 정리된 세션도 정리됨 표시와 함께 남습니다.
5. 숫자가 비어 있거나 모자라면 기록에서 다시 세기 — 그 자리의 대화 기록(transcript)을 읽어 채웁니다. 창을 닫아도 계속되고 끝나면 알려 줍니다.

기간별 통계 — 기록 › 토큰

1. ⌘3 기록에서 오른쪽 위 토큰 을 고릅니다.
2. 기간(최근 30일 · 최근 90일 · 전체)과 눈금(주 · 달)을 고릅니다. 고른 기간의 실제 날짜가 옆에 늘 적힙니다.
3. 기간별 추이 — 주(월요일 시작) 또는 달마다의 토큰 · 추정 비용 · 캐시 적중률.
4. 워크플로우별 — 실행 한 번에 드는 값입니다. 어느 워크플로우가 비싼지가 이 표의 요지입니다(프롬프트를 줄이거나 모델을 낮출 자리를 찾습니다).
5. 상위 소비처 — 과업(worktree)과 프로젝트 순위. 프로젝트별 칩으로 레포 하나만 볼 수 있습니다 — 칩을 고르면 맨 위 합계와 추이 · 워크플로우별까지 함께 그 레포 기준으로 바뀝니다(한 화면의 숫자가 늘 같은 기준입니다).
6. 오른쪽 위 기록에서 되살리기 는 모든 세션의 대화 기록을 훑습니다. 버튼의 숫자가 아직 안 읽은 파일 수입니다.

즐겨찾기 모두#

링크를 소속(워크스페이스 · 프로젝트 · worktree)과 그룹으로 모아 봅니다. 붙여 넣으면 제목이 자동으로 차고, 누르면 브라우저에서 열립니다(⌘5).

담은 것은 전부 보입니다. 화면은 전체 범위로 열리므로, 어느 워크스페이스에 담았는지 기억하지 못해도 여기 있습니다 — 워크스페이스 밖 폴더를 프로젝트로 붙인 「프로젝트」 그룹(단독 프로젝트)에 담은 링크도 마찬가지입니다. 한 워크스페이스만 보려면 제목 옆 보는 범위 고르개로 좁힙니다.

계층은 트리와 같은 한 줄기입니다 — 워크스페이스 › 프로젝트 › worktree. 프로젝트에 담은 링크는 그 워크스페이스 덩어리 안에 들어가고, worktree 에 넣은 링크는 다시 그 프로젝트 안에 한 단계 들여 모입니다. 위를 접으면 아래 링크도 함께 접힙니다. 즐겨찾기는 여전히 그 worktree 의 것이라 상세의 링크 n 에도 그대로 뜹니다. 소속 이름은 트리에 뜨는 그 표기명과 같습니다 — 예전에는 지라 티켓 키(DEMO-1234)만 보여 어느 worktree 인지 알아보기 어려웠습니다.

1. + 즐겨찾기 에 URL 을 붙여 넣고 소속·그룹을 고릅니다. 내 컴퓨터의 문서는 file:///Users/…/문서.html 처럼 넣으면 기본 앱(html 은 브라우저)으로 열립니다 — html·pdf·이미지·텍스트만 열고, 파일이 없으면 그 사유를 알려 줍니다.
2. 메모 (선택) 에 이 링크를 왜 두는지 적어 두면 목록의 제목 아래에 한 줄로 보입니다.
3. 행의 복사 아이콘(열기 ↗ 옆)을 누르면 그 주소가 클립보드에 들어갑니다 — 행 ⋯ › 링크 복사 도 같습니다.
4. 검색창으로 제목·URL·메모를 찾고, 행 ⋯ › 편집 으로 제목·주소·저장 위치·그룹·메모를 고치거나 삭제 합니다. 저장 위치를 바꾸면 그 소속으로 옮겨 갑니다(끌어 놓기와 같은 일입니다). 메모를 비우고 저장하면 지워집니다.

스니펫 모두#

자주 치는 문장을 제목·내용으로 등록해 두면 대화 입력창 아래 버튼으로 붙습니다. 앞 9개는 순서대로 ⌥⇧1~⌥⇧9 를 받습니다(⌘6).

1. + 스니펫 으로 제목과 내용을 적습니다(대화의 내 말에서 스니펫으로 등록 도 됩니다).
2. 끌어서 옮기거나 화살표로 순서를 바꿉니다 — 버튼 순서와 단축키가 따라갑니다. 바꾼 순서는 그대로 저장되어 앱을 다시 켜도 남습니다. 자주 쓰는 것을 앞으로 당기면 ⌥⇧1 도 함께 앞당겨집니다.

메모 모두#

슬랙 스레드 · 이미지 · 글 · 문서 파일을 한자리에 남기는 개인 기록입니다. 비밀번호로 잠기고, 화면을 나가면 다시 잠깁니다(⌘7).

1. 처음 들어가면 비밀번호를 정합니다(4자 이상).
2. + 메모 로 글을 쓰거나, 슬랙 링크·이미지를 끌어다 놓습니다. 이미지는 글자를 읽어 검색되게 합니다.
3. 추가 창에서 프로젝트(하나 · 안 골라도 됩니다)와 라벨(여러 개)을 붙여 두면 나중에 그것으로 모아 볼 수 있습니다.
4. 검색창으로 제목 · 내용 · 작성자 · 첨부 이름 · 라벨을 찾습니다.

비밀번호는 설정 › 메모 비밀번호 변경 에서 바꿉니다.

문서 파일 첨부

한 메모에 txt · md · pdf · csv 같은 문서를 여러 개 붙이고, 펼치면 파일 형식에 맞게 읽습니다. 파일은 앱 데이터 폴더(memo-files)로 복사되므로 원본을 옮기거나 지워도 열립니다.

1. 올리는 길은 넷입니다 — + 메모 의 문서 파일(파일 선택 · 끌어다 놓기 · ⌘V), 펼친 카드의 파일 첨부, 카드 위에 끌어다 놓기(그 메모에 붙음), 화면 빈자리에 끌어다 놓기 · 붙여 넣기(새 문서 메모).
2. 추가 창은 어디에 놓아도 받습니다 — 점선 상자를 겨냥하지 않아도 되고, 종류가 글 이나 슬랙 이어도 됩니다. 파일을 창 위로 끌면 「놓으면 이 메모에 붙입니다」가 뜨고, 놓으면 종류가 문서 파일 로 바뀌며 목록에 더해집니다. 종류가 이미지 일 때만 그림 한 장으로 받습니다(그림이 아니면 그 자리에서 이유를 말합니다).
3. 올리는 동안에도 앱은 그대로 쓸 수 있습니다. 카드에 「올리는 중」이 서고, 끝나면 알림으로 결과(붙인 것 · 붙이지 않은 것과 이유 · 다른 메모에도 있는 파일)를 알려 줍니다.
4. 접힌 줄에는 클립 · 첨부 수 · 형식 아이콘이 서고, 펼치면 본문 아래 첨부 탭에서 파일을 골라 봅니다.
5. 보기 머리의 기본 앱으로 열기 · Finder 에서 보기 · 다른 이름으로 저장 · 삭제. 삭제는 확인을 거치고 앱에 복사해 둔 파일까지 지웁니다(원본은 건드리지 않습니다). 첨부가 있는 메모를 지울 때도 한 번 묻습니다.

한도 · 불가: 파일당 최대 50MB(넘으면 추가 창에서 저장 전에 이유를 보입니다) · 폴더는 올릴 수 없음 · 같은 메모에 같은 내용의 파일은 한 번만(다른 메모에 있으면 알려 줌) · 글은 앞 2MB 까지 보여 줌 · .command · .py · .app 처럼 기본 앱이 곧 실행기인 형식은 기본 앱으로 열기를 막습니다(Finder 에서 보기는 됨) · md 안의 상대 경로 그림은 표시하지 않음 · 한글(HWP)은 앱 안 미리보기 불가 · 첨부 내용은 검색하지 않음(이름은 검색됨) · 스크린샷을 클립보드에서 바로 붙여 넣으면 파일 경로가 없어 받지 않음.

프로젝트 · 라벨로 묶기

메모에 프로젝트 하나와 라벨 여러 개를 붙여 모아 봅니다. 둘 다 선택이라 급한 한 줄은 그냥 남겨도 됩니다.

1. 추가 창(+ 메모) 위쪽의 프로젝트 — 치면 후보가 좁혀지는 칸입니다. 고르지 않으면 상위 없는 메모가 됩니다.
2. 그 옆 라벨 — 치고 ↵(또는 ,) 를 누르면 칩으로 들어갑니다. 없던 라벨도 그 자리에서 만들어집니다. 빈 칸에서 ⌫ 는 마지막 라벨을 뗍니다. 한 메모에 20개까지, 라벨 하나는 40자까지입니다.
3. 목록의 접힌 줄에 프로젝트와 라벨(#라벨)이 서므로 펼치지 않고도 무엇에 관한 메모인지 보입니다(라벨이 넷을 넘으면 +n 으로 접힙니다).
4. 검색창 아래 프로젝트로 거르기 · 라벨로 거르기 로 좁힙니다. 라벨은 여러 개를 고를수록 좁아집니다(모두 가진 메모만). 프로젝트 칸에서 없음 (상위 없는 메모) 를 고르면 어디에도 안 붙인 메모만 봅니다.
5. 붙인 라벨은 검색어로도 걸립니다 — 검색창에 「배포」 를 치면 제목·본문뿐 아니라 그 라벨이 붙은 메모도 나옵니다.

프로젝트를 앱에서 빼도 그 메모는 남습니다(붙어 있던 프로젝트 이름 대신 식별자가 그대로 섭니다). 라벨은 메모를 지우면 함께 사라지고, 아무 메모에도 안 붙은 라벨은 후보에서도 빠집니다.

어디서나 메모 남기기 (⌘⇧M)

일하던 화면을 떠나지 않고 한 줄을 남깁니다. 보드에서든 대화를 쓰다가든 ⌘⇧M 을 누르면 작은 창이 뜨고, 저장하면 그 자리에서 닫힙니다.

1. 어느 화면에서나 ⌘⇧M — 대화 입력창에 손이 있어도 듣습니다(다른 팝업이 떠 있을 때는 쉽니다).
2. 제목 · 본문을 적고 필요하면 프로젝트 · 라벨을 붙입니다. ⌘↵ 로 바로 저장합니다.
3. 메모가 잠겨 있어도 남길 수 있습니다. 다만 잠긴 동안에는 이미 쓴 라벨 후보가 보이지 않고(직접 쳐서 붙입니다), 남긴 메모는 메모 화면에서 잠금을 풀어야 보입니다.
4. 슬랙 스레드 · 이미지 · 문서 파일은 이 창에서 받지 않습니다 — 창 아래 메모 화면 을 눌러 그쪽에서 붙입니다.

종류 · 기간으로 거르기와 쪽 넘김

1. 검색창 아래 종류 칩 — 글 · 슬랙 · 이미지와 첨부 형식(MD · TXT · 로그 · PDF · 표 · 코드 · JSON · 오피스 · HTML · 기타 파일). 여러 개를 고르면 하나라도 맞는 메모가, 한 메모에 첨부가 여러 형식이면 그중 하나라도 맞으면 나옵니다. 칩 옆 숫자는 누르면 나올 개수이고, 없는 종류는 칩이 서지 않습니다. 전체 로 풉니다.
2. 옆의 기간 — 전체 · 오늘 · 어제 · 7일 · 30일 · 날짜 고르기(실행 화면과 같은 기간 고르개). 남긴 날 또는 고친 날이 그 안인 메모입니다.
3. 낱말 · 종류 · 기간은 함께 걸립니다. 목록은 30개씩 끊어 아래 쪽 번호로 넘기고, 거르기를 바꾸면 첫 쪽으로 돌아갑니다.

일지 모두#

하루 동안 연 과업 · 세션 · 실행을 시간대별로 한 장에 보여 줍니다(⌘8).

1. 위쪽 날짜를 눌러 달력에서 고르거나, ‹ › 로 하루씩 옮깁니다. 오늘 로 돌아옵니다.
2. 그날 기록이 없으면 가장 최근 기록으로 를 누릅니다.

브라우저 모두#

링크·문서를 앱을 떠나지 않고 봅니다. 앱과 브라우저를 오가지 않아도 되고, 화면을 좌우로 나누면 한쪽에 웹을 띄워 둔 채 다른 쪽에서 일할 수 있습니다.

1. 레일에서 브라우저 를 누르고 주소창에 주소를 넣습니다(wiki.example.com 처럼 https:// 를 빼도 됩니다). Enter 로 엽니다. 주소가 아닌 말을 치면 구글에서 찾습니다 — 크롬과 같습니다.
2. 내 컴퓨터의 문서도 같은 자리에서 봅니다 — file:///Users/…/report.html 처럼 넣거나, 경로(/Users/…)를 그대로 붙여 넣어도 됩니다. HTML·이미지·텍스트처럼 여는 것이 곧 보기인 형식만 열리고, 없는 파일이면 그 사유가 화면에 뜹니다. PDF 는 전용 창이 따로 있습니다.
3. 왼쪽 위 뒤로 · 앞으로 · 새로고침 으로 움직입니다. ⌘R 도 보고 있는 웹페이지를 다시 읽습니다(앱의 데이터 새로고침이 아닙니다 — 새로고침). 브라우저 버튼은 지금 보는 주소를 시스템 브라우저로 넘깁니다.
4. ⌘⇧S 로 화면을 나눈 뒤 한 칸을 브라우저로 두면, 반대쪽에서 대화·보드를 보면서 같은 화면에서 문서를 읽습니다.

탭

탭 줄 위쪽 ＋ 또는 ⌘T 로 탭을 더 엽니다. ⌘W 는 보고 있는 탭을 닫습니다(마지막 한 장은 닫히지 않고 비워집니다 — 탭이 하나도 없는 브라우저는 갈 곳이 없습니다). 페이지 안의 링크가 새 창을 요청하면 그것도 새 탭으로 열립니다 — 「Google 로 로그인」 같은 로그인 팝업도 새 탭으로 열리고, 로그인이 끝나 팝업이 스스로 닫히면 그 팝업을 연 탭으로 돌아갑니다(팝업 로그인). 링크가 연 새 탭에서 더 돌아갈 페이지가 없을 때 뒤로(← · ⌘←)를 누르면 그 탭을 닫고 연 탭으로 돌아갑니다. 바톤 창을 여럿 띄웠다면 탭 줄은 창마다 따로입니다(앱 메뉴 막대 · 트레이).

⌃Tab · ⌃⇧Tab 으로 다음 · 이전 탭으로 넘어갑니다(크롬과 같은 키). 양끝에서 감싸 돌고, AI 가 연 탭도 같은 줄에서 차례로 옵니다 — 보이는 순서와 키가 넘기는 순서가 같습니다. 페이지 안을 클릭한 뒤에도 그대로 듣습니다.

⌘← · ⌘→ 로 뒤로 · 앞으로 갑니다(크롬과 같은 키). 페이지를 눌러 손이 페이지 안에 있어도 됩니다. 주소창 · 찾기 막대 · 페이지 안의 입력칸에 손이 있으면 그 키는 캐럿 이동이 먼저입니다(macOS 규약) — 그때는 툴바의 ← → 를 쓰세요. 앱의 되짚기 ⌘⌥← / ⌘⌥→ 는 페이지 안에서도 그대로 다녀온 화면으로 갑니다.

페이지가 넘어가도 쓰던 손은 그대로입니다 — 2분할에서 옆 칸 브라우저의 페이지가 바뀌거나 AI 가 탭을 움직여도, 대화 입력창에 쓰던 손은 페이지로 끌려가지 않습니다. 페이지를 눌러 들어간 뒤의 이동은 페이지에 손이 남습니다.

＋ 로 연 빈 탭은 주소창에 손이 갑니다 — 바로 치면 됩니다. 링크로 열린 탭은 그 페이지를 볼 것이므로 손을 가져가지 않습니다.

주소창

• 치다 만 주소는 남습니다 — 다른 패널이나 다른 프로그램에 갔다 돌아와도 쓰던 글이 그대로입니다. 다만 탭을 옮기면 그 탭의 주소를 보입니다(치던 글은 그 탭의 것이니까요).
• 누르면 전체가 선택됩니다 — 그대로 ⌘C 하면 주소가 통째로 복사되고, 치면 통째로 갈립니다. 한 글자만 고치려면 한 번 더 누르면 캐럿이 그 자리에 섭니다(크롬과 같습니다).
• 갔던 주소와 즐겨찾기가 제안으로 뜹니다. 손이 오면 바로 보이고, 치면 좁혀집니다 — 주소뿐 아니라 제목으로도 찾습니다(주소는 기억 못 해도 「그 PR」은 기억하니까요). 순서는 즐겨찾기가 먼저, 그다음 최근에 간 순입니다 — 즐겨찾기는 일부러 모아 둔 자리라 지나간 자취보다 위에 섭니다. 같은 주소가 양쪽에 있으면 즐겨찾기에 붙여 둔 이름으로 보입니다. ↓ ↑ 로 고르면 주소창이 그 줄로 바뀌고, ↵ 로 갑니다. Esc 는 목록만 닫습니다(한 번 더 누르면 주소창을 빠져나갑니다).
• 치는 동안 나머지가 채워집니다. git 까지만 쳐도 github.com/… 으로 차고 더 친 부분만 남긴 채 선택되어 있어, 그대로 ↵ 를 치면 그리로 갑니다. 계속 치면 그 위에 덮여 쓰이고, 지우는 중에는 채우지 않습니다.
• 주소가 아니면 구글에서 찾습니다. vitest mock reset 처럼 치고 ↵ 를 누르면 보던 그 자리에 구글 검색 결과가 뜹니다(새 창이 아닙니다). site:example.com 배포 같은 검색 연산자도 그대로 넘어갑니다. 주소인지 찾을 말인지는 주소 쪽으로 기울여 가릅니다 — build-01:8080 · wiki.내부.kr 처럼 조금이라도 주소 꼴이면 주소로 보고 갑니다(사내 주소가 구글에 찍히는 것이 더 나쁜 쪽이라서요). 3.14 처럼 숫자로 끝나는 점 표기는 찾을 말입니다.

페이지가 열리지 않을 때