AI CLAUDE.md로 팀 규칙을 AI에게 가르치는 법

웅파 2026-10-20 10:35:06 6

CLAUDE.md로 팀 규칙을 AI에게 가르치는 법

2026년 10월 20일 · @martin

프로젝트 규칙과 코딩 컨벤션을 문서로 고정해, 세션이 바뀌어도 같은 품질을 유지하는 방법입니다.

매번 같은 당부를 반복하던 시절

클로드코드로 개발을 다시 시작하고 처음 몇 주는 같은 말을 계속 반복했습니다. "컨트롤러에 로직 넣지 마세요." "에러 응답은 이 형식으로." "한국어로 답해 주세요."

세션이 바뀌면 AI는 어제의 당부를 기억하지 못합니다. 긴 작업 도중에 영어로 돌아가거나, 어제는 서비스 계층에 두던 로직을 오늘은 컨트롤러에 쓰기도 했습니다. 문제는 AI의 실력이 아니라, 규칙이 채팅창에만 있었다는 데 있었습니다.

그래서 규칙을 대화에서 꺼내 저장소에 적기 시작했습니다. 그 중심이 CLAUDE.md입니다. 지금은 AIvance의 모든 제품이 이 파일로 같은 규칙을 공유합니다.

CLAUDE.md는 신입 개발자용 온보딩 문서다

CLAUDE.md는 클로드코드가 세션을 시작할 때마다 읽는 마크다운 파일입니다. 여기 적힌 내용은 매번 대화의 맨 앞에 깔립니다. 사람으로 치면 첫 출근날 받는 온보딩 문서입니다.

효과가 있는 이유는 세 가지입니다.

세션이 바뀌어도 남는다. 채팅으로 한 당부는 세션이 끝나면 사라지지만, 파일은 다음 세션에도 그대로 읽힙니다.
저장소와 함께 버전 관리된다. 규칙이 바뀌면 커밋으로 남고, 코드 리뷰처럼 규칙도 리뷰할 수 있습니다.
사람과 AI가 같은 문서를 본다. 협업자가 들어와도, 다른 AI 도구를 써도 같은 기준이 적용됩니다. 그래서 다른 도구용으로 AGENTS.md도 같은 내용으로 맞춰 둡니다.

핵심은 "무엇을"만이 아니라 "왜"까지 적는 것입니다. 이유를 아는 AI는 규칙에 없는 상황에서도 비슷한 판단을 내립니다.

계층을 나눈다: 나의 규칙과 프로젝트의 규칙

처음에는 프로젝트마다 CLAUDE.md에 모든 걸 적었습니다. 제품이 늘어나자 같은 문장을 여러 파일에서 고치는 일이 생겼습니다. 그래서 규칙을 "어디에 적용되는가"로 나눴습니다.

파일	위치	적용 범위	저장소 커밋	담는 내용
사용자 CLAUDE.md	`~/.claude/CLAUDE.md`	내 모든 프로젝트	안 함	응답 언어, 커밋 메시지 형식, 작업 태도
프로젝트 CLAUDE.md	저장소 루트	해당 프로젝트	함	스택, 계층 규칙, 금지 영역, 응답 규약
`.claude/settings.json`	저장소	해당 프로젝트	함	훅, 허용 명령 같은 팀 공통 설정
`.claude/settings.local.json`	저장소	나만	안 함	개인 환경, 로컬 경로

같은 항목이 양쪽에 있으면 프로젝트 쪽이 이깁니다. 기준은 간단합니다. 협업자가 저장소를 받았을 때도 지켜야 하는 규칙이면 프로젝트에, 내 습관이면 사용자 수준에 둡니다.

한국어 응답 문제도 여기서 해결했습니다. 프로젝트와 무관하게 늘 원하는 것이므로 사용자 수준에 "모든 응답과 코드 주석은 한국어로"를 적었습니다. 긴 작업 중 가끔 영어로 넘어가는 현상이 완전히 사라지지는 않지만, 매번 프롬프트에 덧붙이던 당부는 없어졌습니다.

프로젝트 CLAUDE.md에 반드시 넣는 다섯 가지

