Claude Code 세션 인수인계 템플릿: 다음 사람과 AI 에이전트를 위한 문맥 남기기

Claude Code를 오래 쓰다 보면 문제는 모델의 실력이 아니라 세션 사이의 단절에서 자주 생깁니다. Claude Code가 관련 파일을 찾고, 버그 원인을 좁히고, 일부 수정까지 했는데 마지막에 “내일 이어서”만 남기면 다음 사람은 같은 조사를 다시 시작합니다.

이 글은 그 단절을 줄이기 위한 세션 인수인계 템플릿입니다. handoff는 여기서 “다음 사람이나 다음 AI 에이전트 세션이 바로 이어서 일할 수 있게 남기는 짧은 작업 메모”입니다. 긴 회고가 아니라 목표, 현재 상태, 변경 이유, 검증 증거, 남은 위험, 다음 프롬프트를 정리하는 운영 문서입니다.

공식 기준은 최신 Claude Code 문서를 확인하세요. How Claude Code works는 에이전트 루프, 프로젝트 접근, git 상태, 세션과 컨텍스트를 설명합니다. Memory는 CLAUDE.md와 프로젝트 지시를 설명하고, CLI reference는 CLI 사용법을 다룹니다. 함께 읽을 내부 글로는 CLAUDE.md best practices, verification receipt workflow, team handoff rules가 좋습니다.

먼저 역할을 나눈다

초보자가 자주 하는 실수는 CLAUDE.md와 인수인계 메모를 섞는 것입니다. CLAUDE.md는 장기 규칙입니다. 빌드 명령, 코드 스타일, 아키텍처 규칙, 리뷰 기준, 건드리면 위험한 경로처럼 매 세션에서 유효한 내용을 둡니다.

인수인계 메모는 오늘 작업의 임시 상태입니다. 어떤 파일을 읽었는지, 어떤 가설이 틀렸는지, 무엇을 검증했는지, 무엇이 아직 미확인인지, 다음에 어떤 프롬프트로 시작해야 하는지 기록합니다. context는 작업 배경, verification receipt는 검증 영수증, harness는 에이전트가 안전하게 일하도록 잡아주는 작업 틀로 설명하면 쉽습니다.

flowchart LR
  A["Goal<br/>무엇을 달성할까"] --> B["Current state<br/>어디서 멈췄나"]
  B --> C["Evidence<br/>무엇을 확인했나"]
  C --> D["Risk<br/>무엇이 불확실한가"]
  D --> E["Next prompt<br/>다음에 무엇을 시킬까"]

이 흐름이 있으면 다음 작업자는 전체 대화 기록을 읽기 전에 의미 있는 첫 명령을 실행할 수 있습니다.

바로 쓰는 Markdown 템플릿

# Claude Code session handoff

## Goal
- target outcome:
- explicitly out of scope:

## Current state
- branch:
- dirty files:
- related URL:
- what is known:

## What changed
- changed files:
- reason for change:
- important files not touched:

## Verification receipt
- commands run:
- result:
- manual checks:
- not checked:

## Risks and constraints
- fragile area:
- do not touch:
- requires approval:

## Next prompt
In the next session, compare git status with this handoff, then continue from the unchecked verification items.

가장 중요한 항목은 not checked입니다. 로컬 build가 성공해도 공개 URL, 모바일 화면, CTA 링크, 분석 이벤트, 번역 문구가 맞다는 뜻은 아닙니다. 확인하지 못한 것을 숨기지 않으면 다음 세션은 추측이 아니라 검증부터 시작합니다.

JSON으로 상태를 구조화하기

GitHub Issue, Slack, Notion, 내부 대시보드로 인수인계를 넘긴다면 Markdown 옆에 작은 JSON 요약을 두면 좋습니다.

{
  "slug": "claude-code-session-handoff-template",
  "goal": "Improve the published multilingual article group",
  "status": "draft updated, verification pending",
  "files": [
    "site/src/content/blog/claude-code-session-handoff-template.mdx",
    "site/src/content/blog-en/claude-code-session-handoff-template.mdx"
  ],
  "checksRun": ["frontmatter parse", "code fence scan"],
  "checksMissing": ["production URL check"],
  "nextAction": "Run targeted validation and review locale copy"
}

JSON은 도구가 읽기 쉽지만 판단 이유까지 담기에는 건조합니다. 이유와 맥락은 Markdown에 쓰고, 상태와 체크 목록은 JSON에 두는 방식이 실무에서 가장 다루기 쉽습니다.

실행 가능한 Node.js 스크립트

다음 코드를 scripts/write-handoff.mjs로 저장하세요. Node.js 내장 모듈만 사용하며 현재 git 상태를 읽어 handoffs/ 폴더에 날짜가 붙은 Markdown 파일을 만듭니다.

import { execSync } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";

