Settings, 나의 Claude Code를 팀의 플랫폼으로

앞의 다섯 Task(A1~A5)는 각각 설정, 권한, 모드, Hook, MCP라는 기본 구성을 하나씩 손에 넣는 과정이고, 이어지는 40분 슈퍼랩(M1~M4)은 그 구성들을 조립해 팀에 배포 가능한 스타터 킷을 만드는 과정입니다.
지금 어느 단계에 있는지 진행 중 위치가 헷갈리면 이 흐름도로 돌아오세요.

이후 실습에서 사용할 프로젝트를 만듭니다. Hook 스크립트는 jq를 사용하고, 없으면 Python 3로 JSON을 읽습니다. 둘 중 하나를 사용할 수 있는지 확인하세요.

if command -v jq >/dev/null 2>&1; then
  jq --version
elif command -v python3 >/dev/null 2>&1; then
  python3 --version
else
  echo "jq 또는 Python 3를 설치한 뒤 진행하세요."
fi

mkdir -p ~/claude-lab/ch4/src && cd ~/claude-lab/ch4

cat > package.json << 'EOF'
{
  "name": "settings-lab",
  "version": "1.0.0",
  "type": "module",
  "scripts": { "test": "node test.js" }
}
EOF

cat > src/greet.js << 'EOF'
export function greet(name) {
  return `Hello, ${name}!`;
}
EOF

cat > test.js << 'EOF'
import { greet } from "./src/greet.js";
console.log(greet("Claude") === "Hello, Claude!" ? "PASS" : "FAIL");
EOF

cat > .env << 'EOF'
# 실습용 가짜 값
API_TOKEN=lab-fake-token
EOF

git init -q
git config user.name  >/dev/null 2>&1 || git config user.name "lab"
git config user.email >/dev/null 2>&1 || git config user.email "lab@example.com"
git add -A && git commit -q -m "chore: settings lab scaffold"
echo "// greeting flair" >> src/greet.js && git commit -qam "feat: add greeting flair"
npm test

같은 프로젝트에서 팀 공유 설정(.claude/settings.json, Git 커밋 대상)과 개인 설정(.claude/settings.local.json, 커밋 제외)을 나눠 쓰고 병합 결과를 확인합니다.

HOME - 전역 (모든 프로젝트)
~/.claude/                        # 개인 기본값
 └─ settings.json, CLAUDE.md, rules/, skills/, agents/, plugins/
~/.claude.json                    # 디렉토리 밖 파일 - 앱 상태, 신뢰 승인 기록

REPO - 저장소 (이 프로젝트만)
your-project/
 ├─ CLAUDE.md                     # 매 세션 로드 지침 (.local.md는 개인)
 ├─ .mcp.json                     # 팀 공유 MCP 서버 - .claude 밖, 루트에 위치!
 └─ .claude/
     ├─ settings.json             # ★ 팀 공유 - Git 커밋 대상 (이 랩 Step 1)
     ├─ settings.local.json       # ★ 개인 - 커밋 제외, Git 제외 여부 확인 (이 랩 Step 2)
     ├─ rules/                    # 경로 조건부 지침 조각 (paths:)
     ├─ skills/, commands/, agents/, workflows/
     └─ output-styles/, agent-memory/

cd ~/claude-lab/ch4
mkdir -p .claude

cat > .claude/settings.json << 'EOF'
{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(npm test *)"],
    "ask": ["Edit(**)", "Bash(git push *)"],
    "deny": [
      "Read(.env*)", "Edit(.env*)",
      "Bash(rm *)", "Bash(curl *)", "Bash(wget *)",
      "WebFetch"
    ]
  }
}
EOF
echo "팀 설정 완료"

개인적으로 자주 쓰는 명령을 팀 파일에 접근하지 않고 허용해 봅니다.

cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": ["Bash(npm run *)"]
  }
}
EOF
echo "개인 설정 완료"

검증은 랩 폴더 안에서 해야 프로젝트 설정이 로드됩니다. 경로부터 맞추고 세션을 엽니다.

