클로드 코드 제대로 쓰는 법 | 5가지 필수 설정 - brunch.co.kr

클로드 코드를 설치하고 첫 프롬프트를 입력했는데, 기대만큼 결과가 나오지 않은 경험이 있으신가요? 파일을 수정할 때마다 일일이 허락을 눌러야 하고, 대화가 길어지면 앞서 합의한 내용을 잊어버리고, 복잡한 버그 앞에서는 피상적인 답변만 돌아오는 상황 말입니다. 이런 문제의 상당수는 클로드 코드 자체의 한계가 아니라, 초기 설정을 제대로 하지 않아서 발생합니다. 클로드 코드는 설정 하나하나가 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만 토큰만큼 보유하도록 설계되었습니다. 대화뿐만 아니