여러 제품에 써 보고 남은 항목은 다섯 가지입니다. 이것만 있어도 세션마다 하던 설명의 대부분이 사라집니다.

스택과 실행 명령. CodeIgniter 4, PHP 8.2 이상, MySQL, Ubuntu 같은 환경과 함께 테스트·정적분석·마이그레이션 명령을 한 줄씩 적습니다. 저는 composer ci 하나로 PHPUnit과 PHPStan을 묶어 두고 "완료 전 반드시 통과"라고 적습니다.
계층 규칙. 컨트롤러는 얇게(검증 → 서비스 호출 → 응답), 비즈니스 로직과 트랜잭션은 서비스, DB 접근은 리포지토리. 요청·응답 구조는 readonly DTO, 상태값은 Backed Enum으로 쓴다는 것까지 적습니다.
금지 영역. 인증, 결제, 토큰 서명처럼 임의로 고치면 사고가 나는 모듈을 명시적으로 잠급니다. "이 디렉터리는 수정 전에 반드시 먼저 물어볼 것"처럼 행동으로 적습니다.
응답 규약. API 성공·실패 응답 형식과 에러 코드 명명 규칙입니다. 서비스가 여럿인 MSA 구조에서는 이게 어긋나면 클라이언트 코드가 제품마다 달라집니다.
작업 흐름. 브랜치는 feature → dev → main, 테스트 먼저 작성(TDD), 커밋 단위 같은 진행 방식입니다.

규칙은 좋은 예와 나쁜 예를 코드로 함께 보여줄 때 가장 잘 지켜졌습니다. 예를 들면 이렇습니다.

### Controller 규칙
- 컨트롤러는 얇게: 유효성 검사 → 서비스 호출 → 응답 반환만
- 비즈니스 로직이 보이면 무조건 Service로 추출
- 응답은 반드시 BaseApiController를 거쳐 형식을 통일

### Repository 규칙
- Model은 Repository를 통해서만 접근
- raw query는 반드시 바인딩 파라미터 사용

실제 사례: AILign의 CLAUDE.md

AILign은 CNC·목공 공방용 견적 플랫폼으로, AICreo 위에 플러그인 구조로 얹은 제품입니다. 코드 한 줄 쓰기 전에 docs/SPEC.md(명세 v0.3)와 CLAUDE.md(개발지시서)를 먼저 만들었습니다. 구성은 세 덩어리입니다.

1. 상위 컨벤션 승계. AICreo에서 쓰던 규칙을 그대로 물려받는다고 선언했습니다. TDD, composer ci 게이트, feature → dev → main 워크플로우, KWCAG 접근성 계약, 보안 규칙입니다. 덕분에 공통 규칙을 다시 쓰지 않았습니다.

2. 이 제품만의 아키텍처 규칙 6가지.

규칙	내용	적은 이유
플러그인 독립	플러그인은 독립 모듈로 작성	판매 단위가 플러그인이라 서로 엮이면 안 됨
이벤트 통신	모듈 간 통신은 Events로만	직접 호출이 생기면 독립성이 깨짐
사용자 스코프	모든 질의에 `user_id` 스코프 강제	누락은 곧 다른 공방 데이터 노출, 즉 보안 결함
단일 관문	기능 사용 권한은 Entitlement 한 곳에서만 판단	과금 우회 경로를 막기 위해
과금 무결성	결제·크레딧 처리는 트랜잭션 + 멱등키	중복 차감과 누락을 막기 위해
만료 처리	구독 만료 시 삭제가 아니라 읽기전용	고객 데이터를 볼모로 잡지 않기 위해

특히 "user_id 누락 = 보안 결함"처럼 위반의 무게를 함께 적어 두니, AI가 새 쿼리를 짤 때마다 스코프를 먼저 확인했습니다.

3. 단계별 작업 목록. 1~2단계는 체크리스트 수준으로 잘게 쪼개 두고, 완료할 때마다 체크를 갱신하게 했습니다. 3단계부터는 SPEC.md를 참조하도록 했습니다. 빈 디렉터리에서 시작해도 막히지 않게 초기화 절차(AICreo 복사 → migrate)도 넣었습니다.

