Claude Code의 지시사항을 어디에 작성할 것인가 — 7가지 지시면(Steering Surfaces)과 컨텍스트 부채(Context

Claude Code에는 AI의 동작을 제어하는 수단이 7가지 있습니다. CLAUDE.md

・Rules・Skills・Subagents・Hooks・Output styles・System prompt 추가입니다. 여기에 더해 memory・plugins・managed settings도 동작에 영향을 미칩니다.

문제는 "어떤 지시를 어디에 작성할 것인가"입니다. 위치를 잘못 선정하면 성능보다 먼저 운영이 무너집니다. 예를 들어 모든 절차를 CLAUDE.md에 작성하면, 관계없는 작업에서도 매번 로드되어 컨텍스트(context)를 낭비합니다. 긴 세션에서는 압축 (compaction)에 의해 지시사항이 유실되어 Claude가 따르지 않게 됩니다.

이 기사에서는 각 수단을 "로드 타이밍 / 압축 (compaction) 후의 잔존 여부 / 권위의 강도 / 컨텍스트 비용"의 4개 축으로 정리합니다. 나아가 C4 모델로 로드 메커니즘을 구조화하고, 설정 데이터 모델·구축 방법·운영·베스트 프랙티스까지 일관되게 제시합니다. 출처는 Anthropic 공식 블로그 "Steering Claude Code: skills, hooks, rules, subagents and more"와 Claude Code 공식 문서입니다.

개요

Claude Code는 코딩 태스크를 자율적으로 실행하는 에이전트입니다. 긴 세션, 여러 파일에 걸친 작업, 서브 에이전트(subagent)로의 위임을 통해 동작하기 때문에, "어떤 지시를 어디에 작성했는가"가 성능보다 먼저 질문되는 설계 과제가 됩니다.

Anthropic은 이 과제에 대해 **7가지 지시면 (steering surfaces)**을 제공합니다. 지시면이란 Claude의 동작을 제어하는 수단들의 총칭입니다. 각 수단은 다음 3개 축에서 차이가 납니다.

언제 컨텍스트에 로드되는가(세션 시작 / 온디맨드 / 라이프사이클 이벤트) -
압축 (compaction) 후에도 남는가(사라짐 / 재주입됨 / 압축을 바이패스함) -
얼마나 많은 권위 (authority)를 갖는가(Claude의 판단에 맡기는 지시인가 / 확정적으로 강제하는가)

왜 지시의 위치를 잘못 잡으면 운영이 무너지는가

Claude Code는 모든 지시사항을 컨텍스트 윈도우(context window) 상에서 처리합니다. 컨텍스트는 유한하며, 세션이 길어지면 **compaction (압축)**이 발생하여 오래된 내용이 유실됩니다.

**컨텍스트 부채 (context debt)**란 이 문제가 축적된 상태를 말합니다. 전형적인 진행 과정은 다음과 같습니다.

• 팀원 모두가 CLAUDE.md에 지시사항을 계속 추가하지만, 아무도 삭제하지 않습니다.
• 결과적으로 엔지니어 전원의 모든 세션에서 관계없는 지시사항이 매번 로드됩니다.
• 토큰 소비가 증가하고, Claude가 지시를 따르는 정밀도가 떨어집니다.
• compaction으로 유실되어서는 안 될 지시사항까지 유실되어 운영이 불안정해집니다.

올바른 지시면을 선택하면 "필요할 때만 필요한 지시를 로드하는" 설계가 되어, 컨텍스트 효율과 지시의 확실성을 양립할 수 있습니다. 본 문서는 "무엇을 컨텍스트에 올리지 않고 해결할 것인가"를 판단 축으로 삼아, 각 수단의 배치·로드 메커니즘·데이터 모델·운영 지식을 정리합니다.

특징

7가지 수단 한 줄 요약

#	수단	한 줄 요약
1	CLAUDE.md	매 세션 자동 로드되며, 팀에서 공유하는 상주 지식의 저장소
2	Rules	CLAUDE.md를 보완하는 모듈형 제약 파일. 경로 지정으로 특정 파일 조작 시에만 로드 가능
3	Skills	이름과 설명은 세션 시작 시 로드되고, 본체는 호출 시에만 로드되는 절차서
4	Subagents	독립된 컨텍스트 윈도우에서 동작하며, 결과의 요약(summary)만을 반환하는 격리 워커
5	Hooks	라이프사이클 이벤트에 확정적으로 발화하는 자동화
6	Output styles	system prompt를 직접 변경하여 Claude의 역할(role) 자체를 변경 (built-in 지시는 keep-coding-instructions로 유지)
7	System prompt 추가	CLI 실행 시 --append-system-prompt를 통해 세션 단위의 추가 지시를 전달

전체를 관통하는 설계 사상

점진적 공개 (Progressive disclosure)

• Skills와 Subagents는 이름과 설명만 먼저 로드하고, 본체는 온디맨드 (On-demand)로 로드합니다.
• "필요할 때까지 전체를 읽어들이지 않음"으로써 컨텍스트 비용 (Context cost)을 제로에 가깝게 유지합니다.
• disable-model-invocation: true를 설정하면 Claude가 이 스킬을 자동으로 호출하지 않게 되며, 설명의 사전 로드도 억제됩니다 (/name을 통한 수동 호출은 가능합니다).

컨텍스트에 포함하지 않는 것이 설계 목표

• Hooks는 설정이 컨텍스트 외부에 존재하며, 실행되어도 컨텍스트를 오염시키지 않습니다.
• Subagents는 독립된 컨텍스트 윈도우 (Context window)를 가지므로, 중간 처리 과정이 부모 세션을 오염시키지 않습니다.
• Path-scoped rules는 대상 파일을 건드리기 전까지 로드되지 않습니다.

지시와 강제의 구분

• CLAUDE.md / Rules / Skills에 작성하는 모든 내용은 "지시 (Instruction)"이며, Claude가 이를 준수할지 여부는 확률적입니다.
• "절대로 일어나서는 안 되는 작업"은 Hooks (PreToolUse)와 Permissions (deny 규칙)를 통해 결정론적으로 강제합니다.
• Managed settings는 관리자 배포를 통해 덮어쓰기가 불가능한 조직 전체의 가드레일 (Guardrail)입니다.

4축 비교 테이블

수단	배치 경로	로드 타이밍	Compaction 후	권위의 강도	컨텍스트 비용	주요 용도
CLAUDE.md (root)	CLAUDE.md / .claude/CLAUDE.md / ~/.claude/CLAUDE.md	세션 시작 (전문)	다시 로드되어 재주입됨	높음 (Claude의 판단에 맡김)	높음 (매 요청마다 전체 행)	빌드 명령, 디렉토리 구조, 코딩 규약
CLAUDE.md (서브 디렉토리)	<subdir>/CLAUDE.md	온디맨드 (대상 디렉토리 접촉 시)	자동 재주입 없음	중간	낮음~중간 (접촉 시에만)	디렉토리 고유 규약
Rules	.claude/rules/*.md / ~/.claude/rules/*.md	세션 시작 (paths 미지정 시) / 파일 매칭 시 (path-scoped)	재주입됨	중간 (path-scoped라면 낮음)	언어·디렉토리 고유 제약
Skills	.claude/skills/<name>/SKILL.md / 플러그인 내부	이름과 설명: 세션 시작 / 본체: 호출 시	호출된 것만 예산 내에서 재주입	중간	낮음 (본체는 호출 시에만)	배포 절차, 릴리스 체크리스트, 참조 매뉴얼
Subagents	.claude/agents/<name>.md / ~/.claude/agents/	이름·설명·도구 목록: 세션 시작 / 본체: 호출 시	최종 메시지만 반환	중간	낮음 (독립 컨텍스트 윈도우)	병렬 작업, 로그 분석, 심층 검색 등의 부차적 태스크
Hooks	settings.json의 hooks 키 / 플러그인 내부	라이프사이클 이벤트 발생 시	Compaction을 우회 (항상 유효)	높음 (결정론적 실행)	제로 (출력을 반환하는 경우에만 추가)	린터 (Linter) 실행, 위험 명령 차단, Slack 알림
Output styles	.claude/output-styles/*.md	세션 시작 (캐시 후 재사용)	압축되지 않음 (재적용됨)	최고 (시스템 프롬프트를 직접 변경)	높음 (시스템 프롬프트 수준)	Claude의 역할(Role) 대폭 변경
System prompt 추가	CLI 플래그 --append-system-prompt	시작 시 (해당 세션에만 적용)	압축되지 않음	높음 (시스템 프롬프트에 부가됨)	중간 (프롬프트 캐시 이후에는 낮음)	특정 세션의 규약·포맷 지정
Auto memory (MEMORY.md)

~/.claude/projects/<project>/memory/MEMORY.md |
세션 시작 (상단 200행 / 25KB) | 세션 시작 시 재로드 | 낮음 (Claude가 자율적으로 작성하는 학습 메모) | 낮음 (상단 부분만) | 빌드 명령, 디버깅 패턴, 프로젝트 지식 |

보충: Managed settings 및 Plugins

Managed settings (managed-settings.json / MDM / 레지스트리)는 관리자가 배포하며 사용자가 설정을 덮어쓸 수 없는 조직 가드레일(Guardrail)입니다. 허용/거부 명령, 이용 모델 제한, MCP 서버 제어를 강제하며, claudeMd 키를 통해 managed CLAUDE.md에 상응하는 지시사항도 삽입할 수 있습니다.

Plugins (.claude-plugin/plugin.json + skills/ + agents/ + hooks/)는 Skills / Subagents / Hooks / MCP servers를 하나의 디렉토리에 모아 배포 및 재사용할 수 있게 하는 패키징 계층입니다. 스킬 이름은 플러그인 이름으로 네임스페이스화 (/plugin-name:skill-name)되어 충돌을 방지합니다. .claude/skills/ 바로 아래의 standalone 설정 및 동작과 동일하지만, 여러 리포지토리로의 배포, 버전 관리, 마켓플레이스 등록이 가능합니다.

구조

7가지 수단이 "어느 타이밍에·어떤 경로로 컨텍스트에 로드되는가 / compaction(압축)에서 어떻게 다뤄지는가 / hook은 어디에서 harness가 실행되는가"라는 로드 메커니즘을 C4 model의 3단계로 보여줍니다.

시스템 컨텍스트 다이어그램 (System Context Diagram)

시스템 컨텍스트 다이어그램 요소

요소명	설명
개발자	Claude Code를 대화형으로 사용하여 코딩 작업을 수행하는 사용자
...

컨테이너 다이어그램 (Container Diagram)

여기서의 "컨테이너"는 claude 프로세스 내의 논리적 처리 단위를 가리킵니다. 실제로는 모두 단일 프로세스 내에서 동작합니다.

컨테이너 다이어그램 요소

요소명	설명
세션 초기화 로더 (Session Initialization Loader)	세션 시작 시 CLAUDE.md 계층·rules·output-styles·auto memory를 일괄 로드하는 컨테이너
...

컴포넌트 다이어그램 (Component Diagram)

세션 초기화 로더 (Session Initialization Loader)

요소명	설명
CLAUDE.md 로더	작업 디렉토리에서 상위로 CLAUDE.md / CLAUDE.local.md를 탐색하여, 루트를 향하는 순서로 연결하여 주입한다
import 전개기 (import expander)	@path/to/file 구문으로 참조하는 파일을 세션 시작 시 전개한다. 최대 재귀 깊이는 4 홉(hop)이다
rules paths 매처 (rules paths matcher)	.claude/rules/*.md의 paths를 평가하여, 글로브(glob) 일치하는 파일을 Claude가 읽는 시점에 규칙을 지연 주입(lazy injection)한다
output-styles 인젝터 (output-styles injector)	선택된 output-style을 system prompt 끝에 추가한다. keep-coding-instructions: true로 기본 지시사항을 유지한다
auto memory 리더 (auto memory reader)	MEMORY.md의 상단 200행 또는 25KB를 세션 시작 시 주입한다

Progressive Disclosure 로더 (Progressive Disclosure Loader)

요소명	설명
skill 디스패처 (skill dispatcher)	세션 시작 시 모든 skill의 name과 description을 주입하고, 호출 시에만 SKILL.md 본체를 로드한다. disable-model-invocation: true는 프리로드(preload) 목록에서 제외한다
...	.claude/agents/의 name과 description을 프리로드하여, Agent tool 호출 시 독립 컨텍스트를 가진 subagent를 실행한다
subagent 독립 윈도우 (subagent independent window)	subagent 전용 컨텍스트 윈도우. 최종 메시지만 부모 세션으로 반환한다

컨텍스트 윈도우 매니저 (Context Window Manager)

요소명	설명
토큰 사용량 트래커 (Token Usage Tracker)	컨텍스트 윈도우 (Context Window)의 잔량을 모니터링하고, compaction (압축) 트리거 조건을 판정한다
compaction 엔진	/compact 또는 자동 compaction을 실행하며, 실행 전에 PreCompact hook을 호출한다
compaction 후 재주입기	compaction 후에 프로젝트 루트의 CLAUDE.md를 다시 로드하고, output-styles를 재적용한다. 서브 디렉토리의 CLAUDE.md와 skill (기술) 설명 목록은 재주입하지 않는다

hook 러너 하네스 (hook runner harness)

요소명	설명
이벤트 감지기	SessionStart, PreToolUse, PostToolUse, PreCompact, Stop 등의 라이프사이클 (lifecycle) 이벤트를 감지하여 매처 (matcher)에게 전달한다
matcher 평가기	matcher의 도구 이름 완전 일치, OR 리스트, 정규 표현식, if 조건으로 hook의 실행을 좁힌다
command 핸들러	shell 또는 exec 형식으로 스크립트를 실행하고, 이벤트 JSON을 stdin으로 전달한다
http 핸들러	지정된 URL로 이벤트 JSON을 POST하고, 응답 JSON을 받는다
mcp_tool 핸들러	연결된 MCP 서버의 도구를 이벤트 정보와 함께 호출한다
...

지시사항이 컨텍스트에 포함되는 경로

요소명	설명
상주 컨텍스트 (Resident Context)	compaction 후에도 재주입되며, 모든 턴(turn)에서 유지되는 컨텍스트 영역
...	paths를 가진 rules를, 일치하는 파일을 읽은 시점에 처음으로 주입한다
hook 바이패스 경로	hook은 LLM 컨텍스트를 거치지 않고 harness가 직접 실행하므로 compaction의 영향을 받지 않는다
additionalContext 삽입	hook이 JSON 출력의 hookSpecificOutput.additionalContext를 통해 반환한 내용만 컨텍스트에 추가된다
CLAUDE.md 재주입	compaction 후에는 프로젝트 루트의 CLAUDE.md만 다시 로드한다
소실	서브 디렉토리의 CLAUDE.md는 다음 파일 읽기 시점까지, skill 설명 목록은 호출된 항목에 대해서만 예산(budget) 내에서 유지한다

데이터

각 수단의 설정 파일이 가진 엔티티 (entity), 속성 (attribute), 연관 관계를 모델링합니다.

개념 모델 (Conceptual Model)

정보 모델 (Information Model)

엔티티의 요점

엔티티 (Entity)	요점
CLAUDE.md	세션 시작 시 주입되는 영속적 지시 파일 (Persistent Instruction File). scope는 managed / user / project / local의 4종류. 작업 디렉토리에서 상위 방향으로 탐색하여 발견된 파일을 연결하여 주입함
Rule	.claude/rules/*.md 형태의 모듈형 지시사항. paths의 glob 일치 시에만 주입. paths 생략 시 세션 시작 시 무조건 로드
Skill	SKILL.md와 보조 파일로 구성된 절차서. 디렉토리명이 슬래시 커맨드 (Slash Command) 이름임. 본체는 호출 시 주입되며, 압축 (Compaction) 후에도 호출된 것만 예산 (Budget) 내에서 유지
Subagent	독립된 컨텍스트를 가진 전용 어시스턴트. 마크다운 본문 (body)이 그대로 시스템 프롬프트 (System Prompt)가 됨 (독립된 systemPrompt 필드는 없음). 스코프 우선순위는 관리 (Managed) > CLI --agents > 프로젝트 (Project) > 사용자 (User) > 플러그인 (Plugin)
Hook	settings.json에서 정의하는 라이프사이클 훅 (Lifecycle Hook). skill / subagent의 프론트매터 (Frontmatter)에도 기술 가능. hookSpecificOutput.permissionDecision은 PreToolUse의 hookSpecificOutput 내에 중첩됨
OutputStyle	output-styles/*.md. 본문이 시스템 프롬프트 추가 지시사항. 빌트인 (Built-in) 스타일은 Default / Proactive / Explanatory / Learning
Settings	settings.json. 우선순위는 관리 (Managed) > CLI > 로컬 (Local) > 프로젝트 (Project) > 사용자 (User). 권한 (Permissions)은 모든 스코프에서 결합 병합(Combined Merge)되며, 스칼라 값은 상위 값이 하위 값을 덮어씀
MemoryDir	~/.claude/projects/<project>/memory/. MEMORY.md의 상위 200행 또는 25KB를 세션 시작 시 로드. 동일한 git 리포지토리의 모든 워크트리 (Worktree)에서 공유

구축 방법

CLAUDE.md

스코프에 따라 여러 위치에 둘 수 있습니다. 로드 순서는 범위가 넓은(Broad) 스코프가 우선입니다.

스코프	경로	공유 범위
조직 정책 (Org Policy)	OS 의존적 시스템 경로	모든 사용자
사용자 개인 (User)	~/.claude/CLAUDE.md	자신의 모든 프로젝트
프로젝트 (Project)	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀과 공유 가능
로컬 개인 (Local)	./CLAUDE.local.md (.gitignore 권장)	자신만 사용

/init 명령으로 기존 코드베이스를 분석하여 자동 생성할 수 있습니다. 기존 파일이 있다면 덮어쓰지 않고 개선 제안을 수행합니다.

/init

@path 임포트 (Import) 표기법으로 다른 파일을 읽어올 수 있습니다. 최대 4단계(Hop)까지 재귀적 임포트가 가능하며, 백틱 (Backtick)으로 감싸면 임포트되지 않습니다.

프로젝트 개요는 @README를 참조하세요.
사용 가능한 npm 명령은 @package.json을 참조하세요.
git 워크플로우는 @docs/git-instructions.md를 참조하세요.

권장되는 기술 스타일은 다음과 같습니다. 기준은 200행 이내이며, HTML 주석 (<!-- ... -->)은 컨텍스트에 주입되지 않으므로 유지보수자를 위한 주석으로 사용할 수 있습니다.

# 빌드 명령
- 테스트 실행: `npm test`
- 빌드: `npm run build`
...

대규모 모노레포 (Monorepo)에서 다른 팀의 CLAUDE.md를 제외하려면 claudeMdExcludes를 사용합니다.

{
"claudeMdExcludes": ["**/other-team/CLAUDE.md"]
}

