Claude Code로 레거시 코드를 고칠 때 세션 토큰을 80% 아끼는 격리 규칙

혼자 제품을 만드는 1년 차 이하 개발자가 거대 레거시 코드베이스에 Claude Code를 붙이면 1시간도 안 돼 토큰 예산이 바닥납니다. 사내에 물어볼 시니어는 없고, 기본 CLI 명령어만 익힌 상태에서 터미널을 열었다가 카드 결제 알림만 계속 받게 됩니다.

Claude Code는 대화 상태를 서버에 남기지 않습니다. 시스템 프롬프트, 프로젝트 설정 파일인 CLAUDE.md, 누적 대화 내역, 도구 호출 결과를 매 턴마다 단일 페이로드로 묶어 Anthropic API로 다시 보냅니다. 세션 시작 직후인 12턴에는 15,000토큰 안팎에 머물지만, 에이전트가 탐색을 시작하면서 빌드 산출물이나 수만 줄짜리 로그를 읽는 순간 페이로드는 80,000토큰까지 불어납니다. 610턴을 넘기면 매 턴 120,000토큰에서 200,000토큰이 오갑니다. 턴마다 비용이 복리로 청구되는 구조입니다.

Anthropic 공식 프롬프트 캐싱 단가를 보면 원인이 더 명확해집니다. 동일한 접두사 컨텍스트가 유지되면 기본 입력 토큰 대비 10% 비용만 내면 됩니다. 반면 에이전트가 수만 줄짜리 코드를 불규칙하게 읽어 캐시 접두사가 깨지면, 5분 TTL 기준 1.25배의 캐시 생성 비용이 새로 붙습니다. 몇 번 검색만 돌려도 혼자 감당하기 어려운 요금이 찍히는 이유입니다.

.claudeignore는 작동하지 않는다

루트 디렉토리에 .claudeignore 파일을 만들고 안도하는 개발자가 많습니다. 결론부터 말하면 Claude Code 공식 CLI 엔진에는 그런 설정 파일이 존재하지 않습니다. CLAUDE.md에 "로그 폴더는 읽지 말 것"이라고 적어두는 방식도 모델이 필요하다고 판단하면 무시해 버립니다.

에이전트의 파일 접근을 엔진 단에서 물리적으로 끊으려면 .claude/settings.json 파일의 permissions.deny 설정을 써야 합니다.

프로젝트 루트의 .claude/settings.json에 빌드 산출물과 보안 파일을 먼저 묶어둡니다.

{
  "permissions": {
    "deny": [
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Read(**/node_modules/**)",
      "Read(**/dist/**)",
      "Read(**/build/**)",
      "Read(**/coverage/**)",
      "Read(**/target/**)",
      "Read(**/*.log)",
      "Read(**/*.map)",
      "Read(legacy-backups/**)",
      "Edit(**/dist/**)",
      "Write(**/dist/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish)",
      "Bash(rm -rf *)"
    ],
    "allow": [
      "Read",
      "Edit",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  }
}

백엔드 로직을 손볼 때 프론트엔드 코드까지 긁어모으는 동작을 막으려면 로컬 전용 설정인 .claude/settings.local.json을 따로 둡니다.

{
  "permissions": {
    "deny": [
      "Read(apps/web/**)",
      "Read(frontend/**)",
      "Read(public/**)",
      "Edit(apps/web/**)",
      "Write(apps/web/**)"
    ]
  }
}

에이전트가 cat이나 head 같은 셸 명령어로 대형 로그를 터미널에 통째로 쏟아내는 일도 막아야 합니다. .claude/settings.json에 PreToolUse 훅을 걸어 명령어를 사전에 가로챕니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-large-reads.sh"]
          }
        ]
      }
    ]
  }
}

.claude/hooks/block-large-reads.sh 파일을 만들고 chmod +x로 실행 권한을 줍니다.

