Claude Code를 '완전 에이전트'로 쓰는 법 — Anthropic 개발자가 공개한 실전 팁

개요

  • 주제: Claude Code(터미널 기반 코딩 에이전트)를 단순 자동완성이 아닌 '완전 에이전틱(agentic)' 도구로 활용하는 실전 방법론
  • 핵심 관점: 도구를 가르치고, 검증 가능한 환경을 제공하며, 계획 수립을 우선시하라
  • 핵심 키워드: CLAUDE.md, 코드베이스 Q&A, 슬래시 커맨드, MCP 서버, 피드백 루프, SDK(claude -p), 병렬 작업, 계층적 권한

한 문장 요약: 이 글을 읽으면 Claude Code를 처음 켰을 때 무엇을 입력해야 할지 모르던 상태에서, 팀 컨텍스트를 공유하고 CI/CD까지 자동화하는 단계까지의 경로가 선명해집니다.

핵심 메시지 3가지

① Claude Code는 '한 줄 자동완성'이 아니라 '전체 작업 수행' 도구다

기존 AI 코딩 어시스턴트가 몇 줄 단위의 코드 완성에 집중했다면, Claude Code는 기능 구현·함수·파일 전체 작성·버그 수정을 한 번에 수행하는 완전 에이전트다. VS Code, Xcode, JetBrains 등 모든 IDE와 터미널, 원격 SSH, Tmux 환경에서 동작하며 기존 워크플로우를 바꿀 필요가 없다. (출처: 01_M8HuXu_bOco.mp4 / 영상_발화 시트)

② 성능은 '주입된 컨텍스트 양'에 비례한다

모델이 똑똑해지려면 컨텍스트를 더 많이, 더 정확하게 줘야 한다. 프로젝트 루트의 CLAUDE.md, 슬래시 커맨드, MCP 서버, 권한 설정을 팀용으로 구성해 Git에 체크인하는 것이 핵심 전략이다. (출처: 요약 청크 2·4)

③ '검증 가능한 환경'을 주면 AI가 스스로 반복 수정한다

단위 테스트, Puppeteer 스크린샷, iOS 시뮬레이터 캡처처럼 결과물을 확인할 수단을 제공하면, AI가 스스로 결과를 보고 2~3회 반복 수정해 거의 완벽한 결과물을 만든다. (출처: 요약 청크 1)

1. 시작하기 — 설치와 환경 세팅

Claude Code는 Node.js만 있으면 전역 설치 한 줄로 시작한다. 강연 현장 슬라이드에도 청중이 터미널에서 직접 따라 입력하도록 설치 명령어 한 줄만 크게 표시되어 있었다.

대형 스크린에 'Follow along:' 안내와 함께 표시된 전역 설치 명령어 슬라이드

npm install -g @anthropic-ai/claude-code

설치 후 첫 실행 시 권장하는 환경 세팅 순서는 다음과 같다.

① /terminal-setup → Shift+Enter로 줄바꿈(백슬래시 불필요)
↓
② /theme → 라이트/다크/달토나이저 테마 선택
↓
③ /install-github-app → GitHub 이슈·PR에서 @Claude 멘션 가능
↓
④ /allowed-tools → 자주 쓰는 도구는 매번 승인 없이 자동 허용
↓
⑤ (macOS) 시스템 설정 → 손쉬운 사용 → Dictation 활성화 → 단축키 두 번으로 음성 프롬프트 입력

음성으로 프롬프트를 말하면 "다른 엔지니어에게 말하듯" 구체적 지시를 빠르게 전달할 수 있다. (출처: 01_M8HuXu_bOco.mp4 / 영상_발화 시트)

2. 첫 진입점 — 코드베이스 Q&A로 온보딩 단축

무료형 도구를 처음 열면 프롬프트 바만 보여 무엇을 쳐야 할지 막막하다. 강연이 권하는 가장 쉬운 진입점은 '코드베이스에 질문하기' 다. 원격 인덱싱이나 코드 업로드가 없고, 코드는 로컬에 머무르며, 생성형 모델 학습에도 사용되지 않는다. 설정·대기 없이 즉시 쓸 수 있다.

Anthropic 내부 온보딩 사례가 이 효과를 수치로 보여준다.

