'클로드 코드 제대로 쓰는 법 | 5가지 필수 설정' 정리

클로드 코드 제대로 쓰는 법 | 5가지 필수 설정
출처: https://brunch.co.kr/@wikibook/140

---

1. CLAUDE.md
CLAUDE.md는 프로젝트 구조, 사용하는 기술, 코딩 규칙 등을 알리는 프로젝트 설계서이다. 클로드 코드는 이를 지속적으로 참고하여 프로젝트의 맥락을 빠르게 파악한다.
대화 모드에서 /init 명령을 입력해 현 프로젝트에 맞는 CLAUDE.md 파일을 생성할 수 있다.

프로젝트 규모가 커지면, CLAUDE.md를 계층적으로 배치하는 게 효과적이다.
프로젝트 루트에는 전체 프로젝트의 공통 규칙을, 각 하위 디렉터리에는 해당 영역에 특화된 규칙을 작성하는 방식이다.
어디에 어떤 정의가 들어있는지 시각적으로도 쉽게 파악할 수 있고 효율적으로 관리할 수 있다.

CLAUDE.md 안에 파일을 참조할 때에는 @docs/SPECIFICATION.md처럼 작성하면 된다.
상세설계서 --> @docs/SPECIFICATION.md
UI/UX --> @docs/SCREEN_DESIGN.md
API 명세서 --> @docs/API_SCHEME.md
테스트 명세서 --> @docs/TEST_DEFINITION.md
DB 스키마 --> @schema/DB.md

프로젝트에서 사용하는 기술에 대한 정보도 CLAUDE.md에 함께 기록하면 실수를 줄일 수 있다.

모든 요구사항 정의를 CLAUDE.md에 넣으면 편할 순 있다.
하지만 CLAUDE.md는 상호작용마다 참조하기 때문에, 불필요한 세부 정보를 너무 많이 포함하면 작업 효율과 정확도가 떨어진다.

2. 권한 설정
클로드 코드는 셀 명령을 실행하려고 할 때, 이번 한 번만 실행을 허가할지, 앞으로도 실행을 허용할지 선택할 수 있게 한다.
앞으로도 실행을 허용하는 경우, .claude 디렉터리의 settings.local.json 설정 파일에 허용 규칙 추가를 통해 관리된다.
이는 클로드 코드 설치 시 전역 .gitignore에 자동 기재되어 Git으로 관리되지 않는다.

해당 파일을 직접 수정해 특정 명령의 실행을 허용할 수도 있다.
/permissions 명령어를 통해 CLI에서 권한을 추가할 수도 있다.

권한 규칙은 인수를 받는 함수 형태로 구성되며, 와일드카드를 사용해 다양한 설정 규칙을 지정할 수 있다.
규칙에는 Allow(허용. 디렉터리 자유롭게 읽고 수정), Ask(확인. 디렉터리 수정 시 허락 구함), Deny(거부. 디렉터리 접근 차단)가 있다.
"Bash(*)" --> 모든 bash 명령
"Bash(npm run:*)" --> "npm run"으로 시작하는 모든 명령
"Bash(npm install)" --> 특정 명령(npm install)만
"Read(./.env.*)" --> 환경 변수 파일 접근
"Edit(./config.json)" --> 설정 파일 수정

클로드 코드에서는 Bash(셸 명령어 실행), Edit(파일 편집) 등의 도구를 사용할 수 있다.
이때 크게 권한이 필요한 도구와 필요하지 않은 도구로 나눌 수 있다.
Bash(셸 명령어 실행), Edit(파일 편집), WebFetch(URL 콘텐츠 가져오기) 등은 권한이 필요하고,
Glob(파일 검색), Task(하위 에이전트 실행), TodoWrite(작업 리스트 관리) 등은 권한 없이 사용할 수 있다.

클로드 코드에는 여러 권한 모드가 있다.
default --> 읽기만 자동 허용. 수정이나 명령어 실행 시 매번 허락 구함
acceptEdits --> 읽기, 수정, 일반 명령어 자동 허용. 위험한 bash 명령어는 허락 구함
plan --> 읽기 전용 분석 모드. 수정이나 명령어 실행 없이 계획과 탐색만 수행
auto --> 안전 검사 거쳐, 파괴적 행동 이외의 작업은 자동 허용
dontAsk --> 사전에 승인된 규칙에 포함된 도구만 허용. 나머지는 차단
bypassPermission --> 모두 허용

