Claude Code가 단순 코드 자동완성과 근본적으로 다른 이유 — 이슈에서 PR까지 자동화하는 AI 개발 에이전트의 20가지 핵심 개념 [2026]

솔직히 처음 Claude Code를 접했을 때는 "그냥 Copilot 좀 더 잘하는 버전 아닌가?" 싶었어요. 터미널에서 돌아가는 것만 보고 대충 넘어갔었는데, 어느 날 GitHub 이슈를 자연어 한 줄로 던졌더니 코드를 짜고, 테스트를 돌리고, PR까지 열어주는 걸 보고 나서야 "아, 이건 코드 자동완성이랑은 카테고리 자체가 다른 물건이구나"를 깨달았습니다.

이게 단순히 AI가 코드를 잘 쓰는 게 아니라 에이전틱 개발(agentic engineering) — AI가 계획을 세우고, 도구를 실행하고, 결과를 검증하는 전 과정을 자율로 수행하는 방식 — 이거든요. 커뮤니티 담론도 "vibe coding"에서 훅·서브에이전트·워크플로우를 엮는 구조화된 엔지니어링 패턴으로 빠르게 이동하고 있고요. 저도 이 개념들을 체계적으로 이해하고 나서야 반복 작업이 눈에 띄게 줄고, 컨텍스트 설명 없이도 팀 컨벤션이 일관되게 적용되는 걸 경험했습니다.

이 글을 읽고 나면 Claude Code의 핵심 개념 20가지를 실무 맥락에서 이해하고, CLAUDE.md 하나를 오늘 당장 만들어서 팀 전체의 AI 작업 일관성을 끌어올릴 수 있습니다. 기능 목록 나열 대신, 각 개념이 왜 필요한지, 어떤 문제를 풀어주는지에 집중했어요.

목차

• 핵심 개념
  • 1. CLAUDE.md — 매 세션 자동으로 로드되는 프로젝트 메모리
  • 2. 슬래시 커맨드 — 세션을 제어하는 내장 명령어들
  • 3. 커스텀 커맨드 — 반복 작업을 명령어 하나로
  • 4. Hooks — 라이프사이클 이벤트에 연결하는 자동화 스크립트
  • 5. 서브에이전트 — 컨텍스트를 분리하는 전문 인스턴스
  • 6. Skills — 필요할 때만 로드하는 온디맨드 지식
  • 7. MCP(Model Context Protocol) — AI-도구 통합의 사실상 표준
  • 8. Agent Teams — 병렬 멀티에이전트 오케스트레이션
  • 9. Git Worktrees — 충돌 없는 병렬 격리 개발
  • 10. 권한 시스템 — 도구별 세밀한 접근 제어
  • 11. Auto Mode — 안전하면서도 중단 없는 자율 실행
  • 12. Sandboxing — 커널 수준의 OS 보안
  • 13. 컨텍스트 관리 — /clear와 /compact를 언제 쓰는가
  • 14. TDD 워크플로우 — 실패하는 테스트가 명확한 계약이 된다
  • 15. Dynamic Workflows — 멀티에이전트 흐름을 코드로 표현
  • 16. Monitor Tool — 백그라운드 이벤트 실시간 스트리밍
  • 17. Ultraplan — 클라우드 기반 계획 워크플로우
  • 18. Computer Use — 네이티브 UI 자동화
  • 19. Plugins — 커스터마이징을 번들로 배포
  • 20. Agent View & 세션 관리 — 실행 중인 에이전트를 한 화면에서
• 장단점 분석
  • 장점
  • 단점 및 주의사항
  • 실무에서 가장 흔한 실수
• 실전 적용
  • 예시 1: 이슈 트래커 연동 전체 개발 사이클 자동화
  • 예시 2: 대규모 코드베이스 병렬 마이그레이션
  • 예시 3: 훅을 이용한 자동화 감사 로그
• 마치며
• 참고 자료

핵심 개념

1. CLAUDE.md — 매 세션 자동으로 로드되는 프로젝트 메모리

프로젝트 루트에 CLAUDE.md를 만들어두면 Claude Code가 모든 세션 시작 시 이 파일을 자동으로 읽어요. 팀 컨벤션, 아키텍처 개요, 절대 건드리면 안 되는 영역, 빌드·테스트 명령어 등을 여기에 써두면 됩니다.

