클로드 코드 제대로 쓰는 법 | 5가지 필수 설정
클로드 코드를 설치하고 첫 프롬프트를 입력했는데, 기대만큼 결과가 나오지 않은 경험이 있으신가요? 파일을 수정할 때마다 일일이 허락을 눌러야 하고, 대화가 길어지면 앞서 합의한 내용을 잊어버리고, 복잡한 버그 앞에서는 피상적인 답변만 돌아오는 상황 말입니다. 이런 문제의 상당수는 클로드 코드 자체의 한계가 아니라, 초기 설정을 제대로 하지 않아서 발생합니다.
클로드 코드는 설정 하나하나가 AI의 작업 품질에 직접적인 영향을 미치는 도구입니다. CLAUDE.md에 프로젝트의 기술 스택과 규칙을 명시하면 AI가 일관된 코드를 생성하고, 권한 모드를 적절히 설정하면 반복적인 승인 절차 없이 효율적으로 작업할 수 있으며, 컨텍스트 관리 전략을 세우면 대규모 프로젝트에서도 AI가 맥락을 잃지 않습니다.
이 글에서는 클로드 코드를 본격적으로 활용하기 전에 반드시 알아둬야 할 5가지 필수 설정을 단계별로 살펴봅니다. CLAUDE.md 작성법부터 권한 설정, 컨텍스트 관리, 확장 사고 모드, 그리고 가드레일까지, 각 설정이 왜 필요한지와 어떻게 적용하는지를 도서의 실전 예제와 함께 안내하겠습니다.
1. CLAUDE.md --- 프로젝트의 설계도를 AI에게 전달하라
클로드 코드를 시작할 때 가장 먼저 해야 할 일은 CLAUDE.md 파일을 작성하는 것입니다. CLAUDE.md는 프로젝트의 구조, 사용하는 기술, 코딩 규칙 등을 클로드 코드에게 알려주는 일종의 '프로젝트 설계서'입니다. 이 파일이 없으면 클로드 코드는 매번 프로젝트의 맥락을 파악하느라 컨텍스트를 낭비하게 됩니다.
CLAUDE.md 생성하기
클로드 코드의 대화 모드에서 /init 명령을 입력하면 현재 프로젝트에 맞는 CLAUDE.md 파일이 자동으로 생성됩니다. 클로드 코드가 프로젝트의 파일 구조를 분석하고, 사용 중인 언어와 프레임워크를 감지해서 초기 내용을 채워 줍니다. 물론 이 자동 생성된 내용을 기반으로 프로젝트에 맞게 수정하고 보완하는 과정이 필요합니다.
계층적 배치로 CLAUDE.md 분리하기
프로젝트 규모가 커지면 하나의 CLAUDE.md에 모든 정보를 담기 어렵습니다. 이때 CLAUDE.md를 계층적으로 배치하면 효과적입니다. 프로젝트 루트에는 전체 프로젝트의 공통 규칙을, 각 하위 디렉터리에는 해당 영역에 특화된 규칙을 작성하는 방식입니다.
예를 들어 프론트엔드 소스코드가 위치한 디렉터리(src/front)에는 프론트엔드 요구사항의 CLAUDE.md를 배치하고, 백엔드 소스코드가 위치한 장소(src/server나 src/api)에는 백엔드나 API의 명세서를 배치하며, 테스트를 모은 디렉터리(src/test)에는 테스트를 정의한 CLAUDE.md를 배치하는 식입니다. 각 영역을 디렉터리 단위로 확실히 분리하고 관련 CLAUDE.md만 배치함으로써 어디에 어떤 정의가 들어있는지 시각적으로도 쉽게 파악할 수 있고 효율적으로 관리할 수 있습니다.
@ 파일 참조와 @임포트
CLAUDE.md 안에서 다른 파일을 참조할 때는 @ 표기법을 사용합니다. 예를 들어 프로젝트의 명세서 파일을 CLAUDE.md에 포함시키고 싶다면 '@docs/SPECIFICATION.md'처럼 작성합니다. 대화 모드에서도 @ 기호를 사용하면 특정 파일을 컨텍스트에 직접 포함시킬 수 있습니다.
실제 프로젝트에서는 요구사항 정의, ER 다이어그램, API 명세서, 화면 설계서, 테스트 명세서 등 여러 문서를 CLAUDE.md에서 @임포트로 참조하게 됩니다. 이렇게 하면 컨텍스트는 커질 수 있지만, 한 번에 명세를 확정하고 정리할 수 있습니다.
다만 주의할 점이 있습니다. 클로드 코드로 파일을 생성할 경우 원래 추가해야 할 별도 파일을 참조하기 위한 @를 기본적으로 붙여 주지 않습니다. 클로드 코드의 명세에서는 @가 지정된 파일만 임포트되므로 SPECIFICATION.md를 컨텍스트에 포함하려면 @SPECIFICATION.md와 같이 @을 붙여서 다시 작성해야 합니다.
사용 기술 명시하기
프로젝트에서 사용하는 기술에 대한 정보도 CLAUDE.md에 함께 기록하는 것이 좋습니다. 흔히 사용하는 기술이라도, 예를 들어 자바스크립트 대신 타입스크립트를 사용한다고 명확히 적어 두면 실수를 줄일 수 있습니다. 또한 널리 사용되지 않는 언어나 프레임워크를 선택하면 정확도가 낮아지거나, 지정하지 않은 라이브러리가 임의로 사용될 수 있으니 주의해야 합니다.
CLAUDE.md 비대화에 주의하기
CLAUDE.md에 모든 요구사항 정의를 넣는 방법은 편리하지만, 반드시 모든 세부 사항을 클로드가 알아야 하는 것은 아닙니다. CLAUDE.md는 사용자와 상호작용할 때마다 매번 참조되므로 불필요한 세부 정보를 너무 많이 포함하면 정보의 효율성이 떨어집니다. CLAUDE.md가 너무 비대해지면 작업 효율과 정확도가 떨어지기 때문에 클로드를 시작할 때 경고가 표시되기 시작합니다.
2. 권한 설정 --- 보안과 편의성의 균형 잡기
클로드 코드는 파일을 편집하거나 터미널 명령을 실행할 때 사용자의 허가를 요청합니다. 이 권한 시스템은 AI가 의도치 않은 변경을 하는 것을 방지하는 안전장치이지만, 매번 승인하는 과정이 반복되면 작업 흐름이 끊기게 됩니다. 따라서 프로젝트의 성격에 맞게 권한을 적절히 설정하는 것이 중요합니다.
명령 실행 허가와 permissions
클로드 코드가 셸 명령을 실행하려고 할 때는 'Do you want to proceed?'라는 확인 메시지가 표시됩니다. 이때 세 가지 옵션이 주어집니다. 첫째, 이번 한 번만 실행을 허가합니다. 둘째, 이 디렉터리에서는 앞으로도 실행을 허용합니다. 셋째, 실행을 허가하지 않고, 클로드 코드에 다른 방법을 지시합니다.
둘째 옵션을 선택하면, 이후 같은 종류의 명령을 실행할 때마다 추가 확인을 거치지 않고 바로 처리됩니다. 이 과정에서 프로젝트 루트에 있는 .claude 디렉터리의 settings.local.json 설정 파일에 허용 규칙이 추가됩니다.
이 파일을 직접 수정해 특정 명령의 실행을 허용할 수도 있습니다. 또는 대화 모드에서 /permissions 명령어를 사용해 CLI에서 권한을 추가할 수도 있습니다. Permissions 화면에서 'Add a new rule...'을 선택하면 새로운 명령 규칙을 추가할 수 있으며, 이 규칙은 .claude/settings.local.json 파일에도 저장됩니다.
권한 작성 방법 --- 와일드카드 활용
권한 규칙은 인수를 받는 함수 형태로 구성되어 있으며, 와일드카드를 사용한 다양한 설정 규칙을 지정할 수 있습니다. 예를 들어 'Bash'는 모든 실행을 의미하고, 'Bash(*)'는 임의의 bash 명령을 뜻합니다.
'Bash(npm:*)'처럼 작성하면 npm으로 시작하는 모든 명령을 허용하고, 'Bash(npm install)'처럼 특정 명령만 허용하는 것도 가능합니다. 반대로 특정 명령을 차단할 수도 있습니다. deny 목록에 'Read(./.env.*)'나 'Edit(./config.json)'을 추가하면 환경 변수 파일이나 설정 파일에 대한 접근을 막을 수 있습니다.
참고로 설정 파일의 .claude/settings.local.json은 개인이 사용할 것으로 가정하며, 클로드 코드를 설치할 때 전역 .gitignore에 자동으로 기재되어 Git으로 관리되지 않도록 되어 있습니다. 또한 curl이나 wget과 같이 외부 네트워크와 통신하는 명령은 보안상 위험이 있으므로, 허용 목록에 추가하더라도 실행 전마다 클로드 코드가 반드시 확인을 요청합니다.
도구별 권한 필요 여부
클로드 코드에서 사용할 수 있는 도구는 크게 권한이 필요한 도구와 필요하지 않은 도구로 나뉩니다. Bash(셸 명령어 실행), Edit(파일 편집), MultiEdit(단일 파일에 여러 편집 실행), Write(파일 생성 또는 덮어쓰기), WebFetch(URL 콘텐츠 가져오기), WebSearch(웹 검색 실행), NotebookEdit(Jupyter 노트북 셀 변경) 등은 권한이 필요합니다. 반면 Glob(파일 검색), Grep(패턴 검색), LS(디렉터리 목록), Read(파일 읽기), NotebookRead(노트북 읽기), Task(하위 에이전트 실행), TodoWrite(작업 리스트 관리) 등은 권한 없이 사용할 수 있습니다.
4가지 권한 모드
클로드 코드에는 4가지 권한 모드가 있습니다. 첫째, default 모드는 각 도구를 처음 사용할 때 권한을 요청하며 기본값입니다. 둘째, acceptEdits 모드는 세션에 대해 파일 편집 권한을 자동으로 수락합니다. 셋째, plan 모드는 클로드가 분석과 계획 수립만 할 수 있고, 파일 수정이나 명령 실행은 할 수 없습니다. 넷째, bypassPermissions 모드는 모든 권한 요청을 건너뛰는 모드로 안전한 환경이 필요합니다.
실제로 개발 초기 단계에서는 plan 모드 대신 acceptEdits 모드에서 '실행 계획을 먼저 세우고, 그것을 마크다운으로 작성해 달라'고 지시하는 경우가 많습니다. 이렇게 하면 외부에서 계획 내용을 확인하고, 필요한 정보를 클로드에 제공하기도 쉽습니다. 또한 단계적으로 구현을 진행하다가 원하는 시점에 작업을 중단하거나 다시 시작할 수도 있습니다.
한편 bypassPermissions 모드는 'claude --dangerously-skip-permissions' 명령으로 실행하며, 클로드에 명령 실행의 모든 권한을 부여합니다. 이 모드를 사용할 때는 클로드가 오류를 수정하는 과정에서 드물게 폴더 전체를 삭제하거나 권한을 변경하는 실수를 할 수 있으니, 반드시 주의해서 사용해야 합니다. 바이브 코딩처럼 자동화가 필요한 워크플로나, lint 에러 수정, 보일러플레이트 코드 생성 등에 적합한 모드입니다.
3. 컨텍스트 관리 --- AI의 작업 기억을 최적화하라
클로드 코드를 사용할 때 반드시 이해해야 할 개념이 '컨텍스트 윈도'입니다. 컨텍스트 윈도란 클로드 코드가 한 번에 처리할 수 있는 정보의 총량을 말합니다. 사용자의 프롬프트, 클로드 코드의 응답, 읽어 들인 파일 내용, 명령 실행 결과 등 대화에서 오가는 모든 정보가 이 안에 들어갑니다. 클로드는 컨텍스트 윈도를 최대 20만 토큰만큼 보유하도록 설계되었습니다. 대화뿐만 아니라 코드 정보 등도 보유하기 때문에 프로젝트 규모가 클수록 빠르게 한계에 도달합니다.
/context로 사용량 확인하기
클로드 코드 1.0.86 버전부터는 /context 명령을 통해 컨텍스트 윈도 내용을 시각화할 수 있습니다. 이 슬래시 명령을 실행하면 현재 컨텍스트 점유율이 10×10칸 그림과 함께 백분율로 표시됩니다. 또한 종류에 따라 색으로 구분됩니다. 시스템 프롬프트와 시스템 도구는 흰색, MCP 도구는 파란색, Memory files(CLAUDE.md)는 갈색, 메시지는 보라색, 빈 공간은 회색으로 나타납니다.
Memory files 항목에서는 CLAUDE.md가 얼마나 차지하고 있는지를 보여줍니다. 예시에서는 User(~/.claude/CLAUDE.md) 메모리와 Project(./CLAUDE.md) 메모리가 인식되고 있으며, 각각 얼마나 많은 컨텍스트를 보유하고 있는지 알 수 있습니다. 이처럼 컨텍스트의 상황을 확인함으로써 현재의 MCP 상태나 CLAUDE.md의 로딩 상황 등도 부수적으로 파악할 수 있게 되었습니다.
/clear와 /compact --- 컨텍스트 초기화와 압축
/clear 명령을 사용하면 직접 컨텍스트를 초기화해 클로드를 다음 대화 주제에 집중하게 할 수 있습니다. 클로드에 지시하는 구현 내용이 변경되는 시점 등, 앞으로 지시할 내용에 지금까지의 대화 문맥이 불필요한 경우에는 /clear를 실행하는 것이 좋습니다. 이를 통해 클로드에 명확한 컨텍스트 상태에서 새로운 지시를 내릴 수 있습니다. 또한 컨텍스트도 절약됩니다. 새로운 구현을 시작하려면 /clear를 실행합니다. 예를 들어, 3장에서는 TODO.md를 순차적으로 구현했지만, 본래 1단계 환경 설정, 2단계 백엔드, 3단계 프론트엔드 등 매번 구현할 때마다 기존 지식을 이어받을 필요는 거의 없습니다. 오히려 불필요한 컨텍스트를 끌어들일 수 있습니다. 이 경우 매번 /clear를 실행하면 정확도가 높아집니다.
반면 /compact 명령을 사용하면 사용자가 임의의 타이밍에 능동적으로 컨텍스트를 압축시킬 수 있습니다. 과거 대화에 대해 개요만 남기고 컨텍스트를 압축한 형태로 유지할 수 있습니다. 또한 특정 내용에 초점을 맞추고 싶다면 '/compact API 명세에 초점을 맞춰주세요'처럼 지시할 수 있습니다. 이렇게 지시하면 클로드가 필요한 정보만 대화의 컨텍스트로 유지할 수 있습니다.
Summary instructions로 압축 품질 높이기
압축할 때 항상 특정 내용에 초점을 맞추고 싶다면 CLAUDE.md에 'Summary instructions' 섹션을 작성해 두는 것이 효과적입니다. 예를 들어 '대화 압축을 사용할 때는 코드의 변경 내용에 초점을 맞춰주세요'라고 작성해 두면, 이후 클로드가 컨텍스트를 요약할 때 항상 코드 변경 내용에 집중하도록 설정할 수 있습니다.
/clear 명령을 실행하면 클로드가 지금까지의 대화 내용을 모두 잊고, 이후 대화에 집중할 수 있습니다. 반면, /compact 명령은 지금까지의 대화 내용을 요약하고 압축합니다. 따라서 기본적인 대화 흐름은 기억하지만, 내용이 간소화된다는 점이 차이점입니다. (도서 169페이지 컬럼 참조)
4. 확장 사고 모드 --- 복잡한 문제에 '깊이 생각해'라고 말하기
확장 사고 모드(Extended Thinking Mode)는 클로드 코드가 복잡한 문제에 대해 더 깊은 분석과 사고를 수행하기 위한 모드입니다. 일반적인 응답보다 더 많은 시간을 들여 문제를 다각적으로 검토하고 더 높은 정확도의 답변을 제공합니다. 다만 토큰 수를 소비하기 때문에 최대 토큰 수에 따라 여러 단계로 나뉩니다.
이 모드를 활성화하는 방법은 간단합니다. 프롬프트에 아래 표에 나온 키워드를 넣으면 클로드 코드가 해당 키워드에 맞춘 토큰 예산만큼 사고를 확장하여 답변합니다.
예를 들어, 쉽게 해결되지 않는 문제를 마주했거나 코드 전반에 걸쳐 관련된 부분을 폭넓게 생각하고 싶을 때, 혹은 복잡한 문제를 풀고 싶을 때에는 '생각해'이나 'ultrathink'를 입력해 보세요. 이렇게 지시하면 확장 사고 모드가 발동합니다. 토큰을 많이 소비하기는 하지만, 클로드 코드가 갖춘 능력을 최대한 활용해 충분히 검토해 줍니다.
Tab 키로 사고 확장 모드 전환하기
v2.0.0부터 대화 모드에서 Tab 키를 누르는 것만으로 항상 사고 확장 모드가 되는 기능이 추가되었습니다. 오른쪽 아래에 'Thinking on (tab to toggle)'이라는 표시가 나타나며 항상 사고 확장 모드가 됩니다. 또한 이 설정은 세션을 종료해도 상태가 지속됩니다. 매우 편리하지만, 곧 토큰을 소비하게 되어 압축 경고가 나타날 수 있습니다. 토큰을 낭비하지 않도록 주의하세요.
5. 가드레일 --- AI의 폭주를 막는 안전장치
클로드 코드는 세션별 상태를 유지하지 않으며, LLM은 과거 데이터에서 통계적으로 답을 결정하기 때문에 때로는 앞뒤 문맥을 충분히 이해하지 못하고 제멋대로 코드를 작성하는 경우가 있습니다. 따라서 방향성이 흔들리지 않도록 사용자가 사전에 지켜야 할 명세나 규약을 가능한 한 견고하게 정의해야 합니다. 이제 LLM에 제한이나 규칙을 부여함으로써 '가드레일' 역할을 수행하는 몇 가지 방법을 알아보겠습니다.
컴파일 체크
프로그래밍 언어에서 제공하는 타입을 통한 타입 체크, 참조 오류, 문법 오류 체크입니다. 정적 분석이나 컴파일 체크가 있는 언어가 AI 코드의 폭주를 억제하는 효과가 더 높기 때문에 AI 친화적이라 할 수 있습니다.
테스트
테스트 파일을 작성하고 테스트를 실행해 특정 함수나 프로그램의 정상 작동을 확인하고 보장할 수 있습니다. 유의미한 테스트를 철저히 준비해 두면 LLM에 리팩터링을 안심하고 맡길 수 있습니다. 다만 주의하지 않으면 코드 측의 오류를 수정하는 것보다 정확한 테스트 파일을 잘못된 테스트 파일로 변경해서 테스트를 통과시키려고 할 수도 있으므로 주의가 필요합니다.
린트 검사
명명 규칙 및 코딩 스타일을 통일하고, 정해진 규칙을 준수하지 않는 경우에 대해 경고를 출력할 수 있습니다. 프로젝트를 시작할 때 ESLint, Biome 등과 같은 대표적인 린터를 설정해 둘 것을 권장합니다.
허스키(Husky)로 코드 보호하기
Node.js 애플리케이션에서는 허스키(Husky)를 설치하는 것이 일반적입니다. 허스키를 설치하면 Git을 이용해 커밋하거나 푸시하기 전에 포매터나 린터를 실행하거나 테스트를 실행할 수 있습니다.
이를 통해 코드의 포매팅과 사전 컴파일 검사가 가능합니다. 클로드 코드는 코드를 완벽하게 이해하고 작성하는 것은 아니므로 이를 통해 잘못되거나 지저분한 코드가 커밋되는 것을 방지할 수 있습니다.
가드레일 설정을 프롬프트로 자동화하기
요구사항 정의와 라이브러리 선정이 끝난 시점에서 클로드가 본격적으로 구현에 들어가기 전에 다음 내용을 한꺼번에 지시해 두기를 권장합니다. 'linter를 설치 및 설정하세요', '테스트 라이브러리를 설치 및 구성하세요', 'husky를 설치 및 설정하세요'와 같이 지시합니다. 마지막으로 배포 대상의 클라우드 인프라를 준비하고, 'CI/CD를 설정하세요. Cloud Run에 배포하고, Project ID는 xxxxx입니다. 배포 명령은 Makefile에 정리하세요'처럼 입력하면 됩니다.
초기 단계에서 가드레일을 튼튼하게 설정해 두면, 이후 클로드 코드를 다양하게 구현하더라도 프로그램 코드의 일관성을 유지하기 쉬워집니다. 또한 허스키가 포함돼 있으면 커밋 시 클로드가 린트 오류나 컴파일 오류를 감지하고 수정해 줍니다.
핵심 정리
클로드 코드를 제대로 활용하기 위한 핵심은 '사전 설정'이다. CLAUDE.md로 프로젝트의 맥락을 전달하고, 권한 모드로 작업 효율을 높이며, 컨텍스트 관리로 AI의 기억을 최적화하고, 확장 사고 모드로 복잡한 문제의 정확도를 끌어올리며, 가드레일로 AI의 출력 품질을 보장하면 클로드 코드의 진정한 생산성을 경험할 수 있다.
마무리 --- 다음 단계는?
이 글에서는 클로드 코드를 본격적으로 활용하기 위한 5가지 필수 설정을 살펴보았습니다. CLAUDE.md 작성법, 권한 설정, 컨텍스트 관리, 확장 사고 모드, 가드레일이라는 다섯 가지 설정은 각각 독립적이면서도 서로 연결되어 있습니다. CLAUDE.md에 프로젝트 정보를 잘 정리하면 컨텍스트 효율이 높아지고, 권한 설정을 적절히 하면 가드레일과 함께 안전하면서도 빠른 개발이 가능해집니다.
하지만 이것은 1장에서 다루는 내용의 일부일 뿐입니다. 실제 도서에서는 클로드 코드의 요금 체계부터 계정 등록, 환경 구축, MCP 서버 연동, 훅과 커스텀 명령까지 클로드 코드를 마스터하기 위한 전체 과정이 체계적으로 담겨 있습니다.
5가지 필수 설정의 상세한 실습 과정과 실전 프로젝트 적용 사례가 궁금하다면, 《클로드 코드를 활용한 바이브 코딩 완벽 입문》 1장과 4장에서 환경 구축부터 대규모 시스템 개발까지의 전체 워크플로를 확인하세요.
https://wikibook.co.kr/claude-code/