[AI 터미널 도구 5일차] Claude Code로 프로젝트 운영하기

Posted Mar 6, 2026 Updated Mar 7, 2026

By rkgh17

26 min read

도서명 : AI 자율학습 클로드 코드·코덱스 CLI·제미나이 CLI 완전 활용법

이 포스팅은 길벗 출판사의 코딩 자율학습단 20기 활동의 일환으로, 개인 공부 정리용 포스팅이다.

4장. Claude Code로 프로젝트 운영하기

4.1 - CLAUDE.md

CLAUDE.md는 프로젝트의 목적, 기술 스택, 폴더 구조, 코딩 규칙 등을 이해하는 데 사용하는 핵심 기준이다.

1. CLAUDE.md의 위치와 적용 범위

1. 전역 CLAUDE.md - 개인 기본 규칙

위치 : ~/.claude/CLAUDE.md

모든 프로젝트에 공통으로 적용할 개인 기본 규칙을 정리 (선호하는 언어 스타일, 테스트 도구, 기본 코드 포맷팅 규칙 등)

2. 프로젝트 루트 CLAUDE.md - 프로젝트 전체 규칙

위치 : ./my-project/CLAUDE.md

해당 프로젝트 전체에 공통으로 적용되는 규칙을 기록 (프로젝트 목적, 기술 스택, 폴더 구조, 팀 규칙 등)

3. 서브폴더 CLAUDE.md - 모듈별 세부 규칙

위치 : ./frontend/CLAUDE.md, ./backend/CLAUDE.md, ./apps/admin/CLAUDE.md 등

이 파일은 다음과 같은 경우에만 사용하는 것을 권장

모노레포처럼 서로 다른 앱/서비스가 한 저장소에 공존하는 경우
프론트엔드/백엔드 기술 스택과 규칙이 완전히 다른 경우
레거시 영역과 신규 영역을 분리해 규칙을 다르게 적용해야 하는 경우

2. CLAUDE.md와 일반 대화의 차이

구분	일반 대화	CLAUDE.md
지속성	세션 종료 시 초기화	파일을 수정하거나 삭제하기 전까지 유지
반영 범위	해당 세션에만 적용	해당 프로젝트의 모든 세션에 자동 적용
관리 방식	매번 대화로 요구 사항을 설명	파일을 직접 편집해 규칙을 일관되게 유지
컨텍스트 처리	대화가 길어지면 요약 또는 삭제되면서 누락될 수 있음	세션 시작 시 우선 로드되는 고정 지침으로 유지

단순히 규칙을 저장하는 파일을 넘어 Claude Code의 전체 작업 흐름을 안정적으로 만드는 핵심 역할을 수행함. Claude.md를 사용할 때 얻는 효과는 다음과 같다.

파일 생성, 수정 위치를 자동으로 판단함
일관된 스타일과 규칙을 모든 세션에서 유지
프로젝트가 커질수록 안정성이 높아짐
반복 지시가 거의 사라짐

/init 명령으로 기존 프로젝트를 분석하고, 그 결과를 기반으로 CLAUDE.md 초안을 자동 생성할 수 있다.

3. CLAUDE.md에 포함해야 할 주요 항목

1. 프로젝트 목적(필수) 프로젝트가 무엇을 하는지 1~2줄로 요약

## 프로젝트 목적
개발자를 위한 작업 흐름 자동화 도구

2. 기술 스택 Claude가 어떤 언어, 프레임워크, 인프라를 기준으로 작업해야 하는지 명확히 함

  
## 기술 스택
- Backend: FastAPI + PostgreSQL
- Frontend: Next.js 14 + TypeScript
- Infra: Docker + Docker Compose

3. 프로젝트 구조

backend/        # FastAPI 백엔드
|----app/       # 애플리케이션 코드
|----tests/     # 테스트 코드
frontend/       # Next.js 프런트엔드
|----src        # 소스 코드
docker-compose.yml

4. 핵심 규칙 및 금지 사항

프로젝트에서 반드시 지켜야 하는 규칙을 3~5개만 명확히 작성함. 규칙이 너무 많으면 컨텍스트 공간을 불필요하게 점유함.

  
## 규칙 및 금지
- 타입 힌트 필수(Python/TypeScript)
- 함수는 200줄 이하 유지
- any 타입 사용 금지 -> unknown 활용
- 하드코딩된 URL 금지 -> 환경 변수 사용

5. 개발 명령어(선택사항)

프로젝트 실행 및 테스트에 필요한 기본 명령어를 간단히 정리

## 명령어
docker-compose up   # 전체 서비스 실행
npm run dev         # 프런트엔드 개발 서버
uvicorn app:app     # 백엔드 개발 서버

필요하다면 다음 항목을 추가해도 됨