그 결과 클로드코드에는 "1단계 시작해줘" 한 마디면 충분했습니다. 무엇을, 어떤 규칙으로, 어디까지 할지는 이미 문서에 있었으니까요.

CLAUDE.md는 부탁이고, 훅은 강제다

CLAUDE.md에 "테스트를 꼭 돌릴 것"이라고 적어도, 긴 작업 중에는 빠뜨리는 날이 있습니다. 문서는 어디까지나 부탁이기 때문입니다. 반드시 지켜져야 하는 규칙은 문서에서 꺼내 기계가 지키게 했습니다.

훅으로 강제한다. .claude/settings.json에 PreToolUse·PostToolUse 훅을 걸어, 파일이 바뀔 때마다 테스트와 정적분석이 자동으로 돕니다. AI가 잊어도 훅은 잊지 않습니다.
스킬로 분리한다. 길고 자주 쓰지 않는 규칙은 CLAUDE.md에 다 넣지 않고 .claude/skills/로 뺐습니다. 첫 스킬이 MSA 공통 에러 응답 규약인 api-error-contract입니다. RFC 9457 Problem Details를 기반으로 CI4용 ApiException 계층을 두고, 에러 코드는 .. 형식으로 통일했습니다. 에러 처리를 할 때만 불러오니 평소 컨텍스트가 가벼워집니다.
CI가 마지막 관문이다. 로컬 훅을 통과한 코드는 GitHub Actions와 셀프호스티드 러너에서 한 번 더 검증받고 나서야 배포됩니다.

역할을 정리하면 이렇습니다. CLAUDE.md는 판단 기준을 알려주고, 스킬은 필요할 때만 꺼내 쓰는 상세 매뉴얼이며, 훅과 CI는 어기면 통과하지 못하는 문입니다.

쓰면서 배운 원칙 6가지

코드보다 문서를 먼저 쓴다. 새 프로젝트는 SPEC.md와 CLAUDE.md부터 만듭니다. AI 화상면접 솔루션 명세서에도 "Claude Code 작업 지침" 섹션을 따로 두었습니다.
이유를 함께 적는다. "하지 마라"보다 "하면 이런 사고가 난다"가 더 잘 지켜집니다.
행동으로 적는다. "보안에 신경 쓸 것" 대신 "모든 질의에 user_id 조건을 넣을 것"처럼 확인 가능한 문장으로 씁니다.
짧게 유지한다. 매 세션 읽히는 파일이라 길어지면 핵심이 묻힙니다. 상세한 규약은 스킬이나 docs/로 빼고, CLAUDE.md에는 위치만 적습니다.
같은 지적을 두 번 하면 문서에 올린다. 리뷰에서 같은 실수를 두 번 잡았다면 그건 AI의 문제가 아니라 문서에 빠진 규칙입니다.
기반 프로젝트에서 물려받는다. ci4-board와 AICreo의 규칙을 상위 컨벤션으로 두고, 새 제품은 고유 규칙만 덧붙입니다. 제품이 늘수록 이 구조의 효과가 커졌습니다.

마무리: 혼자여도 팀 규칙은 필요하다

1인 개발자에게 팀 규칙이 왜 필요하냐고 물을 수 있습니다. 클로드코드와 일하면 매 세션 새로운 팀원이 출근하는 것과 같습니다. 그 팀원에게 매일 아침 같은 설명을 반복할지, 온보딩 문서 한 장을 건넬지의 차이입니다.

CLAUDE.md를 정리한 뒤로 AI가 만든 코드를 리뷰하는 시간이 눈에 띄게 줄었습니다. 여러 제품이 같은 계층 구조와 같은 에러 형식을 쓰게 되면서, 한 제품에서 익힌 패턴을 다른 제품에 그대로 가져갈 수 있게 됐습니다.

시작은 거창할 필요가 없습니다. 오늘 AI에게 두 번 이상 한 말이 있다면, 그 문장부터 CLAUDE.md에 옮겨 적어 보세요.

다음글 GitHub Actions로 AI가 만든 코드를 검증하는 파이프라인 이전글 1인 개발자가 클로드코드로 SaaS 11개 만든 기록