DEV Community

Archist
Archist

Posted on • Edited on

Claude Code를 팀의 시니어 개발자로 만들기: .claude 디렉토리 설계 전략

#claudecode #ai #nestjs #productivity

배경 / 문제 상황

AI 코딩 도구를 사용하다 보면 한 가지 불만이 생긴다. 매번 같은 규칙을 알려줘야 한다는 것.

"Entity에는 반드시 comment를 넣어줘", "DTO에는 ApiProperty 빼먹지 마", "import 순서는 이렇게 해"... 10명짜리 팀에서도 코드 리뷰 때마다 같은 코멘트를 반복하는데, AI한테까지 매번 프롬프트로 컨벤션을 주입해야 한다니.

더 큰 문제는 컨텍스트 유실이다. 대화가 길어지거나 새 세션을 열 때마다 AI는 프로젝트의 아키텍처, 네이밍 규칙, 배포 전략 같은 맥락을 잃어버린다. 이전 대화에서 "우리는 Blue/Green 배포를 하니까 Request DTO에 필수 필드를 갑자기 추가하면 안 돼"라고 설명해놓아도 다음 세션에서는 아무것도 기억하지 못한다.

Claude Code의 .claude 디렉토리를 체계적으로 설계하면, AI가 프로젝트의 규칙과 패턴을 항상 이해한 상태에서 코드를 작성한다. 마치 프로젝트에 오래 있었던 시니어 개발자처럼.

나는 NestJS 기반 MSA 모노레포에서 .claude 디렉토리를 설계하면서 얻은 경험을 공유한다.

접근 방법

.claude 디렉토리는 크게 5개 레이어로 나눈다:

.claude/
├── settings.json        # 전역 설정 (hooks, MCP, permissions)
├── rules/               # 코드 작성 규칙 (항상 로드)
├── agents/              # 역할별 전문 에이전트 (12개)
├── skills/              # 슬래시 명령어 워크플로우 (11개)
├── hooks/               # 자동화 훅 (3개)
└── docs/                # 참조 문서
Enter fullscreen mode Exit fullscreen mode

각 레이어의 역할이 명확히 구분되어 있다:

레이어 역할 비유
Rules 어떻게 코드를 써야 하는지 팀 코드 컨벤션 문서
Agents 누구에게 시킬 것인지 역할별 전문가 배정
Skills 무엇을 할 것인지 반복 업무 SOP
Hooks 자동으로 체크할 것 CI/CD 파이프라인
Docs 참고할 것 위키/노션 문서

구현

1. Rules: 코드 컨벤션을 강제하는 법

.claude/rules/ 에 도메인별 규칙 파일을 분리했다. 총 14개의 규칙 파일이 있다:

rules/
├── entity.md              # Entity 작성 규칙
├── dto.md                 # DTO 데코레이터 규칙
├── usecase.md             # Usecase 20줄 제한
├── gateway.md             # Gateway에 비즈니스 로직 금지
├── bullmq.md              # Consumer + Handler 분리 패턴
├── backward-compatible.md # Blue/Green 배포 호환성
├── error-handling.md      # 에러 전파 흐름
├── tcp-communication.md   # 마이크로서비스 통신 규칙
├── sse.md                 # SSE 스트리밍 규칙
├── e2e-test.md            # E2E 테스트 병렬 실행 규칙
├── distributed-cron.md    # 분산 크론 잡 규칙
├── module.md              # NestJS 모듈 구성 규칙
├── import-order.md        # Import 순서 규칙
└── microservice.md        # 마이크로서비스 레이어 규칙
Enter fullscreen mode Exit fullscreen mode

핵심은 구체적인 코드 예시를 함께 넣는 것이다. "이렇게 하지 마" + "이렇게 해"의 Before/After 패턴이 효과적이다:

// 잘못된 예 - 기존 호출자가 mode를 안 보내면 실패
@IsString()
mode: string;

// 올바른 예 - 기존 호출자가 안 보내도 동작
@IsOptional()
@IsString()
mode?: string = 'legacy';
Enter fullscreen mode Exit fullscreen mode

CTO 관점에서 중요한 포인트: Rules 파일 하나가 보통 30~80줄인데, 이 분량이 적절하다. 너무 길면 AI가 핵심을 놓치고, 너무 짧으면 맥락이 부족하다. 하나의 Rule 파일은 하나의 관심사만 다루도록 했다.

2. Agents: 역할별 전문가 팀 구성

12개의 전문 에이전트를 구성했다. 각 에이전트는 모델, 사용 가능 도구, 출력 형식이 다르다:

에이전트 모델 역할 도구 제한
planner opus 구현 계획 수립 Read-only
code-reviewer sonnet 코드 리뷰 Read-only
debugger sonnet 에러 원인 추적 전체
monorepo-builder sonnet 빌드 문제 해결 전체
api-designer haiku API 엔드포인트 설계 전체
dto-entity-designer haiku Entity/DTO 생성 전체
refactorer sonnet 코드 리팩토링 전체
test-designer sonnet 테스트 설계 Read-only
business-logic sonnet 비즈니스 로직 구현 전체
feature-researcher sonnet 기존 기능 분석 Read-only
migration-designer haiku DB 마이그레이션 설계 전체
docker-troubleshooter sonnet Docker 문제 해결 전체

Read-only 에이전트를 분리한 게 핵심이다. code-reviewer와 planner는 disallowedTools: Edit, Write로 설정해서 코드를 분석만 하고 수정하지 않는다. 리뷰하면서 코드를 바꿔버리는 실수를 방지한다.

---
name: code-reviewer
tools: Read, Grep, Glob, Bash
disallowedTools: Edit, Write  # 읽기 전용!
model: sonnet
---
Enter fullscreen mode Exit fullscreen mode

모델 선택 전략도 중요하다. 계획 수립처럼 고수준 판단이 필요한 작업은 opus, 코드 리뷰나 디버깅처럼 분석 위주 작업은 sonnet, Entity/DTO 생성처럼 패턴화된 작업은 haiku로 배정했다. 비용 대비 품질의 균형이다.

3. Skills: 반복 워크플로우를 명령어로

Skills는 /명령어 형태로 호출하는 워크플로우다. 11개를 만들었는데, 가장 임팩트가 큰 3개:

/aidlc (AI-Driven Development Lifecycle):
User Story 티켓을 기반으로 Unit -> Bolt 단위 구현 계획을 수립한다. MCP 서버에서 User Story를 조회하고, 4시간 단위 작업(Bolt)으로 분해한다. 각 Bolt는 Acceptance Criteria 기반 검증 체크리스트를 포함한다.

/implement:
AIDLC에서 만든 Bolt 문서를 읽고 Entity -> DTO -> Service -> Usecase -> Controller 순서로 구현한다. 작업 완료마다 Bolt 문서의 체크리스트를 업데이트하고, 구현 전에 Mermaid 다이어그램으로 데이터 흐름을 시각화한다.

/bdd-cycle:
User Story의 Acceptance Criteria를 Cucumber E2E 테스트로 자동 변환한다. 테스트 결과를 MCP로 다시 업데이트하는 양방향 동기화. 기존 Feature 파일이 있으면 MCP 코드 태그를 자동 매칭한다.

이 세 가지가 연결되면 기획 -> 계획 -> 구현 -> 테스트 사이클이 완성된다:

/aidlc US-42 → spec.md + bolt-01.md 생성
/implement US-42 bolt-01 → 코드 구현 + 빌드 검증
/bdd-cycle 42 → E2E 테스트 자동 생성 + 실행 + MCP 업데이트
Enter fullscreen mode Exit fullscreen mode

4. Hooks: 실수를 자동으로 차단

