도입

터미널에 /status를 입력하는 순간, 화면에 클로드 코드의 버전, 현재 연결된 모델명, 인증된 계정 정보가 한꺼번에 쏟아집니다. 마치 자동차 계기판을 한 번 들여다보는 것처럼, 지금 이 에이전트가 어떤 상태인지를 단번에 파악할 수 있습니다. 이 명령어를 외워야 했을까요? 아닙니다.

"지금 내 클로드 코드 상태가 어떤지 알려줘"라고 자연어로 물어도 에이전트가 알아서 /status를 실행합니다. 기본 명령어(Built-in Command)의 세계는 이렇게 시작됩니다.

핵심 명령어 모음

클로드 코드에는 크게 두 부류의 기본 명령어가 있습니다. 하나는 현재 상태를 확인하는 진단·상태 명령어이고, 다른 하나는 에이전트의 행동 방식을 바꾸는 설정 명령어입니다.

진단·상태 명령어부터 살펴봅니다.

• /model — 사용 중인 모델을 확인하거나 다른 모델로 전환합니다. Opus에서 Sonnet으로, 혹은 Haiku로 바꿀 때 사용합니다.
• /help — 사용 가능한 모든 명령어 목록을 표시합니다. 명령어 이름이 기억나지 않을 때 가장 먼저 떠올릴 명령어입니다.
• /doctor — 설치 상태 진단을 실행합니다. 의존성 누락, 인증 문제, 네트워크 연결 상태를 점검하여 "이상 없음" 혹은 구체적인 문제 원인을 알려 줍니다.
• /status — 클로드 코드의 버전, 연결된 모델, 계정 정보를 한 번에 보여 줍니다.

[그림 10-1] /status 명령어 실행 결과 예시]

여기서 핵심은 이 명령어들을 외울 필요가 없다는 점입니다. 클로드 코드는 자연어를 해석하여 적절한 명령어를 자동으로 실행할 수 있습니다. "진단 한번 돌려봐"라고 말하면 /doctor가 실행되고, "지금 무슨 모델 쓰고 있어?"라고 물으면 /status가 응답합니다. 명령어의 존재를 아는 것은 유용하지만, 암기는 에이전트의 몫입니다.

설정 명령어

설정 명령어는 에이전트의 작동 방식을 조율하는 제어판입니다.

• /memory — 자동 메모리(Auto Memory)를 편집합니다. 에이전트가 대화 중에 학습한 사항을 영구 저장하거나, 저장된 내용을 수정·삭제할 수 있습니다. "나는 항상 경어체를 선호해"라고 말하면 에이전트가 이를 기억하도록 저장합니다.
• /config — 전반적인 설정을 관리합니다. 어떤 모델을 기본값으로 사용할지, 모델이 세는 글 조각 사용량 경고 임계치를 얼마로 잡을지 같은 선택을 여기서 합니다.
• /permissions — 에이전트가 파일을 읽거나 쓰거나 삭제하는 권한을 제어합니다. 민감한 디렉터리에 대한 접근을 차단하거나, 반대로 자유롭게 허용하는 설정을 이곳에서 다룹니다.
• /mcp — MCP 연결 서버(Model Context Protocol Server) 연결을 관리합니다. 외부 도구나 서비스와 에이전트를 이어 주는 통로입니다.
• /agents — 보조 에이전트(Sub-agent) 목록을 확인하거나 관리합니다.

이 명령어들 역시 자연어로 접근할 수 있습니다. "내 권한 설정 보여줘"라고 하면 /permissions 내용이 표시됩니다. 그러나 직접 슬래시 명령어를 입력하는 편이 더 빠를 때도 있습니다. 에이전트가 의도를 해석하는 단계를 건너뛰기 때문입니다. 상황에 따라 자연어와 명령어를 섞어 쓰는 것이 실용적입니다.

설정 계층구조: 사용자, 프로젝트, 내 컴퓨터

기본 명령어가 에이전트와 대화하는 방식이라면, 설정 파일은 에이전트의 기본 행동 양식을 정의하는 청사진입니다. 클로드 코드의 설정은 세 개의 층으로 이루어져 있으며, 각 층이 서로 다른 범위를 담당합니다.

사용자 수준(User Level, 글로벌) 설정은 홈 디렉터리(~/)에 위치합니다. 이 설정은 컴퓨터에 존재하는 모든 프로젝트에 영향을 미칩니다. 어떤 폴더를 열든, 어떤 프로젝트에서 작업하든 항상 적용되는 기본값입니다.

프로젝트 수준(Project Level) 설정은 프로젝트 폴더 안의 .claude/settings.json에 위치합니다. 이 파일은 깃허브(GitHub)에 커밋되어 팀 전체가 공유할 수 있습니다. 팀원 누구든 이 프로젝트를 열면 동일한 설정을 적용받습니다.

내 컴퓨터 프로젝트 수준(Local Project Level) 설정은 .claude/settings.local.json에 위치합니다. 이 파일은 오직 내 컴퓨터에서만 적용됩니다. 깃허브에 올라가지 않으며, 같은 프로젝트를 쓰는 팀원에게는 보이지 않습니다.

[그림 10-2] 설정 계층 구조 다이어그램: 사용자 → 프로젝트 → 내 컴퓨터]

세 계층은 위에서 아래로 우선순위가 결정됩니다. 에이전트가 어떤 동작을 수행하려 할 때, 내 컴퓨터 설정을 먼저 확인합니다. 내 컴퓨터에 해당 규칙이 없으면 프로젝트 설정을 봅니다. 프로젝트 설정에도 없으면 글로벌 설정을 따릅니다.

