Claude Code로 몇 주짜리 작업 이어 가기: RESUME·인계 문서와 맥락 60%·70% 규칙

기준: Claude Code 공식 문서(Status line, Hooks reference, Commands, Context window)와 Git Bash가 설치된 Windows 11의 Node.js 24. 2026년 11월 5일에 확인했습니다. 그림 1은 작업 폴더의 git 기록으로 그린 도표이고, 그림 2는 이 글의 예제 스크립트를 실제로 돌린 출력 글자를 터미널 모양으로 옮긴 그림입니다.

Claude Code와 하루 이틀에 끝나는 일을 할 때는 대화 하나로 충분합니다. 몇 주씩 이어지는 일은 다릅니다. 대화가 길어지면 Claude Code가 앞 내용을 요약해 줄이고, 요약에서 빠진 결정은 다음 날 다시 설명해야 합니다. 새 대화를 열면 처음부터 다시 알려 줘야 합니다.

이 글은 Blender 영상 제작을 Claude Code로 몇 주째 이어 가는 작업 폴더에서 실제로 쓰는 방법을 옮깁니다. 기억을 대화에 두지 않고 파일에 둡니다. 대화는 언제든 끊어도 되게 하고, 새 대화는 파일 몇 장만 읽고 바로 이어 가게 만듭니다.

이 글을 마치면 아래를 할 수 있습니다.

1. 맥락 창이 차면 무슨 일이 생기는지 구분합니다.
2. 새 세션이 가장 먼저 읽을 파일 세 종류(CLAUDE.md, RESUME, 인계 문서)를 만듭니다.
3. 하루를 마칠 때 쓰는 /handoff 명령을 만듭니다.
4. 상태 줄에 맥락 사용률을 띄우고, 60%와 70%에서 Claude에게 알리는 훅을 붙입니다.
5. 새 세션에서 어디까지 읽고 시작할지 정합니다.

시작 전에: Claude Code가 설치되어 있어야 합니다. 설치는 Claude Code 입문에 있습니다. 4절의 예제는 Node.js로 씁니다. 명령 프롬프트에서 node -v를 쳐서 버전이 나오면 준비된 것입니다. Windows에서는 Git for Windows(Git Bash)도 설치해 두세요. 4절의 상태 줄과 훅은 Git Bash에서 돌아가는 것을 기준으로 씁니다.

1. 맥락 창이 차면 생기는 일

**맥락 창(context window)**은 Claude가 한 대화에서 한 번에 볼 수 있는 글의 양입니다. 책상 넓이와 같습니다. 대화, 읽은 파일, 명령 결과가 모두 책상 위에 쌓입니다. 책상이 차면 오래된 서류부터 정리해야 합니다. 뜻은 토큰과 컨텍스트 창 뜻에 자세히 있습니다.

Claude Code에서 책상을 정리하는 방법은 세 가지입니다.

표에서 볼 점은 요약에 무엇이 남을지 내가 고르지 못한다는 것입니다. /compact 뒤에 focus on …처럼 지시를 붙일 수는 있지만, 몇 주 동안 쌓인 결정을 요약 한 번에 다 담기는 어렵습니다. 반대로 CLAUDE.md는 압축 뒤에도 디스크에서 다시 읽힙니다. 그래서 오래 남아야 하는 것은 대화가 아니라 파일에 적어 둡니다.

2. 새 세션이 읽을 파일 세 종류

여기서는 파일을 세 층으로 나눕니다. 새 세션은 위에서부터 필요한 만큼만 읽습니다.

세 층으로 나누는 까닭은 새 세션이 읽는 양을 줄이기 위해서입니다. 새 세션은 안내문과 포스트잇만 읽고 일을 시작합니다. 업무 일지는 그 일을 자세히 알아야 할 때만 엽니다.

2-1. CLAUDE.md에 "세션 시작" 절 넣기

시작 상태: 이어 갈 프로젝트 폴더를 엽니다. 폴더 맨 위에 CLAUDE.md가 없으면 새로 만듭니다.

따라 하기:

1. 프로젝트 폴더 맨 위의 CLAUDE.md를 메모장으로 엽니다.
2. 맨 위에 아래 절을 붙여 넣고 저장합니다.

## 세션 시작
1. RESUME.md 맨 위 "지금 요약" 절만 읽는다. 아래 이력은 필요할 때만 연다.
2. 요약의 "볼 파일"과 "다음 한 걸음"으로 시작한다.
3. 큰 파일(2천 줄이 넘는 것)은 통째로 읽지 않고, 필요한 부분만 찾거나 서브에이전트에게 요약을 맡긴다.

