일은 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

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

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

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

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

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

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

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

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

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

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

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

화면 구성 한눈에#

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

사이드 패널 숨기기#

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

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

1

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

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

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

보드 화면 구성#

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 가 선택지 카드 없이 글로만 묻고 멈췄으면 작업 목록 과 같은 답 대기 딱지가 새 결과 바로 앞에 섭니다 — 문구·색은 작업 목록과 같고, 그 세션에 답을 보내면 함께 빠집니다. 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 가 선 자리)으로 손을 옮깁니다. 레포 노드를 고르면(클릭 · 키보드 포커스) ⌘P 는 곧바로 그 레포를 대상으로 삼습니다 — 다만 상세 패널의 선택(worktree · 세션)은 바뀌지 않습니다. 그룹 안의 worktree · 세션을 고르면 그 worktree 의 레포가 그대로 대상이 됩니다 — 그룹은 트리가 보여 주는 자리만 바꿀 뿐입니다.

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

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

기획 프로젝트 — 초안부터 구체안까지#

기획 타입 프로젝트의 상세에는 기획 칩이 섭니다. 여섯 단계가 총론 → 경계 → 각론 순서로 서고, 다 쓴 뒤 인계 로 개발 프로젝트에 넘깁니다.

1. 단계 행의 쓰기 를 누르면 그 자리에서 글을 씁니다(마크다운). 저장하면 초안 이 됩니다.
2. 정해졌으면 정했음 — 진행률(3/6 · 50%)이 오릅니다. 고칠 것이 생기면 되돌리기 로 초안으로 돌립니다.
3. 글을 비우면 상태가 없음 으로 돌아갑니다 — 빈 글에 「초안」 딱지가 붙으면 진행률이 거짓이 됩니다.
4. 인계 — 여섯 단계를 한 글로 말아 개발 프로젝트에 넘깁니다. 그 레포에 자리(worktree)를 만들고 세션을 열어 그 글을 첫 지시로 줍니다. 다 쓰지 않아도 넘길 수 있습니다 — 안 쓴 단계는 글에 「(아직 쓰지 않았습니다)」 로 남고, 받는 세션은 짐작으로 메우지 않고 먼저 묻습니다.

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

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

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

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. 이름 변경 은 행에서 바로(Enter), 그룹 편집 은 창에서.
11. 그룹 삭제 는 묶음만 풀고 안에 있던 것은 제자리로 돌려보냅니다: 프로젝트는 워크스페이스 아래로, 문서·링크는 워크스페이스 자리로 옮겨져 거기서 계속 열립니다(사라지지 않습니다). 그룹 세션은 닫힙니다 — 돌던 프로세스가 내려가고, 대화는 기록 › 닫힌 세션에 그룹 이름과 함께 남아 되살릴 수 있습니다.

worktree 만들기#

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

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

작업 목록(세션 카드)#

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

• 탭 주의 는 내가 손을 대야 하는 카드만 모읍니다 — 승인 필요 · 응답 없음 · 강제 멈춤됨 · 답 대기 · 아직 안 본 새 결과 · 쓰다 만 작성 중.
• 주의 와 실행 중 탭에는 그 칸에 몇 개가 있는지 숫자 가 함께 붙습니다. 0이면 숫자가 서지 않습니다. 기본 포함 을 꺼 둬도 그 세션들까지 세므로, 가려 둔 줄기 세션이 승인을 기다리는 것도 숫자로 보입니다.
• 기본 포함 을 켜면 base worktree(main 등)의 세션도 보입니다. 숫자는 서 있는데 목록이 비었다면 그 세션이 가려 둔 base 에 있는 것이라, 빈 자리가 「기본 포함」을 켜면 보입니다 라고 알려 줍니다.
• 목록은 어떤 세션도 빠뜨리지 않습니다 — worktree 세션이 먼저 서고, 그 아래로 그룹 세션(그룹 안 worktree 를 아우르는 자리) · 워크스페이스 세션 · 분류 안 됨 묶음이 차례로 섭니다.
• 선택 으로 여러 카드를 골라 한 번에 닫거나(정리), 고른 세션 전부에 같은 요청을 한 번에 넣습니다(요청 보내기 — 다른 세션에 요청 보내기).
• 목록은 열려 있는 세션 전부입니다 — 위 트리에서 행을 옮기거나 눌러도 목록은 바뀌지 않습니다.
• 세션 탭 · ⌘K · 알림 · 트리에서 세션을 고르면 목록이 그 카드가 보이는 자리로 스크롤됩니다. 이미 보이면 움직이지 않고, 키보드 포커스는 쓰던 자리에 그대로 둡니다.
• 한 레포만 보려면 ⌘K 에서 프로젝트를 고릅니다. 목록 머리에 그 레포 칩이 서고, 칩 옆 ✕ 로 풉니다.
• 작성 중 딱지 — 입력창에 아직 보내지 않은 글이 남아 있는 세션에 붙습니다(공백만 있으면 붙지 않습니다). 보내거나 지워서 칸이 비면 딱지는 곧바로 사라집니다. 다른 화면에 다녀와도 초안은 남아 있습니다.
• 새 결과 딱지 — 아직 보지 않은 세션 결과가 있으면 붙습니다. 그 세션을 열어 결과를 보면 사라집니다.
• 강제 멈춤됨 딱지 — 세션이 내 뜻과 무관하게 멈췄을 때 붙습니다: 응답 도중 앱이 꺼짐 · API 오류(사용량 한도 · 인증 · 서버 과부하) · 인터넷 끊김 · 30분 넘게 소식 없음 · 세션 엔진이 도중에 멈춤. 딱지에 마우스를 올리면 사유와 시각이 보입니다. 내가 ⌃C 로 끊었거나, 정상으로 끝났거나, 내 답(승인 · 질문)을 기다리는 세션에는 붙지 않습니다.
• 승인 필요 세션은 카드 셋째 줄의 승인 필요 표시(주황색)로 알 수 있어 따로 딱지를 더하지 않았습니다. 도구 승인과 모델이 내민 질문 카드가 모두 여기 듭니다.
• 답 대기 딱지 — Claude 가 선택지 카드 없이 글로만 묻고 멈춘 세션에 붙습니다(예: 「고쳐도 될까요?」로 답이 끝남). 상태는 대기 그대로지만 나를 기다리는 세션이라 주의 탭에 함께 섭니다. 상단바 답을 기다리는 세션 목록의 「답을 기다리는 대화」와 같은 세션입니다.
  • 그 세션에 한 번 답을 보내면 딱지가 곧바로 빠집니다 — Claude 의 답이 끝날 때까지 기다리지 않습니다. 다른 기기(원격 제어)에서 보낸 답도 같습니다.
  • 세션을 열어 읽기만 해서는 빠지지 않습니다. 질문이 아니었으면 상단바 목록의 숨기기 로도 뺄 수 있습니다.
  • 워크플로우가 그 세션에 넣은 말은 내 답으로 치지 않습니다 — 딱지가 남습니다.
  • Claude 가 다음 답에서 또 글로 물으면 새 질문이라 딱지가 다시 붙습니다.

