5장: Claude Code — CLI 기반 에이전틱 코딩

학습 목표

• Claude Code의 터미널 에이전트 아키텍처와 이 접근의 장단점을 이해합니다.
• CLAUDE.md를 통한 프로젝트 컨텍스트 제공 방식을 파악합니다.
• 도구 시스템과 서브에이전트의 동작 원리를 이해합니다.
• Git 워크플로우 통합, Hooks, MCP 서버 연동을 실전 관점에서 파악합니다.
• 하네스 엔지니어링(Harness Engineering)의 개념을 이해합니다.

IDE 없는 AI 코딩 — 다른 철학

Claude Code는 IDE 확장이 아닙니다. 터미널에서 실행되는 독립적인 에이전틱 코딩 도구입니다. 이 근본적인 차이가 모든 설계 결정에 영향을 미칩니다.

Copilot이나 Cursor가 "IDE 안에서 AI를 사용한다"면, Claude Code는 "AI가 개발자의 도구들을 사용한다"에 가깝습니다. 파일 시스템을 직접 탐색하고, 셸 명령을 실행하며, Git 작업을 수행합니다. IDE에 종속되지 않기 때문에, Vim 사용자든 VS Code 사용자든 동일한 경험을 제공합니다.

# 프로젝트 디렉토리에서 실행
cd my-project
claude
 
# 또는 직접 요청과 함께 실행
claude "이 프로젝트의 아키텍처를 분석해줘"

아키텍처

Claude Code의 아키텍처는 대화 루프, 도구 시스템, 컨텍스트 관리라는 세 가지 핵심 컴포넌트로 구성됩니다.

대화 루프

Claude Code의 핵심은 반복적인 대화 루프입니다. 사용자 입력을 받고, Claude API를 호출하며, 모델이 도구 호출을 요청하면 이를 실행한 뒤 결과를 다시 모델에 전달합니다. 이 루프가 도구 호출 없이 텍스트 응답이 반환될 때까지 반복됩니다.

이 단순한 구조가 강력한 이유는, 모델이 자율적으로 "다음에 무엇을 할지"를 결정할 수 있기 때문입니다. 코드를 읽어야 한다고 판단하면 Read 도구를, 검색이 필요하면 Grep 도구를, 명령 실행이 필요하면 Bash 도구를 호출합니다.

도구 시스템

Claude Code가 사용할 수 있는 주요 도구들은 다음과 같습니다.

이 도구들이 중요한 이유는, IDE의 API에 의존하지 않고 운영체제 수준에서 직접 작업을 수행한다는 점입니다. 이 덕분에 어떤 개발 환경에서든 동일하게 동작합니다.

CLAUDE.md: 프로젝트 컨텍스트의 핵심

CLAUDE.md는 Claude Code에게 프로젝트의 맥락을 제공하는 마크다운 파일입니다. 프로젝트 루트에 위치하며, Claude Code가 실행될 때 자동으로 읽혀 컨텍스트에 포함됩니다.

# 프로젝트명 - CLAUDE.md
 
## 프로젝트 개요
이 프로젝트는 ...에 대한 설명
 
## 기술 스택
- Framework: Next.js 16 (App Router)
- Language: TypeScript strict
- Styling: Tailwind CSS v4
 
## 개발 명령어
pnpm dev          # 개발 서버
pnpm build        # 프로덕션 빌드
pnpm lint         # 린트 검사
 
## 핵심 규칙
1. TypeScript strict — any 사용 금지
2. 컴포넌트는 function 선언 사용
3. 변경 후 빌드 통과 필수
 
## 프로젝트 구조
src/
  app/            # 페이지
  components/     # 컴포넌트
  lib/            # 유틸리티

CLAUDE.md의 효과적인 작성을 위한 핵심 원칙은 다음과 같습니다.

구체적으로 작성: "좋은 코드를 작성하세요" 같은 추상적 지침보다 "함수 선언을 사용하고, any 타입을 금지합니다" 같은 구체적 규칙이 효과적입니다.

계층적 구성: CLAUDE.md는 여러 위치에 존재할 수 있습니다. 프로젝트 루트의 CLAUDE.md는 전역 규칙, 하위 디렉토리의 CLAUDE.md는 해당 영역의 특수 규칙을 담습니다.

빌드/실행 명령어 포함: Claude Code가 빌드하고 테스트할 수 있도록 명령어를 명시합니다.

서브에이전트

Claude Code의 강력한 기능 중 하나는 서브에이전트(Sub-agent) 시스템입니다. 메인 에이전트가 복잡한 작업을 더 작은 단위로 나누어 서브에이전트에게 위임합니다.

