.ai-sdlc/ 파이프라인 실행 중간의 단계 상태만 저장할 때는 ai-sdlc-skills-handoff의 실행 아티팩트를 따른다. 세션을 넘길 때는 이 스킬로 전달 경로와 다음 작업 이슈를 정한다.
핸드오프는 요약이 아니라 재개 가능한 상태다. 다음 세션이 이것만 읽고 같은\n자리에서 다음 명령을 칠 수 있어야 한다. \"뭘 했는지\" 보다 \"지금 어디에 서 있고\n다음에 뭘 치는지\" 가 본체다.
\n컨텍스트 사용량이 40~50% 에 닿으면 하던 걸 멈추고 이 스킬을 부른다. compaction 은\n모델이 뭘 버릴지 스스로 고르므로 안전망일 뿐이다.
\n재개 상태를 두 군데에 나눠 적지 않는다. 나눠 적으면 어느 쪽도 혼자서는 재개\n가능한 상태가 아니게 되고, 다음에 쓸 때 한쪽 내용이 조용히 빠진다(2026-09-21 실측,\n이슈 #152 — 함정·기동 명령은 핸드오프 이슈에만, 새로 확정된 패턴은 다음 이슈\n메모에만 있었다).
\n| 상황 | \n남기는 곳 | \n다음 세션이 받는 것 | \n
|---|---|---|
| 이슈 도중 — 작업 이슈가 아직 열려 있다(컨텍스트 40~50% 등) | \n전용 핸드오프 이슈 + HANDOFF.md(포인터, 아래 \"두 갈래\") | \n핸드오프 이슈 URL | \n
| 이슈 경계 — 작업 이슈를 닫았고 다음 작업 이슈가 이미 있다 | \n다음 작업 이슈에 코멘트 하나 (1-6) — 전용 핸드오프 이슈는 만들지 않는다 | \n다음 작업 이슈 URL | \n
| 인프라 없음 | \nHANDOFF.md | \n파일 경로 | \n
이슈 경계인데 다음 작업 이슈가 아직 없으면 그 이슈를 먼저 만든다. 다음에 할 일이\n정해지지 않았다면 경계가 아니라 그냥 끝난 것이므로 핸드오프를 쓰지 않는다.
\n| \n | 하는 일 | \nHANDOFF.md | \n다음 세션이 받는 것 | \n
|---|---|---|---|
| 인프라 있음 | \n본문을 스크래치 파일에 쓰고 그 내용으로 이슈/티켓/스레드를 만든다 | \n포인터만(이슈 URL·작성 시각·요약·목록 링크) | \n전체 URL | \n
| 인프라 없음 | \nHANDOFF.md 에 전체 내용을 쓴다 | \n본문 그대로 = 원본 | \n파일 경로 | \n
이슈 도중에 끊을 때 본문은 항상 만든다. 인프라가 있으면 그 본문은 이슈에\n들어가고 HANDOFF.md 는 위치만 가리킨다 — 레포에 재개 상태를 평문으로 남기지\n않고, 다음 세션은 파일 한 줄만 읽어도 어디로 가야 하는지 안다. 인프라가 없으면\n갈 곳이 없으므로 본문 자체가 HANDOFF.md 에 남는다(파일 모드) — 절차가 멈추지\n않는다.
| 호출 | \n하는 일 | \n
|---|---|
/handoff (인자 없음) | \n작성 — 이슈 도중이면 인프라 있을 때 이슈를 만들고 HANDOFF.md 엔 포인터만, 인프라 없으면 HANDOFF.md 에 전체 내용; 이슈 경계면 다음 작업 이슈 코멘트 → URL 또는 파일 경로 출력 | \n
/handoff <URL · #N · 파일경로> | \n재개 — 내용을 읽고 단언을 검증한 뒤 이어서 착수 | \n
/handoff done | \n종료 — 결과를 남기고 닫는다(이슈) / 파일에 적는다(파일 모드) | \n
사용자가 URL 이나 HANDOFF.md 경로만 붙여넣어도(설명 없이) 재개 모드로 본다.
\"이 레포는 GitLab 이니까\" 같은 추정으로 명령을 고르지 않는다. 아래를 순서대로\n확인하고, 처음 성립하는 것을 쓴다.
\n# 1) 레포 문서가 트래커를 지정했는가 (가장 강한 신호)\ngrep -riE 'jira|plane|linear|이슈는|트래커' AGENTS.md CLAUDE.md README.md 2>/dev/null | head -5\n\n# 2) git 포지\ngit remote get-url origin\n\n# 3) 인증이 실제로 되는가 (설치돼 있다 ≠ 쓸 수 있다)\ngh auth status 2>&1 | tail -2\nglab auth status 2>&1 | tail -2\n\n# 4) 포지 밖 트래커의 자격증명이 있는가 — 이름만 본다, 값은 출력하지 않는다\nenv | grep -oE '^(JIRA|PLANE|SLACK|LINEAR)_[A-Z_]+' | sort -u\nMCP 도구 목록에 Jira·Plane·Slack 도구가 있으면 그쪽을 CLI 보다 먼저 쓴다\n(자격증명을 셸로 꺼낼 일이 없다).
\n| 판별 결과 | \n쓰는 것 | \n프로젝트 지정 | \n
|---|---|---|
github.com/<owner>/<repo> | \ngh | \n--repo <owner>/<repo> | \n
| GitLab (self-hosted 포함) | \nglab | \nprojects/<owner>%2F<repo> (슬래시는 %2F) | \n
| Forgejo / Gitea | \ncurl + 토큰 | \n/api/v1/repos/<owner>/<repo>/issues | \n
| Jira | \nMCP 도구 또는 REST | \n/rest/api/3/issue · 프로젝트 키 필요 | \n
| Plane | \nMCP 도구 또는 REST | \n/api/v1/workspaces/<ws>/projects/<id>/issues/ | \n
| Slack (티켓 없이 채널로 협업) | \nMCP 도구 또는 curl | \n채널 ID · 스레드 permalink 가 URL | \n
| 아무것도 없음 | \n파일 모드 | \nHANDOFF.md 경로가 곧 주소 | \n
애매하면 파일 모드로 내려간다. 잘못된 트래커에 이슈를 만드는 것보다,\n파일 하나를 정확히 남기고 사용자에게 \"트래커를 쓰려면 알려달라\" 고 하는 게 낫다.\n권한이 없어 이슈 생성이 실패한 경우도 마찬가지 — 실패를 삼키지 말고 파일 모드로\n끝낸 뒤 실패 사실과 원인을 한 줄로 알린다.
\ngit branch --show-current && git status --short\ngit log --oneline -5\ngit worktree list\n\n# 열린 작업 — 트래커에 맞는 것만\ngh pr list && gh issue list --label handoff --state open # GitHub\nglab mr list -P 10 && glab issue list --label handoff -P 5 # GitLab\n\n# 띄워 둔 로컬 서버 — 포트는 이 레포 것으로 바꿔 적는다\nlsof -nP -iTCP -sTCP:LISTEN | grep -E '<앱이름>|<포트>' || true\n검증 게이트를 돌렸다면 결과 원문(통과/실패 줄)을 그대로 옮긴다. 안 돌렸으면\n\"안 돌림\" 이라고 적는다 — 돌린 척이 제일 위험하다.
\n레포의 HANDOFF.md 에 바로 쓰지 않는다 — 인프라가 있으면 이 본문은 이슈로 가고\n파일에는 포인터만 남기 때문이다. 세션 스크래치 디렉터리(또는 /tmp) 에 임시\n파일로 아래 \"본문 템플릿\" 전 항목을 채워 쓴다.
인프라가 전혀 없을 때만(0번 판별 결과 \"아무것도 없음\") 이 본문을 그대로 레포\n루트 HANDOFF.md 에 쓴다 — 이미 있으면 덮어쓴다. 핸드오프는 항상 \"지금\n상태\" 한 장이고, 과거 이력은 트래커와 그 레포의 작업 로그 파일\n(CURRENT_TASK.md 등)이 갖는다. 레포가 이 파일을 추적하지 않는다면\n(.gitignore) 커밋 대신 절대경로를 알린다.
본문은 인라인 --body \"$(...)\" 나 jq --arg 말고 파일 경유 — fenced code·표·\n백슬래시가 들어가면 escape 가 깨지고, 큰 본문은 ARG_MAX 를 넘겨 빈 요청이 된다.\n아래 <본문파일> 은 1-2 에서 쓴 스크래치 파일이다(레포의 HANDOFF.md 가 아니다).
# GitHub\ngh issue create --title \"핸드오프: <한 줄 요약> (<YYYY-MM-DD>)\" \\\n --label handoff --body-file <본문파일>.md\n\n# GitLab\nglab api --method POST \"projects/<owner>%2F<repo>/issues\" \\\n -F \"title=핸드오프: <한 줄 요약> (<YYYY-MM-DD>)\" \\\n -F \"labels=handoff\" \\\n -F \"description=@<본문파일>.md\" \\\n | python3 -c \"import json,sys;d=json.load(sys.stdin);print(d['iid'], d['web_url'])\"\n\n# Forgejo / Gitea — payload 를 파일로 만든 뒤 넘긴다(본문에 백틱·표가 들어가므로)\npython3 -c \"\nimport json;json.dump({'title':'핸드오프: <요약>','body':open('<본문파일>.md').read()}, open('payload.json','w'))\"\ncurl -s -X POST \"$FORGEJO_URL/api/v1/repos/<owner>/<repo>/issues\" \\\n -H \"Authorization: token $FORGEJO_TOKEN\" -H 'Content-Type: application/json' \\\n --data-binary @payload.json \\\n | python3 -c \"import json,sys;d=json.load(sys.stdin);print(d['number'], d['html_url'])\"\nJira / Plane / Slack 은 MCP 도구가 있으면 그것을 쓴다. 없을 때만 REST:
\n# Jira — description 은 ADF 가 기본이지만 대부분 wiki/plain 도 받는다. 프로젝트 키 필수.\ncurl -s -X POST \"$JIRA_URL/rest/api/3/issue\" \\\n -H \"Authorization: Bearer $JIRA_TOKEN\" -H 'Content-Type: application/json' \\\n --data-binary @payload.json \\\n | python3 -c \"import json,sys;d=json.load(sys.stdin);print(d['key'])\"\n# → URL 은 $JIRA_URL/browse/<KEY>\n\n# Plane\ncurl -s -X POST \"$PLANE_URL/api/v1/workspaces/$PLANE_WS/projects/$PLANE_PROJECT/issues/\" \\\n -H \"X-API-Key: $PLANE_TOKEN\" -H 'Content-Type: application/json' \\\n --data-binary @payload.json \\\n | python3 -c \"import json,sys;d=json.load(sys.stdin);print(d['id'], d.get('sequence_id'))\"\n\n# Slack — 티켓 대신 채널 스레드로 협업하는 팀. 본문이 길면 스니펫 업로드가 낫다.\n# 메시지 1건 → permalink 를 URL 로 쓴다 (chat.getPermalink).\npayload 는 셸에 인라인하지 말고 파일로 만든 뒤 --data-binary @ 로 넘긴다\n(위 두 명령의 payload.json). 토큰은 같은 줄에서 변수로만 쓰고 -v/--trace 를\n붙이지 않는다 — verbose 메타라인이 마스킹을 우회한다.
handoff 라벨(또는 그에 해당하는 Jira/Plane 라벨)이 없으면 먼저 만든다. 라벨이\n있어야 다음 세션이 \"열린 핸드오프\" 를 한 번에 찾는다.
HANDOFF.md 에 포인터를 쓰고 커밋한다인프라가 있으면 레포 루트 HANDOFF.md 를 아래 \"포인터 템플릿\"으로 (덮어)쓴다 —\n스크래치 파일의 본문을 옮기지 않는다, 이슈 URL·작성 시각·한 줄 요약·handoff\n라벨 이슈 목록 링크만 남긴다. 레포에 작업 로그 파일이 있으면 맨 위에도 이슈\nURL 한 줄을 남긴다.
파일 모드(인프라 없음)면 이 단계를 건너뛴다 — 1-2 에서 이미 전체 본문을\nHANDOFF.md 에 썼다. 그 경우 파일 맨 위에 \"트래커 없음 — 이 파일이 원본\" 이라고\n적는다.
git add HANDOFF.md && git commit -m \"docs: 세션 핸드오프 (<#N 또는 파일 모드>)\"\n브랜치에 커밋 중이면 푸시까지 한다 — 새 세션이 다른 워크트리에서 이어받을 수 있어야 한다.
\n인프라가 있으면 전체 URL, 없으면 파일 절대경로. /clear 후 그것만\n붙여넣으면 이어진다고 알린다. 파일 모드였다면 \"트래커를 붙이면 다음부터 이슈로\n만든다\" 도 한 줄 덧붙인다.
작업 이슈를 닫은 직후라면 1-2~1-4 대신 이 절차를 밟는다. 상태 수집(1-1)과 사용자\n안내(1-5)는 같다.
\nHANDOFF.md 가 대상이다. 항목마다 유효 / 소멸을\n가른다 — 함정·검증 환경 기동 명령·미결 판단은 대부분 다음 이슈에서도 유효하다.## 착수 메모 — <YYYY-MM-DD>). 유효한 항목은 옮겨 적는다. \"이전 이슈·MR 을\n본다\" 로 떠넘기지 않는다 — 링크는 출처 표시일 뿐 내용을 대신하지 못한다. 이번\n세션에서 새로 확정된 것과 물려받은 것을 구분해 적으면 다음 경계에서 다시 가르기 쉽다.# GitHub\ngh issue comment <다음 N> --body-file <메모파일>.md\n# GitLab\nglab api --method POST \"projects/<owner>%2F<repo>/issues/<다음 N>/notes\" -F \"body=@<메모파일>.md\"\n# Jira / Plane / Slack — MCP 도구로 해당 티켓·스레드에 댓글\n게시한 뒤 빠진 것을 발견하면 코멘트를 하나 더 달지 말고 그 코멘트를 고친다 —\n읽을 곳이 둘이 되는 순간 같은 문제가 다시 생긴다. 이 세션이 이어받았던 핸드오프\n이슈가 열려 있으면 3장대로 닫고, 닫는 코멘트에 다음 작업 이슈 URL 을 적는다.
\nHANDOFF.md 는 이 갈래에서 쓰지 않는다. 레포에 이전 것이 남아 있으면 맨 위에\n# 종료 — <날짜> 와 다음 작업 이슈 URL 을 적어 낡은 포인터를 최신으로 오해하지\n않게 한다.
인프라가 있으면 HANDOFF.md 는 포인터다 — 먼저 그 파일을 읽고 적힌 이슈\nURL 을 연다. 파일 자체를 재개 상태로 쓰지 않는다. 인프라가 없으면 파일 자체가\n본문 전체다.
cat HANDOFF.md # 포인터: 이슈 URL 을 얻는다 (인프라 없으면 이 파일이 본문 전체)\n\n# GitHub\ngh issue view <N> --comments\n# GitLab\nglab issue view <N>\nglab api \"projects/<owner>%2F<repo>/issues/<N>/notes\" | python3 -c \"\nimport json,sys\nfor n in json.load(sys.stdin): print('---', n['author']['username'], n['created_at']); print(n['body'][:2000])\"\n# Jira / Plane / Slack — MCP 도구로 본문과 댓글/스레드 답글을 함께 읽는다\n코멘트가 본문보다 최신일 수 있다 — 이슈 모드면 항상 둘 다 읽는다. 받은 URL 이\n핸드오프 이슈가 아니라 작업 이슈여도 절차는 같다(이슈 경계 갈래로 넘겨받은 경우):\n본문이 범위·검증 기준이고 착수 메모 코멘트가 재개 상태다. 파일 모드는\n파일 하나가 전부이지만, 그만큼 git log 로 언제 갱신됐는지를 같이 본다\n(git log -1 --format='%ci' -- HANDOFF.md).
적힌 것 중 행동을 바꾸는 단언 1~2개는 실제와 대조한 뒤 움직인다. 실전에서\n\"열려 있다\" 던 PR 이 이미 머지돼 있던 적이 있다.
\n| 적혀 있는 것 | \n확인 | \n
|---|---|
| 브랜치/워크트리 | \ngit worktree list, git branch -a --contains <sha> | \n
| PR/MR 상태 | \ngh pr view <N> / glab mr view <N> — 이미 머지됐을 수 있다 | \n
| 이슈/티켓 상태 | \ngh issue view <N> / glab issue view <N> / Jira·Plane 조회 — 이미 닫혔을 수 있다 | \n
| 띄워 둔 서버 | \ncurl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:<port>/ | \n
| 배포된 버전 | \n서비스의 /version·/healthz 를 직접 친다 | \n
| 다음 명령 | \n경로·스크립트가 아직 있는지 (ls, git show --stat) | \n
충돌하면 실제 상태를 믿고 이슈에 코멘트로(파일 모드면 파일에) 교정한다.
\ngit worktree add ../<repo>-<n> <branch>.checkout/switch 금지(pull·읽기만) — 다른 세션의 발밑이 바뀐다.이어받은 작업이 끝나면(또 다른 핸드오프를 쓰는 경우 포함) 핸드오프를 닫는다.
\n# GitHub\ngh issue comment <N> --body-file <결과파일>.md && gh issue close <N>\n# GitLab\nglab api --method POST \"projects/<owner>%2F<repo>/issues/<N>/notes\" -F \"body=@<결과파일>.md\"\nglab issue close <N>\n# Jira / Plane — MCP 도구로 댓글 + 상태를 Done/Completed 로\n# Slack — 같은 스레드에 결과를 답글로 달고 해결 이모지 등 팀 규약을 따른다\n파일 모드면 HANDOFF.md 맨 위에 # 종료 — <날짜> 와 결과를 적고 커밋한다.\n다음 핸드오프를 쓰는 경우라면 그 파일을 새 내용으로 덮어쓰는 것이 종료다.
이슈 경계 갈래로 받은 세션은 닫을 핸드오프 이슈가 없다 — 작업 이슈의 통상 종료(결과\n코멘트 + 클로즈)가 곧 종료이고, 다음 작업이 이어지면 1-6 으로 그 이슈에 메모를 남긴다.
\n닫을 때 한 줄: 무엇이 끝났고, 다음 핸드오프가 있으면 그 URL/경로.\n열린 핸드오프가 둘 이상 쌓이면 어느 게 최신인지 모른다 — 동시에 하나만 연다.
\nHANDOFF.md# HANDOFF — <한 줄 요약>\n\n- 이슈: <URL> (트래커가 없으면 \"없음 — 이 파일이 원본\")\n- 작성: <YYYY-MM-DD HH:MM:SS.mmm>\n- 작업 이슈/PR: #<N> · #<M> (<상태>)\n- 브랜치: `<branch>` · 워크트리: `<path>` (없으면 \"없음 — 새로 만들 것\")\n- HEAD: `<sha>` (<push 여부>)\n\n## 지금 어디까지\n\n<끝난 것 / 안 끝난 것을 사실로. \"대체로 됨\" 금지.>\n\n## 검증 결과 (원문)\n\n```\n<테스트·빌드·게이트의 마지막 실행 결과 그대로. 안 돌렸으면 \"안 돌림\">\n```\n\n## 실행 중인 것\n\n| 대상 | 주소 | 어떻게 띄웠나 |\n| --- | --- | --- |\n| <로컬 서버> | <http://127.0.0.1:포트> | <명령 + 실행 디렉터리> |\n| <터널/프록시> | <127.0.0.1:포트> | <스크립트 경로, pid> |\n\n## 미결 판단\n\n<사람이 정해야 하는 것. 선택지와 각 선택의 결과까지.>\n\n## 다음에 칠 명령\n\n```bash\n# 복붙 가능한 형태로, 실행 디렉터리 포함\ncd <절대경로>\n<command>\n```\n\n## 함정\n\n<이번에 밟은 것. 도구·플랫폼 차이, 잘못 읽기 쉬운 신호 등.>\nHANDOFF.md (본문은 위 템플릿으로 만든 이슈에 있다)# HANDOFF (포인터)\n\n세션 인계 본문은 <트래커> 이슈에 있다. 이 파일은 그 위치만 가리킨다.\n\n- 현재 핸드오프: <이슈 URL>\n- 작성: <YYYY-MM-DD HH:MM:SS.mmm>\n- 요약: <한 줄 — 무엇이 막혀 있고 뭘 기다리는지>\n- 전체 목록: <handoff 라벨 이슈 목록 URL>\nHANDOFF.md 는 포인터. 인프라 없으면 원본은 파일.\n트래커가 없거나 실패해도 핸드오프는 완성된다..env 값·토큰·비밀번호를 넣지 않는다. 키 이름까지만. 트래커가 공개\n채널이면 내부 호스트명·경로도 한 번 더 걸러 본다.