Claude Code CLI 팀 자동화: Hooks·CLAUDE.md·MCP 구축

개발 팀에서 AI 코딩 에이전트를 도입할 때 흔히 겪는 문제는 **“개인마다 결과물 품질이 극단적으로 달라진다”**는 점이다. 한 개발자는 가이드라인에 딱 맞는 정갈한 코드를 얻는 반면, 다른 개발자는 프로젝트 컨벤션을 무시한 일회용 코드를 생성한다. 이는 AI 모델의 한계가 아니라 팀 차원의 컨텍스트 엔지니어링과 훅(Hooks) 자동화 시스템의 부재 때문이다.

Anthropic의 Claude Code CLI는 단순히 터미널에서 채팅하는 도구가 아니다. .claude/settings.json 기반의 Custom Hooks, 프로젝트 맥락을 기계적으로 주입하는 CLAUDE.md, 그리고 데이터베이스·Jira·GitHub을 연결하는 MCP(Model Context Protocol) 레이어를 갖춘 팀 단위 AI 실행 런타임이다.

이 글은 Claude Code CLI를 팀 표준 개발 환경으로 정착시키기 위한 3대 축—Custom Hooks 생태계, CLAUDE.md 컨텍스트 엔지니어링, 팀 공용 MCP 파이프라인 세팅법—을 실전 예제 코드와 함께 심층적으로 다룬다.

핵심 요약

• 컨텍스트 엔지니어링 > 프롬프트 엔지니어링: AI 환각의 90%는 프롬프트 부족이 아니라 맥락(Context) 부재에서 발생한다. 프로젝트 루트에 CLAUDE.md를 구성해 아키텍처 규칙을 자동 제공해야 한다.
• Custom Hooks의 역할: PreToolUse(파일 수정 전 보안/검증), PostToolUse(수정 후 자동 린팅/Prettier), SessionStart(환경 초기화) 훅으로 AI의 동작을 결정론적(Deterministic)으로 통제한다.
• 팀 공용 MCP 세팅: .claude/settings.json을 Git에 커밋하여 팀원 전체가 동일한 MCP 서버(PostgreSQL, GitHub, Figma)와 보안 훅을 공유한다.
• 보안 파이프라인: 훅을 통해 .env 파일 접근 차단, rm -rf 같은 위험 명령어 실행 거부, 비밀키 유출 검사를 게이트웨이 레벨에서 자동화한다.

1. 프롬프트 엔지니어링에서 ’컨텍스트 엔지니어링’으로의 패러다임 전환

2024년까지는 “프롬프트를 얼마나 길고 정교하게 작성하는가”가 화두였다. 하지만 2026년 대규모 언어 모델(LLM) 환경에서 팀의 핵심 생산성은 **‘컨텍스트 엔지니어링(Context Engineering)’**에서 나온다.

[구형 프롬프트 엔지니어링]
개발자 ──(매번 500자 프롬프트 작성)──► AI 에이전트 ──► 규칙 미준수 코드 생성

[2026 컨텍스트 엔지니어링]
개발자 ──(간결한 명령)──► [CLAUDE.md + Custom Hooks + MCP] ──► AI 에이전트 ──► 컨벤션 100% 준수 코드

AI가 프로젝트 아키텍처, 패키지 버전, 코드 스타일, 금지사항을 이미 알고 있다면 개발자는 “User 로그인 기능 추가해줘”라는 한 줄 명령만으로 프로덕션급 코드를 얻을 수 있다.

CLAUDE.md 구성 표준 규격

프로젝트 루트에 위치하는 CLAUDE.md는 Claude Code가 세션을 시작할 때 가장 먼저 읽는 최우선 맥락 파일이다. Claude Code 공식 문서의 권장 규격에 맞춘 예시는 다음과 같다.

# 프로젝트 아키텍처 & 개발 컨벤션

## 기술 스택
- Framework: Next.js 15 (App Router), React 19
- Styling: Tailwind CSS v4, shadcn/ui
- State: TanStack Query v5, Zustand
- Test: Vitest, Playwright

