하네스 엔지니어링 위키

Claude Code · 컨텍스트와 프롬프트 조립

Properties2
tags기능분해, cc, prompt-assembly
aliases컨텍스트와 프롬프트 조립, CLAUDE.md 계층, 컨텍스트 윈도우, compact

16 min read

Claude Code · 컨텍스트와 프롬프트 조립

한 줄 요약

Claude Code는 매 세션을 “기억이 텅 빈 상태”로 시작하기 때문에, 일을 시키기 전에 규정집·개인메모·프로젝트 약속·과거 기록을 정해진 순서로 쌓아 한 묶음의 입력으로 만든다. 왜 배우나 — 이 “쌓는 순서”와 “무엇이 강제 규칙이고 무엇이 그냥 참고인지”를 알아야, 지시가 왜 가끔 안 지켜지는지 이해하고 내 지침을 올바른 자리에 넣을 수 있다.

그림

flowchart TD
  A["claude 실행<br/>빈 컨텍스트로 시작"] --> B["Core 시스템 프롬프트 조립<br/>행동·도구·응답 규칙"]
  B --> C["Output style · append-system-prompt<br/>끝에 덧붙임"]
  C --> D["환경정보 동적 섹션<br/>+ git 상태 블록은 맨끝"]
  D --> E["CLAUDE.md 계층 머지<br/>관리→유저→프로젝트→로컬<br/>@import 최대 4홉 확장"]
  E --> F["자동 메모리 MEMORY.md<br/>처음 200줄/25KB만"]
  F --> G["MCP 도구이름·스킬설명<br/>지연 로드"]
  G --> H[사용자 프롬프트]
  H --> I["모델 추론·도구 사용<br/>대화가 계속 쌓임"]
  I -->|책상이 꽉 참| J["/compact<br/>옛 도구출력 제거 → 대화 요약"]
  J -->|디스크에서 다시 깔림| E

쉽게 풀기

비유: 회의 시작 전 책상 세팅. 새 회의(세션)가 시작될 때마다 참석자(모델)는 아무 기억이 없는 신입처럼 들어온다. 그래서 회의 진행자는 매번 책상에 자료를 같은 순서로 깔아준다.

  1. 회사 규정집을 맨 아래에 깐다 (시스템 프롬프트) “도구는 이렇게 써라, 답은 이렇게 해라” 같은 행동 규칙이다. 이건 비공개라 화면엔 안 보이지만 항상 맨 위(가장 강한 힘)에 놓인다.

  2. 개인 메모 → 프로젝트 약속 → 로컬 메모 순으로 위에 쌓는다 (CLAUDE.md 계층) 넓은 범위(모든 프로젝트에 적용되는 내 습관)가 먼저, 좁은 범위(지금 이 프로젝트만의 약속)가 나중에 온다. 나중에 온 것이 더 가까이 놓여 더 잘 반영된다.

  3. 지난 회의록 요약을 함께 올린다 (자동 메모리) Claude가 과거에 스스로 남긴 메모다. 단, 전부가 아니라 목차에 해당하는 MEMORY.md의 처음 200줄(또는 25KB) 만 깔린다. 나머지는 필요할 때 꺼내 본다.

  4. 지금 어디서 회의하는지 메모도 붙인다 (환경정보) 작업 폴더·OS·git 상태 같은 현재 상황 정보다.

가장 중요한 함정 두 가지.

CLAUDE.md는 "강제 규칙"이 아니다

진짜 규정집(시스템 프롬프트)은 따로 있고, CLAUDE.md는 그 뒤에 붙는 참고용 사용자 메시지다. 즉 “꼭 지켜라”가 아니라 “이런 맥락이야”에 가깝다. 그래서 가끔 안 지켜질 수 있다. 정말 강제하고 싶으면 hook(자동 차단)이나 권한 설정을, 말투·페르소나를 바꾸고 싶으면 output style을 써야 한다.

책상이 꽉 차면 — /compact