제가 처음 만든 CLAUDE.md는 "TypeScript 써요, pnpm 써요" 수준이었는데, 이걸 제대로 채우고 나서부터 프롬프트가 훨씬 간결해졌어요. 팀 컨벤션을 매번 설명하는 수고가 사라지거든요. 실무에서 가장 많이 쓰는 구조는 대략 이렇습니다:

# 프로젝트 개요
NestJS 기반 B2B SaaS 백엔드. PostgreSQL + Redis. 도메인 주도 설계 적용.
 
# 코드 스타일
- TypeScript strict mode 필수
- async/await 사용 (Promise.then 금지)
- 2-space indentation
 
# 절대 수정 금지
- src/infra/db/migrations/ — 마이그레이션은 직접 생성만 가능
- src/auth/crypto.ts — 보안 감사 이후 변경 시 팀 리뷰 필수
 
# 테스트 & 빌드
- 테스트: pnpm test
- 빌드: pnpm build
- 린트: pnpm lint

핵심: CLAUDE.md는 에이전트 팀 전체가 공유하는 규칙집입니다. 서브에이전트든 팀원 세션이든 동일한 파일을 로드하기 때문에, 팀 전체의 AI 작업 일관성을 보장하는 가장 확실한 방법이에요.

2. 슬래시 커맨드 — 세션을 제어하는 내장 명령어들

/로 시작하는 명령어들로, 자주 쓰는 것들만 익혀도 작업 흐름이 크게 달라집니다. /help를 실행하면 현재 세션에서 쓸 수 있는 커맨드 전체 목록을 확인할 수 있어요.

플러그인과 스킬을 추가하면 여기에 커맨드가 더 붙어요. 결국 자신이 만들거나 설치한 것들이 슬래시 커맨드로 집약되는 구조입니다.

3. 커스텀 커맨드 — 반복 작업을 명령어 하나로

.claude/commands/(프로젝트 범위) 또는 ~/.claude/commands/(전역 범위)에 마크다운 파일을 만들면 나만의 슬래시 커맨드가 됩니다. 파일 이름이 커맨드 이름이 되어요.

커밋 메시지 자동 생성 커맨드는 이렇게 만들 수 있어요:

# .claude/commands/commit.md
 
아래 diff를 분석해서 한국어로 커밋 메시지를 작성해줘.
Conventional Commits 형식을 따르되, 본문은 "왜" 변경했는지 중심으로.
 
변경사항:
!git diff --cached

!git diff --cached처럼 !로 시작하는 셸 명령어는 실행 결과가 프롬프트에 자동으로 주입됩니다. $ARGUMENTS로 인자도 받을 수 있어요:

# .claude/commands/review.md
 
$ARGUMENTS 파일을 코드 리뷰해줘.
보안 취약점, 성능 병목, 가독성 순서로 검토하고
각 항목을 심각도(높음/중간/낮음)와 함께 표로 정리해줘.

저장하면 /review src/auth/service.ts 식으로 바로 호출할 수 있습니다. 팀마다 반복되는 작업 패턴이 있을 텐데, 그걸 커맨드로 만들어두면 온보딩 속도도 덩달아 빨라져요.

4. Hooks — 라이프사이클 이벤트에 연결하는 자동화 스크립트

저도 처음엔 "그냥 프리커밋 훅이랑 다를 게 뭐야?" 싶었는데, 완전히 다른 개념이었어요. Claude Code의 라이프사이클 이벤트에 스크립트를 연결할 수 있어서, AI가 특정 행동을 하기 직전·직후에 개입할 수 있거든요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'echo \"[AUDIT] $(date): bash 명령어 실행 예정\" >> ~/.claude/audit.log'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm lint --fix"
          }
        ]
      }
    ]
  }
}

이벤트 종류: PreToolUse는 도구 실행 직전, PostToolUse는 직후, UserPromptSubmit은 프롬프트 제출 시 발동합니다. 파일 저장 후 자동 포맷팅, 위험한 명령어 감사 로깅 같은 동작을 메모리나 프롬프트 없이 시스템 수준에서 강제할 수 있다는 게 핵심이에요.