이 우선순위가 실제로 어떻게 작동하는지 예를 들어 보겠습니다. read라는 파일 읽기 명령이 있다고 합시다. 내 컴퓨터 설정에서 "read를 절대 사용하지 마라"고 지정했다면, 에이전트는 즉시 멈춥니다. 프로젝트와 글로벌에서 허용했더라도 소용없습니다. 반대로 내 컴퓨터과 프로젝트에서는 허용했지만 글로벌에서 금지했다면, 글로벌 단계에서 차단됩니다.

내 컴퓨터이 가장 좁은 범위이면서 가장 먼저 확인되고, 글로벌이 가장 넓은 범위이면서 마지막 관문 역할을 합니다.

settings.json과 settings.local.json의 차이

두 파일은 같은 .claude 폴더 안에 나란히 존재하지만, 용도가 명확히 다릅니다.

settings.json에는 팀 전체가 합의한 규칙을 넣습니다. 코딩 컨벤션, 필수 도구 목록, 공통 MCP 연결 서버 연결 정보 같은 것들입니다. 새로운 팀원이 프로젝트를 클론(clone)하면 이 설정이 자동으로 적용되므로, 온보딩 과정에서 "설정 맞춰 줘"라고 따로 안내할 필요가 줄어듭니다.

settings.local.json에는 나만의 개인 취향을 넣습니다. 선호하는 편집기 동작, 개인 API 키 경로, 내 컴퓨터 전용 디버깅 옵션 같은 것들입니다. 팀 설정과 충돌이 생기면 내 컴퓨터이 우선하므로, 팀 표준을 따르면서도 자기만의 작업 환경을 유지할 수 있습니다.

한 가지 주의할 점이 있습니다. settings.local.json은 .gitignore에 등록하여 깃허브에 절대 올라가지 않도록 해야 합니다. 개인 API 키나 민감한 경로 정보가 포함될 수 있기 때문입니다.

.claude 폴더의 구조와 역할

프로젝트 폴더를 열었을 때 눈에 들어오는 .claude 디렉터리는 클로드 코드의 심장부입니다. 이 폴더 안에 에이전트가 프로젝트를 이해하고 작동하는 데 필요한 모든 구성 요소가 담겨 있습니다.

프로젝트 폴더/

├── .claude/

│   ├── settings.json          # 팀 공유 설정

│   ├── settings.local.json    # 개인 전용 설정

│   ├── rules/                 # 에이전트 행동 규칙

│   ├── skills/                # 재사용 가능한 스킬 파일

│   ├── agents/                # 서브에이전트 정의

│   └── commands/              # 커스텀 명령어

├── CLAUDE.md                  # 프로젝트 두뇌 (메인 컨텍스트)

├── CLAUDE.local.md            # 개인 전용 컨텍스트

├── .env                       # 환경 변수 (API 키 등)

├── .gitignore                 # 깃 제외 목록

└── (프로젝트 파일들)

[그림 10-3] .claude 폴더의 내부 구조와 각 파일의 역할]

CLAUDE.md는 에이전트가 대화를 시작할 때마다 가장 먼저 읽는 파일입니다. 프로젝트의 목적, 핵심 규칙, 다른 파일의 위치를 안내하는 지도 역할을 합니다. CLAUDE.local.md는 CLAUDE.md의 개인 버전으로, 나만의 추가 지시사항을 담습니다.

.gitignore 파일은 깃이 추적하지 않을 파일 목록을 지정합니다. .env 파일(API 키 보관), settings.local.json, 개인용 이미지나 비밀번호 파일 등을 여기에 등록합니다. VS Code에서 이 파일들은 회색으로 표시되어 시각적으로 구분됩니다. 초록색은 깃이 아직 추적하지 않는 새 파일, 노란색은 수정된 파일입니다.

이 색상 체계는 "지금 커밋해야 할 것이 있는가"를 한눈에 알려 줍니다.

rules/ 폴더에는 에이전트의 커뮤니케이션 스타일, 코딩 규칙 같은 행동 지침이 들어갑니다. skills/ 폴더에는 재사용 가능한 워크플로우 레시피가, agents/ 폴더에는 보조 에이전트 정의 파일이 저장됩니다.

글로벌 설정도 이와 유사한 구조를 가집니다. 홈 디렉터리의 .claude 폴더 아래에 settings.json, skills/, agents/, rules/ 등이 위치하며, 여기에 저장된 내용은 어떤 프로젝트를 열든 적용됩니다. 프로젝트마다 반복하고 싶지 않은 공통 설정 — 예컨대 "항상 경어체를 사용하라" 같은 규칙 — 은 글로벌에 두는 편이 효율적입니다.

각 계층에 무엇을 넣을지 정리하면 이렇습니다.

이 구조를 처음 접하면 복잡해 보입니다. 폴더 안에 폴더, 파일 안에 파일. 그러나 실제로 프로젝트를 하나 열고 .claude 폴더를 직접 탐색해 보면, 각 파일의 역할이 이름만으로도 드러납니다. 설정의 계층은 "팀이 합의한 것 / 프로젝트가 요구하는 것 / 내가 원하는 것"이라는 세 겹의 렌즈와 같습니다. 에이전트는 이 렌즈를 안쪽부터 바깥쪽으로 훑으며, 자신이 어떻게 행동해야 하는지를 결정합니다.

기본 명령어가 에이전트와의 즉각적인 대화 수단이라면, 설정 계층은 에이전트의 장기적인 성격을 형성하는 골격입니다. 그런데 에이전트의 기억에는 한 가지 근본적인 한계가 있습니다. 한 번에 읽는 범위(Context Window)라 불리는, 한 번에 처리할 수 있는 정보량의 천장입니다. 이 천장을 넘어서는 방대한 데이터를 에이전트가 활용하려면, 외부 기억 장치가 필요합니다.