카드가 서는 순서

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

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

1

강제 멈춤된 세션 처리하기

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

1

1

이름 고치기

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

키보드와 행 메뉴

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

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

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

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

1

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

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

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

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

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

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

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

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

신규 프로젝트 추가#

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

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

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 에서는 세 갈래 모두 꺼져 있습니다.
• 새 세션 탭의 자리 — 지금 선택된 탭 바로 뒤에 섭니다(⌘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. 세션이 고르라고 물으면 답을 기다립니다 카드가 뜹니다. 질문마다 선택지를 고르고(여러 개 고르는 질문은 체크박스), 맞는 것이 없으면 기타 칸에 직접 씁니다. 모든 질문에 답하면 답 보내기 — 세션이 그 답을 받아 이어갑니다. 넘기려면 답하지 않기.

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·변경 요약)을 보여 줍니다.

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

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

1

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

다른 세션의 대화를 다섯 항목(무엇을 하려던 세션인가 · 확정된 사실 · 결정과 이유 · 만진 파일·명령 · 미해결) 한 장으로 줄여 입력창에 넣습니다. 전송은 하지 않습니다. 앱에서 연 세션뿐 아니라 앱 밖에서 연 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 에 열려 있는 세션이 대상으로 채워집니다(그룹 세션 자신은 빠집니다).

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

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

켜는 곳 · 끄는 곳

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

문서#

과업에 붙은 설계 문서·링크입니다. 워크플로우와 세션이 이 문서를 컨텍스트로 씁니다. 여러 레포에 걸친 그룹에도 같은 방식으로 붙일 수 있습니다 — 그 경우 문서는 구성원 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

성과#

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

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 를 돌립니다.

배포 개발자#

과업에 연결된 배포 티켓(Jira)의 상태입니다. 배포 기능이 켜져 있을 때 보입니다.

1. 정보 칩 배포 …(없으면 배포 없음).
2. 배포 티켓 키를 넣어 연결하거나, 배포 티켓 워크플로우로 만들어 연결합니다.
3. 배포 티켓 워크플로우가 만든 티켓은 이 배포 칸에 수동 등록으로 붙습니다 — 과업의 티켓(요약의 티켓)은 그대로이고, 자동 탐색이 덮지 않습니다.

레포별 ArgoCD 배포 현황은 배포 현황에서 봅니다.

구독 한도 · 새로고침#

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

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

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

답을 기다리는 세션#

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

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

⌘K 명령 팔레트#

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

1. ⌘K 또는 상단바 명령.
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건)입니다. 앱 메뉴 보기 에도 있습니다.

내 티켓#

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

티켓 ID 복사 · 링크 복사#

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

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

EMD/AMD 추정 · 관리 필드#

EMD(Estimated MD) · AMD(Actual MD)는 조직마다 다른 Jira 커스텀 필드입니다. 그래서 앱은 이 필드를 있을 때만 다룹니다.

값을 세션에 추정시키려면 워크플로우 목록에서 돌립니다(전용 버튼은 없습니다):

자동 사냥#

앱이 네 시간마다 최근 7일 안에 들어온 내 task 를 훑어, 할 수 있는 것 을 골라 둡니다. 코드 작업은 승인해야 자리가 열리고, 답변으로 끝나는 일은 승인해야 댓글이 나갑니다.

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

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

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

이어서 하기#