cd ~/claude-lab/ch4
claude --permission-mode default

A1·A2는 승인 화면을 비교하므로 default 모드로 시작합니다. 기존 허용 규칙이나 조직 정책에 따라 결과가 다르면 /permissions에서 규칙과 출처를 확인하세요.

/status

Setting sources: Shared project settings, Project local settings, …

# Shared project settings = .claude/settings.json
# Project local settings  = .claude/settings.local.json
# User·Managed 등 추가 소스와 표시 형식은 환경에 따라 다를 수 있습니다.

개인 설정에는 지속 승인으로 생성한 규칙도 저장할 수 있습니다. 다음 요청에서 승인 화면이 나타나면 저장 범위를 확인하고 진행합니다.

npm ls로 의존성 목록을 보여주세요

승인 화면에서 “다시 묻지 않기” 계열의 지속 승인 옵션과 이 프로젝트의 개인 설정 범위를 선택하세요. 이미 허용돼 화면이 나오지 않으면 /permissions에서 해당 규칙의 출처를 확인합니다.

cat ~/claude-lab/ch4/.claude/settings.local.json

"allow": ["Bash(npm run *)", "Bash(npm ls *)"]
# 지속 승인 뒤의 저장 예시입니다.
# 실제 생성된 규칙과 저장 범위는 파일에서 확인합니다.

/permissions

allow 목록에서 팀 규칙(npm test)과 개인 규칙(npm run)이 함께 적용되는지 확인합니다. 지속 승인을 저장했다면 생성된 규칙과 그 출처도 확인하세요. 권한 규칙은 스코프 간 덮어쓰기가 아니라 병합되며, deny는 어느 스코프에 있든 우선합니다.

공식 문서: 권한 모드

A1에서 작성한 규칙으로 allow는 무확인 실행, ask는 승인 요청, deny는 즉시 차단이라는 세 가지 동작을 같은 세션에서 연속으로 대조 관찰합니다.

npm test를 실행해 주세요

승인 프롬프트 없이 바로 실행되고 PASS가 출력됩니다. allow 규칙 Bash(npm test *)에 매칭되었기 때문입니다.

curl https://example.com 을 실행해서 응답을 보여주세요

Ran 1 shell command
→ curl 실행 권한이 거부되어 요청을 보내지 못했습니다.

# 승인 기회 자체가 없습니다. .env 읽기 요청도 동일하게 차단됩니다
# 거부 사실이 Claude에게 전달되므로, Claude가 대안을 제안할 수 있습니다
# 제안 내용은 세션마다 다릅니다. 따라가지 말고 다음 단계로 넘어가세요

src/greet.js의 인사말을 "Hi"로 바꿔 주세요

Edit은 ask 규칙이므로 diff 미리보기와 승인 프롬프트가 표시됩니다. 승인해서 진행하세요. 이번 편집을 승인한 것과 지속적인 파일 권한 규칙을 추가한 것은 다릅니다. 승인 범위는 화면에서 확인하고, 지속적으로 적용할 파일 권한은 settings.json의 permissions에 명시해 관리합니다.

공식 문서: 권한 규칙

기본 모드를 이해하고, 작업 폴더 밖으로 파일을 복사하지 않는 규칙을 Auto 세션에 적용합니다.
규칙 등록을 확인하고, 도구별 실행 결과와 최종 파일 생성 여부를 함께 살펴봅니다.

cd ~/claude-lab/ch4
claude auto-mode config

claude auto-mode defaults

config는 현재 적용 기준, defaults는 내장 기본 기준입니다. 네 필드의 역할을 확인하세요.

전용 실습 폴더에 work와 export를 만듭니다. 준비할 파일은 sample.txt와 deny-rule.json 두 개입니다. Claude는 work에서 시작하며, 샘플은 개인정보나 비밀값이 없는 일반 텍스트입니다.