설정 파일 위치는 프로젝트 범위라면 .claude/settings.json, 전역 범위라면 ~/.claude/settings.json에 두면 됩니다.

5. 서브에이전트 — 컨텍스트를 분리하는 전문 인스턴스

메인 세션이 길어지다 보면 컨텍스트가 뒤섞여서 품질이 떨어지는 경험, 한 번쯤 해보셨을 거예요. 서브에이전트는 특정 작업을 독립된 컨텍스트 윈도우에서 실행하는 전문화된 Claude 인스턴스입니다.

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: OWASP Top 10 기준으로 코드를 보안 관점에서 검토하는 에이전트
---
 
당신은 5년 경력의 애플리케이션 보안 전문가입니다.
코드를 받으면 OWASP Top 10 기준으로 분석하고,
각 취약점을 심각도(Critical/High/Medium/Low)와 CWE 번호와 함께 보고합니다.
수정 제안은 반드시 코드 예시를 포함합니다.

OWASP Top 10은 웹 애플리케이션에서 가장 흔하게 발견되는 10가지 보안 위협 목록으로, SQL Injection, XSS, 인증 결함 등이 포함됩니다. 전 세계 보안 커뮤니티가 관리하는 사실상의 표준이에요.

공개 레포지터리에 이미 100개 이상의 특화 서브에이전트가 공유되어 있으니, 처음부터 만들기 전에 VoltAgent/awesome-claude-code-subagents를 먼저 둘러보시면 좋아요.

6. Skills — 필요할 때만 로드하는 온디맨드 지식

CLAUDE.md가 항상 로드되는 상시 컨텍스트라면, Skills는 관련 작업이 생겼을 때만 로드하는 온디맨드 지식입니다. .claude/skills/에 마크다운 파일로 정의해요.

# .claude/skills/api-conventions.md
---
name: api-conventions
description: REST API 설계 규약 — 엔드포인트 작성 시 로드
---
 
## 응답 형식
모든 API 응답은 { data, meta, error } 구조를 따릅니다.
 
## 에러 코드 체계
- 4xx: 클라이언트 에러 (validation, auth)
- 5xx: 서버 에러 (db, external service)
 
## 페이지네이션
cursor 기반 페이지네이션 사용. offset 방식 금지.

배포 절차, 특정 외부 API 연동 방법, 도메인 전용 코딩 패턴처럼 항상 필요하진 않지만 필요할 때는 정확해야 하는 지식들을 분리해두면 컨텍스트를 절약하면서도 품질을 유지할 수 있어요. CLAUDE.md에 모든 걸 다 욱여넣지 않아도 되는 이유이기도 합니다.

7. MCP(Model Context Protocol) — AI-도구 통합의 사실상 표준

Anthropic이 오픈소스로 공개한 프로토콜인데, 이제는 OpenAI·Google·Microsoft Copilot까지 채택하면서 업계 표준이 됐어요. 2026년 기준 공식 레지스트리에 9,400개 이상의 서버가 등록되어 있고, 월간 SDK 다운로드가 9,700만 건이라고 합니다.

아래는 Claude Code CLI 기준 MCP 설정 예시입니다. Claude Desktop이나 IDE 확장은 설정 파일 위치가 플랫폼마다 다를 수 있으니 공식 문서를 확인하시는 것을 권장해요:

// .claude/mcp.json
{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "${DATABASE_URL}"
      }
    }
  }
}

이렇게 연결해두면 "이슈 #234 읽고 구현해줘" 한 줄로 GitHub Issues에서 이슈를 읽고, 코드를 작성하고, PR까지 생성하는 흐름이 가능해집니다.

Tool Search: MCP 서버가 많아질수록 세션 시작 시 전체 스키마를 한 번에 로드하면 컨텍스트를 과도하게 소모해요. Tool Search 기능으로 실제로 필요한 도구만 지연 로드해서 컨텍스트 사용량을 최소화할 수 있습니다.

8. Agent Teams — 병렬 멀티에이전트 오케스트레이션

v2.1.32부터 실험 플래그 없이 사용 가능해진 기능이에요. 팀 리드 세션이 작업을 분해해 여러 팀원 에이전트에게 할당하고, 팀원들은 독립 컨텍스트에서 병렬로 작업합니다.