#!/usr/bin/env bash
PAYLOAD=$(cat)
COMMAND=$(echo "$PAYLOAD" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -Eq '(cat|head|tail|less)\s+.*(\.log|\.map|\.lock|dist/|build/)'; then
  echo "대형 파일의 직접 출력이 감지되어 실행을 중단합니다." >&2
  exit 2
fi

exit 0

OS 프로세스 레벨에서 Exit code 2를 반환하면 에이전트의 파일 출력이 즉각 멈춥니다. 불필요한 파일 스캔을 차단해 초기 턴의 토큰 소모량을 절반 아래로 떨어뜨립니다.

파일 전체 재작성을 금지하고 함수 단위로 전달하기

1,000줄이 넘는 레거시 파일에서 변수 하나를 바꾸자고 파일 전체를 새로 쓰게 두면 버그가 생기고 출력 토큰도 버려집니다. Claude Code 내부에는 파일을 덮어쓰는 Write 도구와, 특정 문자열 블록만 교체하는 Edit 도구가 나뉘어 있습니다.

프로젝트 루트의 CLAUDE.md에 수정 규칙을 박아두어야 합니다.

## Code Modification Constraints
- 절대 파일 전체를 새로 작성(Write)하지 말 것.
- 반드시 변경이 필요한 최소 단위만 Edit 도구(old_string -> new_string)로 바꿀 것.
- 버그 수정 시 주변 코드의 포맷이나 공백을 임의로 건드리지 말 것.
- 작업 완료 전 git diff를 확인하여 의도한 변경만 들어갔는지 검증할 것.

대형 파일 전체를 에이전트에 넘기는 대신 대상 함수만 뽑아내는 편이 낫습니다. AST 파서 도구인 ast-grep을 쓰는 셸 스크립트(extract-func.sh)입니다.

#!/usr/bin/env bash
TARGET_FILE=$1
FUNC_NAME=$2

if [ -z "$TARGET_FILE" ] || [ -z "$FUNC_NAME" ]; then
  echo "사용법: ./extract-func.sh <파일경로> <함수이름>" >&2
  exit 1
fi

if command -v sg &> /dev/null; then
  sg run --pattern "function $FUNC_NAME(\$\$\$ARGS) { \$\$\$BODY }" "$TARGET_FILE"
else
  LINE_START=$(ctags -x --c-kinds=f "$TARGET_FILE" 2>/dev/null | grep -w "$FUNC_NAME" | awk '{print $3}')
  if [ -n "$LINE_START" ]; then
    sed -n "${LINE_START},$((LINE_START + 100))p" "$TARGET_FILE"
  else
    grep -n -A 60 "function $FUNC_NAME" "$TARGET_FILE"
  fi
fi

추출한 함수나 스테이징된 git diff만 헤드리스 모드(claude -p)로 전달해 수정을 요구합니다.

# 특정 함수만 주입해 수정 코드 추출
./extract-func.sh src/billing.js processRefund | claude -p "위 함수의 계산 오류를 고친 Edit용 대체 코드 블록(new_string)만 출력할 것."

# 스테이징된 변경점만 검증
git diff --staged src/services/OrderService.js | claude -p "이 diff에서 발생할 수 있는 동시성 결함이나 null 참조 가능성만 지목할 것."

전체 소스코드 대신 50~100줄짜리 슬라이스만 입력으로 넣으면 턴당 토큰 소모량을 90% 가까이 줄일 수 있습니다.

HANDOFF.md로 세션 상태를 저장하고 비우기

작업을 한 세션에서 길게 끌고 갈 이유가 없습니다. 대화 기록이 쌓일수록 매 턴 내야 하는 기본 요금만 불어납니다. Claude 모델은 약 967,000토큰에 이르면 대화 내역을 스스로 요약하는 /autocompact를 지원하지만, 시스템이 코드를 줄이는 과정에서 중요 매개변수나 엣지 케이스 맥락을 날려버리는 일이 흔합니다. 직접 컨텍스트를 비워야 합니다.

터미널에서 세 가지 내장 명령어로 현재 상태를 확인합니다.

/context: 시스템 프롬프트와 대화 기록이 차지하는 메모리 비율을 봅니다.
/usage: 세션 토큰 사용량과 플랜 한도 소진율을 확인합니다.
/cost: 현재 세션까지 누적된 실제 달러 비용을 점검합니다.

토큰이 100,000개를 넘어가거나 특정 작업 단위가 끝났다면 세션을 닫기 전 Claude Code에게 HANDOFF.md 작성을 지시합니다.

현재 세션의 작업 상태를 프로젝트 루트의 HANDOFF.md에 아래 형식으로 기록할 것:
Goal: 작업 목표 및 대상 모듈
Current Progress: 수정한 파일과 구체적인 라인
What Worked: 검증 완료된 로직 및 통과한 테스트
What Failed: 실패한 접근 방식 및 주의 사항
Immediate Next Step: 다음 세션 시작 즉시 실행해야 할 단일 작업

기록이 끝나면 /clear 명령어로 컨텍스트 창을 비웁니다. 새 세션을 열고 이전 세션의 요약본만 넘깁니다.

HANDOFF.md 파일을 읽고 Immediate Next Step 항목부터 작업을 이어갈 것. 이전에 실패한 방식은 시도하지 말 것.

동일한 에러로 3회 이상 헛돌기 시작하면 즉시 Escape 키를 눌러 멈춰야 합니다. 세션을 전부 비우기 애매한 상황이라면 /rewind로 정상 동작했던 직전 턴으로 돌아갑니다. /rewind는 확립된 시스템 접두사 프롬프트 캐시를 보존하기 때문에 추가 캐시 쓰기 비용을 물지 않고 정상 분기로 복귀합니다.

방어 계층별 제어 수준

방어 계층	설정 위치	제어 수준	실측 토큰 절감 효과
하네스 파일 필터링	`.claude/settings.json` (permissions.deny)	CLI 엔진 강제	세션당 초기 스캔 토큰 50%~80% 차단
셸 명령어 방어벽	PreToolUse Hook (`block-large-reads.sh`)	OS 프로세스 차단 (Exit 2)	로그 및 번들 파일 대량 출력 100% 방어
컨텍스트 슬라이싱	`ast-grep`, `git diff` 파이프라인	입력 범위 제한	파일 분석 및 수정 턴당 토큰 90% 감축
세션 수명 관리	`/context`, `/clear`, `HANDOFF.md`	수동 상태 영속화	세션 후반부 누적 복리 토큰 청구액 60% 이상 절감

.claude/settings.json으로 불필요한 경로를 차단하고, 대형 파일 대신 슬라이싱한 코드만 넘기는 규칙을 지켜야 1인 개발 환경에서 Claude Code를 실질적인 개발 도구로 굴릴 수 있습니다.

Claude Code로 레거시 코드를 고칠 때 세션 토큰을 80% 아끼는 격리 규칙

.claudeignore는 작동하지 않는다

에이전트의 파일 접근을 엔진 단에서 물리적으로 끊으려면 .claude/settings.json 파일의 permissions.deny 설정을 써야 합니다.

프로젝트 루트의 .claude/settings.json에 빌드 산출물과 보안 파일을 먼저 묶어둡니다.

{
  "permissions": {
    "deny": [
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Read(**/node_modules/**)",
      "Read(**/dist/**)",
      "Read(**/build/**)",
      "Read(**/coverage/**)",
      "Read(**/target/**)",
      "Read(**/*.log)",
      "Read(**/*.map)",
      "Read(legacy-backups/**)",
      "Edit(**/dist/**)",
      "Write(**/dist/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish)",
      "Bash(rm -rf *)"
    ],
    "allow": [
      "Read",
      "Edit",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  }
}

백엔드 로직을 손볼 때 프론트엔드 코드까지 긁어모으는 동작을 막으려면 로컬 전용 설정인 .claude/settings.local.json을 따로 둡니다.

{
  "permissions": {
    "deny": [
      "Read(apps/web/**)",
      "Read(frontend/**)",
      "Read(public/**)",
      "Edit(apps/web/**)",
      "Write(apps/web/**)"
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-large-reads.sh"]
          }
        ]
      }
    ]
  }
}