회의가 길어져 자료가 넘치면 /compact가 옛 대화를 요약본 한 장으로 줄여 자리를 비운다. 이때 규정집·프로젝트 약속·메모는 디스크에서 다시 깔리므로 살아남는다. 사라지는 건 그때그때 임시로 들어왔던 것들이다.

핵심 정리

로드되는 4가지 재료 (넓은 범위가 먼저, 가까운 범위가 나중에)

재료한 줄 정체강제력
시스템 프롬프트행동·도구·응답 규칙(비공개)강함(진짜 규칙)
CLAUDE.md 계층관리→유저→프로젝트→로컬 지침약함(참고 맥락)
자동 메모리과거에 남긴 회의록 요약약함(참고)
환경정보폴더·OS·git 상태사실 정보

CLAUDE.md 4계층 — 누가 쓰고 어디 두나

순서범위위치(대표)작성자
1관리 정책OS별 시스템 경로(아래 콜아웃)IT/DevOps
2사용자 지침~/.claude/CLAUDE.md본인
3프로젝트 지침./CLAUDE.md 또는 ./.claude/CLAUDE.md팀
4로컬 지침./CLAUDE.local.md(.gitignore)본인

시스템 프롬프트 세부 구성과 토큰 (context-window.md 기준)

  • Core system prompt: 항상 최상단, 비공개, 약 4,200토큰
  • Output style 본문: 시스템 프롬프트 끝에 붙음(Default가 아닐 때)
  • --append-system-prompt: 호출 1회용으로 끝에 덧붙임(-file로 파일도 가능)
  • --system-prompt / -file: 기본 프롬프트를 통째로 교체(append와는 조합 가능, 둘끼리는 상호배타)
  • Environment info: 작업 디렉토리·platform·shell·OS·git repo 여부. git branch/status/최근 커밋은 맨 끝 별도 블록
  • claudeMd(managed): managed/policy 설정에서만 적용, 사용자/프로젝트/로컬에선 무시

관리 정책 CLAUDE.md의 OS별 위치 (조직 전체, 제외 불가)

  • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
  • Linux/WSL: /etc/claude-code/CLAUDE.md
  • Windows: C:\Program Files\ClaudeCode\CLAUDE.md

CLAUDE.md 병합·import·메모리 규칙 (memory.md 근거)

  • 디렉토리 트리 병합: 깊은 폴더에서 실행하면 루트→작업 디렉토리 순으로 연결. 상위가 먼저, 같은 폴더 안에선 CLAUDE.local.md가 CLAUDE.md 다음. 재정의가 아니라 이어붙이기(concatenation).
  • 하위 디렉토리 CLAUDE.md: 시작 시 로드 안 됨 → 그 폴더 파일을 읽을 때 지연 로드.
  • HTML 주석: 블록 수준 <!-- ... -->는 주입 전 제거(코드블록 안 주석은 보존).
  • @import 구문: @path/to/import(상대=가져오는 파일 기준, 절대·@~/... 허용), 재귀 최대 4홉, 시작 시 확장되어 함께 주입(토큰 절약 아님), 외부 import 첫 조우 시 승인 대화·거부 시 영구 비활성.
  • AGENTS.md: CC가 직접 안 읽음 → @AGENTS.md import 또는 ln -s AGENTS.md CLAUDE.md 심볼릭링크.
  • 자동 메모리: 위치 ~/.claude/projects/<project>/memory/, 진입점 MEMORY.md(인덱스, 처음 200줄/25KB만 시작 로드), 토글은 /memory·autoMemoryEnabled:false·CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, 위치 변경은 autoMemoryDirectory, v2.1.59+ 필요.

컨텍스트 윈도우 / 압축 한눈에

항목값
윈도우 크기기본 200,000토큰, [1m] 모델은 100만
자동 압축한계 접근 시 옛 도구출력 제거 → 부족하면 대화 요약
수동 압축/compact(/compact focus on …로 포커스), /clear(완전 비움)
점검 명령/context·/memory·/mcp