내가 이미 손대던 티켓(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

실행 기록 거르기

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

123

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

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

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

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

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

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

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

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

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

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

12

워크플로우 실행하기#

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

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

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

1

시작 알림 · 실행으로 가기

어디서 시작하든 — 입력창의 워크플로우 칩(⌘⌥1~⌘⌥9) · ⌘K · 실행 목록의 실행 · 다시 실행 · 프로젝트 메뉴 · Jira 의 다음 걸음 · 환경 테스트 · 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 에서 위임」 으로 레포마다 한 줄씩 섭니다.

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)가 돕니다. 테스트 를 비우면 그 환경의 테스트 전부입니다.

Wiki 모두#

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

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

기록 모두#

닫거나 삭제된 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 는 보고 있는 탭을 닫습니다(마지막 한 장은 닫히지 않고 비워집니다 — 탭이 하나도 없는 브라우저는 갈 곳이 없습니다). 페이지 안의 링크가 새 창을 요청하면 그것도 새 탭으로 열립니다.

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

⌘← · ⌘→ 로 뒤로 · 앞으로 갑니다(크롬과 같은 키). 주소창이나 찾기 막대에 손이 있으면 그 키는 캐럿 이동이 먼저입니다(macOS 규약) — 그때는 툴바의 ← → 를 쓰세요.

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

주소창

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

페이지가 열리지 않을 때

주소에 아무것도 없거나(404) 서버가 막았거나(403) 접속 자체가 안 되면, 그 자리에 무슨 일인지가 섭니다 — 제목 · 설명 · 그 주소 · 상태 코드, 그리고 다시 시도 와 브라우저로 열기. 팝업 · 문서 패널 · AI 가 연 탭도 같습니다.

• 404 · 410 → 찾을 수 없는 페이지입니다. 주소가 바뀌었거나 지워진 자리입니다.
• 401 · 403 → 볼 권한이 없습니다. 로그인이 필요하거나(그 자리에서 로그인하면 이어집니다) 이 계정에 권한이 없습니다.
• 5xx → 서버가 오류를 냈습니다. 주소를 고칠 일이 아니라 잠시 뒤 다시 하는 일입니다.
• 아예 못 읽은 경우 → 페이지를 열 수 없습니다. 호스트를 못 찾았는지(사내망 · VPN) · 서버가 꺼져 있는지 · 인증서 문제인지를 한 줄로 적고, 원문(ERR_NAME_NOT_RESOLVED)은 괄호에 남깁니다 — 그대로 복사해 물어볼 수 있게.

1Password 로 로그인 채우기

앱 안 브라우저의 로그인 칸을 1Password 에서 채웁니다. 비밀번호는 앱에 저장되지 않습니다 — 채우는 순간에만 받아 쓰고, 금고를 여는 일은 1Password 가 합니다(Touch ID).

1. 연동 › 전체 맨 아래 1Password 로 로그인 채우기. 먼저 1Password 앱 › 설정 › 개발자 에 “Connect with 1Password CLI” 가 있고 켜지는지 확인합니다 — 이것부터 묻는 이유는 그 토글이 앱 밖의 것이라 baton 이 대신 켤 수 없기 때문입니다. 못 켜면 아무것도 설치하지 않고 끝납니다.
2. 켰으면 설치 를 누릅니다. 1Password CLI(op)를 앱이 공식 배포본에서 직접 받아 깝니다 — 받은 것이 1Password 서명인지 확인한 뒤 자리에 두고, 실제로 실행해 보고 끝냅니다.
3. 연결됨 과 계정이 보이면 끝입니다. 깔기만 되고 연동이 아직 꺼져 있으면 「설치했습니다 — 이제 1Password 앱에서 CLI 연동을 켜세요」 라고 적힙니다.
4. 브라우저에서 로그인 페이지를 열면 주소창 오른쪽에 열쇠 버튼이 섭니다. 누르면 그 사이트에 저장된 항목이 뜨고, 고르면 id·비밀번호가 채워집니다(계정이 여럿이면 목록에서 고릅니다).

팝업이 떠 있는 동안

앱의 팝업(확인 창 · 설정 · ⌘K 팔레트 · 메뉴)은 웹 페이지 위에 그려지지 못합니다 — 페이지는 앱이 그리는 그림이 아니라 창에 얹힌 별도의 웹 화면이라, 팝업이 그 뒤로 숨어 버립니다. 그래서 겹치는 동안에는 페이지가 잠깐 비켜섭니다. 비켜서도 읽던 자리는 남습니다:

• 옆 칸의 팝업은 비키게 하지 않습니다. 화면을 나눠 놓고 한쪽에서 창을 열면 반대쪽 페이지는 그대로입니다(움직이고 누를 수도 있습니다) — 팝업에 넣을 값을 옆 칸에서 찾는 것이 분할의 쓰임이기 때문입니다. 칸이 좁으면(640px 미만) 팝업이 창 전체를 덮으므로 그때는 아래처럼 됩니다.
• 겹칠 때는 마지막 모습이 그 자리에 남습니다. 비키기 직전의 화면을 한 장 찍어 깔아 두므로 팝업 밑으로 읽던 글이 그대로 보입니다. 그림이라 누르거나 움직일 수는 없고, 팝업을 닫으면 바로 원래 페이지로 돌아옵니다(처음부터 다시 읽지 않습니다 — 스크롤도 그대로입니다).

