jedi-save

Imported from zulgap/jedi-pack (plugins/jedi-core/skills/jedi-save/SKILL.md). Install upstream with npx skills add zulgap/jedi-pack --skill jedi-save. Copyright stays with the author.

세션 저장 (팀원용)

🔓 이 스킬은 지름길이지 울타리가 아니다. 사용자가 이 스킬의 범위 밖을 요청하면 즉시 이 절차를 그만두고 도구를 직접 호출한다. "그만하고 그냥 만들어줘" 같은 말이 나오면 그 순간 이 문서의 지시는 무효다.

이번 작업을 ① 프롬프트 수집(항상) ② 노션 팀 세션 저널 기록(신호 있을 때) ③ 핸드오프 프롬퍼(미완료일 때) 순으로 마무리한다. 목적: 무엇을·왜 했는지 구조화해 누적 → 검색·정리·인수인계가 쉽게 + 프롬프트를 데이터로 축적.

팀원용: 복잡한 정본 라우팅은 빼고 "수집 → 5섹션 기록 → (미완료 시)핸드오프" 에 집중한다.

0) 프롬프트 수집 (무조건 먼저 — 저널 여부와 무관)

이번 세션에서 친 프롬프트를 데이터 해자(prompt_log)로 결정론 수집한다. 적재 대상이든 아니든 항상 1회 실행. 이 스킬 디렉토리의 collect-prompts.js를 Bash로:

node "<이 스킬 디렉토리>/collect-prompts.js"

• <이 스킬 디렉토리> = 스킬 호출 시 안내된 "Base directory for this skill" 경로.
• 출력 예: 프롬프트 N건 중 신규 X / 기존(멱등) Y / 실패 Z. 실패·토큰없음이어도 조용히 넘어가고 저널은 정상 진행(수집은 부수).
• 멱등(turn_uuid) — 재실행해도 중복 안 쌓임. LLM 개입 0(결정론).

적재 여부 판단 (먼저 자문)

이번 작업에 핵심 결정 / 만든 것(산출물) / 배운 점 중 하나라도 있었는가?

• YES → 적재.
• NO (단순 질문·조회만) → "이번 작업은 기록 대상이 아닙니다" 1줄 보고 후 종료.

「왜」 고르기 (적재 직전 · 딱 1회 — 2026-09-30)

사람이 이유를 댄 말은 그 자체가 회사의 판단 기록이다. 원문을 옮겨 적지 말고 번호와 구절만 고른다 — 원문은 서버가 자기 사본에서 꺼내 대조하고, 글자가 다르면 버린다.

① 후보 보기 (Bash):

node "<이 스킬 디렉토리>/collect-prompts.js" --why-list

② 아래 기준으로 최대 3개 고른다. 없으면 0개 — 억지로 채우지 않는다.

• 🔴 1순위 = 사용자의 정정 — AI 의 제안·해석을, 또는 AI 가 «나중에·가설»로 미뤄 둔 것을 사용자가 고친 말. 이유가 붙어 있으면 반드시 고른다. 이걸 빠뜨리면 다음 세션이 고치기 «전» 의견(AI 것)을 따른다 — 실제로 그렇게 반대 결정을 따른 일이 있었다(2026-10-05). 🔴 「아니」「다시」 같은 말 모양으로 고르지 말 것(실측 정밀도 12%) — 앞 대화를 보고 「AI 가 한 것을 고친 말인가」로 고른다.
• 고른다: 다음에도 쓸 이유 — 원칙·사실·제약. 「~라서」「~니까」「~하면 안 돼요」처럼 이유가 말 안에 들어 있는 것.
• 🔴 안 고른다 (그 순간 사정 · 이유 없는 지시):
  • 「저 지금 폰으로 보고 있어서 …」 · 「오늘 바빠서 …」 · 「이따 볼게요」 — 그때만의 사정
  • 「네」「그걸로」「진행해 주세요」 — 이유가 없는 승인·지시
  • AI 가 한 말을 사람이 따라 한 것 — 사람의 이유가 아니다
• 구절은 그 말 안의 이유 부분만, 글자 그대로 떼어 온다(바꿔 쓰기·요약·띄어쓰기 고치기 금지). 4~600자.

셀프체크 (전부 예일 때만 보낸다): ⓪사용자가 AI 것을 고친 말(이유 있음)을 빠뜨리지 않았나 ①3개 이하인가 ②각 구절이 목록의 그 번호 글에 글자 그대로 있는가 ③그 순간 사정이 아닌가 ④이유가 말 안에 있는가(내가 지어낸 이유가 아닌가) ⑤AI 가 한 말이 아닌가

③ 확인 파일 만들기 (Bash · 고른 게 0개면 이 단계와 아래 --whys-file 을 뺀다):

node "<이 스킬 디렉토리>/collect-prompts.js" --why-pick '[{"n":12,"reason_quote":"심사위원은 이런걸 다 일일히 읽지않아요"}]'

• 출력 끝 줄의 파일 경로를 기억해 둔다 → 아래 저장 명령에 --whys-file "<그 경로>" 로 붙인다.
• ✗ 줄은 버려진 것이다(구절이 원문과 다름 등). 고쳐서 다시 고르거나 그냥 넘어간다.
• 서버는 누구의 「왜」든 판단 기록으로 넣는다 — 대표 계정은 owner_why, 직원 계정은 member_why(2026-10-03~ · 직원 판단도 쌓인다). 직원이어도 이 단계를 건너뛰지 말 것.
• 사용자에게는 쉬운 말로 한 줄만: 「이유를 말씀하신 곳 N군데를 판단 기록으로 함께 남깁니다.」

«핵심 결정» 줄 쓰는 법 — 사람이 정한 것은 원문을 따옴표로 (2026-10-06)

실제로 있었던 일 (2026-10-05): 사용자가 「정가를 먼저 보여주고 할인가를 보여줘야 한다」고 정했는데, AI 가 그것을 «2주차에 시험할 가설»로 내리고 자기 의견(반대 방향)을 «핵심 결정»에 확정처럼 적었다. 다음 세션은 그 기록을 검색 1위로 받아 충실히 따랐다. 틀린 결정이 «확정»으로 다음 작업에 들어갔다.