환경 변수 템플릿(.env 예시)
API 스펙 문서 경로
테스트 규칙

4. CLAUDE.md 작성 및 관리 원칙

CLAUDE.md는 프로젝트 구성의 중심이므로 작성 방식에 따라 Claude의 작업 품질이 크게 달라짐.

1. 중요 규칙은 강조

Claude는 ‘필수’, ‘중요’, ‘금지’ 등의 표현에 높은 가중치를 두고 판단함

**필수** : 모든 API 엔드포인트는 타입 힌트를 포함해야 함.
**금지** : console.log를 프로덕션 코드에 남기지 않는다.

2. 문자 길이는 100줄 이내로 유지

문서가 길수록 실제 작업을 위한 컨텍스트 공간이 줄어들기 때문에 100줄 이내를 권장함.
세부 내용은 coding-style.md, api-design.md 같은 별도 문서로 분리

3. 정기적으로 업데이트하기

기술 스택 변경, 규칙 추가/수정, 신규 파일 구조 도입 등 프로젝트 변화가 있을 때마다 업데이트 하는게 좋다.

4. 파일 참조는 최소화

CLAUDE.md의 분량이 길어지지 않도록 다음처럼 별도 파일을 만들어 참조하는 방식도 사용 가능 하지만 참조된 파일 전체가 컨텍스트에 함께 로드되므로 토큰 비용이 증가될 수 있음

  
## 상세 문서
- 코딩스타일 : @coding-style.md
- API 설계 : @api-design.md

4.2 - 계획 모드를 실제 작업 흐름에 적용하기

계획 모드는 이러한 설계 단계에서 코드 변경 없이 전체 구조와 영향 범위를 분석해 실수 없이 구현으로 이어질 수 있도록 돕는다.

1. 계획 모드를 사용해야 할 시점과 역할

다음 상황에서 사용하면 유리

영향 범위가 명확하지 않은 기능을 수정할 때 (인증, 결제, 라우팅처럼 여러 파일과 모듈이 연결된 기능)
변경이 여러 디렉터리에 걸쳐 있을 가능성이 있을 때
팀 내에서 구현 전략을 선제적으로 공유해야 할 때
레거시 코드 분석이 필요할 때

이때 계획 모드는 단순히 목록을 출력하는 수준이 아니라 Claude가 프로젝트를 깊이 파악해 설계 초안을 만들어주는 단계라고 볼 수 있음. 즉, 구현 단계로 바로 넘어가기 전에 리스크를 줄이고 방향성을 확정하는 설계 문서 역할을 함.

2. 계획 모드의 내부 작동 방식

> JWT 기반 인증 시스템 마이그레이션 계획을 세워줘.

위 상황에서 Claude는 다음과 같이 구조화된 계획을 제시한다.

1 - 기존 인증 흐름 파악
2 - 교체 시 영향을 받는 파일 목록 분석
3 - 마이그레이션 순서 제안
4 - 충돌 가능성 및 리스크 파악
5 - 필요 패키지, 폴더 구조 변화
6 - 설계 대안 비교 (JWT vs Session 기반 등)

이렇게 나온 결과물은 단순한 할 일 목록이 아니라 실제 설계 문서 수준의 정보를 담고 있다.

3. 계획 모드를 기본값으로 설정하기

복잡한 프로젝트나 팀 단위 개발에서는, 새로운 기능을 작업할 때마다 우선 계획을 세우고 변경범위를 파악하는 과정이 필요하다. 이 상황에서 매번 수동으로 계획 모드를 켜는 것은 번거롭고, 실수로 일반 모드에서 바로 구현을 시작해 예상치 못한 변경이 발생할 가능성도 있다.
이러한 위험을 줄이기 위해 Claude Code는 프로젝트별로 기본 모드를 계획 모드로 설정하는 기능을 settings.json파일을 통해 제공

.claude/settings.json

  
{
  "permissions":{
      "defaultMode": "plan"
  }
}

4. 계획 모드를 실전에서 활용하는 세 가지 전략

1. 대규모 작업은 반드시 계획부터 요청

아키텍처 변경, 폴더 구조 개편, 인증 로직 교체처럼 여러 파일이 얽힌 작업에서는 구현으로 바로 들어가기보다 먼저 전체 구조를 분석한 계획을 생성하는 것이 중요하다. 계획 모드를 사용하면 Claude가 먼저 전체 구조를 파악해 작업 항목을 정리함. 아래는 예시.

변경될 파일 목록
구현 순서
구조적 영향 범위
예상되는 충돌 가능성
필요한 리팩터링 작업

2. 계획을 반복 생성하면서 점진적으로 개선하기

계획 모드는 한 번에 완성되는 문서가 아니라 대화를 통해 발전시키는 설계 과정이다.

