Claude Code 핵심 가이드 — 에이전틱 코딩의 모든 것

 

⌨️ Claude Code 핵심 가이드 — 에이전틱 코딩의 모든 것

최종 업데이트: 2026년 2월 25일

1. Claude Code란?

Claude Code는 Anthropic이 만든 에이전틱 코딩 도구다. 코드베이스를 읽고, 파일을 편집하고, 명령어를 실행하며, 개발 도구와 직접 통합된다. 단순 챗봇이 아니라 자율적으로 문제를 탐색하고 해결하는 코딩 에이전트라는 점이 핵심이다.

환경	특징	적합한 용도
Terminal CLI	전체 기능, 커맨드라인 직접 제어	파워 유저, 전체 프로젝트 관리
VS Code	인라인 diff, @멘션, Plan 리뷰	일상 코딩, 코드 리뷰
JetBrains	IDE 통합, 코드 네비게이션	Java/Kotlin/Python 개발
Desktop App	병렬 세션, Git 격리, 앱 프리뷰	멀티태스킹, 대규모 작업
Web	로컬 설치 불필요, PR 생성	원격 작업, 병렬 버그 수정
Slack / CI/CD	GitHub Actions, GitLab 통합	자동화, 코드 리뷰 봇

2. Agentic Loop — 핵심 작동 원리

Claude Code의 핵심은 3단계 에이전틱 루프다. 이 루프를 이해하면 효과적으로 활용할 수 있다.

단계	작업	사용 도구
1. 컨텍스트 수집 (Gather)	코드베이스 탐색, 파일 읽기, 구조 분석, 의존성 추적	Read, Glob, Grep, Bash
2. 액션 실행 (Act)	파일 편집, 명령어 실행, 리팩토링, 새 파일 생성	Edit, Write, Bash, MCP tools
3. 결과 검증 (Verify)	테스트 실행, 빌드 확인, 린트 검사, 자가 수정	Bash (test/build/lint)

💡 핵심 포인트: 세 단계가 별개가 아니라 자연스럽게 섞인다. 디버깅 세션에서는 수집→실행→검증을 수십 번 반복하며, 사용자는 언제든 개입해서 방향을 바꿀 수 있다.

3. 확장 시스템 — 6가지 핵심 기능

기본 도구만으로 대부분의 코딩 작업을 처리하지만, 확장 기능을 추가하면 훨씬 강력해진다.

기능	역할	로딩 시점	언제 사용?
CLAUDE.md	항상 로드되는 프로젝트 컨텍스트	세션 시작 시 항상	코딩 규칙, 빌드 명령어, "절대 하지 마" 규칙
Skills	재사용 가능한 지식/워크플로우	설명만 로드 → 필요시 전체	API 문서, /deploy 같은 슬래시 커맨드
MCP	외부 서비스 연결 (오픈 표준)	세션 시작 시 서버 연결	Google Drive, Jira, Slack, DB 연동
Subagents	격리된 컨텍스트에서 독립 실행	호출 시	파일 리뷰, 리서치, 컨텍스트 오염 방지
Hooks	라이프사이클 이벤트에 자동 실행	이벤트 발생 시	편집 후 자동 포맷, 커밋 전 린트, 알림
Agent Teams	독립 세션 간 협업	명시적 실행	병렬 코드 리뷰, 대규모 기능 개발

💡 선택 가이드: CLAUDE.md → 항상 알아야 하는 것 (~500줄 이내) | Skills → 가끔 필요한 참조 자료나 워크플로우 | Hooks → 예외 없이 매번 실행되어야 하는 것 | MCP → 외부 서비스 연결

4. CLAUDE.md 작성법

프로젝트 루트에 CLAUDE.md 파일을 만들면 Claude Code가 매 세션 시작 시 자동으로 읽는다. /init 명령으로 프로젝트 분석 기반 초안을 자동 생성할 수 있다.

항목	예시
빌드/테스트 명령어	npm run test -- --watch, make build
코드 스타일 규칙	TypeScript strict mode, 2-space indent, Prettier
절대 하지 마 규칙	"main 브랜치에 직접 커밋 금지", "console.log 남기지 마"
프로젝트 구조 설명	src/api/ → API 라우트, src/lib/ → 유틸리티
외부 참조 임포트	@README.md, @docs/architecture.md

✅ 핵심 팁: CLAUDE.md는 git에 체크인해서 팀 전체가 공유하도록 하자. 시간이 갈수록 축적된 지식의 가치가 커진다. 너무 길어지면 (500줄 초과) 참조 콘텐츠를 Skills로 분리한다.

5. 실전 워크플로우 Best Practices

패턴	설명	예시 프롬프트
구체적 지시	모호한 요청 대신 증상/파일/기대 결과를 명시	"잘못된 비밀번호 입력 후 빈 화면이 나오는 auth.ts의 로그인 버그 수정"
탐색 먼저, 계획, 코딩	Plan Mode(Ctrl+G)로 계획 확인 후 실행	"이 코드베이스의 인증 흐름을 설명해줘" → 계획 승인 → 실행
컨텍스트 관리	컨텍스트 윈도우가 차면 성능 저하 → 세션 분리	/compact로 정리하거나 새 세션 시작
병렬 작업	& prefix로 웹에 전송하여 동시 처리	"& auth 테스트 수정" "& API 문서 업데이트"
원스텝 PR	/commit-push-pr 스킬로 커밋→푸시→PR 한번에	"변경사항을 PR로 만들어줘"

6. 주요 CLI 명령어 요약

명령어	기능
/init	프로젝트 기반 CLAUDE.md 자동 생성
/compact	대화 컨텍스트 압축 (메모리 절약)
/help	도움말 및 사용 가능한 기능 확인
/permissions	도구 권한 설정 관리
/hooks	Hooks 설정 인터랙티브 UI
/agents	서브에이전트 목록 및 생성
/tasks	백그라운드 웹 세션 모니터링
/teleport	웹 세션을 로컬 터미널로 가져오기
Ctrl+G	Plan Mode — 에디터에서 계획 편집
Ctrl+O	Verbose 모드 토글 (확장 사고 표시)

💡 설치: npm install -g @anthropic-ai/claude-code (macOS/Linux) 또는 winget install Anthropic.ClaudeCode (Windows). Claude Pro/Max/Teams/Enterprise 구독 또는 API 계정이 필요하다.