---

Claude Code를 쓰다 보면 자연스럽게 부딪히는 문제가 있다. 컨텍스트 윈도우 한계. 한 대화에서 코드 분석, 구현, 테스트, 리뷰를 다 하면 금방 컨텍스트가 차버린다. 이걸 해결하려면 Claude Code의 구조를 이해하고, 작업을 분산시키는 법을 알아야 한다.

전체 구조 — 한눈에 보기

┌───────────────────────────────────────────────┐
│                사장 (사용자)                     │
│           "이거 해줘" / "/ralph" / ...          │
└─────────────────────┬─────────────────────────┘
                      │
┌─────────────────────▼─────────────────────────┐
│           하네스 (Claude Code CLI)              │
│  ┌───────────────────────────────────────────┐ │
│  │ settings.json / hooks / 권한 / MCP 서버    │ │
│  │ 도구(Read, Edit, Bash...) / 모델 선택      │ │
│  └───────────────────────────────────────────┘ │
│                      │                         │
│  ┌───────────────────▼───────────────────────┐ │
│  │        메인 에이전트 (매니저)                │ │
│  │                                           │ │
│  │  참고: CLAUDE.md, Skills, Memory, MCP     │ │
│  │  부림: Subagents, Teams, Tools            │ │
│  └───────────────────────────────────────────┘ │
└───────────────────────────────────────────────┘

회사에 비유하면 이렇다:

• 사용자 = 사장
• 하네스 = 회사 건물 + IT 인프라
• 메인 에이전트 = 매니저
• 서브에이전트 = 팀원(직원)
• 스킬 = 업무 매뉴얼(SOP)
• CLAUDE.md = 사규/취업규칙

하네스 — 회사 건물과 IT 인프라

Claude Code CLI 자체를 “하네스”라고 부른다. LLM(메인 에이전트)을 감싸고 있는 실행 환경이다.

하네스가 제공하는 것:
├─ 도구 (Read, Edit, Bash, Grep, Glob, Agent...)
├─ 권한 관리 (어떤 도구를 허용/차단)
├─ 훅 (특정 이벤트에 자동 실행되는 셸 명령)
├─ MCP 서버 연결 (GitHub, Notion, Playwright...)
├─ 모델 선택 (opus, sonnet, haiku)
└─ 컨텍스트 관리 (대화 압축, 윈도우 관리)

LLM이 직원이라면, 하네스는 그 직원이 일하는 사무실이다. 컴퓨터, 네트워크, 출입 권한, 사내 시스템 — 이 모든 걸 하네스가 제공한다. LLM 자체는 텍스트를 생성할 뿐이고, 실제로 파일을 읽고 쓰고 실행하는 건 전부 하네스가 처리한다.

하네스 엔지니어링 — 사무실 세팅 최적화

하네스 엔지니어링이란 Claude Code의 설정/훅/도구/프롬프트를 최적화하는 작업이다. 새 직원(LLM)이 왔을 때 “우리 회사는 이렇게 일하고, 이 도구 쓰고, 이 규칙 따라”하고 온보딩하는 것과 같다.

