[Claude Code] CLAUDE.md 설정부터 에이전틱 개발 워크플로우까지

들어가며: Claude Code는 왜 다른가?

Claude Code는 단순히 질문에 답하는 챗봇이 아니라, 직접 파일을 읽고 명령어를 실행하며 코드를 수정하는 에이전틱(Agentic) 환경이다. 우리가 코드를 직접 쓰고 리뷰를 요청하는 것이 아니라, 우리가 원하는 바를 설명하면 Claude가 탐색하고 계획하여 구현하는 방식이다.

하지만 이 강력한 자율성에는 '컨텍스트 윈도우 관리'라는 핵심적인 제약 조건이 따른다. 공식 문서가 강조하는 최고의 성능을 내기 위한 전략들을 정리해 본다.

 

1. 환경 구성 및 설정 계층 (Configuration)

Claude Code는 설정의 적용 범위(Scope)를 엄격하게 관리한다. 이를 이해해야 개인용 설정과 팀 공용 설정을 분리할 수 있다.

📋 구성 범위(Configuration Scopes)

범위위치대상팀 공유 여부

Managed	시스템 수준	머신의 모든 사용자	IT 부서 배포용
User	~/.claude/	모든 프로젝트	개인 전용
Project	./.claude/	해당 저장소 협업자	Yes (Git 커밋)
Local	.claude/settings.local.json	현재 저장소의 나	No (GitIgnore)

 

2. 프로젝트의 메모리, CLAUDE.md & Rules

Claude는 세션 시작 시 항상 CLAUDE.md를 읽는다. 이는 코드로만은 알 수 없는 프로젝트의 맥락(비즈니스 로직, 관습, 금기 사항)을 전달하는 통로다.

💡 CLAUDE.md 작성의 Golden Rule

• 단순하게 유지하라: 너무 길어지면 중요한 규칙이 무시된다. "이 줄을 삭제했을 때 Claude가 실수할까?"를 자문해라.
• 이미 알고 있는 것은 빼라: 표준 언어 관습 등 Claude가 기본적으로 아는 내용은 생략한다.
• 추가 지침 임포트: @path/to/file 문법을 사용하여 외부 문서를 참조할 수 있다.

 

3. 에이전틱 개발의 핵심: EPIC 워크플로우

공식 문서와 숙련된 개발자들이 공통으로 제안하는 표준 워크플로우는 탐색(Explore) - 계획(Plan) - 구현(Implement) - 커밋(Commit)으로 이어지는 순환 구조다. 각 단계의 연결을 매끄럽게 관리하는 것이 생산성의 핵심이다.

1단계: 탐색 (Explore) - "코딩 전에 충분히 읽게 하라"

Claude가 바로 코드를 수정하게 두지 마라. Plan Mode를 활성화하여 현재 코드베이스의 구조와 의존성을 파악하는 것이 우선이다.

• 서브에이전트(Subagent) 위임: 많은 파일을 읽어야 할 경우 "서브에이전트를 써서 모듈 구조를 분석해줘"라고 지시하라. 메인 대화창의 컨텍스트를 깨끗하게 유지하면서 요약된 지식만 가져올 수 있다.
• 프롬프트 전략: "로그인 흐름을 담당하는 파일들을 나열하고 데이터 흐름을 설명해줘. 아직 수정하지 마."

 

2단계: 계획 수립 (Plan) - "확장 사고와 계획 편집"

충분한 정보가 모였다면 구체적인 구현 계획 작성을 요청한다. 이때 Claude에게 '더 깊게 생각할 시간'을 주는 것이 중요하다.

• 사고 예산 키워드: 프롬프트에 다음 단어를 포함하여 추론 수준을 강제할 수 있다.
  • think: 기본적인 분석
  • think hard / ultrathink: 복잡한 로직 및 엣지 케이스 검토 (더 많은 토큰 할당)
• 계획서 편집 (Ctrl + G): Claude가 계획을 세우면 Ctrl+G를 눌러 에디터에서 직접 계획을 검토하고 수정하라. 사람이 승인한 계획 위에서 코딩할 때 실패율이 가장 낮다.

 

3단계: 구현 (Implement) - "검증 가능한 코드 생산"

