Claude Code 사용기

1. Overview

Claude Code는 Anthropic이 만든 터미널/IDE 기반 AI 코딩 에이전트다.

파일을 직접 읽고 쓰고, 셸 명령을 실행하고, 여러 단계에 걸친 작업을 스스로 계획해서 처리하는 것이 특징이다.

사용 환경

• 플랜: Pro
• 에디터: VS Code
• 작업: Flutter 앱 개발

2. 설치

CLI로 직접 설치하는 방법도 있지만, VS Code를 주력으로 쓴다면 익스텐션 설치만으로 충분하다.

• VS Code Extensions 탭에서 "Claude Code" 검색 후 설치

3. 간략 사용 방법

기본은 프롬프트로 대화하며 작업을 시키는 것이지만, 실제로 생산성을 크게 좌우하는 것은 CLAUDE.md 설정과 아래에 정리한 명령어/모드 활용이다.

3.1 프로젝트 초기화

• 프로젝트 루트에서 Claude Code를 처음 실행하면 프로젝트 구조를 스캔하고 이해한다.
• /init 명령으로 프로젝트 정보를 담은 CLAUDE.md를 자동 생성할 수 있다.

3.2 단축키

• Shift+Tab: 모드 전환 (기본 → 자동 수정 모드 → 플랜 모드 순환)

3.3 모델 및 사용량 관리

공통 특징

• 하이브리드 추론 모드: 즉각적인 응답(near-instant responses)과 확장된 사고(extended thinking)를 상황에 맞게 전환
• 병렬 도구 사용: 웹 검색, 외부 API 호출 등을 동시에 처리
• 향상된 지시 따르기와 메모리: 복잡하고 다단계인 명령을 더 정확히 처리하고, 시간이 지나며 핵심 정보를 기억해 암묵적 지식을 쌓음
• 200K 토큰 컨텍스트 창: 긴 보고서, 복잡한 코드베이스, 장시간 대화를 한 번에 처리

모델별 특성

모델	성격	적합한 용도
Opus	프론티어 전문가 모델	계획 수립, 고급 추론, R&D, 에이전트 워크플로우
Sonnet	고성능 실무형 모델	코드 작성, 테스트 코드, 리팩토링, 고객 대면 에이전트, 대용량 처리

/model로 모델을 전환할 수 있고, 기본값은 Opus이며 사용량이 일정 비율(약 20%)을 넘으면 자동으로 Sonnet으로 전환된다. 어떤 모델이 쓰이고 있는지 주기적으로 확인하는 습관을 들이는 것이 좋다.

3.4 주요 명령어

명령어	설명
/model	모델 전환
/compact	대화가 길어졌을 때 컨텍스트 요약. 200K 컨텍스트를 초과하면 더 이상 입력이 불가능해지므로, 그 전에 대화 내용을 요약해 유지시켜준다. 작업 전환 시마다 직접 실행하는 것을 권장하며, 대화 도중 갑자기 자동 요약이 발생하면 문제 신호일 수 있다.
/config	테마 등 설정 변경. 권장 설정: auto-compact true, user todo list true, verbose output false, notifications terminal bell
/permissions	자동 실행 권한 설정. 프로젝트 단위는 .claude/settings.local.json, 사용자 단위는 ~/.claude/settings.json에 저장되며, allow / deny / auto-accept edits 옵션이 있다. 예: 특정 디렉토리의 파일 목록 조회를 항상 허용하려면 /permissions → add a new rule → Bash(ls:*) → project settings(local)
/memory	메모리 관리. 프로젝트 메모리는 ./CLAUDE.md, 사용자 메모리는 ~/.claude/CLAUDE.md
/mcp	MCP 서버 관리 및 관련 명령 실행
/bug	Anthropic에 버그 리포트
/clear	대화 히스토리 삭제
/cost	토큰 사용 통계 조회
/doctor	설치 상태 확인
/help	사용 설명서 확인
/login, /logout	계정 로그인/로그아웃, 계정 전환
/pt_comments	풀 리퀘스트 코멘트 조회 (GitHub CLI 연동 필요)
/review	풀 리퀘스트 리뷰 (GitHub CLI 연동 필요)
/status	계정 및 시스템 상태 확인

