Claude Code로 팀 AI 표준을 자동화하는 세 레이어: CLAUDE.md, 커스텀 커맨드, 서브에이전트
Claude Code를 팀에 도입하고 나서 가장 먼저 부딪히는 문제가 있습니다. "왜 내 AI는 axios를 쓰지 말라고 했는데 옆 동료 AI는 멀쩡하게 axios를 쓰고 있지?" 개인 설정 파일이 흩어져 있고, 팀 컨벤션은 누군가의 머릿속에만 있고, 새로 합류한 개발자는 AI에게 물어봐도 엉뚱한 패턴을 받아서 쓰고 있습니다. 결국 AI를 쓰면 쓸수록 팀 코드의 일관성이 오히려 흐트러지는 역설적인 상황이 만들어지죠.
이 문제가 생기는 근본적인 이유는 AI가 "팀의 맥락"을 모르기 때문입니다. 코딩 스타일, 아키텍처 결정, 서비스별 제약 — 이런 것들이 시니어 리뷰어 머릿속에는 있지만 AI에게는 전달되지 않습니다. 매 세션마다 "우리 팀은 axios 안 쓰고요, 비즈니스 로직은 Service에 넣어야 하고요..." 같은 컨텍스트를 반복해서 입력하다가 결국 포기하는 경우도 많이 봤습니다.
CLAUDE.md로 팀 표준을 AI에게 주입하고, 커스텀 커맨드(스킬)로 반복 절차를 코드화하고, 서브에이전트로 병렬 작업을 위임하면 팀의 집단 지성이 AI 행동 기준으로 내재화됩니다. 저도 처음엔 CLAUDE.md 하나만 달랑 만들어놓고 "됐겠지" 했다가, 커스텀 커맨드와 서브에이전트의 조합을 이해하고 나서야 팀원들이 AI가 생성한 코드를 통째로 되돌리는 일이 사라졌습니다.
핵심 개념
CLAUDE.md — AI를 위한 팀 헌법
CLAUDE.md는 마크다운 파일로, Claude Code가 세션을 시작할 때 자동으로 읽어들입니다. 위치는 두 곳입니다.
- 홈 디렉토리 (
~/.claude/CLAUDE.md): 모든 프로젝트에 공통으로 적용되는 개인 설정 - 프로젝트 루트 (
./CLAUDE.md): 해당 레포에만 적용되는 팀 공유 설정
두 파일이 모두 있을 때는 프로젝트 루트의 CLAUDE.md가 홈 설정 위에 추가됩니다. 팀 표준을 공유하려면 프로젝트 루트에 CLAUDE.md를 만들고 Git에 커밋하면 됩니다. 신규 입사자가 레포를 클론하는 순간부터 AI가 팀 컨벤션을 이미 알고 있는 것처럼 동작합니다.
# 프로젝트 규칙
## 금지 패턴
- axios 사용 금지 → fetch API 또는 ky 사용
- TypeScript `any` 타입 사용 금지
- 직접 DOM 조작 금지 → React state로 처리
## 빌드 & 검증 커맨드
- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 린트: `pnpm lint`
## 아키텍처 규칙
- 도메인 경계: frontend(Next.js) / backend(NestJS) / infra(Terraform) 분리
- 비즈니스 로직은 Service에, Controller는 thin하게
- Server Component 기본, Client Component는 최소화
## 코드 스타일
- TypeScript strict mode 필수
- async/await 사용 (`.then()` 금지)
- 2-space indentation💡 팁: 지침의 위치가 중요합니다. LLM은 파일의 처음과 끝에 배치된 내용을 더 신뢰성 있게 따르는 경향이 실무에서 관찰됩니다. 지침 수가 많아질수록 전반적인 준수율도 떨어지기 때문에, 가장 중요한 금지 패턴은 상단에 배치하고 파일은 300줄 이하로 유지하는 것을 권장합니다.
GitHub 등 여러 팀의 공개 사례에 따르면, CLAUDE.md를 잘 운영하는 팀은 AI가 잘못된 패턴을 생성하면 즉시 CLAUDE.md에 추가해 재발을 방지하는 피드백 루프를 운영합니다. "AI가 또 이상한 걸 만들었어"가 아니라 "CLAUDE.md 업데이트 시간이야"가 되는 거죠. 이 루프를 몇 주만 돌리면 파일이 팀의 살아있는 기술 문서처럼 진화합니다.
커스텀 커맨드(스킬) — 절차 지식의 코드화
CLAUDE.md가 "무엇이 맞고 틀린지(fact)"를 담는다면, 커스텀 커맨드(스킬)는 "어떻게 해야 하는지(procedure)"를 담습니다. .claude/skills/ 디렉토리에 SKILL.md 파일로 정의하는 재사용 가능한 절차입니다.
.claude/skills/
├── pr-review/
│ └── SKILL.md # PR 리뷰 체크리스트 자동 실행
├── deploy/
│ └── SKILL.md # 배포 전 검증 + 순서
├── commit/
│ └── SKILL.md # 커밋 메시지 컨벤션 강제
└── db-migration/
└── SKILL.md # 마이그레이션 안전성 검사Claude Code는 세션 시작 시 .claude/skills/ 디렉토리를 스캔합니다. SKILL.md 파일 안에 호출 커맨드를 명시해두면, 대화창에서 /pr-review처럼 슬래시 커맨드를 입력할 때 해당 파일이 로드되어 절차가 실행됩니다. CLAUDE.md가 세션 내내 컨텍스트를 점유하는 것과 달리, 스킬은 호출될 때만 로드되기 때문에 토큰 비용을 아끼면서도 팀 절차를 재사용 가능하게 관리할 수 있습니다.
# SKILL.md 예시 (pr-review/SKILL.md)
## PR 리뷰 스킬
이 스킬은 `/pr-review` 커맨드로 호출됩니다.
### 수행 절차
1. `git diff main...HEAD --name-only`로 변경된 파일 목록 확인
2. 영향 범위가 큰 파일부터 순서대로 다음 항목 검토:
- [ ] TypeScript 타입 안전성 (`any` 사용 여부, 타입 추론 과의존도)
- [ ] 테스트 커버리지 (새 로직에 테스트 존재 여부)
- [ ] 보안 취약점 (SQL injection, XSS, 민감 데이터 노출 패턴)
- [ ] 성능 이슈 (N+1 쿼리, 불필요한 리렌더링)
3. 각 이슈를 severity별로 분류:
- blocker: 머지 전 반드시 수정
- major: 권장 수정
- minor: 스타일 제안
4. 요약 리포트를 마크다운 표 형식으로 출력⚠️ 주의: 스킬 파일은 코드처럼 버전 관리가 필요합니다. 처음엔 열심히 만들어도 프로젝트가 바뀌면서 구식이 되어버리는 경우가 많습니다. 분기별로 스킬 내용이 현재 프로젝트에 맞는지 검토하는 루틴을 만들어두는 것을 권장합니다.
솔직히 "하루에 두 번 이상 같은 프롬프트를 복사해서 붙여넣고 있다면" 스킬로 만들어야 할 신호입니다. 배포 전 체크리스트, PR 리뷰 양식, 커밋 메시지 형식 — 이런 것들이 스킬의 전형적인 후보입니다.
서브에이전트(Subagents) — 병렬 작업 위임
서브에이전트는 독립된 컨텍스트 윈도우에서 실행되는 별도의 Claude 인스턴스입니다. 메인 에이전트가 오케스트레이터 역할을 해서 복잡한 작업을 여러 서브에이전트에 분산하는 구조입니다.
메인 에이전트 (Opus — 오케스트레이션, 복잡한 추론)
├── frontend 서브에이전트 (Sonnet) → UI 컴포넌트 구현
├── backend 서브에이전트 (Sonnet) → API 엔드포인트 구현
└── review 서브에이전트 (Sonnet) → 코드 리뷰 & 보안 검사모델 선택에 대해 제 경험을 공유하자면, 오케스트레이터에는 Opus를 씁니다. 작업을 어떻게 쪼갤지, 서브에이전트 결과가 서로 충돌하지 않는지 판단하는 추론이 핵심이기 때문입니다. 실제 구현을 담당하는 서브에이전트는 Sonnet으로 충분하고, 속도와 비용 면에서 훨씬 낫습니다. 결국 복잡한 판단 = Opus, 집중된 실행 = Sonnet, 대규모 반복 = Haiku로 역할을 나누는 것이 균형점입니다.
포어그라운드(동기) 모드에서는 서브에이전트 결과를 기다린 뒤 메인 에이전트가 다음 단계를 진행하고, 백그라운드(비동기) 모드에서는 여러 서브에이전트가 동시에 작업을 진행합니다.
| 모드 | 특성 | 적합한 상황 |
|---|---|---|
| 포어그라운드(동기) | 순서 보장, 의존성 있는 작업 | A 완료 후 B 시작이 필요한 경우 |
| 백그라운드(비동기) | 병렬 실행, 속도 최적화 | 독립적인 도메인 작업 동시 진행 |
📖 컨텍스트 윈도우(Context Window): LLM이 한 번에 처리할 수 있는 텍스트의 최대 크기입니다. 서브에이전트는 각자 독립된 컨텍스트 윈도우를 가지므로, 메인 에이전트의 컨텍스트가 가득 차더라도 서브에이전트는 깔끔한 상태로 집중 작업을 처리할 수 있습니다.
실전 적용
예시 1: 팀 CLAUDE.md + 커스텀 커맨드로 신규 입사자 온보딩 자동화
실무에서 자주 맞닥뜨리는 상황인데, 신규 개발자가 합류하면 팀 컨벤션을 배우는 데만 1~2주가 걸립니다. 문서는 오래되어 있고, 선배 개발자에게 물어보면 "코드 보면 알아" 소리를 듣는 게 대부분이죠. CLAUDE.md와 커스텀 커맨드를 조합하면 AI가 팀 컨벤션을 즉시 알려주는 온보딩 파트너 역할을 합니다.
# CLAUDE.md (팀 전체 공유)
## 도메인 지식
- 사용자 인증은 JWT (refresh token rotation 방식)
- 결제는 별도 payment-service로 분리됨 (직접 DB 접근 금지)
- 배포 환경: staging(자동 배포) → production(수동 승인 필요)
## 신규 개발자를 위한 안내
- 코드 생성 전 반드시 `pnpm lint`로 스타일 검증
- PR 생성 전 `/pr-review` 커맨드 실행 권장
- DB 스키마 변경 시 `/db-migration` 커맨드 필수 실행# .claude/skills/onboarding/SKILL.md
## 온보딩 스킬
이 스킬은 `/onboarding` 커맨드로 호출됩니다.
### 수행 절차
1. `cat package.json`으로 의존성 및 npm scripts 확인
2. `cat tsconfig.json`으로 TypeScript 설정 파악
3. `ls src/`로 최상위 디렉토리 구조 파악
4. `find . -maxdepth 3 -name "*.module.ts" | head -20`으로 주요 모듈 구조 탐색
5. CLAUDE.md의 아키텍처 규칙과 실제 디렉토리 구조 대조
6. 다음 항목을 마크다운으로 출력:
- **핵심 디렉토리 구조** (3 depth 이하)
- **자주 사용하는 커맨드** (package.json scripts 기반)
- **주의해야 할 팀 컨벤션** (CLAUDE.md의 금지 패턴 요약)
- **첫 PR 전 체크리스트** (lint, test, /pr-review 실행)신규 입사자가 /onboarding을 실행하면 AI가 실제 코드를 직접 분석한 뒤 팀 컨벤션에 맞춘 온보딩 요약을 출력합니다. 문서가 오래되어 있어도 코드를 보고 설명해주니 훨씬 정확하게 동작합니다.
예시 2: 서브에이전트로 풀스택 기능 병렬 개발
새로운 기능을 추가할 때 프론트엔드와 백엔드를 순서대로 구현하는 대신, 서브에이전트를 활용해 동시에 진행할 수 있습니다.
여기서 git worktree가 필요합니다. 쉽게 설명하면 같은 레포를 두 개의 다른 폴더에 동시에 체크아웃하는 기능입니다. 일반 브랜치 전환은 한 폴더에서 한 번에 하나의 브랜치만 쓸 수 있지만, worktree를 쓰면 ../project-frontend는 프론트 브랜치, ../project-backend는 백엔드 브랜치를 각각 독립적으로 유지할 수 있습니다. 서브에이전트들이 서로의 파일을 건드리지 않고 병렬로 작업하기 위한 준비 단계입니다.
# Git worktree 준비
git worktree add ../project-frontend feature/user-profile-frontend
git worktree add ../project-backend feature/user-profile-backend이제 Claude Code 대화창에 다음 오케스트레이션 프롬프트를 직접 입력하면, 메인 에이전트가 두 서브에이전트를 동시에 실행합니다.
사용자 프로필 편집 기능을 구현합니다.
다음 두 서브에이전트를 병렬로 실행해주세요:
## 서브에이전트 1 (frontend)
- 작업 디렉토리: ../project-frontend
- 작업: ProfileEditForm 컴포넌트 구현
- React Hook Form + zod 스키마 검증
- 아바타 이미지 업로드 (드래그앤드롭)
- 낙관적 업데이트 처리
- CLAUDE.md 규칙 준수 필수
## 서브에이전트 2 (backend)
- 작업 디렉토리: ../project-backend
- 작업: PATCH /users/:id 엔드포인트 구현
- DTO 검증, 이미지 S3 업로드 처리
- 트랜잭션 처리
- CLAUDE.md 규칙 준수 필수
완료 후 두 구현이 API 인터페이스에서 일치하는지 검증해주세요.| 단계 | 역할 | 모델 | 선택 이유 |
|---|---|---|---|
| 오케스트레이션 | 작업 분리, 결과 통합, 인터페이스 검증 | Claude Opus | 복잡한 추론과 일관성 판단이 핵심 |
| 프론트엔드 구현 | 컴포넌트 코딩, UI 로직 | Claude Sonnet | 집중된 단위 작업에 속도·비용 최적 |
| 백엔드 구현 | API 엔드포인트, DB 처리 | Claude Sonnet | 동일 |
예시 3: 플러그인으로 팀 AI 표준 패키징
스킬 + 훅 + MCP 서버를 하나의 설치 가능한 단위로 묶어 팀 간에 배포할 수 있습니다. 여러 레포에서 같은 표준을 쓰는 경우 특히 유용합니다.
team-ai-standard/ # 팀 AI 표준 플러그인 레포
├── .claude/
│ ├── skills/
│ │ ├── pr-review/SKILL.md
│ │ ├── deploy/SKILL.md
│ │ └── security-audit/SKILL.md
│ └── hooks/
│ ├── pre-commit.sh # 커밋 전 lint 자동 실행
│ └── post-test.sh # 테스트 후 커버리지 리포트
├── CLAUDE.md # 팀 공통 규칙
└── README.md # 설치 방법# 방법 1: git submodule (버전 고정 — 특정 커밋을 명시적으로 참조)
git submodule add https://github.com/your-team/team-ai-standard .claude-team
# 방법 2: 심볼릭 링크 (항상 최신 — 표준 레포 변경이 즉시 반영됨)
ln -s .claude-team/.claude/skills .claude/skills/team두 방식의 트레이드오프를 정리하면, submodule은 어떤 버전의 표준을 쓰는지 Git 기록에 남아 안정성이 높지만 업데이트를 직접 명령해줘야 합니다. 심볼릭 링크는 표준 레포를 당기면 자동으로 최신이 적용되지만 표준이 바뀌어도 알아채기 어렵습니다. 팀 규모가 크고 거버넌스가 중요하다면 submodule을, 소규모 팀이라면 링크가 편한 선택입니다.
장단점 분석
장점
| 항목 | 내용 |
|---|---|
| 팀 일관성 | CLAUDE.md와 스킬을 Git에 커밋하면 모든 개발자의 AI가 동일한 기준으로 동작 |
| 지식 축적 | 개인 노하우가 팀 공유 스킬로 변환되어 집단 지성이 코드베이스에 내재화 |
| 토큰 효율 | 스킬은 호출 시에만 로드되므로 CLAUDE.md에 모든 내용을 넣는 것보다 비용 절감 |
| 병렬 작업 | 서브에이전트로 독립 도메인 작업을 동시에 진행해 개발 속도 향상 |
| 온보딩 단축 | 신규 개발자가 AI를 통해 팀 컨벤션을 코드 레벨에서 즉시 학습 가능 |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 지침 과부하 | 지침이 많아질수록 LLM 준수율이 균일하게 하락하는 경향이 있음 | CLAUDE.md는 300줄 이하 유지, 나머지는 스킬로 분리 |
| 비용 급증 | 다중 에이전트 루프는 API 크레딧을 빠르게 소모 | 팀별 월간 비용 한도 설정, 모델 티어 전략 적용 |
| PR 리뷰 부담 | AI 활용이 늘면 코드 생산량이 늘어 리뷰어 부담 증가 | 자동화된 1차 리뷰 스킬로 리뷰어 부담 분산 |
| 의존성 리스크 | AI 툴 의존도 심화 시 팀의 자체 디버깅 역량 약화 가능 | AI 생성 코드를 반드시 이해하고 머지하는 문화 형성 |
| 품질 편차 | 복잡한 요구사항에서 생성 코드 품질 불일치 발생 | 보안 패턴과 아키텍처 규칙을 CLAUDE.md에 명시적으로 기술 |
비용 얘기가 나온 김에 솔직히 덧붙이면, 서브에이전트를 처음 도입했을 때 API 비용이 예상의 두 배 넘게 나온 적이 있습니다. 구현 작업에도 Opus를 그대로 쓰고 있어서였는데, Sonnet으로 내리고 나서야 합리적인 수준이 됐습니다. 팀 내 비용 한도를 먼저 정해두는 게 좋습니다.
실무에서 가장 흔한 실수
-
CLAUDE.md에 모든 것을 넣으려는 욕심: 팀 컨벤션, 온보딩 가이드, 도메인 지식, 스타일 가이드를 하나의 파일에 전부 때려넣으면 AI의 지침 준수율이 오히려 떨어집니다. CLAUDE.md는 핵심 규칙만, 절차는 스킬로 분리하는 것이 좋습니다.
-
서브에이전트에게 명확한 경계 없이 작업 위임: "백엔드랑 프론트엔드 동시에 만들어줘"처럼 모호하게 위임하면 서브에이전트들이 서로 다른 인터페이스를 만들어 통합 시 충돌이 생깁니다. API 계약(인터페이스)을 먼저 정의하고 위임하는 방식을 권장합니다.
-
스킬 만들고 방치: 처음엔 열심히 만든 스킬이 프로젝트가 바뀌면서 구식이 되어버리는 경우가 많습니다. CLAUDE.md와 스킬도 코드처럼 PR 리뷰와 버전 관리가 필요합니다. 분기별로 스킬 내용이 현재 프로젝트에 맞는지 검토하는 루틴을 만들어두는 것을 권장합니다.
마치며
CLAUDE.md로 팀 표준을 주입하고, 커스텀 커맨드로 반복 절차를 자동화하고, 서브에이전트로 병렬 작업을 위임하는 세 레이어를 조합하면, AI가 매 세션마다 새로 설명을 받아야 하는 도구가 아니라 팀 컨벤션을 이미 알고 있는 동료처럼 동작하기 시작합니다.
이 글을 읽기 전과 후의 차이가 있다면, AI 행동의 일관성 문제는 AI의 한계가 아니라 컨텍스트 전달 구조의 문제라는 점입니다. 구조만 갖추면 다음 번에 합류하는 신입 개발자도, 팀에서 가장 경험이 적은 사람이 AI에게 물어봐도 팀 표준에 맞는 코드를 받게 됩니다.
지금 바로 시작해볼 수 있는 3단계:
-
오늘 당장 프로젝트 루트에
CLAUDE.md파일을 만들어보시면 좋습니다. 팀에서 "AI가 또 이상한 패턴을 썼어"라고 불평한 적 있는 내용부터## 금지 패턴섹션에 적어보시는 걸 권장합니다. 10줄로 시작해도 충분합니다. -
하루에 두 번 이상 반복해서 사용하는 프롬프트가 있다면,
.claude/skills/<이름>/SKILL.md로 추출해볼 수 있습니다. PR 리뷰 체크리스트나 배포 전 검증 절차가 좋은 후보입니다./로 시작하는 커맨드로 언제든 호출할 수 있게 됩니다. -
다음 번에 풀스택 기능을 개발할 때
git worktree를 활용한 서브에이전트 분리를 시도해볼 수 있습니다. 프론트엔드와 백엔드를 독립된 디렉토리에서 병렬로 진행하면 속도 차이를 직접 체감할 수 있습니다.
참고 자료
- Claude Code 커스터마이제이션 완전 가이드 (CLAUDE.md, 스킬, 서브에이전트) | alexop.dev
- Claude Code 풀스택 이해: MCP, 스킬, 서브에이전트, 훅 | alexop.dev
- 좋은 CLAUDE.md 작성법 | HumanLayer Blog
- 엔터프라이즈 팀을 위한 Claude Code 베스트 프랙티스 | Portkey
- Claude Code 서브에이전트와 에이전트 팀 실전 가이드 | agentsroom.dev
- Claude Code 스킬 완전 가이드: SKILL.md, MCP, 서브에이전트 & 팀 (2026) | duet.so
- 프로덕션 팀을 위한 Claude Code 설정 블루프린트 | DEV Community
- 조직 전체 AI 개발 규칙 공유 방법 | Paul Duvall
![Claude Code가 단순 코드 자동완성과 근본적으로 다른 이유 — 이슈에서 PR까지 자동화하는 AI 개발 에이전트의 20가지 핵심 개념 [2026]](https://storage.googleapis.com/blog-cf724.appspot.com/images/cover/1780729412364.svg)
