안녕하세요, 한양노비입니다.
저번 글에서 Claude Code로 풀스택 프로젝트를 만들고 배포한 이야기를 했었는데요.
이번엔 그 과정에서 삽질하며 쌓은 것과 이번에 새로 들어가는 프로젝트의 클로드 세팅을 하는 과정에서 CLAUDE.md를 어떻게 써야 효과가 있는지, Skills는 뭔지, 정리해보았습니다.
CLAUDE.md — AI에게 주는 업무 매뉴얼
Claude Code에는 CLAUDE.md라는 파일이 있습니다. 세션을 시작하면 이 파일을 자동으로 읽고, 여기에 적힌 규칙을 따릅니다. 쉽게 말하면 신입사원에게 주는 업무 매뉴얼 같은 거예요.
처음엔 이 파일의 중요성을 몰랐습니다. 매번 대화에서 "우리 프로젝트는 Spring Boot고, JPA 쓰고, 이 폴더 구조를 따르고..." 라고 설명했거든요. 세션을 끊으면 또 처음부터 설명해야 했고, 한 세션에서 길게 대화할 때면 이전에 말한 내용이 계속 날아가곤 했습니다. 그때마다 토큰이 날아갔습니다.
잘 쓰면 효과가 큰 이유
CLAUDE.md의 내용은 대화가 시작될 때 컨텍스트 윈도우 앞쪽에 주입됩니다. LLM은 컨텍스트의 앞부분에 더 강한 주의를 기울이는 경향이 있어서, 여기에 적힌 규칙은 준수율이 높습니다.
반대로, 이 파일이 길어지면 실제 코드와 대화에 쓸 수 있는 공간이 줄어듭니다. 그래서 짧고 밀도 높게 쓰는 게 핵심입니다.
작성할 때 알면 좋은 원칙들
첫째, 서술형이 아니라 명령형으로 씁니다.
LLM은 instruction tuning을 거친 모델이라, 지시문 형태에 가장 강하게 반응합니다.
# 나쁜 예
우리 팀에서는 보통 컴포넌트를 만들 때 Zustand를 사용하는 편입니다.
# 좋은 예
상태관리: Zustand 사용. Redux, Context API 사용 금지."~하는 편입니다"는 참고 정보일 뿐이고, "~사용. ~금지."는 따라야 할 규칙으로 인식됩니다.
둘째, 금지 사항을 반드시 명시합니다.
금지 규칙이 없으면 LLM은 학습 데이터에서 가장 흔한 패턴으로 기본값을 잡습니다. any 타입을 안 쓰길 원하면 "쓰지 마"라고 명시적으로 적어야 합니다.
셋째, 조건부 규칙이 효과적입니다.
# 상태 관리 선택 기준
- 서버 데이터 → TanStack Query 사용
- 전역 클라이언트 상태 → Zustand 사용
- 폼 상태 → React Hook Form 사용이렇게 하면 모델이 단순히 규칙을 따르는 것이 아니라, 상황에 맞는 판단을 할 수 있게 됩니다.
넷째, 개발자 컨텍스트 한 줄이 생각보다 임팩트가 큽니다.
## 개발자 컨텍스트
- 역할: 프론트엔드 개발자, 백엔드 인수인계 학습 중이건 정말 꿀팁인게 이 한 줄이 있으면 Service 레이어를 설명할 때 "React의 custom hook과 비슷한 역할"이라는 식의 브릿지를 자동으로 만들어줍니다. 없으면 순수 백엔드 개발자에게 설명하듯 답변이 나옵니다.
CLAUDE.md 분할 — 언제 하면 좋을까
CLAUDE.md가 200줄을 넘어가면 분할을 고려할 시점입니다. 프로젝트 루트에 CLAUDE.md를 두고, 하위 디렉토리에 각각의 CLAUDE.md를 두면 Claude Code가 작업 디렉토리 기준으로 계층적으로 읽습니다.
/CLAUDE.md ← 공통 (기술 스택, 커밋 규칙)
/frontend/CLAUDE.md ← 프론트엔드 전용
/backend/CLAUDE.md ← 백엔드 전용백엔드 작업할 때 프론트엔드 규칙까지 로드할 필요가 없으니까, 컨텍스트가 절약됩니다.
다만 저희 프로젝트는 아직 163줄이라 분할 안 하고 하나로 유지하고 있습니다. Claude Code한테 분할할지 물어봤더니 "지금 당장은 안 하는 게 맞습니다. 163줄짜리 파일을 굳이 쪼갤 필요 없음"이라고 하더라고요. AI한테 물어보는 것도 방법입니다.
Skills — 필요할 때만 꺼내 먹어요~
CLAUDE.md가 "항상 적용되는 사내 규칙"이라면, Skills는 "특정 업무를 할 때만 꺼내 보는 전문 매뉴얼"입니다.
이게 왜 필요한지는 실제로 겪어보면 바로 느낍니다. 저는 백엔드 인수인계용으로 4단계 워크플로우를 만들어서 썼거든요.
- research-api: API 코드를 분석해서 research.md 보고서로 작성
- write-plan: 수정 계획을 plan.md로 작성
- review-plan: plan.md 안의 질문에 답변하고 문서 업데이트
- execute-plan: plan.md에 적힌 대로 순서대로 구현
처음엔 이 4단계 규칙을 전부 CLAUDE.md에 넣었습니다. 합치면 약 1,000~1,500 토큰인데, API 분석할 때 "실행 규칙"은 필요 없고, 실행할 때 "분석 규칙"은 필요 없습니다. 항상 전체가 로드되니까 매번 불필요한 토큰이 낭비됐습니다.
Skills로 분리하면 /research-api를 호출할 때 분석 규칙만 로드되고, /execute-plan을 호출할 때 실행 규칙만 로드됩니다. CLAUDE.md에는 프로젝트 컨텍스트만 200~300 토큰으로 남기면 됩니다.
Skills 만드는 법
.claude/skills/ 디렉토리에 SKILL.md 파일을 만들면 됩니다.
.claude/skills/
├── research-api/
│ └── SKILL.md
├── write-plan/
│ └── SKILL.md
├── review-plan/
│ └── SKILL.md
└── execute-plan/
└── SKILL.md각 SKILL.md의 frontmatter에 description을 적으면 Claude가 관련 작업 시 자동으로 해당 스킬을 로드합니다. disable-model-invocation: true를 추가하면 자동 호출을 막고 /스킬명으로만 호출할 수 있게 됩니다.
execute-plan 같은 "조심해야 하는" 스킬은 자동 호출을 막아두는 게 안전합니다. 실수로 코드를 구현하기 시작하면 곤란하니까요.
실제 사용 흐름
> GET /api/v1/orders 분석해줘
→ Claude가 "API 분석" 키워드를 감지 → research-api 스킬 자동 로드
> /write-plan orders API에 페이지네이션 추가
→ write-plan 스킬 수동 호출 → plan.md 작성
> /review-plan
→ plan.md 내 [질문] 태그 답변
> /execute-plan
→ plan.md 기반 순차 구현매번 긴 프롬프트를 복사 붙여넣기할 필요가 없어졌습니다.
에이전트는 왜 안 쓰나요?
Claude Code에는 에이전트(서브에이전트)라는 기능도 있습니다. 메인 세션에서 서브에이전트를 생성하면 독립된 컨텍스트 창을 새로 받아서 작업하고, 최종 결과만 메인으로 돌려주는 구조입니다. 메인 컨텍스트를 오염시키지 않으면서 무거운 탐색 작업을 위임할 수 있고, 서로 겹치지 않는 작업은 병렬 실행도 됩니다.
근데 실제로 써보니, 지금 저희 상황에서는 스킬만으로 충분했습니다.
에이전트가 진짜 필요한 건 "파일 30개 이상을 분석해야 하거나, 서로 의존하지 않는 기능을 동시에 개발할 때"입니다. 회원관리, 권한관리, 로그관리 API를 동시에 만들라고 하면 에이전트 3개가 병렬로 각각 처리하고 결과만 반환합니다. 순차적으로 하면 3배 걸릴 걸 동시에 끝내는 거죠.
하지만 저희 프로젝트는 도메인 간 의존성이 있어서(예: 권한관리가 회원 Entity를 참조) 병렬로 돌리면 충돌이 날 수 있었고, 혼자 작업하는 규모에서는 스킬 워크플로우로 순차 진행하는 게 오히려 안정적이었습니다. 거기에 가장 큰 이유는 멀티에이전트 워크플로우는 단일 세션 대비 토큰을 상당히 많이 쓴다는 것도 부담이었습니다.
결론적으로, 에이전트는 "있으면 좋은 것"이지 "없으면 안 되는 것"은 아닙니다. CLAUDE.md와 Skills만 잘 잡아도 대부분의 작업은 커버된다고 판단했고, 프로젝트가 커지면서 병렬 처리가 필요해질 때 도입하기로 결정했습니다.
세팅 전체 구조 요약
최종적으로 제가 세팅한 Claude Code 환경을 한 눈에 정리하면 이렇습니다.
프로젝트 루트/
├── CLAUDE.md ← 프로젝트 개요, 기술 스택, 공통 규칙 (간결하게)
├── .claude/
│ ├── settings.json ← Hooks, 퍼미션 설정
│ └── skills/
│ ├── research-api/SKILL.md ← API 분석 워크플로우
│ ├── write-plan/SKILL.md ← 수정 계획 작성
│ ├── review-plan/SKILL.md ← 핑퐁 리뷰
│ └── execute-plan/SKILL.md ← 계획 실행Claude Code한테 직접 물어보기
이번 세팅 과정에서 가장 도움이 됐던 습관이 하나 있습니다. Claude Code 본인한테 "이거 어떻게 작동해?"라고 직접 물어보는 겁니다.
settings.json이 뭐 하는 파일인지, Skills는 어떤 원리로 로드되는지, 에이전트는 언제 쓰면 좋은지 — 이런 질문을 전부 Claude Code한테 직접 했습니다. "너한테 CLAUDE.md를 길게 쓰면 어떻게 처리돼?", "지금 163줄인데 분할하는 게 맞아?" 같은 식으로요. 솔직히 저보다 자기 자신이 어떻게 동작하는지를 더 잘 아니까요.
다만 여기서 중요한 게 있습니다. 답변을 그대로 믿지 않고, 반드시 직접 적용해서 검증했습니다.
실제로 /advisor 기능을 설정할 때, Claude Code가 claude mcp auth "claude.ai Figma" 라는 명령어를 알려줬는데 이건 아예 존재하지 않는 명령어였습니다. hallucination이었던 거죠. 다시 물어보니 다른 방법을 알려줬고, 그걸로 해결했습니다.
AI 도구의 기능을 파악할 때 가장 빠른 루프는 이겁니다: 물어보고 → 적용해보고 → 안 되면 다시 물어보기. 공식 문서를 찾아 읽는 것보다 이 루프가 훨씬 빨랐습니다. 다만 AI가 자기 자신의 기능을 설명하는 것조차 100% 정확하지 않을 수 있다는 점~
마무리
결국 Claude Code 세팅하면서 느끼는건 AI한테 일을 잘 시키는 구조를 만드는 것이었습니다.
CLAUDE.md는 매번 말하기 귀찮은 규칙을 미리 적어두는 거고, Skills는 작업별 전문 매뉴얼을 필요할 때만 꺼내는 거고, Hooks는 Claude가 까먹지 않게 강제하는 겁니다.
이전 글에서도 말했지만, AI를 잘 쓰는 방법은 사람과 잘 협업하는 방법과 크게 다르지 않습니다. 업무 매뉴얼을 잘 정리해두고, 전문가한테 적절히 자문 구하고, 실수 방지 장치를 걸어두는 거죠.
감사합니다, 한양노비였습니다.
참고 자료
- CLAUDE.md 공식 문서 — CLAUDE.md 동작 방식
- Skills 공식 문서 — disable-model-invocation, 호출 방식, 자동 로드 원리
- Introducing Agent Skills (Anthropic 제품 블로그) — Skills 공식 출시 발표
- Equipping agents for the real world with Agent Skills (Anthropic 엔지니어링 블로그) — Skills 설계 철학 및 Progressive Disclosure 원리
- anthropics/skills (GitHub) — Anthropic 공식 Skills 저장소 및 SKILL.md 템플릿
- Best Practices 공식 문서 — 서브에이전트 병렬 처리 및 컨텍스트 관리