3.5 CLAUDE.md

프로젝트 루트에 두는 맞춤 지침 파일이다. 최적화된 md 파일은 토큰 사용도 줄이고 응답 품질도 높인다.

권장 작성 내용

• 자주 사용하는 bash 명령
• 핵심 파일, 유틸리티 함수
• 코드 스타일 가이드라인
• 테스트 지침
• 저장소 에티켓 (브랜치 이름 규칙, 병합, 리베이스)
• 개발자 환경 설정
• 프로젝트 특유의 예상치 못한 동작이나 주의사항
• Claude가 기억해야 할 기타 정보
• 공통으로 사용하는 라이브러리/아키텍처 정보

종류

종류	위치	공유 범위	담기는 내용
프로젝트 메모리	./CLAUDE.md	팀 전체	프로젝트 구조, 핵심 구성요소 개요, 코딩 표준
로컬 프로젝트 메모리	./CLAUDE.local.md	개인 (git 미포함)	샌드박스 URL, 개인 API 키, 테스트 데이터, 개인용 커스텀 명령
사용자 메모리	~/.claude/CLAUDE.md	모든 프로젝트 공통	일반 코드 스타일 선호, 개인 도구 단축키

노하우

• #: 대화 중 즉석에서 CLAUDE.md에 내용 추가
• important, you must 같은 강조 표현 사용. /compact 요약 과정에서도 살아남을 가능성이 높아진다.
• CLAUDE.md를 주기적으로 Claude에게 맡겨 갱신: "지금까지의 대화를 기반으로 CLAUDE.md에 추가할 만한 내용을 추천해줘"
• 파일이 비대해지면 정리도 위임: "CLAUDE.md 파일이 너무 커지고 있는 것 같아. 프로젝트를 전반적으로 다시 이해하고, 불필요한 내용은 삭제하고 과도한 내용은 축소하고 싶어. 수정안을 추천해줘"

3.6 실행 모드

기본 모드 (Default)

작업 하나하나를 직접 확인하고 싶을 때 사용한다.

• 새 라이브러리/프레임워크 기본 사용법을 익힐 때
• 특정 로직 구현을 위한 여러 알고리즘 아이디어를 얻고 싶을 때
• 오류 메시지의 의미를 정확히 이해하고 싶을 때
• 코드 리뷰 전 제3자 의견을 구하고 싶을 때
• 아직 Claude Code를 완전히 신뢰하지 못해 하나씩 컨트롤하고 싶을 때

자동 수정 모드

사용자 승인 없이 코드를 직접 수정한다. 반복 작업에 유용하다. Shift+Tab으로 전환.

• 프로젝트 전반의 변수명/함수명/클래스명 일괄 변경
• 기존 코드를 최신 패턴/스타일 가이드에 맞춰 리팩토링
• JSDoc 등 문서 작업
• 단순 반복 작업
• 테스트 코드 작성
• 깊은 컨텍스트가 필요 없거나, 요구사항이 이미 명확히 정리된 경우

플래닝 모드

가장 강력한 기능. 설계도를 그리듯 소프트웨어 구조와 개발 계획을 수립하는 단계에서 사용한다. Shift+Tab으로 전환.

• 예: "새로운 인증 기능을 만드려고 하는데, 어떤 기술 스택을 사용하고 파일 구조는 어떻게 가져가야 할까?"처럼 개방적이고 전략적인 질문에 적합
• 막연히 구현해야 할 기능이 있을 때 추천