## 맥락 규칙
- 맥락 사용률 60%부터는 새 작업을 시작하지 않고 지금 단계만 마친다.
- 70%가 되면 /handoff로 인계를 쓰고 새 세션에서 이어 간다.

CLAUDE.md는 짧을수록 좋습니다. 이 작업 폴더도 처음에는 표와 경위를 CLAUDE.md에 다 넣어 13 KB(121줄)까지 불어났습니다. 10월 11일에 자세한 표를 다른 문서로 옮기고 5 KB(60줄)로 줄였습니다. 매번 읽히는 파일이 길면, 아직 일을 시작하지도 않았는데 책상이 좁아집니다.

2-2. RESUME.md에 "지금 요약" 만들기

따라 하기:

1. 프로젝트 폴더 맨 위에 RESUME.md를 만듭니다.
2. 아래 틀을 붙여 넣고, 지금 상태로 칸을 채웁니다.

# <프로젝트 이름> 이어하기

## 지금 요약 (<날짜> 인계)

**한 줄:** <지금 어디까지 왔고 무엇에서 멈췄는지 한 문장>

| 무엇 | 내용 |
|---|---|
| 볼 파일 | <결과물이나 비교 그림 경로> |
| 다음 한 걸음 | <새 세션이 맨 먼저 할 일 하나> |
| 사람이 정할 것 | <결정을 기다리는 것> |
| 배운 것 | <다음에 같은 실수를 막는 한 줄> |
| 인계 | reports/<날짜>_인계_<분야>.md |

## 이력: <날짜> <한 일>
- (지난 요약은 여기로 내린다)

규칙은 두 가지입니다. 첫째, "지금 요약"은 30줄을 넘기지 않습니다. 넘으면 오래된 것을 아래 "이력" 절로 내립니다. 둘째, 요약은 고쳐 쓰고, 덧붙이지 않습니다. 덧붙이기만 하면 요약이 다시 일지가 됩니다.

2-3. 고쳐 쓰지 않으면 생기는 일

그림 1. 분야별 진행 상황을 적는 한 장짜리 상태판의 줄 수. 커밋이 있던 날만, 그날 가장 많았던 줄 수 (도표, 작업 폴더의 git 기록)

이 작업 폴더에는 분야마다 지금 상태를 적는 한 장짜리 상태판이 있습니다. 처음에는 새 소식이 생길 때마다 줄을 덧붙였습니다. 그림 1처럼 일주일 만에 65줄이 143줄이 됐고, 새 세션이 상태판을 다 읽지 못하는 일이 생겼습니다. 10월 11일에 규칙을 바꿨습니다. 분야마다 한 줄만 두고, 그 줄을 고쳐 씁니다. 지난 경과는 인계 문서와 RESUME로 보냅니다. 그 뒤로 한 달 가까이 80줄 안팎을 지키고 있습니다.

RESUME의 "지금 요약"도 같습니다. 30줄 상한을 둔 까닭이 여기에 있습니다.

3. 하루를 마치는 /handoff 명령

인계를 매번 손으로 쓰면 빼먹는 칸이 생깁니다. 순서를 명령 하나로 만들어 둡니다. Claude Code는 .claude/commands/<이름>.md 파일을 /<이름> 명령으로 씁니다. 공식 문서는 새로 만드는 명령에는 스킬(.claude/skills/<이름>/SKILL.md)을 권하지만, 명령 파일도 그대로 동작합니다. 여기서는 파일 하나로 끝나는 명령 파일을 씁니다.

따라 하기:

1. 프로젝트 폴더 안에 .claude\commands 폴더를 만듭니다.
2. 그 안에 handoff.md를 만들고 아래를 붙여 넣은 뒤 저장합니다.

---
description: 오늘 작업 인수인계 기록
---
오늘 이 세션에서 한 일을 정리해서 다음 세션이 바로 이어 갈 수 있게 남긴다.

1. RESUME.md 맨 위 "지금 요약" 절(30줄 이내)을 지금 상태로 고쳐 쓴다.
   - 칸: 한 줄, 볼 파일, 다음 한 걸음, 사람이 정할 것, 배운 것, 인계 문서 경로
   - 덧붙이지 말고 고쳐 쓴다. 30줄을 넘으면 오래된 것을 아래 "이력" 절로 내린다.