function run(command) {
  try {
    return execSync(command, { encoding: "utf8" }).trim() || "(no output)";
  } catch (error) {
    return `ERROR: ${error.message}`;
  }
}

const date = new Date().toISOString().slice(0, 10);
const branch = run("git branch --show-current");
const status = run("git status --short");
const recentCommit = run("git log -1 --oneline");
const outDir = "handoffs";
const outFile = join(outDir, `${date}-session-handoff.md`);

mkdirSync(outDir, { recursive: true });

const body = `# Claude Code session handoff

## Goal
-

## Current state
- branch: ${branch}
- recent commit: ${recentCommit}
- dirty files:
\`\`\`text
${status}
\`\`\`

## What changed
-

## Verification receipt
- commands:
- result:
- missing:

## Risks and constraints
-

## Next prompt
Read this handoff, compare it with git status, and continue from the missing verification items.
`;

writeFileSync(outFile, body, "utf8");
console.log(`Wrote ${outFile}`);

먼저 문법을 확인하고 실행합니다.

node --check scripts/write-handoff.mjs
node scripts/write-handoff.mjs

실무에서 효과가 큰 사용 사례

첫째, 다국어 콘텐츠 공개입니다. 한 slug에 일본어, 영어, 중국어, 한국어, 스페인어, 프랑스어, 독일어, 포르투갈어, 힌디어, 인도네시아어 파일이 있으면 어느 locale이 아직 자연스럽지 않은지 놓치기 쉽습니다. 인수인계에는 남은 locale, description 길이, 내부 링크, /products/와 /training/ CTA 확인 여부를 적습니다.

## Goal
- raise the 10-locale article group for slug claude-code-session-handoff-template to publish quality

## Current state
- Japanese canonical body updated
- English and Indonesian reviewed for natural tone
- zh, ko, and hi still need mojibake scan

## Verification receipt
- frontmatter parse: pass
- JSON code block parse: pass
- production URL: not checked

## Next prompt
Check the remaining locale files for mojibake, description length, and missing CTA links. Report only unresolved items.

둘째, 버그 조사가 중간에 멈춘 경우입니다. 예를 들어 “390px 폭에서 가격 카드의 min-width 때문에 CTA가 넘친다”는 사실을 알아냈다면 그 문장을 남겨야 합니다. “CSS 봄”은 다음 사람에게 거의 도움이 되지 않습니다.

셋째, 위험한 코드 리뷰입니다. 인증, 결제, DB migration, 권한 변경은 “리뷰 중”이라는 말로 부족합니다. 어떤 위험을 봤는지, 어떤 테스트가 빠졌는지, 병합 전에 누가 승인해야 하는지를 적어야 합니다.

넷째, 여러 작업자나 AI 에이전트가 동시에 움직이는 경우입니다. 다른 사람이 다른 slug나 브랜치를 맡고 있다면 이번 세션에서 만져도 되는 파일과 만지면 안 되는 파일을 명시합니다. 이 한 줄이 다른 사람의 변경을 덮는 사고를 줄입니다.

피해야 할 실패 사례

실패 1: 파일 경로만 나열합니다. site/src/pages/products.astro보다 “가격 카드 min-width가 390px에서 overflow를 만든다”가 훨씬 유용합니다.

실패 2: 성공한 검증만 씁니다. npm run build 성공은 중요하지만 공개 URL, 모바일 레이아웃, 클릭 추적, 폼 전송, 번역 품질을 증명하지는 않습니다.

실패 3: 긴 대화 요약을 남깁니다. 기록은 길지만 다음 행동이 없으면 다시 읽는 비용만 늘어납니다. 마지막은 항상 붙여 넣을 수 있는 next prompt로 끝내세요.

실패 4: 민감 정보를 그대로 붙입니다. API key, 고객 정보, 내부 가격, 비공개 장애 링크는 쓰지 않습니다. 필요한 경우 secret 이름이나 안전한 내부 문서 위치만 남깁니다.

수익 흐름도 같이 넘긴다

ClaudeCodeLab 같은 콘텐츠 사이트에서는 기술 품질과 수익 흐름을 분리할 수 없습니다. 본문이 좋아도 내부 링크, 무료 자료, 상품 페이지, 상담 페이지가 빠지면 독자의 다음 행동이 끊깁니다. 개인 독자는 무료 자료에서 시작하고, 반복 가능한 템플릿과 체크리스트가 필요하면 products를 봅니다. 팀이 실제 저장소에 CLAUDE.md, 권한, 리뷰 게이트, 검증 영수증, 인수인계 규칙을 넣어야 한다면 Claude Code training and consultation이 맞습니다.

세션 종료 전 30초만 투자해 목표, 현재 상태, 증거, 미확인 항목, 다음 프롬프트를 남기세요. Masa의 공개 작업에서 이 방식을 써 보니, 다음 날 첫 프롬프트가 짧아지고 어제 어디까지 봤는지 찾는 시간이 줄었습니다.