Rules

.claude/rules/*.md에 배치하며, paths 프론트매터 (Frontmatter)로 적용 파일을 한정합니다. paths가 없는 경우에는 세션 시작 시 항상 로드됩니다.

---
paths:
- "src/api/**/*.ts"
...

사용자 수준의 규칙은 ~/.claude/rules/에 두며, 모든 프로젝트에 적용됩니다. 심볼릭 링크(Symbolic link)를 통해 공유 규칙을 재사용할 수 있습니다.

Skills

.claude/skills/<skill-name>/SKILL.md를 본체로 하며, 보조 파일들을 동일 디렉토리에 둡니다.

.claude/skills/deploy/
├── SKILL.md # 메인 절차서 (필수)
├── examples/sample.md
...

장소	경로	적용 범위
개인	~/.claude/skills/<name>/SKILL.md	자신의 모든 프로젝트
프로젝트	.claude/skills/<name>/SKILL.md	이 프로젝트만
플러그인	<plugin>/skills/<name>/SKILL.md	플러그인이 활성화된 곳

SKILL.md의 기술 예시와 주요 필드는 다음과 같습니다.

---
name: deploy-staging
description: 스테이징 환경으로 배포합니다. "스테이징에 배포", "배포하고 싶어"에 반응합니다.
...