2. reports/<오늘 날짜>_인계_<분야>.md 에 오늘 한 일을 자세히 쓴다.
   - 한 일, 결과 파일 경로, 남은 일, 막힌 것과 까닭, 사람에게 물어볼 것
3. 한 일의 결과는 파일에 있는 것만 쓴다. 기억에만 있는 숫자나 결과는 쓰지 않는다.
4. 마지막으로 나에게 세 줄로 보고한다: 오늘 끝낸 것, 내가 확인할 것, 다음에 할 것.

3. Claude Code를 새로 열고 입력 칸에 /를 칩니다. 목록에 /handoff가 보이면 됩니다.

3번 규칙("파일에 있는 것만 쓴다")은 일부러 넣었습니다. 긴 대화 끝에는 요약된 기억과 실제 파일이 어긋날 수 있습니다. 인계 문서에 틀린 숫자가 들어가면 다음 세션이 그것을 사실로 믿고 이어 갑니다.

인계 문서는 9월 30일부터 11월 5일까지 80개 쌓였습니다. 새 세션은 그중 어제 것 하나만 필요할 때 엽니다.

4. 맥락 60%·70%를 알려 주는 상태 줄과 훅

인계는 "언제" 할지가 어렵습니다. 일에 몰두하면 맥락이 얼마나 찼는지 잊습니다. 그래서 두 가지를 붙입니다.

• 상태 줄(status line): Claude Code 화면 아래에 늘 보이는 한 줄입니다. 자동차 계기판의 연료 눈금과 같습니다. 여기에 맥락 사용률을 띄웁니다.
• UserPromptSubmit 훅: 여러분이 말을 보낼 때마다 Claude Code가 실행하는 스크립트입니다. 연료 경고등과 같습니다. 사용률이 기준을 넘으면 Claude에게 짧은 안내를 붙여 보냅니다.

둘은 파일 하나로 이어집니다. 상태 줄 스크립트가 맥락 %를 ~/.claude/ctx/<세션 ID>.json에 적고, 훅이 그 파일을 읽습니다. 훅이 받는 입력에는 맥락 %가 없고, 상태 줄이 받는 입력에는 있기 때문입니다.

60%와 70%는 이 작업 폴더가 정한 선입니다. 공식 권장값이 아닙니다. 70%에서 인계를 시작해도 인계 문서를 쓰고 확인할 자리가 남도록 잡은 값입니다. 여러분 작업에 맞게 바꿔도 됩니다.

4-1. 상태 줄 스크립트 만들기

시작 상태: 2절까지 마친 프로젝트 폴더에서 이어 갑니다.

따라 하기:

1. 탐색기 주소창에 %USERPROFILE%\.claude를 넣고 Enter를 누릅니다. 여러분의 Claude Code 사용자 설정 폴더가 열립니다.
2. 그 안에 statusline.mjs를 만들고 아래를 그대로 붙여 넣은 뒤 저장합니다.

// 상태 줄: 모델 이름과 맥락 사용률을 보여 주고, 세션마다 맥락 %를 파일로 남긴다.
import fs from "node:fs";
import path from "node:path";
import os from "node:os";

let input = "";
process.stdin.on("data", (chunk) => (input += chunk));
process.stdin.on("end", () => {
  let data = {};
  try { data = JSON.parse(input.replace(/^\uFEFF/, "")); } catch {}
  const model = data.model?.display_name ?? "Claude";
  const pct = data.context_window?.used_percentage;

  // 다른 스크립트(훅)가 읽을 수 있게 세션별 파일로 남긴다
  if (data.session_id && typeof pct === "number") {
    try {
      const dir = path.join(os.homedir(), ".claude", "ctx");
      fs.mkdirSync(dir, { recursive: true });
      fs.writeFileSync(path.join(dir, `${data.session_id}.json`), JSON.stringify({ ctx: pct, t: Date.now() }));
    } catch {}
  }

  const shown = typeof pct === "number" ? `${Math.round(pct)}%` : "?";
  console.log(`[${model}] context ${shown}`);
});

3. 같은 폴더의 settings.json을 엽니다. 없으면 새로 만듭니다. 아래 statusLine 칸을 넣고 저장합니다. <사용자 이름>은 여러분의 Windows 사용자 폴더 이름으로 바꿉니다.