가장 효과적인 활용 패턴:

단, 순차적으로 의존하는 작업이나 같은 파일을 여러 에이전트가 편집하는 경우엔 단일 세션이 훨씬 효율적입니다. 병렬이 무조건 빠른 게 아니라는 걸 처음엔 간과하기 쉬운데, 의존성 구조를 먼저 파악하는 게 중요해요.

9. Git Worktrees — 충돌 없는 병렬 격리 개발

Git Worktrees는 하나의 레포지터리에서 여러 브랜치를 동시에 체크아웃할 수 있게 해주는 Git 내장 기능입니다. Claude Code와 조합하면 여러 에이전트가 서로 다른 기능을 동시에, 충돌 없이 개발할 수 있어요.

# 독립 워크트리 생성
git worktree add .claude/worktrees/feature-auth -b feature/auth
git worktree add .claude/worktrees/feature-payment -b feature/payment
 
# 각 워크트리에서 Claude Code 세션 실행
cd .claude/worktrees/feature-auth && claude

실무에서 자주 맞닥뜨리는 상황인데, 같은 기능을 두 가지 접근법으로 구현해보고 싶을 때 워크트리가 특히 유용해요. 두 에이전트가 각자 워크트리에서 독립 구현을 완성하고 나면, 성능·유지보수성·코드 품질을 비교해서 더 나은 걸 선택하면 됩니다. "어떤 방법이 더 좋을까?" 고민만 하는 대신 둘 다 만들어보는 게 오히려 빠를 때가 있거든요.

10. 권한 시스템 — 도구별 세밀한 접근 제어