하네스 엔지니어링 요소:
│
├─ CLAUDE.md 작성         → "이 회사는 이렇게 일해" (사규)
├─ settings.json 설정     → 권한, 환경변수, 모델 설정
├─ hooks 설정             → 자동화 트리거
│   예: "커밋 전에 린트 돌려라"
│   예: "세션 시작 시 특정 컨텍스트 주입"
├─ .claude/agents/*.md    → 커스텀 직원 정의
├─ .claude/skills/*.md    → 커스텀 SOP 정의
├─ MCP 서버 연결          → 외부 도구 확장
└─ 메모리 시스템 구축      → 대화 간 지식 유지

잘 세팅된 하네스는 매번 같은 말을 반복할 필요 없이, LLM이 프로젝트의 규칙과 맥락을 자동으로 파악하게 만든다.

서브에이전트 — 팀원(직원)

서브에이전트는 독립된 컨텍스트 윈도우에서 실행되는 별도의 LLM 프로세스다. 핵심은 “독립된 컨텍스트”라는 점이다. 메인 에이전트의 컨텍스트를 소모하지 않고, 작업 결과의 요약만 돌려준다.

사용 가능한 에이전트 종류

빌트인 에이전트 (Claude Code 기본 제공):

• general-purpose — 범용
• Explore — 코드베이스 탐색 특화
• Plan — 구현 계획 수립

OMC 에이전트 (oh-my-claudecode 플러그인 제공):

• executor — 코드 구현
• debugger — 버그 분석
• code-reviewer — 코드 리뷰
• architect — 시스템 설계
• planner — 작업 계획
• verifier — 완료 검증
• test-engineer — 테스트 전략
• designer — UI/UX
• writer — 문서 작성
• 그 외 다수

커스텀 에이전트 만들기

.claude/agents/ 폴더에 마크다운 파일을 넣으면 바로 사용 가능하다.

---
name: my-reviewer
description: 우리 프로젝트 코딩 컨벤션에 맞는 코드 리뷰
model: opus
tools: ["Read", "Glob", "Grep", "Bash"]
---

너는 코드 리뷰 전문가야.
다음 규칙을 기준으로 리뷰해:
1. 함수명은 camelCase
2. 파일당 200줄 이하
3. any 타입 사용 금지

필드	설명
name	호출 시 사용할 이름
description	언제 이 에이전트를 쓸지 판단 기준
model	haiku(빠름), sonnet(표준), opus(최고성능)
tools	사용 가능한 도구 제한 (생략하면 전부)
본문	시스템 프롬프트 (에이전트의 행동 지침)

스킬 — 업무 매뉴얼(SOP)

스킬은 직원의 “능력”이 아니다. 메인 에이전트가 따르는 업무 절차서다.

/ralph을 호출하면 메인 에이전트의 행동 방식 자체가 바뀐다. “완료될 때까지 반복해라”라는 SOP가 적용되는 것이다. 스킬은 메인 컨텍스트에 로드되어 메인 에이전트가 직접 따른다.

대표적인 스킬들:

• /ralph — “끝날 때까지 퇴근하지 마” (완료까지 자율 반복)
• /tdd — “테스트 먼저 쓰고 구현해” (TDD 프로세스)
• /autopilot — “보고 없이 알아서 끝까지 해” (완전 자율)
• /team — “팀 구성해서 병렬로 처리해” (멀티에이전트 조율)
• /ralplan — “합의될 때까지 계획 토론해” (계획 수립)

커스텀 스킬 만들기

.claude/skills/ 폴더에 마크다운 파일을 넣으면 된다.

---
name: deploy
description: 프로젝트 배포 프로세스
---

1. 빌드 실행
2. 테스트 통과 확인
3. 배포 명령 실행
4. 배포 결과 확인

Subagent vs Skill — 핵심 차이

	Subagent (에이전트)	Skill (스킬)
실행 위치	별도 프로세스 (독립 컨텍스트)	메인 컨텍스트에서 실행
컨텍스트	자기만의 컨텍스트 윈도우 사용	메인 컨텍스트를 소모
정의 파일	.claude/agents/*.md	.claude/skills/*.md
호출 방식	Claude가 자동 판단 또는 사용자 지시	/skill-name 또는 자동 트리거
용도	작업 실행	작업 방법론 정의
비유	팀원	업무 매뉴얼/SOP

한 줄로 정리하면: Skill이 전략, Subagent가 전술.

Team — 프로젝트 팀

Team은 여러 서브에이전트를 조직적으로 운영하는 모드다. 태스크 리스트를 공유하며 병렬로 실행한다.

/team 4:executor "전체 타입 안전성 강화"
→ executor 4명이 태스크 리스트를 나눠서 병렬 처리
→ 메인은 조율만

Team 파이프라인의 기본 흐름:

team-plan    → explore + planner가 계획 수립
team-exec    → executor들이 병렬 구현
team-verify  → verifier가 검증
team-fix     → 문제 있으면 수정 루프

구성요소 관계 총정리

개념	파일 위치	비유	컨텍스트 영향	역할
CLAUDE.md	프로젝트 루트	사규	항상 로드	행동 규칙
Skill	.claude/skills/	업무 SOP	호출 시 메인에 로드	워크플로 정의
Agent	.claude/agents/	직원 프로필	별도 컨텍스트	독립 작업 수행
Hook	settings.json	자동화 장치	하네스 레벨	이벤트 시 셸 실행
MCP	settings.json	외부 협력사	하네스 레벨	외부 서비스 연결
Memory	~/.claude/projects/	업무 일지	세션 시작 시 로드	대화 간 지식 유지
Team	런타임	프로젝트 팀	각자 독립	여러 Agent 조율

실제 흐름 예시

“다크모드 추가해줘”라고 /ralph과 함께 요청하면:

1. Skill 로드: /ralph SOP가 메인 컨텍스트에 주입
   → "완료될 때까지 반복, verifier로 검증"

2. 메인 에이전트 판단:
   → CLAUDE.md 참고: "plan mode 먼저"
   → Memory 참고: "이 프로젝트는 Next.js + Tailwind"

3. Agent(explore) 파견: 코드베이스 조사
   → 별도 컨텍스트에서 실행
   → "Tailwind v4 사용 중, 현재 라이트 테마만" 보고

4. Agent(planner) 파견: 계획 수립
   → "CSS 변수 방식, 3개 파일 수정 필요" 보고

5. Agent(executor) 파견: 구현
   → 별도 컨텍스트에서 코드 수정
   → "완료" 보고

6. Agent(verifier) 파견: 검증
   → "빌드 통과, 토글 동작 확인" 보고

7. ralph SOP에 따라: 검증 통과 → 완료 선언

메인 에이전트는 5번의 Agent 호출을 했지만, 실제 코드를 읽거나 수정한 건 없다. 컨텍스트에는 각 Agent의 요약 보고만 남아서 컨텍스트 수명이 극적으로 늘어난다.

컨텍스트 절약 효과

직접 작업:   ████████████████████ 100% 소모
서브에이전트: ███                  ~15% (결과 요약만)
Team 모드:   ██                   ~10% (조율 메시지만)

시나리오별 추천 방식

상황	추천 방식
파일 1-2개 간단 수정	직접 작업
3개+ 파일 탐색/수정	Agent 위임
”이거 조사해줘”	Agent(Explore)
대규모 구현	/team N:executor
완료까지 알아서	/ralph
계획 먼저	/ralplan → /team
리뷰 + 수정	Agent(code-reviewer) → Agent(executor)

핵심 원칙: 메인 컨텍스트는 지휘관 역할만 하고, 실제 작업은 전부 서브에이전트에게 위임하면 컨텍스트 수명이 5~10배 늘어난다.

← All posts