## 코드 스타일 규칙
- 모든 아티팩트는 TypeScript Strict Mode를 준수한다 (`any` 사용 금지).
- 컴포넌트는 `src/components/` 하위에 목적별로 분리하며, `export default` 대신 Named Export를 사용한다.
- 데이터 패칭은 반드시 Server Actions 또는 `useQuery` 커스텀 훅을 통해 수행한다.

## 금지 사항 (Strict Rules)
- `.env` 및 `.env.local` 파일 내용을 읽거나 수정하지 않는다.
- `node_modules` 하위 파일을 직접 수정하지 않는다.
- `git push --force` 명령을 실행하지 않는다.

## 자주 쓰는 명령어
- Build: `npm run build`
- Test: `npm run test`
- Lint: `npx eslint . --fix`

2. Custom Hooks: AI 에이전트의 결정론적 통제 수단

CLAUDE.md가 규칙을 “선언”하는 가이드라인이라면, Custom Hooks는 AI가 규칙을 위반하지 못하도록 강제로 실행되는 샌드박스 파이프라인이다.

훅 실행 라이프사이클 이벤트

.claude/settings.json 실전 설정 코드

팀 프로젝트에 적용할 수 있는 .claude/settings.json 설정 파일 구조다. 이 파일을 Git 레포지토리에 커밋하면 팀원 전원에게 동일한 보안 훅과 자동화가 적용된다.

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "node .claude/hooks/security-guard.js"
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$CLAUDE_CHANGED_FILE\" && npx eslint --fix \"$CLAUDE_CHANGED_FILE\""
      }
    ]
  }
}

보안 검사 훅 구현 예시 (.claude/hooks/security-guard.js)

AI가 .env 파일을 읽으려 하거나 rm -rf 같은 파괴적인 시도를 할 때 훅 스크립트가 exit code 1을 반환하여 차단한다.

// .claude/hooks/security-guard.js
const input = JSON.parse(process.env.CLAUDE_TOOL_INPUT || '{}');
const toolName = process.env.CLAUDE_TOOL_NAME;

// 1. 민감 파일 접근 차단
if (input.path && (input.path.includes('.env') || input.path.includes('id_rsa'))) {
  console.error('❌ [보안 위반] 민감한 파일에 접근할 수 없습니다:', input.path);
  process.exit(1);
}

// 2. 위험 파괴 명령 차단
if (toolName === 'Bash' && input.command) {
  const dangerousCmds = ['rm -rf /', 'git reset --hard', 'drop database'];
  if (dangerousCmds.some(cmd => input.command.includes(cmd))) {
    console.error('❌ [보안 위반] 위험한 명령어 실행이 금지되었습니다:', input.command);
    process.exit(1);
  }
}

process.exit(0);

이 훅 시스템을 통해 AI가 실수로 데이터베이스를 날리거나 키를 유출하는 사고를 100% 미연에 방지할 수 있다.

3. 팀 공용 MCP(Model Context Protocol) 파이프라인 구축

MCP는 Claude Code가 외부 데이터베이스, 이슈 트래커, 디자인 도구와 통신하는 표준 USB-C 포트다. 개인별로 MCP를 설정하면 키 관리가 번거롭지만, 팀 단위로 공유 MCP를 구성하면 협업 효율이 폭발적으로 상승한다.

[Claude Code CLI] 
       │
       ├─► [Figma MCP] ─────► 디자인 토큰 & 컴포넌트 레이아웃 수신
       ├─► [Postgres MCP] ──► 실제 DB 스키마 & 타입 자동 인스펙션
       └─► [GitHub MCP] ────► PR 생성 & 리뷰 이력 자동 참조

팀 MCP 설정 파일 (.claude/mcp-config.json)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

이 설정을 연결해두면 개발자가 “이슈 #142번에 맞게 DB 스키마를 업데이트하고 PR을 생성해줘”라고 요청했을 때, Claude가 Jira/GitHub 이슈 확인 ➔ Postgres 스키마 파악 ➔ 코드 수정 ➔ PR 발행까지 전체 워크플로우를 자율 수행한다. Cloudflare Agents SDK 가이드에서 다룬 상태 유지 에이전트 패턴과 조합하면 엔터프라이즈급 자동화가 완성된다.

4. 프롬프트 컨벤션과 커스텀 명령(Slash Commands) 팀 표준화

