Artistrator

Posted on Mar 8

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

#claudecode #ai #nestjs #productivity

배경 / 문제 상황

AI 코딩 도구를 사용하다 보면 한 가지 불만이 생긴다. 매번 같은 규칙을 알려줘야 한다는 것. "Entity에는 반드시 comment를 넣어줘", "DTO에는 ApiProperty 빼먹지 마", "import 순서는 이렇게 해"... 프로젝트 컨벤션을 매번 프롬프트에 넣는 건 비효율적이다.

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

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

접근 방법

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

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

각 레이어의 역할이 명확히 구분되어 있다. Rules는 "어떻게 코드를 써야 하는지", Agents는 "누구에게 시킬 것인지", Skills는 "무엇을 할 것인지", Hooks는 "자동으로 체크할 것"을 담당한다.

구현

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      # 에러 전파 흐름
└── ...

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

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

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

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 생성	전체

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

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

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

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

/aidlc (AI-Driven Development Lifecycle):
User Story 티켓을 기반으로 Unit -> Bolt 단위 구현 계획을 수립한다. MCP 서버에서 User Story를 조회하고, 4시간 단위 작업(Bolt)으로 분해한다.

/implement:
AIDLC에서 만든 Bolt 문서를 읽고 Entity -> DTO -> Service -> Usecase -> Controller 순서로 구현한다. 작업 완료마다 Bolt 문서의 체크리스트를 업데이트한다.

/bdd-cycle:
User Story의 Acceptance Criteria를 Cucumber E2E 테스트로 자동 변환한다. 테스트 결과를 MCP로 다시 업데이트하는 양방향 동기화.

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

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" }]
      }
    ]
  }
}

block-dangerous.sh: DROP TABLE, rm -rf /, force push main 같은 위험한 명령을 사전 차단
auto-format.sh: 파일 수정 후 자동으로 Prettier 실행
pr-convention.sh: PR 생성 시 변경된 scope와 stats를 자동으로 PR body에 추가

특히 block-dangerous.sh는 MCP로 DB에 연결된 환경에서 필수다. AI가 실수로 위험한 쿼리를 실행하는 것을 원천 차단한다.

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}" }
    }
  }
}

DB MCP는 실제 스키마를 조회하면서 Entity를 설계하고, Data Platform MCP는 User Story를 조회/업데이트하며 AIDLC 사이클을 돌린다.

결과 / 배운 점

이 설정으로 얻은 것:

코드 일관성: Entity comment 누락, import 순서 위반 같은 실수가 거의 없어짐
워크플로우 자동화: 기획 티켓에서 테스트까지 /aidlc -> /implement -> /bdd-cycle 3단계로 완성
안전장치: Hooks로 위험한 명령 차단, Read-only 에이전트로 리뷰와 수정 분리

설계하면서 배운 점:

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

AI 활용 포인트

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

특히 MCP 서버 + Skills 조합이 강력했다. AI가 단순히 코드만 쓰는 게 아니라, 기획 티켓을 읽고 -> 계획을 세우고 -> 구현하고 -> 테스트까지 하는 전체 사이클을 돌린다. .claude 디렉토리 설계에 초기 투자만 하면, 이후 모든 기능 개발에서 그 투자가 복리로 돌아온다.

DEV Community