구현 단계에서 가장 중요한 것은 'AI가 스스로 자신의 결과물을 체크할 수 있는 기준'을 주는 것이다.

검증 전략	비포 (Before)	애프터 (After)
테스트 기반	"함수 짜줘"	"함수 짜고 npm test 돌려서 성공하면 보고해"
시각적 기반	"UI 예쁘게 해줘"	"스크린샷 찍어서 원본 디자인 이미지랑 대조해봐"
근본 해결	"빌드 에러 고쳐"	"에러 로그 분석해서 근본 원인을 고치고 빌드 확인해"

• 검증 기준 포함: 단위 테스트 케이스, 예상 출력값, 혹은 linter 실행 명령을 프롬프트에 명시하라.
• UI 구현의 경우: Claude in Chrome 확장을 사용하거나 Puppeteer 도구를 연결하여 Claude가 직접 화면을 보게 하라.
• 프롬프트 예시: "로그인 핸들러를 구현해줘. 구현 후 반드시 npm test를 실행해서 성공 여부를 확인하고, 에러가 있다면 스스로 수정해."
• 체크포인트(Checkpoints) 활용: 구현 중에 방향이 틀어지면 Esc를 두 번 누르거나 /rewind를 입력하여 이전 상태로 완벽하게 되돌릴 수 있다.

4단계: 커밋 & PR (Finalize) - "이력 관리와 문서화"

작업이 완료되면 /commit 명령어를 통해 작업 내용을 요약하고 PR을 생성한다. 이 시점에 README.md나 CHANGELOG.md의 업데이트도 함께 요청하는 것이 좋다.

• PR 및 문서화: "방금 작업한 내용으로 커밋하고, 수정 사항을 README.md에 반영해줘."
• 세션 정리: 작업이 완료되면 반드시 /clear를 실행해 다음 작업을 위한 깨끗한 컨텍스트를 확보한다.

 

4. 컨텍스트 및 토큰 관리 전략

컨텍스트가 꽉 차면 성능이 저하되고 이전 지시를 잊는다. 이를 공격적으로 관리해야 한다.

1. /clear를 습관화하라: 작업 단위가 바뀌면 무조건 비워라.
2. /btw 활용: 작업 흐름과 상관없는 짧은 질문은 /btw를 쓰면 대화 기록에 남지 않아 컨텍스트를 아낄 수 있다.
3. 서브에이전트(Subagents) 위임: - "서브에이전트를 써서 인증 시스템 전체를 조사해줘"라고 하면 메인 대화창은 깨끗하게 유지하면서 요약본만 받을 수 있다.
4. /compact: 대화가 길어지면 /compact를 통해 중요한 코드 결정사항만 요약하고 나머지는 압축한다.

 

5. 확장 기능: MCP, Hooks, Skills

Claude Code를 단순한 CLI를 넘어선 '팀의 동료'로 만드는 기능들이다.

• MCP 서버: Notion, Figma, Database 등을 연결한다. claude mcp add로 쉽게 추가 가능하다.
• Hooks: 특정 동작(예: 파일 수정) 직후에 자동으로 실행될 스크립트를 정의한다. "파일 수정 후 항상 linter 실행" 같은 작업에 제격이다.
• Skills: 반복되는 워크플로우를 /skill-name 형태로 저장해둔다. .claude/skills/에 마크다운 파일로 정의할 수 있다.

 

⚠️ 피해야 할 안티 패턴 (Failure Patterns)

• 부엌데기 세션(Kitchen Sink): 한 세션에서 이것저것 다 물어보는 것.
• 반복되는 수정: 두 번 이상 고쳐줘도 안 된다면 세션을 /clear하고 프롬프트를 더 구체적으로 써서 다시 시작해라.
• 신뢰-검증의 격차: Claude의 코드에 "테스트"를 붙이지 않는 것. 검증할 수 없다면 배포하지 마라.

 

6. AI 개발 직관 기르기

Claude Code의 패턴은 고정된 것이 아니다. 때로는 컨텍스트를 길게 유지하는 것이 복잡한 문제 해결에 유리할 때도 있다. 중요한 것은 Claude가 내놓는 결과물을 관찰하며 "언제 구체적으로 지시해야 할지"와 "언제 AI에게 맡겨야 할지" 사이의 직관을 기르는 것이다.