그림을 찍지 못한 자리에서는 「팝업을 닫으면 페이지가 돌아옵니다」 라고 적습니다.

페이지에서 찾기

⌘F 로 보고 있는 페이지 안의 글을 찾습니다(크롬의 그 자리). 주소줄 아래에 찾기 막대가 서고, 치는 대로 첫 번째로 가 섭니다. ↵ 다음 · ⇧↵ 이전 · Esc 닫기이고, 페이지 안을 클릭한 뒤에도 같은 키가 그대로 듣습니다(⌘G·⇧⌘G 도 앞뒤로 넘깁니다). 막대 가운데 숫자는 몇 번째 / 모두 몇 개입니다. AI 가 연 탭에서도 같습니다.

페이지 확대·축소

페이지 안을 한 번 누른 뒤 ⌘+ / ⌘− 를 누르면 그 웹페이지가 커지고 작아집니다(50%~200% · 크롬과 같은 눈금). ⌘0 은 앱 배율과 같게 되돌립니다. 고른 값은 저장되어 다음 실행에도 남습니다.

링크를 여는 네 갈래

앱 어디에 있는 링크든 여는 법은 같습니다 — 브라우저(시스템 브라우저) · 앱에서(앱 안 팝업) · 옆에서(오른쪽 칸 브라우저) · 주소 복사.

• 앱에서 — 앱 창 가운데에 80% 크기 팝업이 뜹니다. Esc 나 바깥을 눌러 닫습니다. 잠깐 확인하고 닫을 때.
• 옆에서 — 화면이 좌우로 나뉘고 오른쪽 칸 브라우저의 새 탭에서 열립니다. 팝업은 위에 겹쳐 그 아래를 볼 수 없으니, 보면서 일할 때는 이쪽입니다(문서를 띄워 놓고 반대쪽에서 고치기). 분할이 꺼져 있었으면 함께 켜집니다 — 화면 분할.

팝업·브라우저 탭은 로그인을 함께 씁니다 — 한 곳에서 로그인하면 나머지도 그 세션으로 열립니다.

AI 가 연 탭

세션에게 「이 페이지 확인해 줘」라고 하면 에이전트가 웹을 직접 열어 보고 누릅니다. 그 페이지는 같은 탭 줄에 서고, 왼쪽에 색 띠와 에이전트 표시, 그리고 어느 세션이 열었는지가 함께 붙습니다 — 내가 연 탭과 한눈에 갈립니다.

1. 탭을 누르면 그 페이지가 무대에 서고, 직접 눌러 볼 수 있습니다. 무엇을 누르고 무엇을 입력하는지 그대로 보입니다.
2. 탭 위에 마우스를 올리면 지금 하는 동작(browser_read 같은)이 뜹니다.
3. 한 세션이 탭을 여럿 열 수 있습니다 — 두 페이지를 오가며 비교할 때 그렇게 씁니다.

모니터링 개발자#

Grafana 대시보드 링크를 등록하면 그 화면을 앱 안에서 봅니다.

1. + 대시보드 에 Grafana 대시보드 주소를 붙여 넣습니다.
2. 왼쪽에서 대시보드·패널을 고르고, 오른쪽 위에서 범위 · 자동 새로고침 주기를 정합니다.
3. Grafana 버튼은 브라우저로 엽니다.

진단 모두#

셋업 점검 목록(시작 시 · 5분마다 재검사)과 MCP 서버 상태를 봅니다.

1. 전체 재검사 로 지금 다시 점검합니다. 행마다 고치기 버튼이 있습니다.
2. MCP 서버가 인증 필요 · 응답 없음 이면 재인증 — 브라우저가 열리고 승인은 직접 합니다.

버전

화면 맨 아래에 지금 앱이 무엇으로 도는지가 한 줄로 적힙니다. 이 앱에는 claude 가 둘 있습니다 — 세션은 앱에 번들로 들어 있는 SDK 가 품은 claude 로 돌고, MCP 등록 · 로그인은 PATH 의 claude 명령으로 돕니다. 둘은 서로 다른 프로그램이라 버전이 다를 수 있습니다.

설정 메뉴#

레일 맨 아래 설정 을 누르면 뜹니다.

잠자기 방지 — 자리를 비워도 세션이 끊기지 않게#

세션에 긴 일을 시키고 자리를 옮기는 동안 컴퓨터가 잠들면 그 일이 끊깁니다. 설정 › AI 실행 › 잠자기 방지 를 켜면 앱이 컴퓨터를 깨어 있게 붙듭니다.

켜져 있으면 창 오른쪽 위에 커피 아이콘이 섭니다 — 켜졌을 때만 보이므로 그 표시가 있으면 붙들고 있는 것입니다. 그 아이콘을 누르면 바로 끕니다. 창을 내려놓았으면 트레이 아이콘에 마우스를 올려 확인합니다(Baton · 잠자기 방지 켜짐).

설정은 다음 실행에도 남습니다 — 켜 둔 채로 앱을 껐다 켜면 다시 붙듭니다. 끄면 OS 의 전원 설정대로 돌아갑니다.

Finder 에서 보기 (윈도우: 탐색기로 보기)#

그 폴더를 OS 의 파일 관리자에서 엽니다 — macOS 는 Finder, 윈도우는 탐색기입니다. 터미널 열기 가 있는 자리에는 전부 있습니다(조건이 같습니다 — 실재하는 폴더).