.claude/hooks/block-large-reads.sh 파일을 만들고 chmod +x로 실행 권한을 줍니다.

#!/usr/bin/env bash
PAYLOAD=$(cat)
COMMAND=$(echo "$PAYLOAD" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -Eq '(cat|head|tail|less)\s+.*(\.log|\.map|\.lock|dist/|build/)'; then
  echo "대형 파일의 직접 출력이 감지되어 실행을 중단합니다." >&2
  exit 2
fi

exit 0

파일 전체 재작성을 금지하고 함수 단위로 전달하기

프로젝트 루트의 CLAUDE.md에 수정 규칙을 박아두어야 합니다.

## Code Modification Constraints
- 절대 파일 전체를 새로 작성(Write)하지 말 것.
- 반드시 변경이 필요한 최소 단위만 Edit 도구(old_string -> new_string)로 바꿀 것.
- 버그 수정 시 주변 코드의 포맷이나 공백을 임의로 건드리지 말 것.
- 작업 완료 전 git diff를 확인하여 의도한 변경만 들어갔는지 검증할 것.

대형 파일 전체를 에이전트에 넘기는 대신 대상 함수만 뽑아내는 편이 낫습니다. AST 파서 도구인 ast-grep을 쓰는 셸 스크립트(extract-func.sh)입니다.

#!/usr/bin/env bash
TARGET_FILE=$1
FUNC_NAME=$2

if [ -z "$TARGET_FILE" ] || [ -z "$FUNC_NAME" ]; then
  echo "사용법: ./extract-func.sh <파일경로> <함수이름>" >&2
  exit 1
fi

if command -v sg &> /dev/null; then
  sg run --pattern "function $FUNC_NAME(\$\$\$ARGS) { \$\$\$BODY }" "$TARGET_FILE"
else
  LINE_START=$(ctags -x --c-kinds=f "$TARGET_FILE" 2>/dev/null | grep -w "$FUNC_NAME" | awk '{print $3}')
  if [ -n "$LINE_START" ]; then
    sed -n "${LINE_START},$((LINE_START + 100))p" "$TARGET_FILE"
  else
    grep -n -A 60 "function $FUNC_NAME" "$TARGET_FILE"
  fi
fi

추출한 함수나 스테이징된 git diff만 헤드리스 모드(claude -p)로 전달해 수정을 요구합니다.

# 특정 함수만 주입해 수정 코드 추출
./extract-func.sh src/billing.js processRefund | claude -p "위 함수의 계산 오류를 고친 Edit용 대체 코드 블록(new_string)만 출력할 것."

# 스테이징된 변경점만 검증
git diff --staged src/services/OrderService.js | claude -p "이 diff에서 발생할 수 있는 동시성 결함이나 null 참조 가능성만 지목할 것."

전체 소스코드 대신 50~100줄짜리 슬라이스만 입력으로 넣으면 턴당 토큰 소모량을 90% 가까이 줄일 수 있습니다.

HANDOFF.md로 세션 상태를 저장하고 비우기

터미널에서 세 가지 내장 명령어로 현재 상태를 확인합니다.

/context: 시스템 프롬프트와 대화 기록이 차지하는 메모리 비율을 봅니다.
/usage: 세션 토큰 사용량과 플랜 한도 소진율을 확인합니다.
/cost: 현재 세션까지 누적된 실제 달러 비용을 점검합니다.

토큰이 100,000개를 넘어가거나 특정 작업 단위가 끝났다면 세션을 닫기 전 Claude Code에게 HANDOFF.md 작성을 지시합니다.

현재 세션의 작업 상태를 프로젝트 루트의 HANDOFF.md에 아래 형식으로 기록할 것:
Goal: 작업 목표 및 대상 모듈
Current Progress: 수정한 파일과 구체적인 라인
What Worked: 검증 완료된 로직 및 통과한 테스트
What Failed: 실패한 접근 방식 및 주의 사항
Immediate Next Step: 다음 세션 시작 즉시 실행해야 할 단일 작업

기록이 끝나면 /clear 명령어로 컨텍스트 창을 비웁니다. 새 세션을 열고 이전 세션의 요약본만 넘깁니다.

HANDOFF.md 파일을 읽고 Immediate Next Step 항목부터 작업을 이어갈 것. 이전에 실패한 방식은 시도하지 말 것.

방어 계층별 제어 수준

방어 계층	설정 위치	제어 수준	실측 토큰 절감 효과
하네스 파일 필터링	`.claude/settings.json` (permissions.deny)	CLI 엔진 강제	세션당 초기 스캔 토큰 50%~80% 차단
셸 명령어 방어벽	PreToolUse Hook (`block-large-reads.sh`)	OS 프로세스 차단 (Exit 2)	로그 및 번들 파일 대량 출력 100% 방어
컨텍스트 슬라이싱	`ast-grep`, `git diff` 파이프라인	입력 범위 제한	파일 분석 및 수정 턴당 토큰 90% 감축
세션 수명 관리	`/context`, `/clear`, `HANDOFF.md`	수동 상태 영속화	세션 후반부 누적 복리 토큰 청구액 60% 이상 절감

Claude Code로 레거시 코드를 고칠 때 세션 토큰을 80% 아끼는 격리 규칙

Related Video

50분만 투자하세요, 1000시간 이상의 Claude Code 노하우를 알려드립니다 (2026 가이드)

Claude Code로 레거시 코드를 고칠 때 세션 토큰을 80% 아끼는 격리 규칙

.claudeignore는 작동하지 않는다

파일 전체 재작성을 금지하고 함수 단위로 전달하기

HANDOFF.md로 세션 상태를 저장하고 비우기

방어 계층별 제어 수준

More from the community

사내 시스템에 llm api 붙일 때 마주하는 현실적인 한계와 대응법

레거시 백엔드에 GPT-6 Astra 붙일 때 예산 승인과 보안 통과를 먼저 끝내는 법이 있습니다

에이전트끼리 대화하다 6천만 원 청구서가 나오는 이유

사내 RAG 벡터 검색에 Okta 권한 필터를 직접 거는 방법

브라우저 에이전트에게 내 구글 계정을 통째로 넘기면 안 되는 이유

Apple Won the AI Race

Comments (0)

Claude Code로 레거시 코드를 고칠 때 세션 토큰을 80% 아끼는 격리 규칙

.claudeignore는 작동하지 않는다

파일 전체 재작성을 금지하고 함수 단위로 전달하기

HANDOFF.md로 세션 상태를 저장하고 비우기

방어 계층별 제어 수준