필드	필수	설명
name	선택	표시 이름 (명령어 이름은 디렉토리 이름)
description	권장	스킬의 용도. 자동 매칭에 사용
argument-hint	선택	오토컴플리트 (Auto-complete)용 힌트
disable-model-invocation	선택	true로 설정 시 자동 실행을 비활성화
user-invocable	선택	false로 설정 시 / 메뉴에서 숨김
allowed-tools / disallowed-tools	선택	스킬 실행 중 허용 / 금지할 도구
model / effort	선택	스킬 실행 중 모델 및 에포트 (Effort) 덮어쓰기
context	선택	fork를 통해 서브 에이전트 (Sub-agent)로 실행
hooks / paths	선택	스킬에 연결된 훅 (Hooks) / 자동 활성화 glob

!command`` 구문을 사용하여 스킬 실행 시 셸 명령의 출력을 삽입할 수 있습니다.

Subagents

.claude/agents/<name>.md의 프론트매터 (Frontmatter)에서 정의하며, 본문이 시스템 프롬프트 (System prompt)가 됩니다. /agents 명령으로 대화형으로 생성 및 편집할 수 있습니다.

---
name: code-reviewer
description: 코드 리뷰를 수행하며 품질, 보안, 베스트 프랙티스 (Best practices)를 지적합니다. 코드 변경 후 자동으로 호출됩니다.
...