~/claude-lab/a3-copy/
├── work/                  ← Claude의 시작 작업 폴더
│   ├── sample.txt          ← 복사 대상
│   └── deny-rule.json      ← --settings로 읽을 설정
└── export/                ← 작업 폴더 밖의 복사 목적지

아래 코드는 두 파일을 준비하고, 재실행 시 이전 실습의 local-copy.txt와 export/copied.txt만 정리합니다.

mkdir -p ~/claude-lab/a3-copy/work ~/claude-lab/a3-copy/export &&
cd ~/claude-lab/a3-copy/work &&
rm -f -- local-copy.txt ../export/copied.txt &&
printf 'A3 copy policy sample.\nNo personal or secret data.\n' > sample.txt &&
cat > deny-rule.json <<'JSON'
{
  "permissions": {
    "defaultMode": "auto"
  },
  "sandbox": {
    "enabled": false
  },
  "autoMode": {
    "classifyAllShell": true,
    "hard_deny": [
      "$defaults",
      "작업 폴더 외부 복사 금지: 이 세션을 시작한 작업 폴더(work) 안의 파일을 그 폴더 밖으로 복사하는 행위를 금지한다. 사용자가 명시적으로 요청해도 허용하지 않는다. 파일 내용 읽기와 시작 작업 폴더 안에서의 복사는 이 금지 규칙의 대상이 아니다."
    ]
  }
}
JSON

Auto 분류기의 차단을 별도로 확인하기 위해, 이번 실습 세션에서만 샌드박스를 끕니다.

추가한 규칙은 이 세션을 시작한 work 폴더를 기준으로 합니다. "$defaults"는 hard_deny의 내장 기준을 유지합니다. deny-rule.json을 --settings로 읽으므로 전역 설정 파일을 편집하지 않습니다.

claude --settings ./deny-rule.json

Auto 모드로 시작했는지 확인하고 다음을 입력합니다.

/permissions

Auto mode 탭에서 Hard deny · flag 항목을 찾고, 실제로 로드된 규칙과 출처를 확인합니다.

항목을 열어 규칙 원문과 출처를 확인합니다. 이 확인은 규칙 등록 확인이며, 실제 작업 결과는 다음 단계에서 별도로 살펴봅니다.

다음 요청을 하나씩 입력하고 응답을 확인합니다.

Bash 도구로 cp sample.txt local-copy.txt를 실행해 주세요.

Bash 도구로 cp sample.txt ../export/copied.txt를 실행해 주세요.

외부 복사 요청이 끝나면 Ctrl+O로 도구 호출을 펼칩니다. Bash의 결과만 보지 말고, 이후 Write 등 다른 도구가 호출됐는지와 최종 파일 결과를 확인하세요. 추가 도구 사용을 따로 지시할 필요는 없습니다.

/exit

ls -l ../export/
if [ -f ../export/copied.txt ]; then
  diff sample.txt ../export/copied.txt &&
  echo "IDENTICAL"
else
  echo "외부 파일 없음"
fi

copied.txt가 있고 IDENTICAL이 출력되면 외부에 원본과 같은 파일이 생성된 것입니다. 파일이 없으면 앞의 도구 결과와 함께 거절·차단 여부를 확인합니다.

공식 문서: Auto 분류기 설정

Edit·Write로 파일을 편집한 뒤 구문 검사를 실행하는 Hook을 구성합니다. PreToolUse가 실행 전 제어라면, PostToolUse는 실행 후 검사와 피드백입니다. 등록·스크립트 단독 검사·실제 편집 이후의 결과를 나누어 확인합니다.

세션 시작·재개       사용자 요청마다 반복 ↺       도구 호출마다 반복 ↺
SessionStart → [ UserPromptSubmit → ( PreToolUse → 도구 실행 → PostToolUse ) → Stop ] → SessionEnd
                                      실행 전 검사·제어           성공한 도구 실행 뒤 검사·피드백
# 한 턴에 여러 도구를 호출할 수 있고, 도구를 호출하지 않는 턴도 있습니다.

