클로드 코드에게 일을 잘 시키는 방법

클로드 코드는 그냥 질문에 답하는 도구가 아닙니다. 프로젝트의 규칙을 읽고, 팀의 작업 방식을 기억하고, 반복 업무를 일정한 방식으로 처리하게 만들 수 있습니다.

그런데 여기서 자주 생기는 문제가 있습니다.

처음에는 모든 지시를 CLAUDE.md에 적습니다. 실행 명령어, 폴더 구조, 코딩 규칙, 배포 절차, 답변 스타일, 위험한 명령 금지까지 한 파일에 계속 붙입니다. 당장은 편하지만, 시간이 지나면 클로드 코드가 매번 읽어야 하는 지시가 너무 많아집니다.

Anthropic 원문은 이 문제를 이렇게 다룹니다. 클로드 코드에 지시를 전달하는 방법은 하나가 아니라 여러 가지이고, 각각은 읽히는 시점과 유지되는 방식이 다릅니다.

이 글에서는 원문에 나온 7가지를 한국어로 풀어보겠습니다.

• CLAUDE.md
• Rules
• Skills
• Subagents
• Hooks
• Output styles
• system prompt append

먼저 기준부터 잡기

원문은 각 방법을 비교할 때 세 가지를 봅니다.

1. 지시가 언제 컨텍스트에 들어오는가
2. 긴 대화가 압축된 뒤에도 유지되는가
3. 지시가 얼마나 강하게 적용되는가

여기서 컨텍스트는 클로드 코드가 현재 작업을 이해하기 위해 들고 있는 작업 공간입니다. 이 공간에는 사용자의 말만 들어가는 것이 아닙니다. 시스템 지시, 도구 설명, 프로젝트 메모, 스킬 설명 같은 정보도 함께 들어갑니다.

아래 이미지는 사용자가 첫 메시지를 보내기 전에도 어떤 정보들이 이미 컨텍스트에 들어갈 수 있는지 보여줍니다.

그래서 지시를 아무 데나 많이 넣는 것이 항상 좋은 전략은 아닙니다. 모든 작업에 필요하지 않은 지시가 계속 들어오면, 실제 작업에 써야 할 공간을 차지합니다.

아래 표를 먼저 보고 가면 뒤 내용이 훨씬 쉽습니다.

이 표를 억지로 외울 필요는 없습니다. 이제 하나씩 실제 감각으로 풀어보겠습니다.

CLAUDE.md는 프로젝트 전체 안내입니다

CLAUDE.md는 클로드 코드가 프로젝트를 시작할 때 읽는 대표적인 안내 파일입니다. 루트에 있는 CLAUDE.md는 세션 시작 때 읽히고, 긴 대화가 압축된 뒤에도 다시 읽힙니다.

그래서 거의 모든 작업에 필요한 정보가 잘 어울립니다.

# 프로젝트 안내

- 패키지 매니저는 pnpm입니다.
- 개발 서버는 pnpm dev로 실행합니다.
- 테스트는 pnpm test로 실행합니다.
- 주요 앱 코드는 apps/web에 있습니다.
- 공통 UI 컴포넌트는 packages/ui에 있습니다.

반대로, 특정 폴더에서만 필요한 규칙이나 배포 절차처럼 가끔만 필요한 내용까지 전부 넣으면 파일이 무거워집니다. 루트 CLAUDE.md의 모든 줄은 관련이 있든 없든 매 세션에서 비용을 만듭니다.

원문은 작업 위치에 따라 어떤 CLAUDE.md가 읽히는지 아래 그림으로 설명합니다.

왼쪽처럼 프로젝트 루트에서 작업을 시작하면 루트 기준의 CLAUDE.md가 세션 시작 때 읽힙니다. 오른쪽처럼 packages/api 같은 하위 폴더에서 작업하면 그 위치에 맞는 CLAUDE.md가 읽힙니다. 하위 폴더의 CLAUDE.md는 모든 세션에 항상 들어오는 것이 아니라, 관련 파일을 다룰 때 들어오는 성격이 강합니다.

좋은 CLAUDE.md는 긴 규칙 모음이 아니라 프로젝트의 지도에 가깝습니다. 어디에 무엇이 있고, 어떤 명령을 쓰고, 팀 전체가 공통으로 지키는 기본 약속이 무엇인지 알려주는 정도가 적당합니다.