> 다크 모드 지원 가능을 추가하는 계획을 세워줘.
[계획 제시]
> 좋은데, 시스템 테마 자동 감지도 포함해줘.
[계획 보완]
> 라우터에 테마 상태를 반영하는 부분도 고려해줘.
[재계획]

이렇게 반복해서 계획을 다듬으면 기능 정의 -> 요구사항 정리 -> 설계 확정의 흐름이 자연스럽게 이어짐

3. 대화 없이 설계안만 빠르게 생성해 비교하기

Claude Code는 대화형 세션을 열지 않고도 요청한 설계안만 즉시 생성해 파일로 저장하는 명령형 모드를 지원한다.

  
# Redux 설계안
claude --permission-mode plan -p "Redux 기반 글로벌 상태 관리 구현 전략" > redux.md
# Zustand 설계안
claude --permission-mode plan -p "Zustand 기반 글로벌 상태 관리 구현 전략" > zustand.md
# 두 설계안 비교
diff redux.md zustand.md

4.3 - 컨텍스트 관리와 토큰 최적화

토큰의 기본 개념

AI모델은 텍스트를 그대로 처리하지 않고, 내부의 토크나이저 라는 변환 프로그램을 사용해 단어, 구두점, 기호, 공백 등을 잘게 나눈 최소 단위로 변환한다. 이 단위를 토큰 이라고 한다.

영어 : “Claude Code is an excellent tool.” - [ "Claude", "Code", "is", "an", "excellent", "tool", "."] - 약 6~7토큰
한글 : “Claude Code는 훌륭한 도구입니다.” - [ "Claude", "Code", "는", "훌륭", "한", "도구", "입니다", "."] - 조사, 형용사, 어미가 분리되어 약 8~10토큰

한글은 영어보다 토큰이 많이 적용되므로 짧고 명확한 문장일수록 토큰 효율이 좋아지고 모델이 컨텍스트를 더 정확히 파악할 수 있다.
토큰은 사용자의 요청 문장뿐 아니라 그 요청을 처리하는 데 필요한 대화 이력, CLAUDE.md, 도구 정의, 참조된 파일 내용까지 모두 보내기 때문에 컨텍스트를 과도하게 사용하는 상황을 예방할 수 있다.

토큰 사용량 확인 방법

1 - /context 명령
2 - 로그 파일에서 직접 확인
- ~/.claude/projects/ 폴더에 JSONL 형식으로 저장한다. 각 메시지의 usage 필드에 포함된 input_tokens, output_tokens 값을 확인할 수 있다.
3 - 웹 기반 토큰 계산기 사용
- 별도의 웹 도구를 이용해 텍스트를 직접 입력하고 토큰 수를 확인할 수도 있다.
- token-counter.app/anthropic : 웹 브라우저에서 직접 토큰 계산
- claude-tokenizer.vercel.app: Anthropic의 token counting API 기반 토큰 계산기

토큰 절약을 위한 실전 관리 전략

1. 오래된 대화 이력 비우기
- /clear 또는 새 세션 시작으로 불필요한 컨텍스트 제거
- 이전 대화의 맥락이 더 이상 필요하지 않다면 적극적으로 초기화
2. CLAUDE.md는 간결하게 유지
- 파일이 길어질수록 요청마다 로드되는 토큰 양 증가
- 핵심 규칙과 프로젝트 원칙만 유지
- 세부 지침은 별도 파일로 분리한 후 필요한 순간에만 @로 참조
3. 참조 파일 최소화
- 전체 파일을 통째로 보내지 말고 필요한 범위만 발췌해서 제공
- 특히 대규모 파일(수백~수천 줄)은 필요한 부분만 선택해서 전달
4. 불필요한 수정 요청을 줄이기 위한 계획 요청을 먼저 하기
- 바로 수정 요청을 하기보다 먼저 계획을 요청해 전체 변경 범위를 정리
- 계획을 기반으로 한 번에 수정 요청을 하면 여러 번의 왕복 수정으로 생기는 토큰 과다 소비를 줄일수 있음
5. 프롬프트 캐싱 활용
- 반복되는 요청은 Claude가 프롬프트 캐시를 재사용
- 동일한 설정, 지침, 환경 설명을 매번 토큰으로 다시 보내지 않아도 됨
- 캐시가 유지되는 동안 중복 토큰 소비를 크게 줄일 수 있음

프롬프트 캐싱으로 비용 절감하기

Claude Code는 Anthropic이 제공하는 프롬프트 캐싱 시스템을 내부적으로 활용해 반복되는 입력 토큰 비용을 최대 90% 까지 절감한다. 사용자가 따로 설정하지 않아도 자동으로 적용되는 기능.