주의: 제시된 계획에 무조건 승인하지 말 것. 첫 번째 제안은 일단 거절하고 "No, keep planning"으로 더 다듬게 하는 편이 낫다. 조금이라도 부정확하거나 잘못된 부분이 있으면 반드시 거절한다.

3.7 고급 기능 (CoT, 확장된 사고)

Chain of Thought (CoT)

최종 답변 전에 사고 과정을 명시적으로 기술하도록 유도하는 프롬프팅. 사고와 답변을 태그로 분리할 수 있다.

예: "REST API를 어떻게 설계할지 단계별로 생각하고 답변해줘" 대신, "REST API를 구축하려면 어떻게 해야 할지 생각 과정을 <thinking> 태그에 입력하고, 그 내용을 분석해서 <answer> 태그에 답변해줘"처럼 요청한다.

확장된 사고 (Extended Thinking)

CoT의 발전된 형태. "고민해라"라고 프롬프팅하면 더 많은 사고 후 답변한다. 강도가 강할수록 사고 예산(thinking budget)이 늘어난다.

• Think
• Think Hard
• Think Harder
• Ultrathink

3.8 커스텀 슬래시 커맨드

형식: /<prefix>:<command-name> [arguments]

• prefix: 커스텀 커맨드의 스코프
• command-name: 커맨드가 정의된 마크다운 파일 이름 (확장자 .md)
• arguments: 커맨드에 전달할 선택적 매개변수

종류

• 프로젝트 커맨드: .claude/commands/
• 사용자 커맨드: ~/.claude/commands/

사용 예시

• ~/.claude/commands/refactor-code.md → /refactor-code

네임스페이스

• ~/.claude/commands/code/refactor.md, ~/.claude/commands/code/analyze.md처럼 하위 폴더로 구성하면 /code:refactor, /code:analyze 형태로 사용한다.

파일(.md) 정의 규칙

Claude는 마크다운 문법과 문맥을 이해한다.

• #: 제목
• -: 리스트
• !: bash 커맨드 명시
• @: 파일 참조

3.9 MCP 연동

MCP(Model Context Protocol)는 외부 API, 데이터베이스, 애플리케이션과 상호작용할 수 있게 해주는 프로토콜이다. 예를 들어 GitHub 이슈 생성 같은 작업을 MCP를 통해 수행할 수 있다.

연결 방식 3종

방식	설명	등록 명령 예시
stdio	Claude Code가 사용자 컴퓨터에서 직접 로컬 프로세스를 실행하고 그 프로세스와 통신	claude mcp add context7 -- npx -y @upstash/context7-mcp
SSE (Server-Sent Event)	한 번 연결을 맺으면 서버가 필요할 때마다 클라이언트로 업데이트를 푸시	claude mcp add --transport sse context7 https://mcp.context7.com/sse
HTTP	클라이언트 요청에 서버가 응답하는 방식. MCP에서는 보통 스트리밍을 지원하는 HTTP 서버를 의미	claude mcp add --transport http context7 https://mcp.context7.com/sse

연동 확인: claude mcp list

3.10 기획부터 개발까지 (PRD, 실행계획)

PRD (Product Requirement Document)

"무엇을 만들 것인가"를 정의하는 문서. 기획/디자인/마케팅/개발 등 관련자 전원이 같은 그림을 보게 하는 핵심 커뮤니케이션 도구다.

기본 질문:

• 어떤 사용자를 위해 만드는가
• 어떤 문제를 해결해주는가
• 비즈니스 측면에서 어떤 이득이 있는가
• 어떤 기능과 경험을 제공해야 하는가
• 사용자는 어떤 경험을 하게 되는가
• 우리는 무엇을, 왜 만드는가

작성 항목:

1. 문제 정의 — 해결하려는 유저/비즈니스 문제를 명확하고 간결하게 서술 (예: "현재 사용자가 X 문제를 겪고 있어 이탈률이 Y%에 달한다")
2. 타겟 사용자 및 사용 사례 — 핵심 사용자가 누구이고, 어떤 상황에서 어떻게 사용하는지 정의
3. 제안 해결책 — 어떤 해결책을 제시할지 짧게 서술
4. 목표 및 성공 지표 — 기능 나열이 아니라 지표로 표현 (예: "로그인 기능 추가"가 아니라 "재방문률 15% 상승")
5. 경쟁사 분석 — 다른 서비스가 동일 문제를 어떻게 해결하는지 정리
6. MVP 요구사항

주의: PRD를 작성시키는 에이전트에는 다른 업무를 함께 시키지 말고, PRD 작업만 전담시키는 편이 결과물 품질이 좋다.

실행계획

PRD를 구현하기 위한 계획 문서. 아키텍처, API 명세, 데이터 스키마 등 구현 방법을 정의한다. 컨텍스트 크기 한계는 큰 문제를 작고 명확하고 해결 가능한 문제로 쪼개는 방식으로 대응한다.

기본 질문:

• 어떤 기술 스택을 사용할 것인가
• 아키텍처를 어떻게 구성할 것인가
• 데이터를 어떤 모델로 저장할 것인가
• 어떤 함수와 클래스를 작성할 것인가
• 어떤 작업을 먼저 수행할 것인가

작성 절차:

1. 작업 분해 — PRD의 사용자 스토리 하나를 가져와 구현에 필요한 모든 기술 작업을 나열 (예: 소셜 로그인 스토리 → 프론트엔드 UI 버튼, 백엔드 OAuth 콜백 API, User 테이블 소셜 ID 컬럼 추가)
2. 기술 명세 — 각 태스크의 구체적 기술 결정 (API request/response 형태, 라이브러리, 에러 처리)
3. 의존성 파악 — 선후 관계 정의 (예: 백엔드 API가 나와야 프론트엔드 연동 테스트 가능)
4. 산출물 및 일정 — 각 태스크 소요 시간 예측, 완료 기한, 스프린트 계획

PRD와의 차이는 정확한 기술 스택과 단계별(step-by-step) 태스크가 명시된다는 점이며, PRD 하나에 실행계획이 반드시 하나만 대응해야 하는 것은 아니다.

3.11 서브 에이전트

메인 에이전트가 작업 처리를 위해 또 다른 에이전트(서브 에이전트)를 생성해 진행시키는 방식이다. 메인은 이전 대화 히스토리를 알고 있는 반면, 서브 에이전트는 전달받은 단순 명령만 수행한다. 서브 에이전트에 내릴 지시도 결국 프롬프트로 작성해야 한다.

에이전트별로 별도의 컨텍스트 용량이 생기기 때문에 효율적이며, 병렬 처리가 필요할 때 특히 유용하다. "서브에이전트를 만들어서 작업해줘" 처럼 직접 요청하면 된다.

커스텀 서브 에이전트

기본적으로는 세팅값이 없는 상태로 시작하지만, 미리 정의해두면 특정 작업 시 최적화된 서브 에이전트가 자동으로 실행된다.

생성 방법: /agent 명령 또는 마크다운 파일을 직접 생성한다. 에이전트 이름을 입력하면 .md 파일이 생성되며, 아래 필드를 정의한다.

• name
• description
• color 등

---

4. 알아 두면 좋을 팁

원래 정리한 노트에서 다루지 않은 부분 중 실무에서 자주 쓰는 내용을 추가한다.

• /rewind (체크포인트 되돌리기):
  Claude Code의 자동 체크포인트 되돌리기.
  원치 않는 방향으로 변경이 진행됐을 때, 대화나 파일 상태를 이전 시점으로 되돌릴 수 있다.
• Hooks:
  특정 이벤트(도구 실행 전/후, 세션 시작 등)에 셸 명령을 자동 실행하는 기능.
  .claude/settings.json에 등록한다.
  lint 자동 실행, 커밋 전 포맷 검사, 특정 명령 차단/치환(이 프로젝트에서 쓰는 rtk 프록시가 대표 사례) 등에 활용 가능하다.
