Claude Code를 혼자 쓸 때와 팀 단위로 세팅할 때는 근본적으로 다른 문제를 풀어야 한다. 개인 사용자에게는 '어떻게 더 잘 쓰느냐'가 질문이지만, 테크 리드에게는 '어떻게 팀 전체가 일관된 수준으로 쓰게 만드느냐'가 진짜 질문이다. 최근 공개된 Claude Code 실전 활용 가이드(arps18.github.io)와 MCP 아키텍처 분석, 그리고 Anthropic의 Claude Opus 4.8 출시를 함께 읽으면, 이 질문에 답하는 실전 레이어 전체가 보인다.
CLAUDE.md: 규칙 문서가 아니라 누적 인프라다
많은 팀이 CLAUDE.md를 온보딩 문서처럼 쓴다. 프로젝트 설명, 코딩 스타일, API 문서, 긴 튜토리얼까지 우겨넣는다. 이건 틀린 방향이다. CLAUDE.md는 매 세션 시작 시 로드되는 지침이다. 길수록 컨텍스트를 잡아먹고, 정작 중요한 규칙의 가중치가 희석된다.
Claude Code 팀이 실제로 운영하는 CLAUDE.md는 단순하다. bun을 쓰고 npm은 쓰지 않는다. 변경 후 타입체크, 테스트, 린트, PR 전 전체 검증—빌드 명령과 검증 순서에만 집중한다. 스타일 취향이나 코드베이스 설명은 없다.
실용적인 운영 원칙은 하나다. 각 줄마다 "이 줄을 제거하면 Claude가 실수할까?"를 묻고, 아니라면 삭제한다. 그리고 Claude가 실수했을 때 "Update CLAUDE.md so you do not repeat this."를 지시한다. Claude가 자기 실수를 정밀한 규칙으로 요약하게 만드는 것이다. 몇 주 반복하면 프로젝트의 함정이 규칙 목록으로 쌓인다. 이게 Compounding Engineering이다.
.claude 디렉터리: 팀 지식의 물리적 구조
.claude/ 디렉터리는 CLAUDE.md 하나를 두는 폴더가 아니다. 계층형 설정 시스템이다. 프로젝트 범위(.claude/)는 git에 커밋해 팀과 공유하고, 전역 범위(~/.claude/)는 개인 선호를 담는다.
핵심 구조를 정리하면 이렇다. rules/*.md는 경로별 지침—마이그레이션 폴더에만 필요한 규칙은 전체 세션을 부풀리는 CLAUDE.md보다 .claude/rules/migrations.md에 glob과 함께 두는 게 맞다. skills/<name>/SKILL.md는 슬래시 명령으로 호출되는 재사용 프롬프트다. agents/*.md는 서브에이전트 정의, .mcp.json은 팀이 공유하는 MCP 서버 설정이다.
모노레포에서는 root/CLAUDE.md와 root/services/billing/CLAUDE.md가 함께 로드된다. 폴더별 관례가 다른 코드베이스에서 이 계단식 로딩 구조가 힘을 발휘한다.
Skills와 Subagents: 재사용과 격리의 설계
Skills는 Claude Code를 '무엇이든 할 수 있는 에이전트'에서 '이 프로젝트를 잘 아는 에이전트'로 바꾸는 단위다. .claude/skills/<name>/SKILL.md를 만들면 /name으로 호출된다. 세션 시작 시엔 frontmatter 설명만 로드되고, 실제 호출 시에만 전체 내용과 보조 파일이 주입된다—컨텍스트 효율성을 유지하면서 전문성을 쌓는 구조다.
https://arps18.github.io 가이드에서 소개한 Anthropic 공식 /code-review skill은 네 개의 병렬 에이전트가 diff를 감사하고 신뢰도 점수 기반 발견만 보고한다. /batch skill은 마이그레이션을 여러 병렬 에이전트에 분산하고 각자 worktree에서 처리한다. 하루에 한 번 이상 반복하는 작업이 있다면 skill로 만들어라. git에 커밋된 skills는 새 엔지니어가 clone하는 즉시 팀의 누적 실천 방식을 얻게 한다.
Subagents는 다른 문제를 푼다. 자체 컨텍스트 창과 도구 권한을 갖고 실행된 뒤 요약을 반환한다. 핵심 가치는 격리다—많은 파일을 읽어도 메인 세션 컨텍스트를 채우지 않는다. /pr-review 에이전트를 tools: Read, Grep, Glob, Bash의 읽기 중심 권한으로 구성하고, model: opus로 고위험 리뷰에 강한 모델을 쓰는 패턴이 실전에서 유효하다. 구현을 맡은 Session A와 새 컨텍스트에서 검토하는 code-reviewer subagent를 분리하면 구현 편향이 줄어든다.
MCP: 에이전트를 외부 세계와 연결하는 표준 인터페이스
MCP(Model Context Protocol)는 function calling의 다음 단계다. dev.to의 Hermes Agent 아키텍처 분석이 잘 짚었듯이, MCP는 단순한 API 엔드포인트가 아니라 에이전트의 인지 능력과 운영 능력을 분리하는 표준화된 워크샵 인터페이스다.
Claude Code에서 .mcp.json은 프로젝트 범위로 팀 전체가 공유한다. /plugin marketplace add owner/repo로 커뮤니티 marketplace를 추가하고, Plugins는 skills·hooks·subagents·MCP servers를 하나의 설치 가능한 단위로 묶는다. 이 구조가 팀 레벨 세팅을 가능하게 한다—한 명이 세팅하면 팀 전체가 같은 도구 환경을 갖는다.
MCP의 실질적 가치는 확장성이다. 에이전트 코드는 Python으로 작성하고, 고성능 DB 도구는 Go로, 브라우저 자동화는 Node.js로 운영할 수 있다. MCP 표준을 따르는 한 에이전트는 재훈련 없이 새 도구를 쓸 수 있다. 단, 동적 스키마 생성이 전제돼야 한다. 100개 도구를 한꺼번에 주입하면 모델 추론 능력이 저하된다. 사용 가능한 도구만 런타임에 스키마로 제공하고, 권한이 없는 도구는 스키마에서 제거하는 방식이 프로덕션 레벨 안정성을 만든다.
Opus 4.8: 품질 검증 레이어를 바꾸는 변수
Anthropicが 출시한 Claude Opus 4.8은 이 세팅 전체의 품질 보장 층위를 다시 계산하게 만든다. 코드 내 결함을 놓칠 확률이 이전 모델 대비 약 4배 낮아졌다. 불확실한 부분을 스스로 표시하고, 계획이 타당하지 않을 때 이의를 제기한다.
테크 리드 관점에서 주목할 건 두 가지다. 첫째, subagent의 model: opus 지정이 이제 더 강력한 의미를 갖는다. 고위험 PR 리뷰나 security-reviewer 에이전트에 Opus 4.8을 붙이면 이전보다 유의미하게 다른 결과가 나온다. 둘째, Dynamic Workflows—수백 개의 병렬 서브에이전트를 실행하는 기능이 연구 프리뷰로 추가됐다. /batch skill과 결합하면 대규모 코드베이스 마이그레이션 작업의 구조가 바뀐다. Fast Mode의 속도가 2.5배 빨라지고 비용이 3배 저렴해진 것도 팀 단위 활용에서 ROI 계산을 다시 하게 만드는 변수다.
팀 레벨 세팅의 실행 순서
이론은 충분하다. 내일 당장 시작할 수 있는 순서를 정리한다.
1단계: CLAUDE.md 최소화. 지금 팀의 CLAUDE.md에서 "이 줄이 없으면 Claude가 실수하나?"를 물어라. 살아남는 줄만 남겨라. 빌드 명령, 검증 순서, 프로젝트 함정(gotchas)만 있으면 충분하다.
2단계: .claude 디렉터리 구조화. rules, skills, agents 폴더를 만들고 git에 커밋한다. 새 팀원이 clone하면 바로 쓸 수 있어야 한다.
3단계: 반복 작업 skill화. PR 리뷰, 디버깅 루틴, 마이그레이션 패턴—팀에서 하루에 한 번 이상 반복되는 작업을 /code-review, /diagnose 같은 skill로 만든다.
4단계: .mcp.json 공유. 팀이 공통으로 쓸 MCP 서버를 .mcp.json에 정의하고 커밋한다. 개인 오버라이드는 settings.local.json으로 분리한다.
5단계: Opus 4.8을 품질 게이트에 배치. 일상 개발에는 빠른 모델을, PR 머지 전 최종 리뷰 subagent에만 Opus 4.8을 써라. 비용과 품질의 균형점이 여기 있다.
시사점: 설정 파일이 팀의 엔지니어링 문화가 된다
Claude Code의 생산성 차이는 프롬프트 실력에서 오지 않는다. .claude/ 디렉터리에 무엇이 쌓여 있느냐에서 온다. 팀의 실수 이력이 CLAUDE.md 규칙으로, 반복 작업이 skill로, 리뷰 기준이 subagent 정의로 코드화될 때—그 저장소는 단순한 코드베이스가 아니라 팀의 엔지니어링 판단이 누적된 시스템이 된다.
AI-First 팀 리빌딩의 실질적 진입점은 거창한 아키텍처 결정이 아니다. .claude/ 디렉터리를 git에 커밋하는 것, 그리고 팀이 같은 도구 환경을 공유하게 만드는 것이다. Claude Opus 4.8의 품질 향상과 Dynamic Workflows가 이 구조 위에서 작동할 때, 팀의 AI 활용 수준은 단순 합산이 아니라 복리로 올라간다.