항목 기존 방식 Claude Code 활용 출처
기술 온보딩 기간 2~3주 2~3일 영상_발화 시트
코드 인덱싱 원격 DB 필요 없음(로컬) 영상_발화 시트
초기 설정 필요 불필요 영상_발화 시트

단축률 산식(근거 수치 기준): - 기준 기간 = 2~3주 = 10~15일 - 개선 기간 = 2~3일 = 2~3일 - 단축률 = (10 − 2) ÷ 10 = 80% (최소 구간 기준) - 최대 구간 기준 = (15 − 3) ÷ 15 = 80%

즉 두 구간 모두에서 약 80%의 온보딩 기간 단축이 성립한다.

설치 명령어 슬라이드 아래, 'Follow along' 지시에 따라 청중이 일제히 손을 든 컨퍼런스 현장

활용 예시 질문: - "이 함수는 인자가 왜 15개이고 이름이 이렇게 이상한가?" → Git 히스토리를 탐색해 도입자·배경까지 답변 - "이번 주에 무엇을 출시했는가?" → Git 로그 기반 주간 요약 보고서 생성 - "이 클래스는 어떻게 인스턴스화하는가?" → 단순 텍스트 검색이 아닌 사용 예시까지 심층 답변

3. 컨텍스트 관리 — CLAUDE.md와 슬래시 커맨드, 팀 공유 계층

Claude의 성능은 컨텍스트에 비례하므로, 컨텍스트를 '자동 추가'와 '온디맨드 호출'로 나누어 관리한다.

CLAUDE.md(자동 추가) — 세션 시작 시 자동 로드되어 첫 사용자 턴에 포함된다. 공통 bash 명령어·스타일 가이드·아키텍처 결정·핵심 파일을 담되 간결하게 유지한다.

슬래시 커맨드(온디맨드 호출) — 반복 작업을 자동화한다.

저장 위치 호출 형식 용도 예시
~/.claude/commands/foo.md /user:foo 개인용 반복 작업
.claude/commands/foo.md /project:foo 팀 공유 명령
.claude/commands/a/foo.md /project:a:foo 하위 폴더 명령

사전 정의 예: create-release-pr.md, fix-github-issue.md, lint.md. 파일 참조는 @a/foo.py 형식, 메모리 즉시 저장은 # 단축키, /memory로 로드된 파일 확인·편집이 가능하다.

팀 공유 4계층 구조 — Memory·Slash commands·Permissions·MCP servers를 아래 계층으로 관리한다.

계층 Memory Permissions MCP servers
Enterprise /Library/Application Support/ClaudeCode/CLAUDE.md policies.json —
Global ~/.claude/CLAUDE.md ~/.claude/settings.json claude mcp
Project(shared) CLAUDE.md .claude/settings.json .mcp.json
Project(just me) CLAUDE.local.md .claude/settings.local.json —

Tip #5 더 많은 컨텍스트가 더 똑똑한 Claude를 만든다. Tip #6 개인용/팀용, 자동 추가/지연 로드 여부를 고려해 튜닝하라. Tip #7 CLAUDE.md·MCP·권한·슬래시 커맨드를 팀용으로 구성하고 Git에 체크인하라. (출처: 요약 청크 2·4)

4. 고급 활용 — 도구 연동·피드백 루프·SDK·병렬·단축키

도구 연동

  • Bash 도구: --help(-h)로 사용법을 알려주면 학습해 대신 실행 (예: barley CLI로 마지막 학습 실행 오류 로그 확인)
  • MCP 서버: claude mcp add barley_server -- node myserver로 등록, .mcp.json을 커밋해 팀과 공유

피드백 루프가 만드는 자율성

① 결과물 생성 → ② 테스트/스크린샷으로 검증 → ③ 스스로 2~3회 반복 수정 → ④ 거의 완벽한 결과물

실전 프롬프트 4종 (Steer Claude to use tools your way)

  1. 이슈 #8732 수정안 제안 → 선택 구현
  2. @app/tests/signupTest.ts 엣지 케이스 식별 및 테스트 업데이트
  3. commit·push·pr 자동화 (Git 로그·커밋 포맷 분석 → 브랜치 생성 → PR 생성)
  4. 3개 병렬 에이전트로 @services/aggregation/feed_service.cpp 정리 아이디어 브레인스토밍