• .claude/settings.json vs settings.local.json:
  팀과 공유할 설정은 settings.json(git 포함),
  개인 로컬 설정은 settings.local.json(git 미포함)으로 나눠 관리하는 것이 안전하다.
  권한 설정도 이 두 파일에 나눠 저장된다.
• @ 파일 참조를 프롬프트에서 직접 사용:
  커스텀 커맨드뿐 아니라 일반 대화에서도 @path/to/file로 특정 파일을 명시적으로 컨텍스트에 포함시킬 수 있다.
  파일 탐색을 Claude에게 맡기지 않고 직접 지정하면 토큰 소모를 줄이고 정확도를 높일 수 있다.
• 플랜 모드에서 승인 시점 활용:
  플랜을 승인하면 그 시점부터 실제 파일 수정이 시작된다. 계획 단계에서 충분히 질문하고 대안을 요구하는 것이, 수정 이후 되돌리는 것보다 항상 비용이 적게 든다.
• 컨텍스트가 길어졌을 때는 새 세션이 답일 때도 있음:
  /compact로 요약해도 대화 주제가 완전히 바뀌었다면, 요약된 과거 맥락이 오히려 새 작업에 노이즈가 될 수 있다.
  이럴 때는 /clear로 새로 시작하고 필요한 맥락만 CLAUDE.md나 @파일 참조로 다시 넣는 편이 낫다.
• 서브 에이전트 결과는 요약본이라는 점 유의:
  서브 에이전트의 최종 보고만 메인 대화에 반영되고 중간 과정은 보이지 않는다. 중요한 코드 변경은 반드시 diff나 파일 내용을 직접 확인하는 습관이 필요하다.

5. 실제 사용 방법 (내가 일하는 순서)

기능 하나를 붙일 때, 보통 아래 순서를 반복한다.

1. Plan 파일 작성
   플랜 모드로 진입해 작업 계획을 파일로 먼저 뽑는다. 머릿속에만 있는 계획은 대화가 길어지면 흐트러지기 쉬워서, 파일로 고정해둔다.

2. 질의응답으로 완성도 높이기
   나온 계획을 바로 승인하지 않는다. 애매한 부분, 빠진 예외 케이스를 질문으로 던지고 답을 받으며 계획을 다듬는다. 제일 중요한 단계!

3. Todo 리스트 작성
   계획이 다듬어지면 실행 가능한 단위로 쪼갠 todo list를 만든다. 순서와 의존 관계가 명확해진 상태에서 다음 단계로 넘어간다.

4. 코드 수정 요청
   todo 항목 단위로 실제 코드 변경을 요청한다.

5. 코드 및 동작 확인
   변경된 코드와 실제 동작을 직접 확인한다. 자동 수정 모드라도 결과 검증은 반드시 사람이 한다.

6. 완료 후 spec 문서 작성, plan 파일 삭제
   작업이 끝나면 plan 파일은 지우고, 결정 사항과 구조를 spec 문서로 남긴다.

아직 정리 안 된 고민

spec 문서로 남기는 게 맞는지, 아니면 관련 폴더마다 CLAUDE.md를 만들어 지식을 분산시키는 게 맞는지는 아직 확신이 없다. 지금은 Codex, Claude 등 여러 에이전트가 섞인 환경을 염두에 두고 있어서, 특정 도구 종속적인 CLAUDE.md보다는 에이전트 무관하게 읽히는 spec 문서 쪽으로 하고 있다. 다만 이 판단이 맞는지는 계속 검증 중이다.

• 서브 에이전트 결과는 요약본이라는 점 유의: 서브 에이전트의 최종 보고만 메인 대화에 반영되고 중간 과정은 보이지 않는다. 중요한 코드 변경은 반드시 diff나 파일 내용을 직접 확인하는 습관을 들이자!