/compact 생존표 (context-window.md "What survives compaction")

  • 시스템 프롬프트 + output style → 불변(애초에 메시지 기록이 아님)
  • 프로젝트 루트 CLAUDE.md + 무범위 규칙 → 디스크에서 재주입
  • 자동 메모리 → 디스크에서 재주입
  • 호출된 스킬 본문 → 재주입(스킬당 5,000·총 25,000토큰 상한, 오래된 것부터 드롭)
  • paths: frontmatter 규칙 → 매칭 파일 재독 전까지 소실
  • 하위 디렉토리 중첩 CLAUDE.md → 그 폴더 파일 재독 전까지 소실
  • 스킬 설명 목록 → 재주입 안 됨(실제 호출한 스킬만 보존)
  • Hooks → 해당없음(코드로 실행되지 컨텍스트가 아님)

실제 예시

(1) 실제 자동 메모리 인덱스 — MEMORY.md는 본문이 아니라 목차다

// /home/seunghyeong/.claude/projects/-home-seunghyeong/memory/MEMORY.md
# Memory Index
 
- [ppt-forge 플러그인](ppt-forge-plugin.md) — /mnt/d/ppt-forge, 슬롯 계약 PPTX 파이프라인, FMEA 109건, soffice 미설치 주의
- [사용자 프로필](user-profile.md) — AI 전문강사 + AX 컨설턴트, D드라이브 데이터를 LLM Wiki로 관리 계획
- [하네스 학습 6study](harness-study-6study.md) — D:\6study 옵시디언 볼트, 7개 에이전트 프레임워크 ... codex exec 헤드리스 가능

각 줄은 지연 로드되는 주제 파일을 가리킨다. “처음 200줄/25KB만 시작 시 로드”라는 정책이 이 인덱스 패턴을 강제한다.

(2) 프로젝트 CLAUDE.md — AGENTS.md를 가져오고 Claude 전용 지침 추가

// 임의 프로젝트 ./CLAUDE.md — AGENTS.md import + Claude 전용 지침 (memory.md L130-136 형식)
@AGENTS.md
 
## Claude Code
 
`src/billing/` 아래의 변경 사항에 대해 Plan Mode를 사용합니다.

(3) 조직 전체 강제 — 별도 파일 없이 직접 주입