Claude Code SDK (claude -p)

CI/CD·인시던트 대응·파이프라인용 저수준 접근. Unix 유틸리티처럼 파이프 처리한다.

claude -p "what did i do this week?" --allowedTools Bash(git log:*) --output-format json
git status | claude -p "what are my changes?" --output-format=json | jq '.result'

아키텍처: Your agentic application → Claude Code SDK → Anthropic/Bedrock/Vertex API → Claude models. 현재 CLI 지원, TypeScript·Python SDK는 추후 출시 예정.

병렬 작업(Multi-Claude) 4가지

① 별도 터미널 탭에서 여러 체크아웃 → ② git worktrees 단일 체크아웃 → ③ SSH + TMUX → ④ GitHub Actions

핵심 단축키 8종

키 기능
Shift+Tab 편집 자동 승인 모드 전환
# 메모리 생성(즉시 CLAUDE.md 저장)
! bash 모드 진입(출력이 컨텍스트에 포함)
@ 파일/폴더 컨텍스트 추가
Esc 현재 작업 중단(세션 손상 없음)
Double-Esc 히스토리 이동 / --resume 재개
Ctrl+R 전체 출력 보기
/vim vim 모드 활성화

보안 아키텍처 (Q&A 핵심)

구현 중 가장 어려운 부분은 bash 명령어 안전성 확보였다. bash는 시스템 상태를 변경할 수 있어 위험하지만 전부 수동 승인하면 생산성이 떨어진다. 해결책은 읽기 전용 명령어 + 정적 분석으로 조합 안전성을 판단하고, allowlist/blocklist를 계층별로 구성하는 것이다.

왜 IDE가 아닌 CLI인가

① 보편성 — VS Code·Vim·Emacs·Xcode를 쓰는 내부 인력에게 터미널이 유일한 공통분모. ② 미래 대비 — 모델 성능이 빨라 연말엔 IDE 자체가 불필요해질 수 있어 상위 UI에 과도하게 투자하지 않음. 참고로 Anthropic 기술 인력의 약 80% 가 매일 Claude Code를 사용한다. (출처: 요약 청크 3)

관점 포인트

  • 설치·시작: Node.js 한 줄이면 끝. 인덱싱·업로드·대기가 없으므로 '오늘 바로' 적용 가능.
  • 진입 전략: 거대한 기능 지시보다 코드베이스 Q&A로 시작해 신뢰를 쌓고, 편집 단계에서는 먼저 계획 세우게 한 뒤 승인하는 것이 오류를 줄인다.
  • 컨텍스트 설계: CLAUDE.md는 간결하게, 팀 공유는 4계층으로, 개인 설정은 CLAUDE.local.md로 분리해 커밋하지 않는다.
  • 자율성 확보: 검증 수단(테스트·스크린샷)을 제공해야 AI가 스스로 반복 수정한다.
  • 파이프라인 통합: claude -p + --output-format json으로 CI/CD·인시던트 대응에 연결한다.
  • 보안 전제: 자동 승산은 allowlist/blocklist와 정적 분석 위에 성립한다.

최종 핵심 정리

확인해야 할 핵심 질문 - ☐ 우리 팀은 CLAUDE.md를 Git에 체크인해 컨텍스트를 공유하고 있는가? - ☐ 코드베이스 Q&A로 신규 입사자 온보딩을 2~3주 → 2~3일 수준으로 압축할 수 있는가? - ☐ 단위 테스트·스크린샷 등 '검증 가능한 환경'을 AI에 제공해 반복 수정 루프를 돌리고 있는가? - ☐ claude -p SDK를 CI/CD·인시던트 파이프라인에 연결할 지점이 있는가? - ☐ bash 자동 승인은 allowlist/blocklist와 정적 분석으로 안전장치가 걸려 있는가?

한 줄 요약: Claude Code를 잘 쓰는 비결은 복잡한 설정이 아니라 — 도구를 가르치고, 검증 가능한 환경을 주고, 계획을 먼저 세우게 하는 'surprisingly vanilla'한 습관이다.