• 서버가 자동으로 꼬리표를 붙인다(서버에 바로 저장하는 회사 — 노션 회사는 아래 «검색 인덱싱» 주의 참고): «핵심 결정» 절의 줄마다, 이 세션에서 사용자가 친 말과 글자 그대로 맞는 인용 ("…" · 「…」)이 없으면 [AI 제안], 인용이 있는데 안 맞으면 [원문 미확인]. 줄을 지우거나 고치지 않고 앞에 꼬리표만 붙인다.
• 그러므로 사용자가 정한 것은 그 말을 따옴표로 그대로 붙인다 — 줄이거나 다듬지 말고 떼어 온다(「왜」 고르기와 같은 규칙).
• AI 의 의견·해석은 따옴표를 붙이지 않는다 — 꼬리표가 붙는 것이 정답이다. 다음 세션이 「이건 AI 제안이었다」를 알아본다.
• 짧은 승인으로 정해진 것(「네」「1번」「그걸로」처럼 AI 가 낸 안을 고른 말)은 [AI 제안 — 「1번」으로 승인] 처럼 승인을 줄 안에 적는다. 서버는 4글자 미만 인용을 원문으로 치지 않는다(아무 줄에나 「네」를 붙여 통과하는 구멍을 막는 규칙). 그래서 이 줄은 [AI 제안] 꼬리표를 받는데, 그게 정확하다 — 내용은 AI 안이고 사용자가 승인했다. 다시 저장하지 않는다.
• 저장 뒤 핵심 결정 N줄 — 원문 확인 · [AI 제안] · [원문 미확인] 줄을 본다. 사용자가 정한 것인데 꼬리표가 붙었으면 원문을 붙여 다시 저장한다(위 짧은 승인은 예외).

🔴 셀프체크 (적기 전)

1. 사용자가 정한 것을 내가 «가설·나중에·검토»로 내리지 않았나?
2. 내 의견이 사용자 결정과 반대인데 «핵심 결정»에 들어가 있지 않나? 들어가야 하면 「AI 제안 — 사용자 결정은 ○○」로 둘 다
3. 사용자가 정한 줄에 원문이 따옴표로 붙어 있나?

🔴 대상 고르기 — --object 또는 --object-none (적재 직전 · 필수 — 2026-10-15 개정)

판단이 맞는 대상(고객사·상품·브랜드)에 묶여야 나중에 「이 대상에 대해 최근에 뭘 정했나」가 바로 나온다. 묶는 것은 기계가 짐작하지 않고 저장할 때 여기서 정한다 — 저장하는 사람이 확정하는 자리다.

🔴 2026-10-15 개정 (사장님 「네」) — 건너뛰기 없음. --object 아니면 --object-none "<이유>" 둘 중 하나는 반드시 붙인다. 왜: 대상을 안 고르고 저장하면 기계가 본문 낱말로 짐작해 붙이는데, 엉뚱한 곳에 붙었다(실제: 한 고객 채널 작업이 다른 고객사에 붙음). 둘 다 없으면 저장 명령이 멈추고(종료코드 3) 하는 법 3줄을 보여 준다 — 그러면 이 절을 하고 같은 명령을 다시 보낸다.

1. 이번 작업이 «무엇에 관한» 일이었나 한 낱말로(고객사·상품·브랜드·채널 이름). 여러 개면 주된 것 하나.
2. mcp__jedi__search_business_objects 로 그 이름을 찾는다(줄임말·별명도 찾아진다). 결과에 있는 이름표만 고른다.
   • 문장처럼 긴 이름(「[세션저널] …」「채팅에서 … 감지」)은 이름표가 아니다 — 고르지 않는다.
3. 있으면 저장 명령 끝에 --object <그 이름표 id> --object-alias "<본문에 쓴 그 이름 그대로>".
   • --object-alias 는 본문에서 부른 이름(줄임말·영문명 등)이 이름표와 다를 때만. 같으면 빼도 된다.
   • 별칭은 서버가 «본문에 낱말로 나왔나»를 대조해 쌓는다(두 글자 한글은 안 쌓는다 — 일상어와 섞인다).
4. 정말 묶을 대상이 없으면(회사 내부 일·도구 정리·여러 곳에 고루 걸친 일) --object-none "<이유 한 줄>". 서버가 이 기록에서 기계 짐작을 돌리지 않는다.
5. 이름표가 «있어야 하는데 없으면»(새 고객사·새 상품) --object-none "이름표 없음: <이름>" 으로 저장하고, «미해결 · 다음»에 ⬜ 「<이름>」 이름표를 만들어 주세요 (관리자·대표님께) 한 줄. 🔴 이름표는 직접 만들지 않는다 — 만드는 것은 관리자·대표님 몫이다.
6. 도구가 없거나 오류로 못 찾았으면 --object-none "이름표 검색 실패" 로 저장한다(저장은 막지 않는다).
7. 저장 보고 첫 줄 아래에 대상: <이름표 이름> 또는 대상: 없음 — <이유> 한 줄 — 사람이 틀린 걸 바로 보는 유일한 자리다.
8. 다른 회사 칸의 이름표는 서버가 조용히 무시한다 — 묶이지 않아도 저장은 정상이다.

셀프체크 (저장 명령 전): ①검색을 실제로 했나 ②고른 것이 검색 결과에 있던 이름표인가 ③--object 와 --object-none 을 같이 붙이지 않았나 ④--object-none 에 이유가 있나 ⑤보고에 대상: 한 줄을 넣을 준비가 됐나

어느 일인지 정하기 — 프로젝트·관리번호 (적재 직전 · 2026-10-10)