3. 컨텍스트 관리
클로드 코드에는 한번에 처리할 수 있는 정보의 총량인 컨텍스트 윈도 개념이 있다.
최대 20만 토큰만큼 보유하도록 설계되었다.
프롬프트, 응답, 읽은 파일 내용, 명령 실행 결과 등 모든 정보가 카운트되기에, 프로젝트 규모가 클수록 빠르게 한계에 도달한다.

/context 명령어를 통해 컨텍스트 윈도 크기 및 점유율을 확인할 수 있다.
이 중 Memory files는 CLAUDE.md의 점유율을 보여준다.

/clear 명령어를 통해 직접 컨텍스트를 초기화할 수 있다.
앞으로 지시할 내용에 지금까지의 대화 문맥이 불필요한 경우, /clear를 실행하여 명확한 컨텍스트 상태에서 새 지시를 내리고, 컨텍스트를 절약할 수 있다.

/compact 명령어를 통해 직접 컨텍스트를 압축시킬 수 있다.
기본적인 대화 흐름은 기억하지만, 내용이 간소화된다.
'/compact API 명세에 초점을 맞춰주세요'처럼, 특정 내용에 초점을 맞춰 필요한 정보만 컨텍스트로 유지할 수 있다.
압축 시 항상 특정 내용에 초점을 맞추고 싶다면, CLAUDE.md에 'Summary instructions' 섹션을 작성하면 된다.

4. 확장 사고 모드
복잡한 문제에 대해 더 깊은 분석과 사고를 수행할 수 있는 모드이다.
일반 응답보다 더 많은 시간을 들여 문제를 다각적으로 검토하고, 더 높은 정확도의 답변을 제공한다.
이때 토큰 수도 더 많이 소비한다.

사용하는 토큰 수에 따라 3단계로 나뉜다.
적은 예산 --> 생각해
중간 예산 --> 깊게 생각해
최대 예산 --> 철저히 생각해

쉽게 해결되지 않는 문제를 마주했거나 코드 전반에 걸쳐 관련된 부분을 폭넓게 생각하고 싶을 때 사용하면 된다.

+대화 모드에서 Tab 키를 누르면 항상 사고 확장 모드가 된다
편리하지만, 토큰을 많이 소비하므로 주의가 필요하다

5. 가드레일
클로드 코드는 세션별 상태를 유지하지 않기에, 때로 앞뒤 문맥을 충분히 이해하지 못하고 제멋대로 코드를 작성할 수 있다.
따라서 방향성이 흔들리지 않도록 사용자가 사전에 지켜야 할 명세나 규약(가드레일)을 견고하게 정의해야 한다.

컴파일 체크 --> 타입 체크, 참조 오류, 문법 오류 체크를 통해 AI 코드의 폭주를 억제할 수 있다
테스트 --> 테스트 파일을 작성하고 테스트를 실행해 특정 함수나 프로그램의 정상 작동을 확인하고 보장할 수 있다.
린트 검사 --> 명명 규칙 및 코딩 스타일을 통일하고, 정해진 규칙을 준수하지 않는 경우 경고를 출력한다.
허스키(Husky)로 코드 보호 --> Node.js에서는 허스키를 설치하면 커밋이나 푸시 전에 포매터나 린터를 실행하거나 테스트를 실행할 수 있다.

6. 경제적으로 이용하는 핵심 방법
/cost 명령어를 사용해 현 세션에서 사용 중인 비용을 수시로 확인
작업 주제가 바뀌거나 불필요한 대화가 쌓이면 /clear 명령어로 컨텍스트 정리
컨텍스트가 70~80% 정도 찼을 때 수동으로 미리 정리
단순한 반복 작업이나 가벼운 수정은 더 저렴하고 빠른 하이쿠 등 경량 모델 선택
모호한 프롬프트는 불필요한 재답변과 토큰 소모를 유발하므로, 처음부터 원하는 작업 범위를 명확하게 지시
분석이 필요 없는 대용량 로그 파일이나 빌드 폴더는 클로드 코드가 읽지 않도록 설정

요금제는 사용량을 봐서 API/Pro/Max 결정. 시작은 Pro.