1. 첫 번째 요청(초기 캐시 생성 단계)
- 시스템 프롬프트와 CLAUDE.md가 처음으로 모델에 전달되며 캐시에 저장됨
- 사용자 메시지는 그대로 처리되어 입력 토큰이 100% 비용으로 계산
2. 두번째 요청부터(캐시 활용 단계)
- 시스템 프롬프트와 CLAUDE.md는 새로 전송하지 않고 캐시를 읽어 재사용. 이 과정에서 두 파일의 입력 비용이 약 90%까지 절감됨
- 사용자 메시지는 캐싱 대상이 아니므로 매번 기본 토큰 비용이 발생함.

캐시의 기본 TTL(Time To Live)은 약 5분이며, 필요한 경우 최대 1시간까지 유지할 수 있다.

긴 대화를 유지하기 위한 컨텍스트 구조 이해하기

Claude가 동시에 유지할 수 있는 대화, 파일, 규칙, 도구 정의의 최대 범위가 컨텍스트 윈도우이다.

Claude Code 세션의 컨텍스트 구조 - /context 명령으로 컨텍스트 구조 분석

System prompt : Claude Code의 기본 동작 지침 (역할, 규칙, 환경 정보 등)
System tools : 사용 가능한 도구들의 스키마 정의 (Bash, Read, Edit, Grep 등의 함수 명세)
Skills : /commit 같은 슬래시 커맨드(스킬)의 프롬프트 내용
Messages : 실제 대화 내용 (유저 메시지 + Claude 응답)
Free space : 아직 사용하지 않은 컨텍스트 공간
Autocompact buffer : 텍스트가 꽉 찼을 때 자동 압축을 위해 예약된 버퍼 공간

컨텍스트 윈도우가 포화되면 다음과 같은 문제가 발생할 수 있다.

Claude가 이전 결정 사항을 잊거나 일관성을 잃음
응답 속도가 저하됨
출력이 중간에 끊기거나 오류 발생
새 파일 또는 긴 코드의 참조가 제한됨

위를 방지하기 위해 다음 두 가지를 습관화 하는 것이 좋다

1 - /context 명령으로 사용량을 주기적으로 점검하기
2 - 컨텍스트 사용량이 70%를 넘으면 /compact로 정리하기

안정적인 세션 유지를 위한 메모리 관리 전략

컨텍스트 윈도우를 압축하는 방법에는 자동, 수동이 있다.

자동 압축

다음은 자동 압축의 작동 방식이다.

1 - 트리거 : 컨텍스트 사용량이 95% 도달
2 - 분석 : 대화 중 유지해야 할 핵심 정보 식별
- 최근 결정 사항
- 코드 변경 이력
- 진행 중인 작업 단계
3 - 요약 : 오래된 대화 내용을 압축 요약문으로 변환
4 - 교체 : 기존 대화 일부를 요약본으로 대체
5 - 계속 : 확보된 공간으로 새로운 요청 처리 위 단계를 통해 세션이 중단 없이 유지되고 중요한 결정 사항이 보존되지만, 압축 시점은 예측하기 어렵고 일부 세부 대화가 요약되는 과정에서 사라질 수 있음.

수동 압축 - /compact

# 전체 대화 이력 수동 압축
> /compact

# 특정 내용만 압축
> /compact 코드 변경 사항만 요약, TODO 리스트는 그대로 유지

# 길이 제한 설정
> /compact 500단어 이내로 압축

# 특정 주제만 유지
> /compact 인증 시스템 관련 내용만 상세히 남기고 나머지는 간략히

압축 타이밍

다음 상황에 수동 압축을 실행하면 효과가 크다

기능 단위 개발이 끝난 시점
대규모 리팩터링을 완료한 직후
Git 커밋을 마친 뒤
‘프런트엔드에서 백엔드로’처럼 작업 영역을 전환할 때
/context로 확인한 결과, 사용량이 70% 이상일 때

토큰 사용 최적화 전략

1 - 큰 작업은 먼저 계획부터 요청해 접근 범위 정리
- 아키텍처 변경, 인증 로직 교체처럼 범위가 큰 작업은 곧바로 수정하지 말고 먼저 계획을 요청해 변경 파일, 순서, 리스크를 정리한다.
2 - /context로 사용량 점검하기
- /context 명령으로 현재 세션의 토큰 사용량을 확인한다.
3 - 복잡한 작업의 문서화와 /clear 사용하기
- 대규모 작업의 경우 진행 상황을 마크다운 파일로 저장하게 한 뒤 /clear로 컨텍스트를 초기화하고, 새 세션에서 해당 파일을 읽어 작업을 이어가는 방식이 효과적
4 - 프롬프트 캐싱으로 비용 절감하기 (자동)

Study

AI CLI 코딩 자율학습단 20기

This post is licensed under CC BY 4.0 by the author.