• 보드 트리 행 ⋯ — 워크스페이스 · 프로젝트 · worktree · 세션. 여는 폴더는 터미널 열기와 같은 폴더입니다(워크스페이스는 자기 폴더, 프로젝트는 그 레포의 줄기, worktree · 세션은 그 worktree).
• 상세 머리의 경로 옆 — 터미널 아이콘 바로 옆의 폴더 아이콘.

그 폴더가 열립니다 — 창에 뜨는 것은 폴더 안입니다(상위 폴더에서 골라진 채 뜨지 않습니다). 폴더가 디스크에서 사라졌으면 항목이 잠기고, 눌러도 아무 창이 뜨지 않는 경우에는 사유를 알려 줍니다.

메모 첨부의 Finder 에서 보기는 다릅니다 — 거기가 가리키는 것은 폴더가 아니라 파일 하나라서, 그 파일이 담긴 폴더가 열리고 파일이 골라진 채 뜹니다.

연동 — 무엇이 켜지고, 어디서 끄나#

켜는 것은 연동에서, 끄는 것은 프로젝트에서. 앱 전체를 켜고 끄는 스위치는 없습니다 — 연동 화면에서 그 도구의 계정을 만들면 켜지고, 특정 프로젝트에서만 안 쓰고 싶으면 그 프로젝트 › 연동에서 「이 프로젝트에서는 사용 안 함」을 고릅니다.

레일의 화면(Jira 등)은 계정이 하나라도 있으면 늘 보입니다. 프로젝트에서 끈 것은 그 프로젝트의 자리에서만 빠집니다 — 그 프로젝트의 티켓 · 칩 · 워크플로우가 사라지고, 화면 자체는 남습니다.

GitHub 은 「연결」이 켭니다

GitHub 는 vcs 계정이 하나라도 있을 때만 켜집니다(gh 에 로그인돼 있으면 앱이 첫 실행에 그 계정을 만듭니다). 계정이 없으면 PR · 배포 · 릴리스 노트가 꺼지고 셋업의 GitHub 단계도 목록에서 빠집니다 — gh 를 깔지 않아도 첫 실행이 끝납니다.

쓰고 싶지 않은 자리는 그 프로젝트에서 끕니다(위 표의 사용 안 함). 전역으로 끄는 스위치는 두지 않습니다 — 「연동했는데 여기서는 아니오」라는 상태가 생기면 어느 쪽이 참인지 알 수 없습니다.

조직 값 — 전이 이름 · 자동 사냥 대상 · 주소 · 멘션#

Jira 는 조직마다 상태 이름과 이슈타입이 다릅니다(In Review · 리뷰중 · Code Review). 앱은 연동이 처음 통과할 때 한 번 실측해서 채우고, 못 찾으면 비워 둡니다. 고치는 자리는 셋업 › 기본값 › 설정 입니다.

슬랙 쪽 조직 값은 셋업 › 슬랙 › 토큰 입력 에 있습니다 — 리뷰 채널 id 와 리뷰 멘션(쉼표로 구분한 슬랙 user id). 멘션을 비우면 리뷰 요청 글이 아무도 태그하지 않습니다. 토큰 칸을 비워 두면 지금 토큰을 그대로 씁니다.

배포 티켓의 배포 티어·승인 매니저 기본값은 app.config.json 의 deploy.tiers·deploy.defaultTier·deploy.manager 가 정합니다. 매니저를 비우면 시작 폼에서 사람이 적습니다.

저장하면 ~/.baton/app.config.json 에 쓰이고 그 자리에서 바로 적용됩니다(앱을 다시 켜지 않아도 됩니다). Jira 주소와 인증 방식을 바꿀 때만 앱을 다시 켜야 합니다.

워크플로우는 의존을 스스로 말합니다. 각 워크플로우 정의에 필요한 연동(Jira · 슬랙 · GitHub · 배포 · 인증이 필요한 MCP)이 적혀 있어, 그중 하나라도 꺼지면 그 워크플로우는 목록 · 팔레트 · 칩 · 버튼 · 예약에서 함께 사라지고 시작도 되지 않습니다. 무엇이 몇 개 숨었는지는 실행 목록 위 안내 한 줄이 말해 줍니다.

OS 알림#

세션이 답을 마쳤거나 승인을 기다릴 때, 백그라운드로 보낸 워크플로우 실행이 끝났을 때, 배포 요청을 보냈을 때 — 앱은 오른쪽 아래 토스트로 알립니다. 앱 창을 보고 있지 않으면(다른 앱에 가 있거나 ⌘Q 로 창을 치웠을 때) 같은 내용을 macOS 알림 센터로도 보냅니다.

• 누르면 그 자리로 — 세션 알림은 그 세션 탭으로, 실행 알림은 실행 화면의 그 실행으로 갑니다. 창을 닫아 두었으면 창을 다시 띄웁니다.
• 창을 보고 있으면 뜨지 않습니다 — 토스트와 겹치기만 하기 때문입니다. 보고 있던 세션이 끝난 것은 토스트도 뜨지 않습니다.
• 세션 알림은 창을 닫아도 옵니다. 실행 · 배포 알림은 앱 창이 떠 있을 때(뒤에 있거나 최소화돼 있어도) 옵니다.
• 설정 › OS 알림 에서 세션 답변 · 승인 대기 · 워크플로우 실행 결과 · 배포 요청 결과 를 따로 끕니다. 배포 요청 결과는 배포 기능이 켜져 있을 때만 보입니다.