3개의 hook을 설정했다:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "command": "bash .claude/hooks/block-dangerous.sh" }]
    }],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "command": "bash .claude/hooks/auto-format.sh" }]
      },
      {
        "matcher": "Bash",
        "hooks": [{ "command": "bash .claude/hooks/pr-convention.sh" }]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode
  • block-dangerous.sh (PreToolUse): DROP TABLE, rm -rf /, force push main 같은 위험한 명령을 실행 전에 차단
  • auto-format.sh (PostToolUse): 파일 수정 후 자동으로 Prettier 실행, .ts/.tsx/.js/.json 파일만 대상
  • pr-convention.sh (PostToolUse): PR 생성 시 변경된 scope와 stats를 자동으로 PR body에 추가

특히 block-dangerous.sh는 MCP로 DB에 연결된 환경에서 필수다. AI가 실수로 위험한 쿼리를 실행하는 것을 원천 차단한다. 실제로 이 블로그 글을 작성할 때도 본문에 포함된 키워드 때문에 hook이 발동해서 차단당했다. Hook이 잘 작동한다는 증거다.

5. MCP 서버 연동

MCP 서버 2개를 연결해서 AI가 프로덕션 DB를 읽고, User Story를 관리할 수 있게 했다:

{
  "mcpServers": {
    "my-db": {
      "type": "sse",
      "url": "https://my-service.example.com/sse",
      "headers": { "Authorization": "${MCP_TOKEN}" }
    },
    "my-data-platform": {
      "type": "sse",
      "url": "https://my-platform.example.com/sse",
      "headers": { "Authorization": "${MCP_TOKEN}" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

DB MCP는 실제 스키마를 조회하면서 Entity를 설계하고, Data Platform MCP는 User Story를 조회/업데이트하며 AIDLC 사이클을 돌린다. AI가 실제 데이터를 보면서 코드를 쓰기 때문에 "테이블에 이 컬럼 있어?" 같은 질문이 사라진다.

결과 / 배운 점

이 설정으로 얻은 것:

  • 코드 일관성: Entity comment 누락, import 순서 위반 같은 실수가 거의 없어짐
  • 워크플로우 자동화: 기획 티켓에서 테스트까지 /aidlc -> /implement -> /bdd-cycle 3단계로 완성
  • 안전장치: Hooks로 위험한 명령 차단, Read-only 에이전트로 리뷰와 수정 분리
  • 온보딩 시간 단축: 새 팀원이 .claude 디렉토리를 보면 프로젝트 컨벤션을 한눈에 파악 가능

설계하면서 배운 점:

  1. Rules는 구체적일수록 좋다 — "좋은 코드를 써" 보다 "Entity에 comment 필수, Before/After 예시 포함"이 100배 효과적
  2. 에이전트는 역할로 나눠야 한다 — 만능 에이전트보다 planner(Read-only) + implementer(Edit 가능) 분리가 안전
  3. Skills는 조합이 핵심 — 개별 스킬보다 /aidlc -> /implement -> /bdd-cycle 체인이 진짜 가치

아쉬웠던 점

솔직히 몇 가지 아쉬운 부분이 있다.

1. Rules 파일이 너무 많아졌다. 14개 규칙 파일이 매 대화마다 컨텍스트에 로드되면서 토큰을 상당량 차지한다. AI의 응답 품질과 속도에 영향을 줄 수 있다. 핵심 규칙과 참조용 규칙을 분리하는 전략이 필요했다.

2. Agent 간 컨텍스트 공유가 안 된다. planner가 수립한 계획을 code-reviewer가 참조하려면 파일 시스템을 경유해야 한다. 에이전트 간 직접적인 컨텍스트 전달 메커니즘이 없어서, .aidlc/ 디렉토리에 중간 산출물을 남기는 우회 방식을 쓰고 있다.

3. Skill 프롬프트 유지보수 비용이 크다. /implement 스킬 하나가 400줄짜리 마크다운이다. 프로젝트 구조가 바뀌면 스킬 프롬프트도 같이 수정해야 하는데, 이 동기화가 빠지기 쉽다. 스킬이 코드베이스의 실제 상태와 어긋나면 AI가 존재하지 않는 패턴을 따르려고 한다.

4. Hook의 false positive. block-dangerous.sh가 본문 내용의 키워드를 감지해서 정상적인 명령도 차단하는 경우가 있었다. 실제로 이 블로그 글을 DEV.to에 올릴 때도 본문에 포함된 DB 관련 키워드 때문에 curl 명령이 차단당했다. 패턴 매칭의 정밀도를 높여야 한다.

향후 보완할 점

1. Rules의 계층화: 현재는 모든 규칙이 동일한 우선순위로 로드된다. rules/core/(항상 로드)와 rules/reference/(필요 시 참조)로 나눠서 토큰 효율을 높일 계획이다.

2. Skill 자동 검증: 스킬 프롬프트에서 참조하는 파일 경로가 실제로 존재하는지 CI에서 검증하는 스크립트를 추가하려고 한다. grep -r 'apps/' .claude/skills/ | xargs -I{} test -f {} 같은 간단한 체크만으로도 상당한 drift를 잡을 수 있다.

3. Agent 메모리 시스템 활용: Claude Code의 auto memory 기능을 좀 더 적극적으로 활용해서, 자주 반복되는 디버깅 패턴이나 의사결정 히스토리를 세션 간에 공유할 수 있게 할 예정이다.

4. 팀 단위 확장: 현재는 1인 CTO가 설계하고 사용하는 구조다. 팀원들이 각자의 .claude/settings.local.json으로 개인 설정을 오버라이드하면서도 핵심 Rules와 Skills는 공유하는 구조로 발전시켜야 한다.

5. 성과 측정: .claude 설정의 ROI를 정량적으로 측정하고 싶다. AI가 생성한 코드의 코드 리뷰 리젝률, 컨벤션 위반 건수, 기능 개발 리드타임 같은 메트릭을 수집해서 설정 최적화에 피드백 루프를 만들 계획이다.

AI 활용 포인트

Claude Code 자체의 .claude 시스템을 최대한 활용한 사례다. 별도 도구 없이 Claude Code가 제공하는 rules, agents, skills, hooks만으로 개발 워크플로우 전체를 커버했다.

특히 MCP 서버 + Skills 조합이 강력했다. AI가 단순히 코드만 쓰는 게 아니라, 기획 티켓을 읽고 -> 계획을 세우고 -> 구현하고 -> 테스트까지 하는 전체 사이클을 돌린다.

.claude 디렉토리 설계에 초기 투자만 하면, 이후 모든 기능 개발에서 그 투자가 복리로 돌아온다. 다만 그 "초기 투자"가 생각보다 크고, 유지보수도 꾸준히 필요하다는 점은 미리 감안해야 한다.

Top comments (0)