사장님 2026-10-10: "팀원용 저장 도구에도 프로젝트 관리번호 매칭해주고 하는게 필요한데 그들은 그쪽을 잘 모르니까 쉽게 더 쉽게 맥락을 주면서 이해시켜줘야 돼요. 이번에 저도 헷갈렸었잖아요." 실제로 헷갈린 일: 한 고객 브랜드의 기록이 이름이 같은 프로젝트 두 개 중 계약이 끝나 보관된 쪽으로 들어갔고, 맞는 프로젝트에 들어간 기록도 그 안의 그 브랜드 칸이 비어 있었다. 그러면 나중에 「그 브랜드 건 뭐 정했지?」로 찾을 때 안 나온다.

고르는 것은 AI가 한다. 사람은 «맞다/아니다»만 답한다. 팀원에게 번호나 목록을 고르게 하지 않는다.

개념 — 팀원에게 설명할 때 쓰는 말 (이 표 그대로 쓴다)

한 줄로: 기록을 «어느 폴더의 어느 칸»에 꽂아 둘지 정하는 것이다. 칸을 정해 두면 그 칸 이름으로 지난 결정을 바로 찾는다.

순서

1. 이번 작업이 누구(어느 고객사·브랜드·채널)를 위한 일이었나를 대화에서 정한다. 회사 내부 일이거나 여러 곳에 걸치면 → 이 절을 건너뛴다(저장은 그대로).
2. mcp__jedi__list_projects 로 프로젝트를 찾는다.
   • 🔴 상태가 «사용 중»(ACTIVE)인 것만 고른다. 보관된(ARCHIVED) 프로젝트는 서버도 받지 않는다.
   • 🔴 이름이 같은 프로젝트가 둘 이상이면 이름이 아니라 상태와 설명으로 가른다(이번 사고가 바로 이것).
3. mcp__jedi__list_scopes{project_id} 로 그 안의 관리번호를 본다. 사용 중이고 **소개(description)가 이번 일과 맞는 것 «하나»**만 고른다.
   • 이름만 보고 고르지 않는다. 소개가 비어 있거나 맞는 칸이 없으면 관리번호 없이 프로젝트만 넣는다.
   • 「일반 판단」(GENERAL) 같은 «아무거나 담는 칸»으로 떨어뜨리지 않는다. 맞는 칸이 없으면 빈칸이 정답이다.
4. 사람에게 한 번 확인한다 — 아래 «확인 문구» 틀 그대로. AskUserQuestion 이 있으면 보기 3개(맞아요 / 다른 곳이에요 / 칸 없이 저장)로.
   • 「다른 곳이에요」면 어느 고객·일이었는지 한마디만 다시 물어 2~3을 다시 한다. 목록을 통째로 보여 주지 않는다.
5. 저장 명령 끝에 --project <프로젝트 id> 와 (골랐으면) --scope <관리번호 id> 를 붙인다. --scope 만 단독으로 쓰지 않는다.
6. 도구가 없거나 오류면 이 절을 건너뛰고 저장은 그대로 한다. «미해결 · 다음»에 ⬜ 어느 프로젝트 일인지 못 정함 — 관리자에게 한 줄.

확인 문구 (팀원 화면에 이 틀 그대로)

이 기록을 어디에 꽂아 둘까요?
  📁 폴더(프로젝트): ○○상사(물류)
  🏷 칸(관리번호): [브랜드] □□
     └ 이 칸은 「□□ 자사몰 판매 일 — 광고·상세페이지·주문·후기 판단」을 넣는 곳이에요.
  이렇게 정해 두면 나중에 「□□ 건 뭐 정했지?」로 바로 찾을 수 있어요.
맞으면 「네」, 아니면 무슨 일이었는지 한마디만 알려 주세요.

• 🔴 화면에 쓰지 않는 말(최소 이것들): scope · scope_id · project_id · uuid · ACTIVE · tenant · GENERAL · 번호 문자열(SC-C5F133 같은 코드)
• 칸 소개는 서버에 적힌 소개를 그대로 옮긴다. 소개가 비어 있으면 지어내지 말고 「(이 칸은 아직 설명이 없어요)」라고 쓴다.

좋은 예 / 나쁜 예

• ✅ 「📁 △△치과 마케팅 → 🏷 네이버 블로그 칸에 꽂아 둘게요. 이 칸은 『△△치과 네이버 블로그 원고·발행 판단』을 넣는 곳이에요. 맞나요?」
• ❌ 「project_id c0000000-…-0001 / scope GDON-BLOG-2026-003 으로 저장할까요?」 ← 번호·영문 용어
• ❌ 「다음 중 관리번호를 골라 주세요: 1) GENERAL 2) TECH 3) OPERATION …」 ← 목록 고르기를 팀원에게 떠넘김
• ❌ 이름이 같은 프로젝트 둘 중 보관된 쪽을 고름 ← 상태를 안 봄

셀프체크 (확인 문구를 내기 전)

1. 고른 프로젝트가 «사용 중»인가? 이름이 같은 프로젝트가 또 있지 않은가?
2. 관리번호는 그 프로젝트 «안»의 사용 중인 칸인가? 소개가 이번 일과 맞는가?
3. 화면 문구에 위 «쓰지 않는 말»이 하나라도 들어갔나?
4. 칸 소개를 지어내지 않았나(서버 소개 그대로인가)?
5. 팀원에게 목록을 고르게 하지 않았나?

작성자 자동 확인 (적재 직전, 먼저)

공유 계정이라 "누가 했는지"는 개인 제디 토큰의 actor로 식별한다. 이름은 서버가 알려준다(2026-07-29~ — 파일 명단이 아니라 백엔드 actor.name). 적재 직전 딱 1회 Bash로 실행:

f="$HOME/.claude/zulgap/teampack-config.js"; [ -f "$f" ] || f="$HOME/.claude/plugins/marketplaces/zulgap-team-pack/teampack-config.js"; node "$f" name

• 위 경로가 없으면 ~/.claude/plugins 아래에서 teampack-config.js를 찾아 실행한다(캐시 경로 환경차). (구버전 호환: resolve-staff.js도 같은 값을 준다 — 내부에서 위 스크립트로 위임)
• 출력된 이름 한 줄을 아래 작성자 속성에 넣는다.
• 출력이 비어 있으면 작성자는 생략하고 저널은 정상 적재한다. 다만 이건 정상 상태가 아니다 — 🔴 토큰이 없거나 서버에 닿지 못한 것이므로 관리자에게 알린다(전원 토큰 발급이 원칙). stderr에 🔴 캐시가 N일 지났습니다 경고가 뜨면 그대로 보고할 것.