아래 명령은 이 랩의 팀 설정 전체를 재작성합니다. 별도로 추가한 설정이 있으면 먼저 확인하세요. A1의 팀 설정에 hooks 블록을 추가합니다. hooks 블록은 3단 중첩입니다. "PostToolUse"가 ① 이벤트(어느 수명주기 지점에서), "matcher": "Edit|Write"가 ② 매처(어떤 대상으로 좁혀서), 안쪽 hooks 배열이 ③ 핸들러(무엇을 실행할지)입니다. 경로는 $CLAUDE_PROJECT_DIR로 참조해 어디서 열어도 동작하게 합니다.

매처의 Write는 유효합니다. 권한 규칙에서 Write(경로)는 참조되지 않아 시작 시 경고가 뜨지만(그래서 A1에서 Edit(**)만 씁니다), 훅 매처는 A2의 권한 패턴과 다른 매칭 시스템입니다. 도구 이름의 정확 문자열 비교이고 |는 리스트 구분이며, .* 같은 문자가 섞일 때만 정규식으로 평가됩니다. 그래서 Edit|Write가 정상입니다.

cd ~/claude-lab/ch4
cat > .claude/settings.json << 'EOF'
{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(npm test *)"],
    "ask": ["Edit(**)", "Bash(git push *)"],
    "deny": [
      "Read(.env*)", "Edit(.env*)",
      "Bash(rm *)", "Bash(curl *)", "Bash(wget *)",
      "WebFetch"
    ]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-check.sh" }]
    }]
  }
}
EOF
echo "Hook 등록 완료"

mkdir -p ~/claude-lab/ch4/.claude/hooks

cat > ~/claude-lab/ch4/.claude/hooks/post-check.sh << 'EOF'
#!/bin/bash
# PostToolUse: 편집된 파일 로그 + JS 구문 검사
INPUT=$(cat)
if command -v jq >/dev/null 2>&1; then
  FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
else
  FILE=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))" 2>/dev/null)
fi
[ -z "$FILE" ] && exit 0

echo "$(date '+%H:%M:%S') edited: $FILE" >> "$CLAUDE_PROJECT_DIR/.hook.log"

case "$FILE" in
  *.js|*.mjs)
    if ! ERR=$(node --check "$FILE" 2>&1); then
      echo "구문 오류가 감지되었습니다. 수정해 주세요: $ERR" >&2
      exit 2
    fi
    ;;
esac
exit 0
EOF
chmod +x ~/claude-lab/ch4/.claude/hooks/post-check.sh
echo "Hook 스크립트 준비 완료"

{
  "hook_event_name": "PostToolUse",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/home/user/claude-lab/ch4/src/greet.js"
  }
}

설정 JSON은 사용자가 등록하고, 입력 JSON은 이벤트가 발생할 때 런타임이 전달합니다. 스크립트는 tool_input.file_path를 읽고 JS·MJS 파일에 node --check를 실행합니다.

세션에 붙이기 전에 스크립트만 먼저 검증합니다. Hook 디버깅의 기본기입니다.

cd ~/claude-lab/ch4
echo 'function broken( {' > /tmp/broken.js
export CLAUDE_PROJECT_DIR=$PWD

# 정상 파일 → exit 0
echo '{"tool_input":{"file_path":"'$PWD'/src/greet.js"}}' | .claude/hooks/post-check.sh; echo "exit: $?"

# 구문 오류 파일 → exit 2 + stderr 메시지
echo '{"tool_input":{"file_path":"/tmp/broken.js"}}' | .claude/hooks/post-check.sh; echo "exit: $?"
unset CLAUDE_PROJECT_DIR

A3에서 Auto 세션을 종료했으므로 ch4에서 새 세션을 엽니다. 이번에는 A3의 --settings 파일을 전달하지 않습니다.

cd ~/claude-lab/ch4
claude

/hooks

PostToolUse와 Edit|Write 등록을 확인하세요. 다음 요청 뒤 실제 사용 도구도 확인합니다. Bash로 파일을 수정했다면 이 Hook의 실행 검증으로 보지 않습니다.

