Claude Code에 팀의 규칙을 새기고, 반복은 절차로 만듭니다

3.1 CLAUDE.md 계층: 개인·프로젝트·디렉토리 세 층위

CLAUDE.md는 Claude Code가 매 작업 전에 읽는 규칙 파일입니다. 세 층위로 나뉩니다. 개인 층위(~/.claude/CLAUDE.md)는 내 모든 프로젝트에 적용되고 버전 관리에 올리지 않아 팀과 공유되지 않습니다. 프로젝트 층위(저장소 최상단)는 git에 함께 커밋되어 팀 전체가 같은 규약을 받습니다. 디렉토리 층위는 특정 폴더 안에서만 적용됩니다. 규칙이 길어지면 @import 문법으로 다른 파일을 끌어오거나, 주제별 규칙을 .claude/rules/ 폴더로 나눠 관리합니다.

3.2 슬래시 명령과 스킬: 반복 작업을 정의합니다

자주 반복하는 지시는 슬래시 명령(slash command, 채팅창에서 /이름 으로 부르는 사용자 정의 명령)으로 정의합니다. .claude/commands/ 에 두면 팀이 공유하고, ~/.claude/commands/ 에 두면 나만 씁니다. 더 큰 단위의 작업 절차는 스킬(skill)로 묶습니다. .claude/skills/ 아래 SKILL.md 파일의 머리말(frontmatter)에 context: fork(별도 맥락에서 실행), allowed-tools(허용 도구 제한), argument-hint(인자 안내) 같은 설정을 적어, 언제 어떻게 실행될지 규정합니다.

3.3 경로 규칙: 파일 위치에 따라 규약을 자동으로 불러옵니다

코드베이스가 커지면 프론트엔드와 백엔드가 요구하는 규약이 서로 다릅니다. 이때 규칙 파일 머리말에 paths와 glob 패턴(예: src/api/**)을 적으면, 해당 경로의 파일을 다룰 때만 그 규약이 자동으로 켜집니다. 같은 성격의 파일이 여러 폴더에 흩어져 있을 때는, 폴더마다 CLAUDE.md를 두는 방식보다 glob 규칙 하나로 묶는 편이 관리가 정확합니다.

3.4 계획 모드와 직접 실행: 언제 멈춰 설계하는가

계획 모드(plan mode)는 코드를 바로 고치기 전에 Claude Code가 먼저 설계안을 세워 승인을 받는 방식입니다. 파일 여러 개를 동시에 바꾸거나, 구조를 결정해야 하거나, 되돌리기 어려운 아키텍처 선택이 걸린 작업이라면 계획 모드로 멈춰 설계를 확인한 뒤 실행합니다. 반대로 범위가 좁고 명확한 수정은 직접 실행이 빠릅니다. 코드베이스를 폭넓게 훑어 파악해야 할 때는 탐색(Explore) 서브에이전트에 조사를 맡깁니다.

3.5 반복 개선: 예시와 테스트로 정확도를 끌어올립니다

에이전트의 품질은 한 번에 완성되지 않고 반복으로 다듬습니다. 원하는 동작을 말로 설명하기보다 구체적인 입력과 기대 출력의 예시를 주면 정확도가 빠르게 오릅니다. 테스트를 먼저 정해 두고 통과할 때까지 고치는 방식(test-driven), Claude가 설계자에게 거꾸로 질문하며 요구사항을 좁혀 가는 인터뷰 패턴도 유효합니다. 서로 얽힌 문제는 순차로, 독립된 문제는 병렬로 나눠 처리하면 반복 주기가 짧아집니다.

3.6 CI/CD 연동: 사람 없이 돌아가는 검토 파이프라인

Claude Code는 사람이 대화창에 앉아 있어야만 작동하는 도구가 아닙니다. -p(또는 --print) 옵션을 주면 사람의 입력 없이 한 번에 실행되어 결과만 돌려주므로, CI/CD 파이프라인에 넣을 수 있습니다. --output-format json 과 --json-schema를 함께 쓰면 결과를 정해진 형식으로 받아 다음 단계가 바로 읽습니다. 이때 CLAUDE.md는 파이프라인이 참고하는 팀 규약 맥락이 됩니다. 코드를 작성한 인스턴스가 스스로를 검토하기보다, 별도의 독립 인스턴스에 검토를 맡겨야 치우침 없는 지적이 나옵니다.

! 흔한 함정

• 개인 층위(~/.claude/CLAUDE.md) 규칙이 팀에도 적용될 것이라 착각하는 경우 — 이 파일은 버전 관리에 올라가지 않아 나에게만 적용됩니다. 팀 공유가 필요하면 프로젝트 층위에 둡니다.
• 모든 규약을 하나의 거대한 CLAUDE.md에 몰아넣는 것 — 특정 파일 종류에만 필요한 규칙까지 매번 읽혀 맥락이 흐려집니다. 경로 glob 규칙이나 .claude/rules/ 로 나눕니다.
• 구조를 바꾸는 다중 파일 작업을 계획 모드 없이 바로 실행해, 절반쯤 진행된 뒤에야 방향이 어긋났음을 발견하는 것.
• CI에서 코드를 만든 인스턴스에 자기 검토를 맡기는 것 — 같은 맥락에 갇혀 놓친 문제를 그대로 지나칩니다. 독립된 검토 인스턴스에 맡깁니다.