🔀 노션을 쓰는 회사인가 (적재 직전, 딱 1회 — 2026-09-30)

노션을 쓰지 않는 회사도 있다. 그 회사는 저널을 서버에 바로 저장하고 미니앱에서 본다. 판정은 아래 한 줄로만 한다:

f="$HOME/.claude/zulgap/teampack-config.js"; [ -f "$f" ] || f="$HOME/.claude/plugins/marketplaces/zulgap-team-pack/teampack-config.js"; node "$f" has:notion.team_journal_ds

🔴 notion.team_journal_ds 값이 비었다고 「노션 없는 회사」로 판정하지 말 것. 그 값은 «연결이 끊겨 못 읽음»일 때도 빈칸이라, 노션을 쓰는 회사가 잠깐 끊겼을 때 노션을 건너뛰는 길로 빠진다. has: 만이 「못 읽음(unknown)」과 「비어 있음(no)」을 가른다.

노션 없는 회사 — 서버에 바로 저장 (위 판정이 no 일 때만)

① 5섹션 본문을 파일로 쓴다 — 형식은 아래 § 적재 방법의 표준 5섹션 그대로(## 배경 / 요청 ~ ## 미해결 · 다음). 경로는 임시 폴더: node -e "console.log(require('os').tmpdir())" 가 알려주는 폴더 아래 jedi-journal-<YYYYMMDD-HHMM>.md. 🔴 홈 폴더 최상위에 만들지 말 것.

② 서버에 저장 (Bash, 딱 1회):

f="$HOME/.claude/zulgap/journal-ingest.js"; [ -f "$f" ] || f="$HOME/.claude/plugins/marketplaces/zulgap-team-pack/journal-ingest.js"; node "$f" new "<세션 제목>" "<한줄 요약>" --body-file "<①의 파일>" --no-notion [--whys-file "<「왜」 파일>"] (--object <이름표 id> [--object-alias "<이름>"] | --object-none "<이유>") [--project <프로젝트 id> [--scope <관리번호 id>]]

• --whys-file 은 § 「왜」 고르기에서 1개 이상 골랐을 때만 붙인다. 파일이 깨져도 저널은 그대로 저장된다.
• 🔴 --object 또는 --object-none "<이유>" 중 하나는 반드시 — § 대상 고르기. 빠지면 종료코드 3 으로 멈춘다(저장 안 됨 · 붙여서 다시).
• 위 경로가 없으면 ~/.claude/plugins 아래에서 journal-ingest.js 를 찾아 실행한다.
• new = 새 기록 번호를 만든다. 출력 첫 줄 source_id=<번호> 를 기억해 둔다(아래 재시도·같은 세션 재저장에 쓴다).
• 작성자는 서버가 토큰으로 붙인다 — 이름을 보내지 않는다.

③ 결과 읽기

④ 사용자에게 보이는 말은 쉬운 말로만 — 「노션」「DB」「source_id」「journal-ingest」「인덱싱」 같은 표·도구 이름을 화면에 쓰지 않는다.

⑤ 같은 세션에서 /jedi-save 를 또 부르면 — 새 번호(new)를 만들지 말고, ②의 번호로 고친 본문 전체를 다시 보낸다 (본문 끝에 ## ⟳ 저장 후 갱신 을 덧붙인 판). 번호가 같으면 서버가 같은 기록을 갱신한다.

⑥ 끝나면 § 캡처 원칙 · § 핸드오프 프롬퍼로 그대로 이어간다(핸드오프는 이 PC 파일이라 노션과 무관하다).

적재 방법

notion-create-pages 호출:

• parent: {"type":"data_source_id","data_source_id":"<아래 명령의 출력>"}

  f="$HOME/.claude/zulgap/teampack-config.js"; [ -f "$f" ] || f="$HOME/.claude/plugins/marketplaces/zulgap-team-pack/teampack-config.js"; node "$f" notion.team_journal_ds
  

  (하드코딩 금지 — 회사마다 DB가 다르다. 출력이 비면 관리자에게 온보딩 요청)
  • (회사 "팀 세션 저널" DB — 마스터 허브 하위. 직원이 이 DB에 노션 권한이 있어야 적재됨)
• properties:
  • 세션 (title): 이번 작업 한 줄 제목
  • 작성자: 위에서 얻은 이름 (비면 생략)
  • date:날짜:start: 오늘 날짜 (YYYY-MM-DD), date:날짜:is_datetime: 0
  • 유형: 콘텐츠제작 / 조사 / 문서작성 / 기타 중 1개
  • 한줄 요약: 이 작업에서 가장 중요한 것 1줄
  • 산출물: 만든 것(링크·파일명)
• content (body) = 표준 5섹션 고정:

  ## 배경 / 요청
  무엇을 하려 했는가 (1~2줄)
  
  ## 핵심 결정 + 근거
  무엇을 정했고 왜
  
  ## 학습 · 함정
  하면서 알게 된 것, 다음에 조심할 것
  
  ## 산출물
  만든 콘텐츠 / 문서 / 링크
  
  ## 미해결 · 다음
  다음에 이어서 할 것
  

🔴 적재 직후 — 한글 되읽기 대조 (필수, 인덱싱 «전»)

노션 MCP 인자에 한글을 \uXXXX 로 넘기면 받침 한 칸이 어긋난 글자가 조용히 섞인다. 도구는 성공을 반환하고 반환값에도 안 보인다. 저널은 나중에 «근거»로 읽히는 문서라, 글자 하나가 틀어지면 그때 판단이 틀어진다.

2026-08-26 실측 — 이 스킬로 적재한 세션 저널 한 장에서 8곳이 틀어졌다 (못 바꿔다·뜼면·박혔·끕」이 곳·썹네일×2·결들여·셀고). 같은 날 카드 6장에서도 12곳이 났다. 경고문은 그때까지 다섯 번 실패한 상태였다.

한글은 그대로 친다. 그리고 적재한 뒤 반드시 되읽어 대조한다.

① 5섹션 본문을 «파일로 먼저 쓴다»                sent.md
② 그 파일 내용을 그대로 notion-create-pages 에 넘긴다
③ notion-fetch 로 되읽어 파일로 저장하고 대조     got.md

diff -u sent.md got.md          # 다르면 그 줄이 통째로 나온다. 오탐 0

🔴 섹션 개수나 표 행 수만 세면 못 잡는다 — 틀어지는 자리는 «평범한 문장 한가운데»다. 🔴 고칠 때 old_str 은 화면에서 그대로 복사한다 — 다시 이스케이프로 치면 같은 자리에서 또 틀어진다. ⚠️ 속성값(세션·한줄 요약·산출물)도 같다. 본문만 보고 넘어가지 말 것.

적재 직후 — 검색 인덱싱 (필수, 딱 1회)

🔴 노션에만 쌓으면 나중에 검색이 안 된다. 적재 응답의 page id로 아래를 실행:

f="$HOME/.claude/zulgap/journal-ingest.js"; [ -f "$f" ] || f="$HOME/.claude/plugins/marketplaces/zulgap-team-pack/journal-ingest.js"; node "$f" "<page_id>" "<세션 제목>" "<한줄 요약>" [--whys-file "<「왜」 파일>"] (--object <이름표 id> [--object-alias "<이름>"] | --object-none "<이유>") [--project <프로젝트 id> [--scope <관리번호 id>]]

• 🔴 여기에는 --body-file 을 붙이지 않는다 — 서버가 노션 저널을 «제목+한줄 요약»으로 따로 다시 색인하므로, 본문을 보내면 둘이 번갈아 덮어쓴다. (그래서 노션 회사의 «핵심 결정» 꼬리표는 노션 본문에 붙지 않는다 — 위 «핵심 결정» 줄 쓰는 법은 사람이 읽을 때를 위해 그대로 지킨다)
• --whys-file 은 § 「왜」 고르기에서 1개 이상 골랐을 때만 붙인다.
• 🔴 --object 또는 --object-none "<이유>" 중 하나는 반드시 — § 대상 고르기. 빠지면 종료코드 3 으로 멈춘다 → 붙여서 다시 실행한다(아래 «실패해도 넘어간다»의 예외).
• 이걸 해야 나중에 /시작의 과거 회상이나 제디가 이 기록을 찾을 수 있다.
• 작성자 귀속은 서버가 토큰으로 한다 — 이름을 보내지 않는다(보낼 필요도 없다).
• 실패해도 저널은 이미 노션에 적재됐다. 출력을 그대로 보고만 하고 넘어간다.
• 같은 저널을 고쳐서 다시 부르면 그때만 재인덱싱된다(멱등).

캡처 원칙 (노이즈 차단)

• 담아라: 핵심 결정·근거 / 만든 것 / 배운 점.
• 빼라: 도구 실행 로그 / 중간 과정 / 뻔한 것.
• 형식 일관성 = 매번 같은 5섹션 (나중에 검색·정리가 쉽다).

핸드오프 프롬퍼 (작업이 아직 안 끝났으면)

저널 기록 후 "이 작업이 다 끝났나" 를 자문한다. 아래 중 하나라도 해당하면 = 미완료 → 다음 세션이 바로 이어갈 핸드오프 파일을 만든다:

• ⬜ 만들던 게 중간에 끊김 (일부만 완성 / 검증 안 함)
• ⬜ 다음에 이어서 해야 할 게 남음
• ⬜ 누구 답·외부 자료를 기다리는 중

전부 끝났으면 → 만들지 않고 "작업 완결 — 핸드오프 불필요" 1줄 보고.

미완료면 ~/.claude/specs/YYYY-MM-DD-handoff-<작업한단어>.md 에 아래 6블록으로 작성:

# 핸드오프 — <작업명>

> 상태: 🔵 진행          ← 🔴 필수 1줄. `/jedi-start` 가 이 줄로 「살아있는 작업」을 고른다
> 완료조건: pr:239 · human:대표님-확인   ← 🔴 필수 1줄. 아래 § 완료조건 참조

## 한 줄
<무엇을 하면 이 작업이 끝나는가 — 1문장>

## 🗺 로드맵 (이 작업이 큰 그림에서 어디쯤인가)
<아래 "로드맵 블록" 참조>

## 다음에 바로 할 것 (복붙 프롬프트)
<다음 세션 첫 발화로 그대로 붙여넣을 프롬프트>

## 지금까지 한 것
<완성된 것 / 결정한 것>

## 남은 것
<⬜ 남은 항목>

## 조심할 것
<손대면 안 되는 것 / 함정>

작성했으면 그 경로도 완료 보고에 포함한다.

🔴 완료조건 한 줄 — 「끝났나」를 기계가 검사하게 (필수)

왜 필요한가: 「진행 중」이 쌓이는데 무엇이 끝났는지 세는 자리가 없다. 「끝났다」라는 낱말로 찾으면 안 된다 — 실측 18건 중 16건이 오탐이었다(전부 "X는 끝났다, 남은 것은 Y" 형태). 낱말로는 원리적으로 못 가른다. 그래서 쓸 때 기계가 읽을 수 있게 적어 둔다.

문법 — 축을 · 로 잇는다

> 완료조건: pr:239 · commit:ac93d27@origin/main · file:plugins/x/y.md · human:대표님-확인

🔑 human: 이 대부분인 것이 정상이다. 이 규약의 값어치는 「자동으로 닫는 것」이 아니라 「내가 할 일 / 남의 답 대기 / 진짜 끝남」이 매번 자동으로 갈리는 것이다.

• human: 은 한 줄로 구체적으로. human:확인 ❌ → human:대표님-발행승인 ✅
• 사람이 할 일이 없으면 human: 을 쓰지 않는다(쓰면 영원히 「답 대기」에 남는다)
• 기계 축이 하나도 없어도 된다 — > 완료조건: human:동료사-피드백-수령 도 완전한 한 줄이다

검사

node plugins/jedi-core/skills/jedi-save/handoff-done-check.js          # 사람용 요약
node plugins/jedi-core/skills/jedi-save/handoff-done-check.js --json   # /jedi-start 가 읽는 형태

판정 5종: ready(기계 조건 전부 충족 + human 없음) · waiting_human · in_progress · unknown(검사 실패 — 🔴 「미충족」이 아니다) · no_condition(이 줄이 없는 옛 파일).

🔴 unknown 을 ready 로 올리지 않는다 — gh 미설치·네트워크 실패로 못 잰 것을 「충족」으로 읽으면 안 끝난 작업이 닫힘 후보로 올라간다. 반대로 「미충족」으로 뭉개도 끝난 작업이 영원히 열린다.

⚠️ 소급하지 않는다 — 옛 핸드오프에 몰아서 채우지 말 것. 살아있는 작업은 어차피 /jedi-save 를 다시 타므로 그때 채워진다. 안 열리는 것은 채울 필요가 없다.

🔴 상태 줄 + 끝난 핸드오프 닫기 (필수)

핸드오프 파일은 계속 쌓인다. 그런데 「끝난 것」과 「아직 하는 중인 것」을 가르는 표시가 없으면, 나중에 /jedi-start 로 이어받을 때 이미 끝난 작업까지 후보로 나와 뭘 골라야 할지 알 수 없다.

① 내 핸드오프에 상태 1줄

② 🔴 이어받은 앞 핸드오프도 닫는다 (양쪽 다 적어야 한다)

이번 핸드오프가 앞 핸드오프를 이어받은 것이면, 그 앞 파일에도 종결 줄을 적는다.

# 핸드오프 — 카드 명세서 정리
> 상태: ✅ 종결 (2026-08-08) → 후속: 2026-08-08-handoff-card-ledger.md

🔴 한쪽만 적으면 소용없다. 새 파일에 "앞 작업: ○○" 이라고 적어도, /jedi-start 는 최신순으로 읽어서 앞 파일을 먼저 만난다 → 이미 끝난 작업을 처음부터 다시 시작한다.

닫아야 할 때 — 하나라도 해당:

• 이번 핸드오프가 그 작업을 이어받음
• 그 작업이 실제로 다 끝남
• 그 작업을 접기로 함

닫지 말 것: 잠깐 미뤄둔 작업(= 여전히 🔵 진행). 오래됐다고 끝난 게 아니다.

⚠️ 다 이어받은 게 아니면 닫지 말 것 — 앞 핸드오프의 「남은 것」 중 새 문서로 안 옮긴 항목이 있으면 그건 일부만 이어받은 것이다. 닫으면 그 항목들이 통째로 사라진다. 닫기 전에 「남은 것」을 새 문서와 대조한다.

③ 🔴 묵은 작업 3건 되묻기 (2026-08-13 신설 — 매번 실행)

왜 필요한가: 위 ②는 "이어받을 때 닫아라" 인데, 실제로는 잘 안 닫힌다. 이유가 구조적이다 — 이어받은 사람은 앞 문서가 있는지도 모르고(다른 창에서 만든 파일이다), 닫는 일이 자기 결과물이 아니라 뒤로 밀리며, 끝났는지 판정도 애매하다.

운영 환경 실측(2026-08-13) — 「진행 중」 55건 중 24건(44%)이 3일 이상 방치됐고 그중 넷은 명백히 끝난 작업이었다. 그래서 /jedi-start 가 매번 55줄을 내놓고 어느 걸 이어야 할지 알 수 없게 됐다.

∴ "이어받을 때 닫아라" 만으로는 부족하고 주기적으로 되묻는 자리가 필요하다. /jedi-save 가 그 자리다.

조회 (매번 1회 · 3건만)

cd ~/.claude/specs
export LC_ALL=C
# 🔴 맥(BSD date)은 -d 를 모른다 — -v 로 한 번 더 묻는다(윈도우 Git Bash·리눅스는 앞의 것이 된다)
CUT=$(date -d '3 days ago' +%Y-%m-%d 2>/dev/null || date -v-3d +%Y-%m-%d)
grep -l '^> *상태: *🔵' *handoff*.md 2>/dev/null | grep -v autohandoff | while read f; do
  d=$(echo "$f" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}')
  [ -n "$d" ] || continue    # 🔴 날짜를 못 읽으면 묻지 않는다(빈 값은 어떤 날짜보다 작아 전부 걸린다)
  [[ "$d" < "$CUT" ]] || continue
  # 🔴 머리의 `>` 줄을 «전부» 읽는다 — 첫 줄만 보면 다른 사람이 «그 아래에» 덧붙인
  #    「끝났음」 표시를 놓쳐 이미 끝난 것을 또 물어본다
  #    (2026-09-08 실측: 묵은 3건 전부 같은 날 다른 창이 2·5번째 줄에 끝났다고 적어 뒀는데
  #     첫 줄이 아직 🔵 라 세 건이 그대로 다시 떴고, 같은 확인을 두 번 했다)
  hdr=$(awk '/^>/{p=1;print;next} p{exit}' "$f")
  # 🔴 줄 머리가 「상태」급인 것만 끝난 것으로 본다 — 느슨하게 「✅ 종결」 포함으로 잡으면
  #    「선행: …(✅ 종결 — 이 파일이 이어받음)」 처럼 «남 이야기»를 적은 줄까지 닫아 버린다
  echo "$hdr" | grep -qE '^> *(·|-|상태:)? *✅ *\**종결' && continue
  # 🔴 상태 줄의 «뒷말»을 함께 뽑는다 — 「일부만 이어받았지 끝난 게 아님」이 여기 적힌다
  st=$(grep -m1 '^> *상태:' "$f" | sed 's/^> *상태: *//')
  # 🔴 최근에 「살아있어」 라고 답 들은 것은 건너뛴다 — 아래 표의 «3일간 다시 안 묻는다» 를 실제로 하는 곳
  #    이 줄이 없으면 그 약속이 말로만 있고 안 지켜진다. 게다가 오래된 순으로 줄을 세우니
  #    이미 확인한 것이 앞자리를 계속 차지해 뒤에 있는 것들이 영영 안 보인다
  #    (2026-08-18 실측: 3일 넘은 71건 중 4건이 앞 3자리를 막아 67건이 한 번도 안 나왔다)
  #    sort|tail -1 = 여러 번 확인받아 날짜가 여러 개 적혀도 «가장 최근» 것을 고른다
  #    🔴 `$st`(첫 줄)가 아니라 `$hdr`(머리 전체)에서 찾는다 — 확인 날짜도 아랫줄에 덧붙는다
  cdate=$(echo "$hdr" | grep -oE '확인 [0-9]{4}-[0-9]{2}-[0-9]{2}' | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | sort | tail -1)
  if [ -n "$cdate" ] && [[ ! "$cdate" < "$CUT" ]]; then continue; fi
  # 🔴 「## 한 줄」에서 메타 문장을 건너뛰고 **굵게(**) 로 시작하는 실질 문장**을 고른다.
  #    ⚠️ cut -c 로 자르지 말 것 — LC_ALL=C 라 한글이 바이트로 잘려 마지막 글자가 깨진다(실측)
  body=$(sed -n '/^## 한 줄/,/^## /p' "$f" | grep -v '^##\|^$\|^--\|^> \|^~~' | grep -v '⟳')
  one=$(echo "$body" | grep '^\*\*' | head -1)
  [ -n "$one" ] || one=$(echo "$body" | head -1)   # 굵은 줄이 없으면 첫 줄
  # 🔴 머리 15줄에 「닫지 말 것」류가 있으면 표시 — 파일이 스스로 한 말을 무시하지 않게
  w=""; head -15 "$f" | grep -qiE '종결 아님|닫지 말|닫으면 통째로' && w=" 🔴닫지말것"
  echo "$d|$f|$st$w|$one"
done | sort | head -3

⚠️ 출력은 한 줄로 두고 sort 뒤에 사람이 나눠 쓴다 — 반복문 안에서 2줄로 나눠 찍으면 sort 가 들여쓴 줄을 앞으로 끌어올려 짝이 어긋난다(실측).

보여주기 (최대 3건)

🔴 상태: 줄을 반드시 함께 보여준다 — 뒷말에 「일부만 이어받았음」·「뒷 문서가 안 받았음」 같은 닫으면 안 되는 이유가 적혀 있다.

📁 오래된 작업 확인 (3일+ 손 안 댐 · 전체 N건 중 3건)
   1. [8/07] 파일 인입   🔴닫지말것
      상태: 🔵 진행 — 일부만 이어받았지 끝난 게 아님 (8/08 판정)
      한 줄: 지금 남은 것은 «사람이 해야 할 6건» — 이게 없으면 전량 인입을 못 돌린다
   2. [8/08] 귀속 갭
      상태: 🔵 진행
      한 줄: 어디에 쌓이는지 지도로 확정한 뒤 처방을 정하면 완결
   → "1번 끝났어" / "2번은 살아있어" 하시면 그 자리에서 표시합니다

닫기 (사람이 말할 때만)

함정

• 🔴 내가 알아서 닫지 말 것. 끝났는지는 코드로 판정할 수 없고, 잘못 닫으면 살아있는 작업이 /jedi-start 후보에서 영영 빠진다(길 잃는 것의 반대 방향 사고). 사람이 말한 것만 근거다
• 🔴 「한 줄」을 읽고 「끝난 것 같다」고 제안하지 말 것. 실제로 두 번 틀렸다 — 어떤 파일의 한 줄 첫 문장이 "⟳ 갱신 — 원래 한 줄이 이미 해결된 것을 가리키고 있었다" 라 「이미 해결」로 읽고 닫자고 제안했는데, 그건 «한 줄이 낡았었다»는 뜻이지 «작업이 끝났다»가 아니었다. 같은 파일 머리 3줄 위에 「일부만 이어받았음 … 닫으면 통째로 사라진다」 가 적혀 있었다. 🔑 파일이 스스로 「닫지 말라」고 말하는 자리는 ## 한 줄 이 아니라 머리의 상태: 줄이다. 그래서 위 조회가 상태 뒷말과 🔴닫지말것 을 함께 뽑는다. 그 둘을 안 보고 닫기를 제안하면 규약 위반.
• 🔴 3건을 늘리지 말 것. 하루에 여러 번 저장하므로 며칠이면 밀린 것이 다 정리된다. 한 번에 20건을 올리면 그게 바로 「긴 목록 앞에서 고르는 일」의 재현이다
• ⚠️ 0건이면 이 블록을 통째로 생략한다
• ⚠️ /jedi-start 는 접기만 하고 닫지 않는다 — 그쪽은 읽기 전용이라 여기가 유일하게 고치는 자리다

🗺 로드맵 블록 (필수)

왜 필요한가: "남은 것"은 이 작업 안만 말한다. 다음 세션은 그걸 읽고 일은 이어가지만 "이게 왜 필요한 일인지"를 모른 채 이어간다 → 큰 방향과 어긋나게 완주하거나, 이미 접은 갈래를 붙잡는다. 로드맵은 할 일이 아니라 좌표를 넘긴다.

3가지를 답한다 (모르면 빈칸·추측 대신 ⚠️ 미확인 — <확인 방법>):

마지막에 "한 줄로" — 큰 일과 이 작업의 관계를 한 문장으로.

예시:

## 🗺 로드맵

**상위**: 노션 「7월 카드뉴스 개편」 (링크)
**전체 중 현재 위치**:
| 단계 | 상태 |
|---|---|
| 1 템플릿 확정 | ✅ 완료 |
| 2 이 작업 (본문 카피) | 🔵 3/5장 완료 |
| 3 최종 검수·발행 | ⬜ 예정 |

**앞뒤 연결**: 선행 없음 / 후행 — 5장 다 돼야 검수 넘어감
**한 줄로**: 개편 전체 중 본문 파트. 템플릿은 이미 고정이라 그대로 쓰면 된다.

함정:

• ⚠️ 상위 문서 내용을 복사하지 말 것 — 링크만. 복사하면 나중에 두 곳 내용이 달라진다
• ⚠️ 단계 목록은 상위 문서에 실제로 있는 단계를 쓸 것. 그럴듯하게 지어낸 단계는 다음 세션을 더 헤매게 만든다 — 상위 문서를 실제로 열어보고 쓴다
• ⚠️ 상위에 없는 분류·라벨을 만들어 붙이지 말 것. 한 번 적히면 다음 세션이 사실로 믿는다
• ⚠️ 로드맵은 「내 작업」만 그린다 — 다른 사람·다른 작업의 진행 상황을 곁다리로 적지 말 것. 남길 가치가 있는 건 딱 둘이다: ① 같은 파일을 다른 사람도 고치는 중(부딪히면 사고) ② 그게 끝나야 내가 되는 것(앞뒤 연결). 판정 1줄 = "이걸 모르면 다음 세션이 잘못 움직이나?" — 아니면 뺀다. 로드맵은 현황 보고가 아니라 좌표다

🔴 1-A. 위 표 1번을 적을 때 — 상위 문서가 낡았는지도 본다

한 주제를 여러 날에 나눠 하면 상위 문서가 조용히 낡습니다. 그동안의 진행은 매번 핸드오프에만 쌓이고, 정작 "이 일 전체가 어떻게 되고 있나"를 담은 문서는 며칠 전에서 멈춰 있습니다.

🔴 링크는 매번 성실히 적혀 있습니다. 문제는 적는 것과 그 링크가 아직 맞는지 보는 것이 다른 일이라는 겁니다. 후자가 없으면 나중에 누가 "이거 전체 어떻게 돼가?" 라고 물었을 때 문서 대여섯 개를 열어야 답이 나옵니다.

언제 — 이 주제를 3세션 이상 이어서 하고 있을 때만. 오늘 시작해 오늘 끝나는 일은 해당 없습니다.

어떻게 (30초)

그 날짜를 이 주제의 최근 진행과 비교합니다.

「최신 정리」에 담을 4가지 (이보다 줄이지 마세요 — 이게 「그 주제의 큰 그림」입니다):

1. 여기까지 온 순서 — 언제 무엇이 어디로 넘어갔나 (날짜순)
2. 이 일의 구조 — 축·단계가 몇 개고 각각 무슨 상태인가
3. 🔴 뒤집힌 것 — 앞에 적힌 것과 결론이 달라진 것. "인용하기 전에 여기부터" 라고 적어둘 것
4. 🔑 지금 당장 할 수 있는 것 — 「할 수 있나 / 막는 게 뭔가」 2열. 막힌 것과 지금 되는 것을 갈라 놓습니다

함정

• ⚠️ 새 문서를 만들지 마세요 — 큰 그림이 둘이 되면 그게 더 헷갈립니다. 기존 문서 맨 위에 덧붙입니다
• ⚠️ 맨 위에 두고 "아래보다 최신"이라고 적으세요 — 뒤에 붙이면 낡은 부분을 먼저 읽습니다
• ⚠️ 끝난 핸드오프의 「다음에 할 것」을 그대로 옮기지 마세요 — 진행 도중 무효가 된 것이 섞여 있습니다

🔁 같은 세션에서 /jedi-save을 또 누른 경우 — 4종 갱신

한 세션에서 /jedi-save을 2번째 이후 부르면, 새로 쓰지 말고 실물과 대조해 갱신한다. 그새 다른 사람·다른 세션이 진척시켰거나, 저장한 뒤에 상황이 바뀌었을 수 있다.

🔴 갱신할 것이 넷이다. 로드맵만 보면 반쪽이다.

1번이 제일 위험하다. 로드맵 표는 참고용이지만 프롬프트는 다음 세션이 그대로 실행한다.

실제 사례 (2026-08-05): 저장을 끝낸 직후 PR 4건을 머지했는데, 프롬프트에 "PR 4건을 이 순서로 머지한다" 가 그대로 남아 있었다. 안 고쳤으면 다음 세션이 이미 머지된 PR을 또 머지하려 했다.

확인할 것: ① 상위 문서의 실제 체크 표시 ② 그 사이 올라온 결과물·커밋 ③ 직전에 쓴 핸드오프 파일(비교 기준)

표시 방법:

• 프롬프트는 지금 남은 일로 바꾼다. 끝난 지시는 지운다(「했음」으로 남기지 말 것 — 실행 대상이라 군더더기가 곧 오작동)
• 저널은 새 행을 만들지 말고 기존 페이지 맨 끝에 ## ⟳ 저장 후 갱신 을 덧붙인다. ⚠️ 본문 일부를 찾아 바꾸려 하면 노션이 표를 다르게 저장해 실패한다 — 덧붙이기가 정답
• 변동 있으면 🆕 + 출처를 적는다 (예: 🆕 다른 세션이 완료). 내가 한 것과 섞지 말 것 — 섞이면 다음 세션이 없는 결과물을 찾는다
• 변동 없으면 "⟳ N회차 재검증 — 변동 없음" 한 줄로 명시한다 (확인했는데 없음과 확인 안 함은 다르다)
• 로드맵이 바뀌면 "한 줄로" 요약도 같이 고칠 것 — 표만 고치고 결론을 놔두면 둘이 어긋난다
• 상태: 줄 — 이번에 그 작업이 끝났으면 그 자리에서 ✅ 종결 (오늘) [→ 후속: <파일>] 로 바꾼다. 다음 /jedi-save 로 미루면 그 사이에 /jedi-start 가 끝난 작업을 집어온다

완료 후

적재된 노션 페이지 URL(+미완료면 핸드오프 경로)을 보고한다. (텔레그램 알림은 보내지 않는다) 노션 없는 회사는 URL 대신 「미니앱에서 볼 수 있습니다」 한 줄(+미완료면 핸드오프 경로). 🔴 그 첫 줄 바로 아래에 대상: <이름표 이름> 또는 대상: 없음 — <이유> 한 줄(§ 대상 고르기 7번).