서브에이전트는 메인 에이전트보다 제한된 도구를 가지며, 특정 작업에 집중합니다. 예를 들어, 대규모 코드베이스에서 특정 패턴을 찾는 작업을 서브에이전트에게 위임하면, 메인 에이전트의 컨텍스트 윈도우를 절약하면서 작업을 병렬로 수행할 수 있습니다.

Git 워크플로우 통합

Claude Code는 Git과 깊이 통합됩니다. 단순히 코드를 수정하는 것을 넘어, 커밋 메시지 작성, 브랜치 관리, PR 생성까지 수행합니다.

# 변경 사항 커밋 요청
claude "현재 변경 사항을 적절한 커밋 메시지와 함께 커밋해줘"
 
# PR 생성 요청
claude "이 브랜치의 변경 사항으로 PR을 만들어줘"

Claude Code의 Git 통합에서 주목할 점은 안전 장치입니다. 기본적으로 파괴적인 Git 명령(force push, hard reset 등)은 실행하지 않으며, 반드시 사용자의 명시적 허가를 요구합니다. 이는 자동화된 에이전트가 실수로 코드를 손상시키는 위험을 방지합니다.

Hooks: 자동화된 워크플로우

Hooks(훅)는 Claude Code의 특정 이벤트에 자동으로 실행되는 스크립트를 정의합니다. settings.json에서 설정하며, 다음과 같은 이벤트를 지원합니다.

• PreToolUse: 도구가 실행되기 전에 실행 (검증, 차단)
• PostToolUse: 도구 실행 후에 실행 (로깅, 후처리)
• Notification: 알림이 발생할 때 실행

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "pnpm lint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Bash command requested: $CLAUDE_TOOL_INPUT'"
      }
    ]
  }
}

Hooks를 활용하면 Claude Code가 파일을 수정할 때마다 자동으로 린트를 실행하거나, Bash 명령 실행 전에 로깅하는 등의 자동화된 워크플로우를 구성할 수 있습니다.

MCP 서버 연동

Model Context Protocol(MCP)은 AI 모델이 외부 도구와 데이터 소스에 접근하기 위한 표준 프로토콜입니다. Claude Code는 MCP 서버와 연동하여 도구 시스템을 확장할 수 있습니다.

MCP를 통해 Claude Code가 접근할 수 있는 범위가 크게 확장됩니다.

• GitHub: 이슈, PR, 코드 검색을 직접 수행
• 데이터베이스: 스키마 조회, 쿼리 실행으로 데이터 기반 개발
• Slack: 팀 커뮤니케이션 채널의 정보 참조
• 커스텀 도구: 조직 내부 API나 도구와의 연동

하네스 엔지니어링

하네스 엔지니어링(Harness Engineering)은 Claude Code를 중심으로 등장한 새로운 개념입니다. AI 에이전트가 동작하는 환경(하네스)을 설계하고 최적화하는 것을 의미합니다.

하네스 엔지니어링의 구성 요소는 다음과 같습니다.

• CLAUDE.md: 프로젝트 컨텍스트와 규칙
• Hooks: 자동화된 워크플로우와 안전 장치
• MCP 서버: 외부 도구와 데이터 접근
• settings.json: 도구 권한과 동작 설정
• Git 설정: 브랜치 전략과 커밋 규칙

이 요소들을 체계적으로 구성하면, Claude Code가 프로젝트의 맥락을 깊이 이해하고, 일관된 품질의 코드를 생성하며, 안전하게 동작하는 환경을 만들 수 있습니다.

Copilot/Cursor 대비 장단점

정리

이번 장에서는 Claude Code의 독특한 접근 방식을 심층 분석했습니다.

• Claude Code는 터미널에서 동작하는 에이전틱 코딩 도구로, IDE에 종속되지 않습니다.
• CLAUDE.md를 통해 프로젝트 컨텍스트를 제공하고, 서브에이전트를 활용하여 복잡한 작업을 분할합니다.
• Git 워크플로우와 깊이 통합되며, 파괴적 명령에 대한 안전 장치를 내장합니다.
• Hooks와 MCP를 통해 자동화된 워크플로우와 외부 도구 연동을 지원합니다.
• 하네스 엔지니어링이라는 새로운 개념으로 AI 에이전트의 동작 환경을 체계적으로 설계합니다.

다음 장에서는 Windsurf, OpenAI Codex, Google Antigravity 등 나머지 주요 도구들을 살펴보고, 각 도구의 고유한 포지셔닝을 비교하겠습니다.