필드	필수	설명
name	필수	소문자 영숫자와 하이픈으로 구성된 고유 식별자
description	필수	언제 이 에이전트에게 위임해야 하는지
tools / disallowedTools	선택	사용 가능 / 제외할 도구 (생략 시 모든 도구 상속)
model	선택	sonnet / opus / haiku / fable / 전체 모델 ID / inherit
permissionMode	선택	default / acceptEdits / auto / dontAsk / bypassPermissions / plan
maxTurns	선택	최대 턴 수
skills / mcpServers / hooks	선택	프리로드 (Preload)할 스킬 / MCP 서버 / 연결된 훅
memory	선택	영구 메모리 범위 (user / project / local)
isolation	선택	worktree를 통해 독립된 git 워크트리에서 실행

CLI 플래그를 통해 세션 한정의 서브 에이전트를 정의할 수도 있습니다.

claude --agents '{"code-reviewer":{"description":"코드 리뷰 전문","prompt":"품질과 보안에 집중","tools":["Read","Grep","Glob"],"model":"sonnet"}}'

Hooks

settings.json의 hooks 키에 등록합니다. 스킬 / 에이전트의 frontmatter에도 기술할 수 있습니다.

{
"hooks": {
"EventName": [
...

종류 (type)	설명
command	셸 명령(shell command)을 실행
http	HTTP 엔드포인트(endpoint)를 호출
mcp_tool	MCP 서버의 도구를 호출
prompt	Claude에게 yes / no 판정을 요청
agent	서브 에이전트(sub-agent)를 기동하여 검증

주요 라이프사이클(lifecycle) 이벤트는 PreToolUse (도구 사용 전 · 차단 가능) / PostToolUse (도구 사용 성공 후) / UserPromptSubmit / Stop / SessionStart / SessionEnd / PreCompact (압축 전) / PostCompact / SubagentStart / SubagentStop / FileChanged 입니다. 이것들은 일부이며, 전체 이벤트 목록은 공식 Hooks 레퍼런스를 참조하십시오.

매처(matcher)는 완전 일치 ("Bash"), 파이프 구분 ("Edit|Write"), 정규 표현식 ("^Notebook"), 빈 문자열 (모든 도구)을 지원합니다. 종료 코드(exit code)가 0이면 stdout의 JSON을 분석하고, 2이면 이벤트별 확정적 차단 (PreToolUse는 도구 호출을 차단하고 stderr를 Claude에게 전달, Stop은 중지를 방지, PreCompact는 압축을 차단)을 수행하며, 그 외의 코드는 비차단(non-blocking) 에러로 간주하여 계속 진행합니다.

Output styles

.claude/output-styles/<name>.md에 배치하며, 본문 내용이 시스템 프롬프트(system prompt) 추가 지시사항이 됩니다.

---
name: Diagrams first
description: 모든 설명의 서두에 도표를 제시함
...

keep-coding-instructions: true는 응답 스타일만 변경하고, 코딩용 기본 지시사항을 유지합니다. 생략하면 내장된(built-in) 소프트웨어 엔지니어링 지시사항을 상속받지 않습니다. force-for-plugin은 플러그인 활성화 시 자동 적용되는 설정입니다 (플러그인 전용).

System prompt 추가

CLI 플래그를 통해 호출 시 지정합니다.