Allow / Ask / Deny 세 가지 규칙 타입으로 각 도구의 접근 범위를 제어합니다. 글로벌 → 프로젝트 → 로컬 순으로 설정이 상속됩니다.

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/**)",
      "Bash(pnpm test)",
      "Bash(pnpm lint)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  }
}

최소 권한 원칙: MCP 서버 연결 시 특히 중요해요. 실제로 저도 처음에 "일단 DB MCP를 읽기/쓰기 모두 허용하자"고 했다가 테스트 중에 프로덕션 데이터를 건드릴 뻔한 적이 있었거든요. 데이터베이스 MCP는 읽기 전용으로만 허용하고, 프로덕션 접근 권한은 명시적으로 deny 처리하는 것을 권장합니다.

11. Auto Mode — 안전하면서도 중단 없는 자율 실행

--dangerously-skip-permissions 없이도 중단 없는 작업이 가능하게 해주는 모드입니다. 분류기 모델이 각 명령 실행 직전에 안전성을 검토해서 범위 확대·미인가 인프라 접근·악의적 행위를 차단해요.

Anthropic 내부 테스트에서 권한 프롬프트를 84% 줄였다고 합니다. "자율적으로 돌리되 안전하게"라는 상충되는 요구를 어느 정도 해소해주는 기능이에요. 긴 배치 작업을 돌릴 때 "이 명령어 실행해도 될까요?" 팝업이 계속 뜨던 경험이 있다면, 이 모드가 꽤 반가울 거예요.

12. Sandboxing — 커널 수준의 OS 보안

권한 시스템이 "무엇을 할 수 있는가(what)"를 정의한다면, 샌드박스는 "얼마나 깊이 들어갈 수 있는가(how far)"를 커널 수준에서 제한합니다. Bash 도구의 파일시스템·네트워크 접근을 OS 수준에서 격리해요.

두 레이어는 상호 보완적으로 작동합니다. 권한 시스템을 우회하더라도 샌드박스가 실제 피해를 막는 마지막 방어선 역할을 해요. 멀티에이전트 환경에서 수십 개 에이전트가 동시에 돌아갈 때, 이 이중 레이어가 있다는 게 심리적으로도 꽤 안심이 됩니다.

13. 컨텍스트 관리 — /clear와 /compact를 언제 쓰는가

긴 세션은 컨텍스트가 비대해져 응답 속도가 느려지고 정확도가 떨어져요. 처음엔 이게 Claude Code 자체 문제인 줄 알았는데, /clear 한 번 누르고 다시 물어보면 확연히 달라지더라고요.

저는 기능 단위로 작업을 마칠 때마다 /clear를 습관화했는데, 이게 생각보다 체감 품질 차이가 큽니다. "왜 갑자기 이상한 코드가 나오지?" 싶을 때 열에 여덟은 컨텍스트 문제거든요.

14. TDD 워크플로우 — 실패하는 테스트가 명확한 계약이 된다

실패하는 테스트를 먼저 작성하고 커밋하면 Claude Code가 달성해야 할 명확한 목표를 갖게 됩니다. 모호한 프롬프트보다 "이 테스트를 통과시켜줘"가 훨씬 더 정확한 결과를 낸다는 걸 직접 써보고 나서야 실감했어요.

// 먼저 실패하는 테스트를 작성 (NestJS 예시)
describe('UserService.createUser', () => {
  it('이메일 중복 시 ConflictException을 던져야 한다', async () => {
    await userService.createUser({ email: 'existing@test.com', password: 'pw' });
 
    await expect(
      userService.createUser({ email: 'existing@test.com', password: 'pw' })
    ).rejects.toThrow(ConflictException);
  });
 
  it('생성된 유저의 비밀번호는 bcrypt 해시여야 한다', async () => {
    const user = await userService.createUser({
      email: 'new@test.com',
      password: 'plaintext',
    });
    expect(user.password).not.toBe('plaintext');
    expect(user.password).toMatch(/^\$2[aby]\$/);
  });
});

이 테스트 파일을 커밋하고 "이 테스트들을 통과하도록 UserService를 구현해줘"라고 하면, Claude Code가 Red(실패) → Green(구현) → Refactor(정리) 사이클을 자율로 수행합니다. NestJS 예시이긴 하지만, Python에서 pytest, Go에서 testing 패키지를 써도 동일하게 적용돼요. 프레임워크가 달라도 "테스트가 계약서다"라는 원칙은 그대로입니다.

15. Dynamic Workflows — 멀티에이전트 흐름을 코드로 표현

하나의 스크립트에서 여러 에이전트를 오케스트레이션하는 기능입니다. agent(), parallel(), pipeline(), phase() 함수를 조합해 멀티에이전트 흐름을 코드로 표현할 수 있어요.

아래는 개념 구조를 설명하기 위한 의사 코드입니다. 실제 실행 가능한 API 형태는 공식 문서에서 확인하시는 것을 권장해요:

// 개념 설명용 의사 코드
const codeReviewWorkflow = pipeline([
  phase('분석',
    parallel([
      agent('bug-finder', '버그와 로직 오류를 찾아줘'),
      agent('security-checker', 'OWASP Top 10 기준으로 보안 이슈를 찾아줘'),
      agent('perf-analyzer', '성능 병목을 찾아줘'),
    ])
  ),
  phase('종합',
    agent('reviewer', '앞선 분석 결과를 통합해 우선순위별 리뷰 리포트를 작성해줘')
  ),
]);

분석 에이전트 세 개가 병렬로 돌고, 전부 끝나면 종합 에이전트가 결과를 통합하는 구조예요. 각 단계가 독립 컨텍스트에서 실행되기 때문에 앞 단계의 잡음이 뒷 단계에 영향을 주지 않는다는 게 핵심입니다.

16. Monitor Tool — 백그라운드 이벤트 실시간 스트리밍

배포 직후 에러 로그를 모니터링하거나, CI 파이프라인 진행 상황을 대화창으로 스트리밍할 때 사용하는 도구입니다. "배포 후 5분간 에러 로그를 모니터링하면서 이상이 생기면 즉시 알려줘"라고 하면, 백그라운드 프로세스에서 발생하는 이벤트가 대화로 들어와요.

현재 얼리 프리뷰 단계라 프로덕션에서 충분히 검증된 사례는 아직 많지 않습니다. 지속적인 스트리밍이 필요한 모니터링 시나리오에 어떻게 녹아들지 지켜봐야 하는 단계이고, 실전 활용 예시는 정식 출시 이후 추가할 예정이에요.

17. Ultraplan — 클라우드 기반 계획 워크플로우

CLI에서 계획 초안을 작성하고, 웹 에디터에서 팀과 함께 검토·댓글을 달고, 원격 실행하거나 로컬로 가져오는 플로우입니다. 복잡한 멀티에이전트 작업을 팀과 공유하고 협업하는 방식으로 발전할 것으로 보여요.

이것도 현재 얼리 프리뷰 단계입니다. "AI 작업을 팀 단위 협업 산출물로 만든다"는 방향성 자체는 흥미롭지만, 지금 당장 프로덕션 워크플로우에 넣기보다는 정식 출시를 기다려보는 것이 좋을 것 같아요.

18. Computer Use — 네이티브 UI 자동화

터미널에서 Claude가 직접 앱을 열고, UI를 클릭하며, 변경 사항을 검증하는 기능입니다. 리서치 프리뷰 단계로, 코드 변경 후 "실제로 UI가 의도대로 동작하는지" 브라우저에서 직접 확인하는 검증 자동화에 활용될 수 있어요.

"코드를 바꾸고 나서 눈으로 확인하는" 작업이 자동화된다는 방향성은 꽤 매력적입니다. 다만 리서치 프리뷰인 만큼, 프로덕션 환경에서 쓸 수 있는 수준인지는 좀 더 지켜봐야 하는 단계예요.

19. Plugins — 커스터마이징을 번들로 배포

커스텀 스킬·서브에이전트·훅·슬래시 커맨드를 하나의 패키지로 묶어 배포하는 시스템입니다. .zip 아카이브와 URL 설치를 지원해요.

# URL로 플러그인 설치
claude plugin install https://example.com/my-plugin.zip
 
# 설치된 플러그인 확인
/plugins

Security Plugin이 특히 주목받고 있어요. 코드 편집·diff·커밋을 실시간으로 모니터링해서 SQL Injection, XSS, 하드코딩된 크리덴셜 등 고위험 취약점 클래스 약 25가지를 자동 탐지합니다. 보안 리뷰 없이 CI를 돌리는 팀이라면 이 플러그인 하나가 꽤 든든한 안전망이 될 수 있어요. 팀 표준 개발 환경을 하나의 플러그인으로 묶어서 배포하는 용도로도 활용도가 높습니다.

20. Agent View & 세션 관리 — 실행 중인 에이전트를 한 화면에서

여러 Claude Code 세션을 단일 화면에서 관리하는 통합 뷰입니다. 실행 중인 프로세스, 대기 중인 승인 요청, 완료된 작업이 한 눈에 보이고, 좌우 방향키로 관련 세션 간 전환이 가능해요.

에이전트 팀이나 병렬 워크트리를 운영하다 보면 "지금 어느 에이전트가 뭘 하고 있지?"를 추적하는 게 생각보다 번거로워요. 여러 터미널 탭을 오가며 눈으로 쫓던 작업이 하나의 대시보드로 정리되는 거라고 보시면 됩니다. 병렬 세션이 많아질수록 이 뷰의 가치가 커져요.

장단점 분석

장점

단점 및 주의사항

결정론(Determinism): 동일한 입력에 항상 동일한 출력이 나오는 성질입니다. AI 모델은 확률적으로 동작하므로 근본적으로 비결정론적이에요. TDD와 훅은 이 불확실성을 코드 수준에서 제어하는 실용적인 대응책입니다.

실무에서 가장 흔한 실수

1. CLAUDE.md 없이 시작하기 — 팀 컨벤션을 매번 프롬프트에 포함하는 건 비효율적이고 일관성도 보장되지 않아요. 프로젝트 온보딩 첫 번째 단계로 CLAUDE.md 작성을 넣어두는 것을 권장합니다.
2. 세션을 무한정 이어가기 — 긴 세션에서 계속 작업하면 앞의 내용이 뒤의 결과에 의도치 않게 영향을 줍니다. 독립 작업마다 새 세션을 여는 것이 권장 패턴이에요.
3. MCP 서버에 과도한 권한 부여 — "일단 다 연결해두자"는 접근은 보안 리스크를 키웁니다. 실제로 자주 쓰는 서버만 연결하고, 각 서버의 권한 범위를 최소화하는 것이 좋아요.

실전 적용

예시 1: 이슈 트래커 연동 전체 개발 사이클 자동화

GitHub MCP를 연결하면 이슈를 자연어 한 줄로 처리할 수 있습니다.

# GitHub MCP 연결 후
> "이슈 #156을 읽고, feature/issue-156 브랜치에서 구현하고,
   테스트를 작성한 다음 PR을 열어줘. PR 본문에는 이슈 링크와
   변경 사항 요약을 포함해줘."

내부적으로 일어나는 일:

예시 2: 대규모 코드베이스 병렬 마이그레이션

레거시 콜백 코드를 async/await으로 전환하는 작업을 모듈별로 병렬화하는 패턴입니다. 저희 팀에서는 이 방식으로 3개 모듈 마이그레이션을 순차 처리보다 훨씬 빠르게 완료했어요.

# 각 모듈마다 독립 워크트리 생성
git worktree add .claude/worktrees/migrate-auth -b migrate/auth
git worktree add .claude/worktrees/migrate-payment -b migrate/payment
git worktree add .claude/worktrees/migrate-notification -b migrate/notification
 
# 각 워크트리에서 독립 세션 실행
cd .claude/worktrees/migrate-auth
claude "src/auth/ 아래 콜백을 async/await으로 전환. CLAUDE.md의 코드 스타일 준수."

각 에이전트가 서로 다른 브랜치에서 독립적으로 마이그레이션을 완료하면, 통합 테스트를 돌려서 머지하면 됩니다.

예시 3: 훅을 이용한 자동화 감사 로그

AI가 어떤 명령을 실행했는지 추적하는 감사 로그를 훅으로 강제하는 구성이에요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'echo \"[AUDIT] $(date): bash 실행 예정\" >> ~/.claude/audit.log'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm lint --fix"
          }
        ]
      }
    ]
  }
}

PostToolUse의 Write 훅은 파일이 저장될 때마다 린트를 자동으로 돌려줍니다. 훅에서 사용 가능한 환경 변수 목록은 공식 문서의 Hooks 섹션에서 확인하시는 것을 권장해요.

마치며

Claude Code는 단순히 코드를 생성하는 도구가 아니라, CLAUDE.md·훅·서브에이전트·MCP를 체계적으로 구성했을 때 비로소 진가를 발휘하는 에이전틱 개발 환경입니다.

오늘 당장 시작할 수 있는 3단계:

1. 현재 프로젝트 루트에 CLAUDE.md를 만들어보시면 좋습니다. 아키텍처 개요와 pnpm test, pnpm build 명령어, 절대 건드리지 말아야 할 경로 세 가지만 먼저 적어두는 것으로 충분해요. 이것만으로도 매 세션마다 컨텍스트를 설명하는 수고가 크게 줄어듭니다.
2. 반복하는 작업이 있다면 커스텀 커맨드로 만들어보시는 것을 권장합니다. .claude/commands/commit.md에 !git diff --cached를 주입하는 커밋 메시지 생성 커맨드가 좋은 시작점이에요.
3. 작업 단위마다 /clear를 습관화해보시면 체감 품질 차이를 바로 경험하실 수 있습니다. 새 기능을 시작하거나 다른 파일로 넘어갈 때마다 컨텍스트를 초기화하면 응답 정확도가 눈에 띄게 달라져요.

참고 자료

• Claude Code Best Practices | Anthropic
• Claude Code What's New | Anthropic
• Claude Code 권한 설정 | Anthropic
• Claude Code MCP 연동 | Anthropic
• Claude Code 서브에이전트 생성 | Anthropic
• Claude Code 에이전트 팀 | Anthropic
• Claude Code 슬래시 커맨드 | Anthropic
• Auto Mode 구현 | Anthropic Engineering
• Sandboxing | Anthropic Engineering
• 50 Claude Code Tips and Best Practices | builder.io
• awesome-claude-code | GitHub
• awesome-claude-code-subagents | GitHub
• Claude Code Hooks·Subagents·Skills Complete Guide | dev.to
• Claude Code Multi-Agent Orchestration 2026 | shipyard.build
• Claude Code Customization Guide | alexop.dev
• Model Context Protocol 공식 문서
• How I Use Every Claude Code Feature | Shrivu Shankar