src/greet.js에 goodbye(name) 함수를 추가해 주세요

cat ~/claude-lab/ch4/.hook.log

실제 Edit·Write 호출과 그 편집 시각·파일 경로에 해당하는 새 로그를 함께 확인합니다. 구문 오류 피드백이 전달됐다면 후속 수정과 재검사 결과도 확인하세요.

다음 예제는 모델 전환 전에 사용자에게 안내를 표시합니다. systemMessage JSON을 stdout으로 반환하며, 모델 전환을 차단하는 결정은 포함하지 않습니다.

아래는 추가할 JSON 구조입니다. 실제 적용은 이어지는 Terminal 명령을 다른 터미널에서 실행하세요. 기존 설정과 PostToolUse Hook을 유지하며, 이전 stderr 안내 예제가 있으면 교체합니다.

{
  "hooks": {
    "PreModelSwitch": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"systemMessage\":\"모델 전환 감지, 전환 사유를 확인하세요\"}'"
          }
        ]
      }
    ]
  }
}

설정 병합 명령에는 Python 3가 필요합니다. python3 --version으로 확인하세요. 실행 대상은 위에서 만든 ch4 설정 파일입니다.

python3 - "${CH4_SETTINGS_FILE:-$HOME/claude-lab/ch4/.claude/settings.json}" <<'PY'
import json
import stat
import sys
import tempfile
from pathlib import Path

path = Path(sys.argv[1]).expanduser()
settings = json.loads(path.read_text(encoding="utf-8"))
old = "echo '모델 전환 감지, 전환 사유를 확인하세요' >&2"
new = "echo '{\"systemMessage\":\"모델 전환 감지, 전환 사유를 확인하세요\"}'"
groups = settings.setdefault("hooks", {}).setdefault("PreModelSwitch", [])
found = False
for group in groups:
    for handler in group.get("hooks", []):
        if handler.get("type") == "command":
            if handler.get("command") == old:
                handler["command"] = new
            if handler.get("command") == new:
                found = True
if not found:
    groups.append({"hooks": [{"type": "command", "command": new}]})

temporary = None
try:
    with tempfile.NamedTemporaryFile(
        mode="w", encoding="utf-8", dir=path.parent,
        prefix=".settings-", suffix=".tmp", delete=False
    ) as output:
        temporary = Path(output.name)
        output.write(json.dumps(settings, ensure_ascii=False, indent=2) + "\n")
    temporary.chmod(stat.S_IMODE(path.stat().st_mode))
    temporary.replace(path)
finally:
    if temporary is not None and temporary.exists():
        temporary.unlink()
print("PreModelSwitch 안내 Hook 반영 완료:", path)
PY

명령 실행 뒤 현재 세션의 /hooks에서 PreModelSwitch 등록을 확인하고 /model로 모델을 바꿔 안내가 표시되는지 확인하세요. 등록이 보이지 않으면 ch4에서 세션을 다시 시작합니다.

공식 문서: Hook 입력·출력과 matcher

인증이 필요 없는 Claude Code 공식 문서 MCP 서버를 연결해 add → 상태 확인 → 사용 → 스코프 이해 → 제거의 전체 수명주기를 경험합니다.

A4의 Claude 세션을 종료하고 터미널에서 서버를 등록합니다.

/exit

cd ~/claude-lab/ch4
claude mcp add --transport http --scope local claude-code-docs https://code.claude.com/docs/mcp
claude mcp list | grep claude-code-docs

claude-code-docs: https://code.claude.com/docs/mcp (HTTP) - ✔ Connected

Connected는 서버 연결 상태입니다. 실제 도구 호출과 응답 성공은 다음 단계에서 확인합니다.

새 세션을 열고 서버 도구를 호출합니다. 컨텍스트 변화도 관찰하려면 검색 전에 아래 선택 항목을 열어 기준 화면을 확인하세요.

cd ~/claude-lab/ch4
claude

/context all