{
  "statusLine": {
    "type": "command",
    "command": "node \"C:/Users/<사용자 이름>/.claude/statusline.mjs\""
  }
}

settings.json에 이미 다른 칸이 있으면, 맨 바깥 { } 안에 "statusLine": {…}만 쉼표로 이어 넣습니다. 경로는 역슬래시(\) 대신 슬래시(/)로 씁니다. Windows의 Claude Code는 Git Bash가 있으면 Git Bash로 이 명령을 실행하는데, Git Bash는 역슬래시를 지워 버려 경로가 깨집니다.

상태 줄은 세션을 열 때, Claude의 답이 올 때마다, /compact가 끝날 때 다시 그려집니다. 세션 처음에는 아직 사용률 값이 없어서 context ?로 보일 수 있습니다. 사용률은 입력 쪽 토큰(대화, 읽은 파일, 캐시)만 셉니다.

4-2. 맥락 감시 훅 만들기

따라 하기:

1. 프로젝트 폴더 안에 .claude\hooks 폴더를 만듭니다.
2. 그 안에 ctx_watch.mjs를 만들고 아래를 그대로 붙여 넣은 뒤 저장합니다.

// UserPromptSubmit 훅: 말을 보낼 때마다 이 세션의 맥락 %를 읽어, 기준을 넘었으면 Claude에게 알린다.
import fs from "node:fs";
import path from "node:path";
import os from "node:os";

const WARN = 60;     // 새 일을 시작하지 않는 선
const HANDOFF = 70;  // 인계하고 새 세션으로 옮기는 선

let input = "";
process.stdin.on("data", (chunk) => (input += chunk));
process.stdin.on("end", () => {
  try {
    const data = JSON.parse(input.replace(/^\uFEFF/, "") || "{}");
    const sid = String(data.session_id || "");
    if (!sid || /[\\/.]/.test(sid)) return;
    const file = path.join(os.homedir(), ".claude", "ctx", `${sid}.json`);
    if (!fs.existsSync(file)) return;
    const pct = JSON.parse(fs.readFileSync(file, "utf8")).ctx;
    if (typeof pct !== "number" || pct < WARN) return;

    const text = pct >= HANDOFF
      ? `이 세션의 맥락 사용률은 ${Math.round(pct)}%입니다. 이 프로젝트의 규칙상 ${HANDOFF}%부터는 새 작업을 시작하지 않고, 지금 단계를 마친 뒤 /handoff로 인계 문서를 쓰고 새 세션에서 이어 갑니다.`
      : `이 세션의 맥락 사용률은 ${Math.round(pct)}%입니다. 이 프로젝트의 규칙상 ${WARN}%부터는 새 작업을 시작하지 않고 지금 단계만 마칩니다.`;
    process.stdout.write(JSON.stringify({
      hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: text },
    }));
  } catch {
    // 읽지 못하면 아무것도 하지 않는다(대화를 막지 않는다)
  }
});

3. 프로젝트 폴더의 .claude\settings.json을 엽니다. 없으면 새로 만듭니다. 아래를 넣고 저장합니다.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/ctx_watch.mjs\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

훅 스크립트에서 눈여겨볼 곳이 세 군데 있습니다.

• 안내는 명령이 아니라 사실로 씁니다. 공식 문서는 훅이 넣는 글을 "배포 대상은 production입니다"처럼 사실 문장으로 쓰라고 권합니다. 시스템 명령처럼 보이는 글은 Claude가 끼어든 지시로 보고 여러분에게 되물을 수 있습니다. 그래서 "멈춰라"가 아니라 "이 프로젝트의 규칙상 …합니다"로 썼습니다.
• 읽지 못하면 조용히 넘어갑니다. 이 훅은 말을 보낼 때마다 실행되고, 끝날 때까지 Claude가 기다립니다. 오류로 대화를 막으면 안 되므로 모든 실패를 catch에서 삼킵니다. timeout도 5초로 짧게 줬습니다(이 훅의 기본값은 30초입니다).
• 훅은 알리기만 합니다. 세션을 스스로 끝내거나 새로 열지는 못합니다. /clear와 새 세션 시작은 여러분이 합니다.

4-3. 먼저 시험하기

Claude Code에 붙이기 전에, 스크립트만 따로 돌려 봅니다. 가짜 입력 JSON을 넣고 출력이 맞는지 봅니다.

따라 하기:

1. Git Bash를 열고 cd로 statusline.mjs가 있는 사용자 설정 폴더(~/.claude)로 갑니다.
2. 아래 두 줄을 차례로 실행합니다. 첫 줄의 65를 42, 74로 바꿔 가며 되풀이합니다.

echo '{"session_id":"demo-session","model":{"display_name":"Opus"},"context_window":{"used_percentage":65}}' | node statusline.mjs
echo '{"session_id":"demo-session","prompt":"hi"}' | node "/c/<프로젝트 폴더>/.claude/hooks/ctx_watch.mjs"

그림 2. 상태 줄 스크립트와 훅을 42%, 65%, 74%로 돌린 결과. 그림은 첫 명령의 입력 JSON을 줄여 보였고, 훅의 JSON 출력은 읽기 쉽게 줄을 나눴습니다. 실제 출력은 한 줄입니다 (실행 출력, Git Bash)

그림 2처럼 세 가지가 나오면 됩니다. 42%에서는 상태 줄 글자만 나오고 훅은 아무것도 출력하지 않습니다. 65%에서는 60% 안내가, 74%에서는 /handoff 안내가 나옵니다. 시험이 끝나면 ~/.claude/ctx/demo-session.json은 지워도 됩니다.

시험이 맞으면 Claude Code를 엽니다. 화면 아래에 [모델 이름] context N%가 보이면 상태 줄이 붙은 것입니다.

5. 새 세션에서 이어 가는 순서

훅이 70%를 알리면 아래 순서로 옮깁니다.

따라 하기:

1. 지금 하던 단계(파일 하나 고치기, 시험 한 번 돌리기)만 마칩니다.
2. /handoff를 실행합니다. Claude가 RESUME의 "지금 요약"과 인계 문서를 고친 뒤 세 줄로 보고합니다.
3. RESUME.md를 직접 열어 "다음 한 걸음"이 한 가지로 적혔는지 봅니다.
4. /clear를 실행합니다. 앞 대화는 지워지지 않고 /resume 목록에 남습니다.
5. 새 대화에 "RESUME 지금 요약부터 이어 가자"라고 보냅니다. CLAUDE.md의 "세션 시작" 절 덕분에 Claude가 요약만 읽고 시작합니다.

여기서는 한 걸음 더 나눕니다. 일을 분야별 "작업 줄"로 나누고, 줄마다 카드 한 장(읽을 것, 흐름, 넘기는 것)을 둡니다. 새 세션은 /lane <줄 이름>으로 시작해 그 카드와 그 줄의 RESUME 요약만 읽습니다. 분야가 여러 개면 새 세션이 다른 분야의 기록까지 읽느라 책상을 채우는 일을 막아 줍니다.

6. 긴 작업에서 함께 지키는 것

서브에이전트에게 일을 나누는 방법은 서브에이전트와 멀티 에이전트에 있습니다.

연습 문제

1. 지금 하는 프로젝트 하나를 골라 RESUME.md "지금 요약"을 15줄 안으로 써 보세요. "다음 한 걸음"이 한 가지인지 확인합니다.
2. /context를 실행해 지금 맥락에서 가장 큰 칸이 무엇인지 적어 보세요.
3. ctx_watch.mjs의 WARN을 50으로 바꾸고 4-3절 시험을 다시 돌려 보세요. 42%와 65%에서 출력이 어떻게 달라지는지 보세요.
4. 하루를 마칠 때 /handoff를 실행하고, 다음 날 새 세션에서 RESUME만 읽고 이어 갈 수 있었는지 적어 보세요.

자주 하는 실수와 해결

한 줄 정리

기억은 파일에(CLAUDE.md → RESUME 지금 요약 → 인계 문서), 맥락은 눈금으로(상태 줄), 넘어가는 때는 경고등으로(60% 멈춤·70% 인계). 훅을 처음 만든다면 아래 첫 글의 위험한 명령 막기 예제가 좋은 짝입니다.

함께 읽기

• Claude Code 훅으로 AI 에이전트의 위험한 명령 막기
• 토큰과 컨텍스트 창 뜻
• 서브에이전트와 멀티 에이전트: AI 여러 명에게 일 나누기

참고 자료

• Claude Code Docs: Customize your status line
• Claude Code Docs: Hooks reference
• Claude Code Docs: Commands
• Claude Code Docs: Explore the context window
• Claude Code Docs: Extend Claude with skills
• 그림 라이선스: 그림 1·2는 AZTechnology가 작업 폴더의 기록과 이 글의 예제로 만든 그림입니다.