메모 비밀번호 변경#

1. 설정 › 메모 비밀번호 변경.
2. 현재 비밀번호와 새 비밀번호(두 번)를 넣습니다. 바꾸면 메모 화면이 다시 잠깁니다.

다른 기기로 옮기기#

쓰던 baton 을 새 기기에서 그대로 이어 받습니다. 설정 › 내보내기 · 가져오기 한 창에 두 문이 있습니다.

내보내기 (지금 쓰던 기기에서)

1. 설정 › 내보내기 · 가져오기 → 내보내기 탭. 무엇이 얼마나 담기는지 미리 보입니다.
2. 지난 대화까지 옮기려면 대화 기록 · 보관 폴더도 함께 담기 를 켭니다. 기본은 꺼져 있습니다 — 수백 MB 가 될 수 있습니다. 켜면 사용 토큰 되살리기 의 재료도 함께 갑니다.
3. 꾸러미 만들기 → 저장할 자리를 고릅니다. baton-2026-09-20.zip 파일 하나가 만들어집니다.

가져오기 (새 기기에서) — 세 걸음

1. 읽기 · 검사 — 꾸러미를 고르면 만든 앱 · 만든 때 · 담긴 수와 지금 이 기기의 수를 나란히 보여 줍니다. 이 걸음은 아무것도 쓰지 않습니다. 꾸러미가 이 앱보다 새 판이면 여기서 막습니다 — 앱을 먼저 업데이트하세요.
2. 경로 다시 짚기 — 기기가 바뀌면 절대경로가 전부 거짓이 됩니다. 워크스페이스마다 「이 기기에서는 어디인가」를 폴더로 짚습니다. 같은 자리가 실재하면 미리 채워 둡니다. 없으면 건너뛰기 — 그 워크스페이스는 옛 경로 그대로 남고 지워지지 않습니다.
3. 적용 — 사라지는 것 · 들어오는 것 · 백업 자리를 확인하고 이 기기를 덮어쓴다 를 누릅니다. 끝나면 앱을 다시 시작 하세요.

개인 설정 파일 · 데이터 위치#

• ~/.baton/app.config.json — 번들 설정(조직 Jira 주소·프로젝트 등) 위에 겹쳐지는 내 설정. 있는 키만 덮습니다.
• ~/.baton/secrets.json — 토큰(권한 0600). 셋업 화면이 채우므로 손으로 만들 일은 거의 없습니다.
• 앱 DB · 사용자 워크플로우·에이전트 · 로그도 ~/.baton 아래에 있습니다. 로그는 앱 메뉴 도움말 › 로그 폴더 열기.

자세한 키와 백업·삭제는 설치 런북 7·8절을 보세요.

서브에이전트 동시 개수 한도#

세션이 일을 나눠 맡기면(서브에이전트) 그 하나하나가 도구를 부르고, 앱은 그만큼 기록하고 그립니다. 한꺼번에 너무 많이 띄우면 앱이 느려지고 토큰도 그만큼 씁니다.

그래서 한 세션이 동시에 띄울 수 있는 수는 5개입니다. 넘는 요청은 그 자리에서 미룹니다 — 세션에게 「지금 도는 것이 끝난 뒤 다시 부르라」고 알려 주므로 일이 사라지지는 않습니다. 미룬 사실은 대화에 한 줄로 남습니다.

대화 기록 보존 · 앱이 켜질 때 하는 정리#

앱의 모든 기록은 ~/.baton/baton.db 파일 하나에 들어 있습니다. 저장은 바뀐 부분만 쓰므로 파일이 커져도 저장이 느려지지 않습니다. 그래도 파일을 한 번에 다루는 일(백업 · 꾸러미로 내보내기 · 다른 기기로 옮기기)이 있어 무한정 자라게 두지는 않습니다.

앱은 켜질 때 한 번 다음을 정리합니다. 쓰는 동안에는 하지 않습니다(정리하느라 멈추면 고치려던 문제를 다시 만듭니다).

• 세션마다 최근 대화 2,000줄만 남기고 그보다 오래된 줄을 걷습니다. 화면이 한 번에 읽는 양은 500줄이라 보이는 것은 달라지지 않습니다. 수를 바꾸려면 ~/.baton/app.config.json 의 app.messageKeepPerSession 에 적습니다.
• 갈피(책갈피)를 찍어 둔 줄은 남깁니다 — 상한보다 오래된 줄이어도 그렇습니다. 사람이 손으로 표시해 둔 것을 앱이 말없이 지우지 않습니다.
• 끝난 워크플로우 실행이 들고 있던 중간 작업 값을 비웁니다(화면에 나오지 않는 값입니다). 실패한 실행은 그대로 둡니다 — 「이어서 돌리기」가 그 값을 씁니다.
• 걷어낸 자리를 실제로 반납해 파일을 줄입니다.

말로 워크플로우 돌리기 — 실행 카드#