Rules는 특정 상황의 규칙입니다

Rules는 .claude/rules/에 두는 마크다운 규칙입니다. CLAUDE.md와 비슷해 보이지만 용도가 조금 다릅니다.

예를 들어 이런 규칙이 있다고 해보겠습니다.

API 핸들러는 요청을 처리하기 전에 Zod로 입력값을 검증한다.

중요한 규칙이지만, 문서 파일을 고칠 때나 CSS를 수정할 때까지 항상 읽힐 필요는 없습니다. 이럴 때 Rules에 경로 조건을 걸 수 있습니다.

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

API 핸들러는 요청을 처리하기 전에 Zod로 입력값을 검증합니다.

이렇게 하면 src/api/** 또는 *.handler.ts에 해당하는 파일을 다룰 때만 규칙이 들어옵니다. 원문에서는 이것을 path-scoped rule로 설명합니다.

Rules를 고르는 기준은 이렇습니다.

Skills는 필요할 때 펼치는 작업 절차입니다

Skills는 .claude/skills/ 아래에 두는 작업 매뉴얼입니다. 각 스킬은 SKILL.md를 갖고, 그 안에 이름, 설명, 실제 절차가 들어갑니다.

중요한 점은 처음부터 모든 내용이 컨텍스트에 들어가지 않는다는 것입니다. 세션 시작 때는 스킬의 이름과 설명만 들어가고, 본문은 그 스킬이 실제로 호출될 때 읽힙니다.

원문 이미지는 이 차이를 보여줍니다.

그래서 Skills는 절차가 있는 일에 잘 맞습니다.

- 배포 체크리스트
- 코드 리뷰 절차
- 릴리즈 노트 작성
- 장애 보고서 정리
- 블로그 초안 작성 흐름

이런 내용을 CLAUDE.md에 길게 넣으면, 배포하지 않는 날에도 배포 절차가 계속 읽힙니다. 반면 Skills로 두면 필요할 때만 펼쳐봅니다.

예를 들어 코드 리뷰 스킬이라면 이런 식입니다.

# 코드 리뷰 스킬

1. 변경된 파일을 먼저 확인한다.
2. 동작 변경, 보안 위험, 테스트 누락을 우선 찾는다.
3. 발견한 문제를 심각도 순서로 정리한다.
4. 확실하지 않은 추측은 질문으로 남긴다.
5. 파일과 줄 번호를 함께 적는다.

원문에서는 호출된 Skills가 대화 압축 후에도 일정 예산 안에서 다시 들어오지만, 여러 스킬을 많이 호출하면 오래된 것부터 빠질 수 있다고 설명합니다. 즉 Skills도 무한히 쌓아두는 공간은 아닙니다.

Subagents는 메인 대화를 어지럽히지 않는 별도 작업자입니다

Subagents는 .claude/agents/에 두는 별도 작업자입니다. 이름, 설명, 사용할 도구 목록은 세션 시작 때 알려지지만, 실제 본문 지시는 메인 대화에 자동으로 들어오지 않습니다.

클로드 코드가 필요하다고 판단하면 Agent 도구로 Subagent를 호출합니다. 그러면 Subagent는 자기만의 새 컨텍스트에서 일하고, 메인 대화에는 최종 요약과 메타데이터만 돌아옵니다.

이 구조는 긴 조사에 좋습니다.

- 큰 로그 파일에서 장애 원인 찾기
- 의존성 위험 조사하기
- 오래된 코드베이스에서 관련 파일 훑기
- 여러 문서를 읽고 핵심만 요약하기

Skills와 헷갈릴 수 있는데 기준은 간단합니다.

블로그 작성으로 비유하면, 본문을 쓰는 작업은 메인 대화에서 진행하고, 원문 이미지 후보를 따로 모으는 긴 조사는 Subagent에게 맡길 수 있습니다. 중요한 것은 Subagent의 긴 작업 과정이 부모 대화의 컨텍스트를 직접 차지하지 않는다는 점입니다.

Hooks는 말이 아니라 자동 실행입니다

Hooks는 클로드 코드에게 “해줘”라고 부탁하는 지시가 아닙니다. 특정 이벤트가 발생했을 때 실행되는 자동 장치입니다.

원문 이미지는 클로드 코드의 작업 흐름에서 Hook이 끼어들 수 있는 지점을 보여줍니다.

Hooks는 settings.json, 관리 정책, 스킬이나 에이전트 설정에 등록할 수 있습니다. 종류도 여러 가지가 있습니다.

모든 Hook은 정해진 이벤트에서 실행됩니다. 특히 command, HTTP, mcp_tool은 더 결정적으로 동작합니다. 반면 prompt와 agent는 별도 모델 판단이 들어갈 수 있습니다.

Hooks가 필요한 대표 사례는 이렇습니다.

- 파일 수정 뒤 자동으로 린트나 포맷팅을 실행한다.
- 작업 완료 시 Slack에 알림을 보낸다.
- 위험한 명령을 실행하기 전에 차단한다.
- 대화 압축 전에 기록을 백업한다.

여기서 중요한 차이가 있습니다.

CLAUDE.md에 “위험한 명령은 실행하지 마”라고 적는 것은 지시입니다. 대부분 잘 따르겠지만, 긴 세션이나 애매한 상황에서는 실패할 수 있습니다. 정말 막아야 하는 일은 Hook이나 권한 설정처럼 결정적인 장치로 다루는 편이 맞습니다.

Output styles는 답변 방식과 역할을 바꿉니다

Output styles는 .claude/output-styles/에 두는 파일입니다. 세션 시작 때 시스템 프롬프트에 들어가고, 대화 압축으로 사라지지 않습니다.

이 방법은 지시를 강하게 전달합니다. 대신 영향 범위도 큽니다. 원문에서는 Output styles가 기본 출력 스타일을 대체할 수 있기 때문에 조심해서 써야 한다고 설명합니다.

예를 들어 이런 요구는 Output styles 후보입니다.

- 항상 설명형으로 답한다.
- 학습 모드처럼 이유를 자세히 알려준다.
- 더 주도적으로 작업을 진행한다.
- 일반 어시스턴트처럼 답한다.

하지만 Output styles를 잘못 만들면 클로드 코드가 기본적으로 갖고 있던 개발 도우미 역할 일부가 약해질 수 있습니다. 원문에서는 먼저 내장 스타일을 확인하라고 권합니다. Proactive, Explanatory, Learning 같은 기본 스타일이 이미 많은 경우를 커버하기 때문입니다.

system prompt append는 이번 실행에 붙이는 추가 지시입니다

append-system-prompt는 기본 시스템 프롬프트를 바꾸는 것이 아니라, 실행할 때 추가 지시를 덧붙이는 방식입니다. Output styles처럼 역할 자체를 크게 바꾸기보다, 기본 역할 위에 더하는 느낌입니다.

잘 맞는 예시는 이런 것입니다.

- 이번 세션에서는 답변을 짧게 한다.
- 특정 도메인의 용어를 우선 사용한다.
- 출력 형식을 일정하게 맞춘다.
- 특정 코딩 표준을 더 강조한다.

다만 이것도 길게 많이 붙이면 입력 토큰이 늘고, 지시가 서로 충돌할 가능성이 커집니다. 원문에서는 지시가 많아질수록 지시 준수력이 오히려 약해질 수 있다고 설명합니다.

빠르게 판단하는 기준

실전에서는 아래처럼 판단하면 됩니다.

오늘 바로 정리해보기

지금 쓰고 있는 지시를 아래처럼 나눠보세요.

## 항상 알아야 하는 프로젝트 정보
- 

## 특정 파일이나 폴더에서만 필요한 규칙
- 

## 순서대로 따라야 하는 작업 절차
- 

## 반드시 실행되거나 막혀야 하는 자동화
- 

## 답변 방식이나 말투
- 

그리고 이렇게 옮기면 됩니다.

클로드 코드 설정은 지시를 많이 쓰는 싸움이 아닙니다. 적절한 위치에 두는 싸움입니다.

처음부터 완벽히 나눌 필요는 없습니다. 오늘은 CLAUDE.md에 있는 한 문장만 골라서 물어보세요.

이 지시는 항상 필요한가, 특정 상황에서만 필요한가?

이 질문이 시작점입니다.