서론
Claude Code는 각기 다른 범위(scope), 로딩 논리(loading logic) 및 유지보수 패턴을 가진 세 가지 별도의 구성 메커니즘을 제공합니다. 많은 개발자들이 이들을 혼용하여 사용하며, 이는 종종 미묘하지만 비용이 많이 드는 실수를 초래합니다. settings.json에 규칙을 작성하는 것은 아무런 효과를 낼 수 없습니다. 실행 시간 매개변수(runtime parameters)를 CLAUDE.md에 넣으면 대화 컨텍스트가 비대해집니다(bloats). 메모리 안에 정적 사실(static facts)을 저장하면 잘못된 추론(incorrect inference)이 발생할 수 있습니다. 본 문서는 각 구성 요소의 핵심 위치를 명확히 하고, 로딩 순서, 실용적인 구문법, 일반적인 함정(pitfalls), 그리고 프로덕션급 에이전트 워크플로우를 위해 이들을 올바르게 결합하는 방법을 설명합니다.
세 가지 시스템은 서로 다른 계층에서 작동하며, 서로를 대체하지 않습니다.
settings.json: 프로그램 실행 환경 구성(Runtime environment configuration), 프로그램에 의해 읽힘.CLAUDE.md: 인간이 작성한 프로젝트 사양(Human-authored project specification), AI에 의해 읽힘.memory: 세션 간 지식 저장소(Cross-session knowledge storage), AI에 의해 자동으로 작성 및 인덱싱됨.
가장 자주 오해되는 특성은 settings.json의 '한 번 로드 시 효과'라는 의미입니다(load-once semantic). 시작된 후 적용되는 모든 수정 사항은 전체 재시작(full restart)이 이루어지기 전까지는 효력이 발생하지 않습니다. 단순히 채팅 창을 편집하고 다시 로드하는 것만으로는 이 파일 내부의 변경 사항을 활성화할 수 없습니다.
1. settings.json – 프로그램 실행 구성
1.1 핵심 범위(Core Scope)
settings.json은 Claude Code를 위한 환경 변수, 권한, 도구 후크(tool hooks) 및 UI 표시 매개변수를 정의합니다. 이는 LLM에 의해 해석되기보다는 애플리케이션 실행 시간(application runtime)에 의해 소비됩니다. 모델 자체는 파일 내용을 직접 읽을 수 없으며, 파싱된 구성은 에이전트 세션이 시작되기 전에 프로그램 환경으로 주입됩니다.
1.2 파일 재정의 계층 구조(File Override Hierarchy)
구성 설정은 전역(global), 프로젝트 및 로컬 인스턴스 레벨에 걸쳐 캐스케이드(cascade) 됩니다. 나중에 작성된 항목이 이전에 작성된 항목을 재정의합니다.
- 전역
~/.claude/settings.json: 모든 워크스페이스에서 공유됩니다. 토큰 엔드포인트, 프록시 설정, 언어 선호도 및 모델 선택을 저장합니다.
- 프로젝트 레벨
.claude/settings.json: Git에 커밋됩니다. 팀 공유 훅(hook), 도구 권한 및 리포지토리 전체 명령어 허용 목록을 정의합니다.
- 프로젝트
.claude/settings.local.json: 개인 로컬 오버라이드입니다. 버전 관리에서 제외되며, 비공개 환경 변수와 사용자 지정 셸 명령을 위해 사용됩니다.
1.3 주요 설정 섹션
env: 환경 변수 주입 (Environment Injection)
이 블록은 Claude Code가 사용하는 셸 컨텍스트에 환경 변수를 주입합니다. 여기에 있는 값들은 UI 입력 선택을 재정의하므로, UI 프록시 설정을 변경한 후 다시 시작하면 실패할 수 있습니다. 개발자는 env | grep -i anthropic 명령어를 통해 주입된 변수를 확인할 수 있습니다.
{
"env": {
"ANTHROPIC_BASE_URL": "https://xxx.xxx/anthropic",
...
permissions: 명령어 허용 / 거부 규칙 (Command Allow / Deny Rules)
권한 규칙은 셸 실행 동작을 제어합니다. allow 배열에는 반복적인 확인 없이 실행되는 승인된 명령어가 포함되어 워크플로우 속도를 향상시킵니다. deny 블록이 더 높은 우선순위를 가지며 위험한 작업을 무조건 차단합니다.
{
"permissions": {
"allow": [
...
훅(Hooks)은 도구 호출 전후에 사용자 지정 스크립트를 실행합니다. 일반적인 사용 사례로는 자동 코드 포맷팅, 린트 검사 및 파일 쓰기 후 상태 보고가 있습니다.
statusLine: 사용자 지정 상태 표시 (Custom Status Rendering)
이 섹션은 하단 상태 표시줄을 사용자 정의합니다. 활성 모델 이름, Git 브랜치, 컨텍스트 토큰 소비 백분율 및 기타 런타임 메트릭을 표시할 수 있습니다.
1.4 주요 기능 및 일반적인 버그
1.4 주요 기능 및 일반적인 버그
- 일회성 로딩 (One-time loading): 해당 파일은 시작 시에만 구문 분석됩니다. 진행 중인 세션에서는 실시간 편집이 적용되지 않습니다. Claude Code를 완전히 재시작해야 합니다.
- 잘못된 JSON에 대한 무음 실패 (Silent failure on malformed JSON): 구문 오류가 발생하면 명시적인 경고 없이 전체 설정 파일이 무시됩니다. 저장하기 전에 항상 JSON을 검증하십시오.
- 버전 관리 관행 (Version control practice): 전역 및 프로젝트 설정 파일은 Git으로 추적되며,
settings.local.json은 로컬에 유지되고 커밋되지 않습니다.
2. CLAUDE.md – AI를 위한 프로젝트 명세서
2.1 범위 (Scope)
CLAUDE.md는 사람이 작성한 지침 텍스트로, 모든 대화 시작 시 LLM 컨텍스트에 완전히 로드됩니다. 이는 에이전트가 준수해야 하는 코딩 규칙, 아키텍처 제약 조건, 테스트 요구 사항 및 리포지토리 규칙을 정의합니다. AI는 이 규칙들을 읽고 따르지만, 프로그램 런타임은 이 파일을 구문 분석하지 않습니다.
권장되는 유지보수 패턴은 대규모의 단일 CLAUDE.md를 ./claude/rules/ 아래의 규칙 파일들로 분할하는 것입니다. 사양을 주제별로 그룹화하세요: 로깅 표준, 기술 스택 제약 조건, 데이터베이스 규칙 및 API 계약 규칙 등. 모듈식 파일은 수천 줄짜리 단일 문서를 유지하는 대신 점진적인 업데이트를 단순화합니다.
2.2 작성할 내용 (What to Write)
AI가 소스 코드를 단순히 읽는 것만으로는 추론할 수 없는, 강제 가능한 규칙을 추가하십시오. 테스트 표준은 다음과 같습니다: AI가 팀 합의를 위반하는 작동하는 코드를 생성할 수 있다면, 여기에 제약 조건을 작성해야 합니다.
예시로 강제 가능한 제약 조건:
- 계층형 아키텍처 제한: Facade, Service, DAO, Mapper 레이어링 및 교차 레이어 금지.
- 필수 코드 스타일, import 순서 지정 및 로깅 필드 스키마.
- 테스트 요구 사항: 모든 변경 사항은 단위 테스트를 제공해야 합니다.
- 변경 워크플로우: OpenAPI 사양 변경은 해당 구현 파일과 테스트 파일을 업데이트해야 합니다.
2.3 작성하지 않을 내용 (What Not to Write)
2.3 작성하지 않을 내용 (What Not to Write)
코드베이스에 이미 보이는 중복 정보는 피하세요. 개인 프록시 주소, 로컬 포트 또는 일회성 설정 메모와 같은 임시 로컬 환경 세부 사항은 기록하지 마세요. 이러한 환경 설정은 settings.json에 속하며, CLAUDE.md가 아닙니다.
CLAUDE.md는 새로운 채팅 세션마다 전체 내용이 로드됩니다. 문서 길이가 길어질수록 더 많은 컨텍스트 창 용량을 소모하고 작업 콘텐츠에 사용할 수 있는 공간을 줄입니다. 규칙 문서는 밀도가 높아야 합니다. 서술적인 배경 설명이나 선택적 제안보다는 하드 제약 조건에 집중하세요. 간결한 규칙이 장황한 산문보다 더 강력한 가중치를 지닙니다.
3. memory – 대화 간 메모리 (Cross-Conversational Memory)
3.1 범위 (Scope)
메모리는 AI가 자동으로 기록하는 관찰 내용을 저장합니다. 이는 별도의 채팅 세션 전반에 걸쳐 반복되는 컨텍스트 재도입 문제를 해결합니다.
CLAUDE.md와 비교한 차이점:
CLAUDE.md: 대화 중 절대 변경되지 않는 정적인 인간 작성 규칙입니다.memory: 작업 실행 이력으로부터 학습된 AI가 작성한 사실적 관찰 내용입니다.
3.2 인덱스 및 본문 투계층 아키텍처 (Index and Body Two-Tier Architecture)
메모리는 인덱스 + 본문 설계를 채택합니다. 인덱스는(보통 약 4KB) 매 세션마다 전체가 로드됩니다. 전체 본문(종종 최대 100KB)은 관련 후크가 트리거될 때만 선택적으로 로드됩니다. 이 설계는 CLAUDE.md처럼 모든 기록을 무조건 로드하는 것에 비해 토큰 오버헤드를 줄여줍니다.
각 메모리 항목에는 메타데이터, 결론, 추론 과정(reasoning trace), 그리고 관련성 후크가 포함됩니다. 후크는 전체 메모리 본문을 컨텍스트로 가져올지 결정하는 조건부 트리거 역할을 합니다. 모호한 후크 설명은 오탐(false negatives)을 유발하여 관련 메모리가 로드되는 것을 방해합니다.
3.4 네 가지 메모리 항목 유형 (Four Memory Entry Types)
3.4 네 가지 메모리 항목 유형 (Four Memory Entry Types)
userhook: 사용자 선호도, 작업 흐름 습관 및 확인된 운영 단계. 이 규칙이 적용되는 이유를 설명하는 추론(reasoning)을 반드시 포함해야 합니다.project: 프로젝트별 제약 조건, 코드 패턴 및 고정된 저장소 컨벤션.feedback: 과거 실패 요약 및 이전 작업 시도에서 학습한 수정 사항들.reference: 외부 문서, URL, 티켓 ID 및 사양 링크.
3.5 중요한 특징 (Important Traits)
메모리는 기록 시점의 스냅샷을 저장합니다. 실시간 상태 추적(real-time state tracking)이 아닙니다. 메모리에 저장된 사실은 코드 리팩토링이나 설정 변경 후에 구식이 될 수 있습니다. 에이전트는 메모리 항목들을 라이브 파일 검사 결과가 아닌 역사적 관찰(historical observations)로 취급합니다.
3.6 무엇을 저장하지 말아야 하는가 (What Should Not Be Saved)
소스 코드, Git 히스토리 또는 CLAUDE.md에 이미 존재하는 정보를 중복해서 기록하지 마십시오. 메모리는 그렇지 않으면 반복적인 인간의 설명이 필요할 만한 교훈들을 담아야 합니다. 간단한 필터링 테스트: 이 사실이 3개월 후에 반복되는 질문을 막아줄까요? 아니라면, 기록하는 것을 건너뛰세요.
4. 비교 요약 및 결정 트리 (Comparative Summary & Decision Tree)
4.1 핵심 비교 표 (Core Comparison Table)
| 항목 | settings.json | CLAUDE.md | memory |
| :--- | :--- | :--- |
| 리더(Reader) | 프로그램 실행 시간(Program runtime) | AI LLM | AI LLM |
| ... |
4.2 배치 결정 논리 (Decision Logic for Placement)
- 환경 변수, 셸 허용 목록(shell allowlist) 및 실행 시간 매개변수 →
settings.json.
- 영구적인 팀 코딩 표준 및 아키텍처 규칙 →
CLAUDE.md.
- 학습한 교훈, 프로젝트 관찰 및 반복되는 함정들 →
memory.
4.3 경계 예시 (Boundary Examples)
- 프록시 설정(Proxy configuration):
settings.json의 환경 변수 섹션에 속합니다. 프록시 정보를 CLAUDE.md에 배치하면 컨텍스트 토큰을 낭비하게 됩니다.
- 데이터베이스 연결 규칙: 영구적인 아키텍처 제약 조건이므로,
CLAUDE.md에 작성해야 합니다.
- 과거 실패:
별도로 전역 공유 설정과 프로젝트별 규칙을 분리해야 합니다. 로컬에서만 사용되는 사적인 재정의(override)는 settings.local.json만을 사용하세요.
수정 후 유효성 검사 워크플로우:
- 수정 전에 백업 파일을 생성합니다.
- JSON 구문(syntax)을 유효성 검사합니다.
- Claude Code를 완전히 재시작합니다.
- 환경 변수를 출력하여 주입(injection) 여부를 확인합니다.
권한 설계 원칙: 거부 규칙이 우선순위를 가집니다. 최소 허용 목록(allowlist)에서 시작하여 명령 범위를 점진적으로 확장하세요. 실행 후 권한 로그를 감사해야 합니다.
5.2 CLAUDE.md 유지보수
규칙 세트를 단일하고 거대한 마크다운 문서로 통합하기보다는 여러 주제 파일로 분할해야 합니다. 각 규칙은 위반 시의 결과를 정의해야 합니다. 오래된 규칙은 주기적으로 제거하세요. 구식 규칙은 컨텍스트 비용을 증가시키고 에이전트에게 혼란을 줄 수 있습니다. 필수 제약 조건(mandatory constraints)은 이 문서 안에 유지해야 합니다.
5.3 메모리 유지보수
메모리는 완전히 자동적인 기록에 맡기기보다는 능동적으로 관리되어야 합니다. 개발자는 메모리 쓰기 또는 삭제를 명시적으로 요청할 수 있습니다. 선택적 로딩을 위해 정확한 후크 조건(hook conditions)을 작성하세요. 인덱스를 주기적으로 검사하고, 중복된 레코드를 병합하며, 만료된 관찰 기록(observations)을 보관해야 합니다.
5.4 결합 워크플로우
표준 프로덕션 워크플로우는 다음과 같습니다: CLAUDE.md에 영구 규칙을 정의하고, settings.json을 통해 런타임 환경을 구성하며, 메모리가 작업 교훈(task lessons)을 축적하도록 합니다. 주기적으로 메모 기록을 검토하고 정리해야 합니다. 에이전트 개발 워크플로우에서는 개발자가 LLM 트래픽을 다중 모델 엔드포인트 및 요청 라우팅을 관리하는 API 게이트웨이인 4sapi를 통해 라우팅할 수 있습니다.
6. 일반적인 실패 문제 해결
6. 일반적인 실패 문제 해결
- Environment proxy가 작동하지 않는 경우:
settings.json 내부의 env 섹션을 확인하고, env 명령어로 주입을 검증한 후 에이전트를 재시작하세요.
- AI가 아키텍처 규칙을 무시하는 경우:
CLAUDE.md에 규칙이 존재하는지 확인하고, 문서 길이와 제약 조건의 명확성을 점검하세요.
- 풀었던 문제에서 반복적인 실수를 하는 경우: 메모리 훅(memory hooks)을 검증하고, 관련 메모리 항목이 매칭되는 작업이 시작될 때 로드되도록 하세요.
- 설정 변경 사항에 아무런 영향이 없는 경우: 가장 흔한 근본 원인은 전체 Claude Code 프로세스를 재시작하지 않고
settings.json만 편집하는 것입니다.
결론
Claude Code의 세 가지 구성 시스템은 책임을 명확하게 분리합니다. settings.json은 에이전트 프로그램의 실행 환경을 제어합니다. CLAUDE.md는 매번 세션 시작 시 LLM에 정적인 프로젝트 규칙을 전달합니다. 메모리는 게으른 로딩(lazy loading) 방식으로 과거 관찰 기록을 저장하여 반복적인 컨텍스트 설정을 줄여줍니다. 설정 콘텐츠를 잘못 배치하면 성능 저하, 보안 위험, 예상치 못한 에이전트 동작을 초래할 수 있습니다. 이들의 로딩 의미론과 경계를 숙달하는 것이 신뢰할 수 있는 코드 에이전트 배포에 필수적입니다. 여러 모델로 구성된 에이전트 시스템을 구축할 때, 개발자들은 통합 게이트웨이 서비스를 통해 엔드포인트 관리를 단순화할 수 있습니다.
국제 접속: https://4sapi.com
국내 접속: https://4sapi.cn