「리뷰 반영 돌려줘」처럼 워크플로우 를 말로 시키면, 세션은 값을 채워 워크플로우 실행 카드를 세우고 거기서 멈춥니다(상단바 답을 기다리는 세션 에도 돌릴지 정할 워크플로우 로 오릅니다). 내가 누르기 전에는 한 줄도 돌지 않습니다.

12

• 기다리지 않습니다. 실행을 시작하면 세션은 실행 번호만 받고 그 자리에서 답합니다 — 결과는 실행 기록 과 앱의 알림이 말합니다. 「아까 그거 어떻게 됐어?」라고 물으면 세션이 지금 단계를 읽어 줍니다.
• 한 번에 하나만 돌립니다. 여러 개가 필요하면 하나씩 시키세요.
• 같은 자리에서 이미 돌고 있는 워크플로우는 카드가 서지 않고 「이미 돌고 있습니다」로 답합니다 — 겹쳐 돌리면 같은 폴더에서 두 실행이 부딪힙니다.
• 필수 값을 채울 근거가 없으면 세션은 값을 지어내지 않고 무엇을 채워야 하는지 먼저 묻습니다.
• 처리된 카드는 실행함(실행 번호) 또는 실행 안 함(사유) 으로 접혀 남습니다.

대화의 링크 — 보고 고른다#

대화 위쪽 가장 왼쪽 아이콘(🔗)을 누르면 이 세션의 대화에 나온 링크가 오른쪽 목록으로 섭니다. 웹 주소와 로컬 파일 경로를 함께 모읍니다 — 세션이 쓴 HTML 보고서, 첨부한 PDF, 내가 붙여 넣은 대시보드 주소가 한자리에 있습니다.

12

• 내가 준 것과 대화에서 나온 것으로 묶입니다. 같은 주소가 여러 번 나왔으면 한 줄이고 N회 가 붙습니다.
• 이미 등록한 것은 체크(문서) · 채운 별(즐겨찾기)로 서고 다시 눌리지 않습니다.
• 못 담는 줄은 버튼이 꺼지고 왜 가 적힙니다 — 붙일 과업이 없는 세션(워크스페이스 · 그룹), 문서로 담을 수 없는 종류, 50MB 가 넘는 파일, 사라진 파일.
• 문서로 담는 것은 HTML · Markdown · PDF 입니다. 그 밖의 파일(PNG · CSV · 텍스트 등)도 즐겨찾기로는 담깁니다.
• MCP 서버 · 로그인 · API · localhost 같은 도구·설정 주소는 기본으로 접혀 있습니다 — 지워진 것이 아니라서 도구·설정 N 을 누르면 섭니다.
• 프로젝트 세션에서는 문서가 그 프로젝트의 기본 워크트리에 붙습니다. 어디에 붙는지는 목록 머리에 미리 적힙니다.

대화의 링크 — 열기 · 즐겨찾기에 담기#

답이나 설명에 적힌 주소를 누르면 그 자리에 작은 물음이 섭니다. 고르기 전에는 아무 일도 일어나지 않습니다.

• 이미 담긴 주소는 묻지 않습니다 — 바로 엽니다. 위 스코프(프로젝트 · 워크스페이스)에 담아 둔 주소도 담긴 것으로 봅니다(같은 주소가 두 번 담기지 않습니다).
• 묻지 않고 바로 열려면 ⌥ 또는 ⌘ 를 누른 채 링크를 클릭합니다.
• 담을 자리가 없는 세션(어디에도 매이지 않은 세션)에서는 묻지 않고 그냥 엽니다.
• 담은 것은 즐겨찾기 와 상세의 링크 n 에서 보입니다. 이름은 링크 글자를 쓰고, 주소만 적힌 링크면 호스트 · 첫 경로 로 줄여 담습니다.

의미 찾기 — 모르는 말을 집어서 묻는다#

글을 드래그해서 집으면 그 끝에 작은 뜻 버튼이 섭니다. 누르면 두세 줄짜리 뜻이 그 자리에 뜹니다 — 영어면 한국어 뜻과 이 글에서 무엇을 가리키는지, 한국어라도 전문용어·줄임말이면 같은 방식입니다. 집은 글 위에서 오른쪽 클릭해도 같은 메뉴(의미 찾기 · 복사)가 섭니다.

1. 모르는 말을 드래그해서 집습니다(두 글자 이상).
2. 끝에 선 뜻 버튼을 누릅니다 — 또는 집은 글 위에서 오른쪽 클릭 → 의미 찾기.
3. 뜻을 확인하는 중… 이 돌다가(보통 6~7초) 답이 그 자리에 앉습니다.

• 대화창만이 아닙니다 — 위키 · 문서 · 티켓 설명 · 워크플로우 결과 · 메모처럼 집을 수 있는 글이면 어디서나 됩니다.
• 답은 짧습니다(세 줄 이내). 읽다가 막힌 자리를 풀어 주는 것이 목적이라, 긴 설명 대신 결론만 옵니다. 모르는 말이면 모르겠습니다 라고 답합니다 — 지어내지 않습니다.
• 앞뒤 글을 함께 봅니다. 그래서 같은 낱말이라도 문맥에 따라 다르게 답합니다 — 사전 뜻만 필요한 것이 아니라 「지금 이 문단에서 무엇을 말하는가」가 답이어야 하기 때문입니다.
• 입력칸은 빠집니다 — 쓰는 중인 칸에서 오른쪽 클릭하면 평소대로 잘라내기 · 붙여넣기 메뉴입니다.
• 창을 닫아도 찾는 일은 끝까지 갑니다. 같은 말을 다시 집으면 기다리지 않고 바로 뜹니다(앱을 끄면 지워집니다 — 어디에도 저장하지 않습니다).
• 링크 글자를 집어서 물으면 링크 메뉴 보다 의미 찾기가 먼저 섭니다. 집은 글이 없으면 평소대로 링크 메뉴입니다.