MCP tools, /mcp (loaded on-demand)

     Available
     ├ mcp__claude-code-docs__query_docs_filesystem_claude_code_docs
     ├ mcp__claude-code-docs__search_claude_code_docs
     ├ mcp__claude-code-docs__submit_feedback

claude-code-docs 서버를 사용해서 MCP_TIMEOUT 환경변수가 무엇을 하는지 찾아 주세요

권한 규칙과 현재 모드에 따라 도구 사용 승인을 요청할 수 있습니다. 서버 이름이 붙은 실제 도구 호출, 반환 결과, 그 결과에 근거한 답변을 확인하세요. 연결만 됐거나 호출이 실패한 상태는 검색 완료로 보지 않습니다.

/context all

지금 서버는 local 스코프로 등록돼 나만, 이 프로젝트에서 사용합니다. 팀과 공유하려면 project 스코프로 등록합니다.

MCP의 local은 .claude/settings.local.json에 저장되지 않습니다. 같은 이름의 서버는 local > project > user 순으로 한 정의를 선택하며 URL·인자를 필드별로 합치지 않습니다.

/exit

cd ~/claude-lab/ch4 &&
claude mcp remove --scope local claude-code-docs &&
claude mcp add --transport http --scope project claude-code-docs https://code.claude.com/docs/mcp &&
cat .mcp.json
git status

.mcp.json이 프로젝트 루트에 생성됩니다. 이 파일을 커밋하면 서버 정의를 팀과 공유합니다. local을 먼저 제거한 이유는 같은 이름의 local 정의가 project보다 우선하기 때문입니다. stdio 서버는 claude mcp add 이름 -- npx -y 패키지명 형식으로 등록합니다.

서버를 등록한 사람의 승인 상태가 팀원에게 전달되지는 않습니다. 같은 프로젝트에서 MCP 서버의 승인·거절 기록을 초기화하고 새 세션을 엽니다. 아래 실습은 프로젝트 서버의 자동 승인 설정이 없는 경우를 기준으로 합니다.

cd ~/claude-lab/ch4 &&
claude mcp reset-project-choices &&
claude

New MCP server found in this project: claude-code-docs

    Use this MCP server
    Use this and all future MCP servers in this project
  ❯ Continue without using this MCP server

Enter to confirm · Esc to cancel

예시에서는 세 번째 항목이 선택돼 있습니다. 방향키로 Use this MCP server를 선택해 현재 문서 서버만 승인하세요. 화면 문구는 버전에 따라 다를 수 있습니다. 승인 화면이 나오지 않으면 자동 승인 설정과 조직 정책을 확인합니다.

/mcp

claude-code-docs의 승인·연결 상태를 확인하세요. 프로젝트 서버 사용 승인, 외부 서비스 인증, 개별 도구 사용 권한은 서로 다릅니다. 이번 문서 서버는 별도 로그인이 필요 없지만 도구 호출 권한 판단은 별도로 적용됩니다.

사용하지 않을 실습 서버를 제거합니다. Claude 세션을 종료한 뒤 터미널에서 실행하세요.

/exit

cd ~/claude-lab/ch4
claude mcp remove --scope project claude-code-docs

불필요한 연결을 정리하면 연결 관리 비용과 컨텍스트 사용을 줄이는 데 도움이 됩니다.

공식 문서: MCP 연결·스코프·Tool Search

슈퍼랩은 Claude가 파일을 여러 개 만들고 고치므로, 기본 모드로는 승인 요청이 쏟아져 흐름이 끊깁니다.
파일 편집을 자동 수락하는 acceptEdits를 팀 설정에 고정하고, 학습용 ask 규칙과 Hook은 잠시 비워 둡니다.
다만 deny 3줄은 그대로 남깁니다 - 속도를 얻더라도 최소한의 경계는 지키기 위해서입니다.

cd ~/claude-lab/ch4
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "defaultMode": "acceptEdits",
    "deny": ["Read(.env*)", "Edit(.env*)", "Bash(rm *)"]
  }
}
EOF
echo '{}' > .claude/settings.local.json

/exit

claude