// managed-settings.json — 별도 파일 없이 조직 CLAUDE.md를 직접 주입 (memory.md L288-292)
{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

(4) 말투·진행 방식 바꾸기 — output style로 시스템 프롬프트 톤 변경

// .claude/output-styles/diagrams-first.md — 시스템 프롬프트 톤 변경 (output-styles.md L64-77)
---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---
 
When explaining code, architecture, or data flow, start with a Mermaid diagram showing the structure, then explain in prose.

(5) 직접 만들 때 템플릿 — 루트 CLAUDE.md(200줄 이하 목표)

// ./CLAUDE.md
@AGENTS.md
 
# 프로젝트 컨텍스트
- 빌드: `npm run build`  / 테스트: 커밋 전 `npm test` 실행
- API 핸들러는 `src/api/handlers/` 에 위치
- 들여쓰기 2칸
 
## 가져오기
- git 워크플로우 @docs/git-instructions.md
- 개인 선호(worktree 공유용) @~/.claude/my-project-instructions.md

(6) 경로 범위 규칙 — 해당 파일 읽을 때만 로드

// .claude/rules/api.md
---
paths:
  - "src/api/**/*.{ts,tsx}"
---
# API 규칙
- 모든 엔드포인트 입력 검증
- 표준 오류 응답 형식

직접 만들 때 체크리스트

  • 루트 CLAUDE.md는 200줄 이하(초과 시 .claude/rules/ 또는 skill로 분리)
  • 항상 필요 없는 지침 → paths: 규칙(매칭 파일 읽을 때만 로드)
  • 다단계 절차/한 부분만 중요 → skill로(컨텍스트 절약). 호출형 skill은 disable-model-invocation: true
  • AGENTS.md 있으면 @AGENTS.md import 또는 심볼릭링크(Windows는 import)
  • 압축 후 생존 필요한 규칙은 paths: 빼거나 루트 CLAUDE.md로 이동
  • 톤/페르소나 강제는 output style, 1회용은 --append-system-prompt
  • 자동 메모리는 /memory로 감사·편집. MEMORY.md는 인덱스로만 유지
  • 확인: /memory(로드 목록) · /context(토큰 사용) · /mcp(서버 비용)

요약 & 셀프체크

3줄 요약:

  1. 매 세션은 빈 상태로 시작하므로, 시스템 프롬프트 → CLAUDE.md 계층 → 자동 메모리 → 환경정보를 정해진 순서로 쌓아 입력을 만든다.
  2. CLAUDE.md·메모리는 “강제 규칙”이 아니라 시스템 프롬프트 뒤에 붙는 참고 맥락이다 — 진짜 강제는 hook/권한, 톤 강제는 output style.
  3. 대화가 한계에 닿으면 /compact가 옛 내용을 요약하지만, 디스크 기반(시스템·루트 CLAUDE.md·메모리)은 다시 깔려 살아남는다.

스스로 답해보기:

  • 내가 ~/.claude/CLAUDE.md와 프로젝트 ./CLAUDE.md에 서로 다른 지침을 넣으면, 둘 중 어느 쪽이 더 가까이(나중에) 놓이고 그 이유는?
  • “이 폴더에선 무조건 lint를 통과해야 push 가능”을 진짜로 강제하려면 CLAUDE.md에 적는 것으로 충분한가? 아니라면 무엇을 써야 하나?
  • /compact 후에 paths: 규칙이 사라졌다면, 그 규칙을 다시 살리는 방법은?

연결

CC_개요 · _분석축_루브릭

Codex 교차검증

원본 노트에는 별도 Codex 교차검증 섹션이 없었다. 본 재작성은 기존 근거 파일(아래 “근거 파일”)의 사실만 보존하며 추측으로 내용을 바꾸지 않았다. 향후 Codex로 교차검증한 내용은 이 콜아웃에 누적 기록한다.

근거 파일

  • /mnt/d/6study/10_프레임워크분석/_원문아카이브/claude-code/memory.md (CLAUDE.md 계층·로드순서·@import 4홉·AGENTS.md·자동메모리 위치/200줄·claudeMd/claudeMdExcludes·압축 생존)
  • /mnt/d/6study/10_프레임워크분석/_원문아카이브/claude-code/context-window.md (시작 컨텍스트 토큰 예시·200K MAX·1m·압축 생존표·자동압축)
  • /mnt/d/6study/10_프레임워크분석/_원문아카이브/claude-code/output-styles.md (시스템 프롬프트 끝 주입·keep-coding-instructions·frontmatter·CLAUDE.md와 비교표)
  • /mnt/d/6study/10_프레임워크분석/_원문아카이브/claude-code/how-claude-code-works.md (컨텍스트 윈도우 구성·when-context-fills-up·Compact Instructions)
  • /mnt/d/6study/10_프레임워크분석/_원문아카이브/claude-code/cli-reference.md (—system-prompt/-file·—append-system-prompt/-file·—exclude-dynamic-system-prompt-sections)
  • /mnt/d/6study/10_프레임워크분석/_원문아카이브/claude-code/settings.md (claudeMd L210·claudeMdExcludes L211·outputStyle L246·시스템 프롬프트 비공개 L615)
  • /home/seunghyeong/.claude/projects/-home-seunghyeong/memory/MEMORY.md (실제 자동 메모리 인덱스 예시)
  • /home/seunghyeong/harness-work/claude-code/.claude/commands/ (소스 루트엔 CLAUDE.md 없음, commands만 존재 — 확인함)

그래프 뷰

백링크