팀원들이 자주 사용하는 반복 명령을 커스텀 슬래시 명령(Slash Commands)으로 등록해둘 수 있다. .claude/commands/ 디렉토리에 마크다운 파일로 정의하면 된다.

PR 작성 자동화 명령 (.claude/commands/make-pr.md)

---
description: "현재 브랜치의 변경사항을 분석하여 표준 양식의 GitHub PR을 작성합니다."
---

다음 절차에 따라 PR을 작성해줘:
1. `git diff main...HEAD`를 수행하여 변경된 모든 파일과 로직을 분석한다.
2. 커밋 메시지와 변경 내용을 바탕으로 PR 제목과 본문을 작성한다.
3. PR 본문에는 [주요 변경사항], [테스트 방법], [영향 범위] 섹션을 포함한다.
4. `gh pr create` 명령을 사용하여 PR을 생성한다.

개발자는 터미널에서 /make-pr 한 줄만 입력하면 팀 컨벤션에 완전히 맞춘 PR이 즉시 작성된다.

| 3단계: 파이프라인 연동 | 3~4주차 | 팀 공용 MCP(GitHub, DB, Figma) 및 커스텀 명령 등록 | PR 작성, DB 마이그레이션 자동화 |

5. CI/CD 자동 검증 파이프라인 및 헤드리스 런타임 연동

Claude Code CLI는 로컬 터미널뿐만 아니라 CI/CD 파이프라인의 헤드리스(Headless) 에이전트 런타임으로도 동작한다. GitHub Actions에서 PR이 오픈되었을 때 claude CLI를 비대화형(Non-interactive) 모드로 실행하여 코드 리뷰 및 자동 정적 분석을 수행할 수 있다.

# .github/workflows/claude-ci-review.yml
name: Claude Code Auto Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Claude Code CLI
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Non-Interactive Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --non-interactive "현재 PR의 git diff를 분석하고, CLAUDE.md의 컨벤션 준수 여부와 보안 취약점을 검사해 PR 댓글로 작성해줘."

이 CI 파이프라인이 구축되면 개발자가 로컬에서 훅을 우회해서 커밋하더라도, GitHub Actions 상의 Claude 헤드리스 런타임이 CLAUDE.md 규칙 위반 여부를 2차 검증하여 PR에 자동으로 지적 사항을 남긴다.

6. 팀 도입 가이드: 3단계 전환 로드맵

자주 묻는 질문

CLAUDE.md 파일이 너무 길어지면 성능이 떨어지나요?

네, 떨어집니다. CLAUDE.md가 너무 비대해지면 컨텍스트 윈도우의 토큰을 과도하게 소모하고 핵심 규칙을 유실할 수 있습니다. 150~300줄 이내로 유지하는 것이 좋으며, 세부적인 디자인 가이드는 Claude 디자인 도구 가이드처럼 MCP나 별도 문서 파일로 분리하여 필요할 때만 참조하도록 설계해야 합니다.

Custom Hooks는 Windows 환경에서도 동일하게 동작하나요?

.claude/settings.json에서 command에 Bash 커맨드를 직접 적으면 Windows(cmd/PowerShell)에서 동작하지 않을 수 있습니다. 훅 스크립트를 Cross-platform을 지원하는 Node.js 파일(node .claude/hooks/script.js)로 작성하면 OS에 구애받지 않고 동일하게 동작합니다.

팀원이 개인 키(API Key)를 Git에 실수로 올릴 위험은 없나요?

Custom Hooks의 PreToolUse 이벤트에 Git 스태이징 파일 검사 스크립트를 연결해두면 .env나 sk-로 시작하는 API 키가 포함된 코드는 git commit 전 단계에서 자동으로 차단됩니다.

Claude Code CLI와 Cursor 중 팀 환경으로 무엇이 더 적합한가요?

터미널 중심의 CI/CD 파이프라인 연동, 강력한 커스텀 훅 통제, 대규모 멀티파일 리팩터링에는 Claude Code CLI가 압도적으로 유리합니다. 반면 실시간 인라인 자동완성과 비주얼 편집이 위주라면 Cursor가 편합니다. 최근 우수한 팀들은 두 도구를 병행하며 .claude/settings.json과 .cursorrules를 함께 관리합니다.