PRD 초안 쓰기 · 테스트케이스 만들기#

레포가 필요 없는 일은 실행마다 새 작업 폴더(~/.baton/work/runs/<실행 id>)에서 세션이 열리고, 결과는 그 폴더에 파일로 남습니다. PRD 초안 쓰기 는 기획·통합 프로젝트가 있을 때 목록에 서고, 테스트케이스 만들기 는 어느 타입에서나 섭니다.

1. 실행 화면(또는 ⌘K)에서 PRD 초안 쓰기 › 실행.
2. 주제 · 배경·문제(왜 지금 필요한지, 누가 어떤 상황에서 불편한지) · 참고 자료(링크나 붙여 넣은 글 — 고객 개인정보는 넣지 않습니다) · 목표 일정 을 넣고 실행.
3. 세션(prd-writer 역할)이 초안을 쓰면 확인 단계에서 멈춥니다. 실행 상세나 상단바 답 대기 배지 에서 초안을 읽고 고친 뒤 저장 · 다시 쓰기 · 중단 중 하나를 고릅니다.
4. 저장 하면 PRD-<주제>.md 가 실행 폴더에 남고, 실행 상세의 링크로 엽니다.

테스트케이스 만들기 도 같은 흐름입니다 — 기획서 (본문 또는 링크) · 범위·제외 · 형식(마크다운 표 · CSV)을 주면 qa-case-writer 가 정상·경계·예외 케이스 표를 만들고, 확인에서 저장 하면 파일로 남습니다.

내 일하는 방식을 워크플로우로#

1. 실행 화면 + 추가 에 「회의록을 받아 요구사항 표로 정리하고, 내가 확인하면 파일로 남겨 줘」 처럼 적습니다.
2. 초안을 읽고 추가. 레포가 필요 없는 일은 레포 없는 세션(scope: none)으로 만들어집니다.
3. 동료가 만든 워크플로우 파일은 가져오기 로 들입니다.

레일 버튼이 전부 잠겨 있어요#

필수 셋업 항목이 통과하지 않았습니다. baton 준비 화면에서 한 번에 설정 을 누르거나 실패한 행의 버튼을 누르세요. 첫 실행 뒤에 필수 항목이 깨지면 화면을 막지 않고 레일 연동 에 빨간 숫자만 뜹니다.

PR 칩 · Jira 화면 · 배포 버튼이 안 보여요#

그 연동의 계정이 없습니다(또는 그 프로젝트에서 「사용 안 함」으로 두었습니다). 연동 화면에서 확인하세요 — 꺼진 기능은 막히지 않고 사라집니다.

상단바에 「MCP 인증 필요」 가 떠요#

배지를 누르면 진단 으로 갑니다. 해당 서버의 재인증 을 누르고 브라우저에서 승인하세요. 필수 MCP(Atlassian 등)가 없으면 셋업의 한 번에 설정 이 설치까지 합니다.

Jira 티켓이 안 읽혀요 (레일 Jira 에 느낌표)#

기본 브라우저에서 조직 Jira 에 로그인되어 있어야 합니다. 로그인한 뒤 셋업 Jira 행 다시 확인. 조직 주소가 다르면 ~/.baton/app.config.json 에서 덮어쓰세요(개인 설정 파일).

세션이 멈춰 있는 것 같아요#

대부분 사람의 승인·답을 기다리는 중입니다. 상단바 답 대기 배지 를 눌러 보세요. 카드에 응답 없음 이면 세션을 열어 ⌃C 로 응답을 끊고 다시 지시하세요.

세션이 앞의 내용을 잊는 것 같아요#

컨텍스트가 모자랄 수 있습니다. 입력창 위 컨텍스트 n% 남음 이 주의색이면 압축 하거나, 새 세션을 열고 세션 가져오기 로 알아낸 것만 옮기세요.

⌘Q 를 눌렀는데 앱이 안 꺼져요#

의도된 동작입니다. ⌘Q 는 창만 치우고 일은 계속 돌립니다. 창은 ⌘⇧O · Dock · 트레이로 되돌리고, 완전히 끄려면 앱 메뉴나 트레이의 Baton 종료 를 누르세요.

배포 현황에 「로그인 필요」 가 떠요#

그 ArgoCD 서버의 토큰을 못 찾았습니다. 카드의 브라우저로 열기 로 로그인하거나 토큰 넣기 로 secrets.json 에 넣으세요. 메뉴에 배포 현황 자체가 없으면 그 프로젝트가 배포를 쓰지 않는 타입입니다.

오류를 알리고 싶어요 — 로그는 어디에?#

앱 메뉴 도움말 › 로그 폴더 열기 에 app.log 가 있습니다. 비밀 값은 적히지 않습니다.