사전 준비 확인
2분80분 내내 사용할 실습 프로젝트를 만듭니다. Hook 스크립트가 jq를 사용하므로 설치 여부도 확인합니다.
jq --version || echo "jq 없음: brew install jq 권장, 없어도 Hook은 python3로 대체 동작"
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
설정 계층, 팀 설정과 개인 설정의 공존
9분
같은 프로젝트에서 팀 공유 설정(.claude/settings.json, Git 커밋 대상)과
개인 설정(.claude/settings.local.json, 커밋 제외)을 나눠 쓰고
병합 결과를 확인합니다.
| 우선순위 | 스코프 | 파일 | 용도 |
|---|---|---|---|
| 1 | Managed | OS 시스템 경로 (Ch3) | 조직 강제, 사용자가 못 덮음 |
| 2 | CLI 인자 | --settings 등 | 세션 한정 오버라이드 |
| 3 | Local | .claude/settings.local.json | 개인 실험, 커밋 제외 |
| 4 | Project | .claude/settings.json | 팀 표준, Git 커밋 |
| 5 | User | ~/.claude/settings.json | 개인 전역 기본값 |
cd ~/claude-lab/ch4
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
"model": "sonnet",
"permissions": {
"allow": [
"Read(**)", "Grep", "Glob",
"Bash(npm test:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git status)"
],
"ask": ["Edit(**)", "Write(**)", "Bash(git push:*)"],
"deny": ["Bash(rm -rf:*)", "Bash(curl:*)", "Read(**/.env*)"]
}
}
EOF
echo "팀 설정 완료"
개인적으로 자주 쓰는 명령을 팀 파일을 건드리지 않고 허용해 봅니다.
cat > .claude/settings.local.json << 'EOF'
{
"permissions": {
"allow": ["Bash(ls:*)", "Bash(cat package.json)"]
}
}
EOF
echo "개인 설정 완료"
claude
/status
Setting sources:
- project (.claude/settings.json)
- local (.claude/settings.local.json) # 두 소스가 함께 로드됨
/permissions
allow 목록에 팀 규칙(npm test, git ...)과 개인 규칙(ls, cat package.json)이 병합되어 함께 보이면 성공입니다. 권한 규칙은 스코프 간 덮어쓰기가 아니라 병합되며, deny는 어느 스코프에 있든 우선합니다.
.claude/settings.json은 커밋해 팀 표준으로, settings.local.json은
.gitignore에 넣어 개인용으로 유지하세요. 설정 파일은 저장 즉시 핫 리로드되어 대부분의 키는 재시작 없이 적용됩니다.
설정 가능한 전체 키는 세션에서 /config --help로 확인할 수 있습니다.
권한 패턴 문법, 3단 대조 실험
9분A1에서 작성한 규칙으로 allow는 무확인 실행, ask는 승인 요청, deny는 즉시 차단이라는 세 가지 동작을 같은 세션에서 연속으로 대조 관찰합니다.
| 패턴 | 의미 | 예시 |
|---|---|---|
Bash(npm test:*) | npm test로 시작하는 모든 명령 (prefix 매칭) | npm test, npm test -- --watch |
Read(**/.env*) | 모든 깊이의 .env 계열 파일 (경로 글롭) | .env, config/.env.prod |
Bash(git status) | 정확히 이 명령만 (exact 매칭) | git status |
npm test를 실행해 주세요
승인 프롬프트 없이 바로 실행되고 PASS가 출력됩니다. allow 규칙 Bash(npm test:*)에 매칭되었기 때문입니다.
curl https://example.com 을 실행해서 응답을 보여주세요
Bash(curl:*) 규칙(deny)에 의해 차단됨
# 승인 기회 자체가 없음. .env 읽기 요청도 동일하게 차단됩니다
src/greet.js의 인사말을 "Hi"로 바꿔 주세요
Edit은 ask 규칙이므로 diff 미리보기와 승인 프롬프트가 표시됩니다. 승인해서 진행하세요.
이 승인 화면에서 "항상 허용"을 선택하면 해당 규칙이 settings.local.json에 기록됩니다.
PostToolUse Hook, 편집 뒤 자동 검사
10분Claude가 파일을 수정할 때마다 자동으로 구문 검사가 도는 Hook을 답니다. Ch3의 PreToolUse가 실행 전 차단이라면, PostToolUse는 실행 후 피드백입니다. exit 2의 stderr가 Claude에게 전달되어 스스로 고치는 루프가 만들어지는 것이 핵심입니다.
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 스크립트 준비 완료"
A1의 팀 설정에 hooks 블록을 더해 재작성합니다. 경로는 $CLAUDE_PROJECT_DIR로 참조해 어디서 열어도 동작하게 합니다.
cd ~/claude-lab/ch4
cat > .claude/settings.json << 'EOF'
{
"model": "sonnet",
"permissions": {
"allow": [
"Read(**)", "Grep", "Glob",
"Bash(npm test:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git status)"
],
"ask": ["Edit(**)", "Write(**)", "Bash(git push:*)"],
"deny": ["Bash(rm -rf:*)", "Bash(curl:*)", "Read(**/.env*)"]
},
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-check.sh" }]
}]
}
}
EOF
echo "Hook 등록 완료"
세션에 붙이기 전에 스크립트만 먼저 검증합니다. 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
src/greet.js에 goodbye(name) 함수를 추가해 주세요
cat ~/claude-lab/ch4/.hook.log
편집 시각과 파일 경로가 기록되어 있으면 Hook이 동작한 것입니다. 세션에서 /hooks를 입력하면
등록된 Hook 구성을 확인할 수 있습니다. 만약 Claude가 구문 오류가 있는 코드를 저장하면
stderr 메시지가 Claude에게 전달되어 다음 턴에서 스스로 수정합니다.
prettier --write나 eslint --fix를 넣는 것이 auto-format 패턴입니다.
MCP 서버 연결, 첫 외부 도구
10분인증이 필요 없는 Claude Code 공식 문서 MCP 서버를 연결해 add → 상태 확인 → 사용 → 스코프 이해 → 제거의 전체 수명주기를 경험합니다.
cd ~/claude-lab/ch4
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list
claude-code-docs: https://code.claude.com/docs/mcp (HTTP) - ✓ Connected
claude-code-docs 서버를 사용해서 MCP_TIMEOUT 환경변수가 무엇을 하는지 찾아 주세요
첫 호출에서 새 도구 사용 승인을 요청합니다. 승인하면 출력의 도구 호출에 서버 이름 라벨이 붙어,
답이 웹 검색이 아닌 MCP 서버에서 왔음을 확인할 수 있습니다. /mcp로 서버 패널도 열어 보세요.
| 스코프 | 저장 위치 | 대상 |
|---|---|---|
| local (기본) | ~/.claude.json의 프로젝트 항목 | 나만, 이 프로젝트만 |
| project | 프로젝트 루트 .mcp.json | 저장소를 클론한 팀 전체 (승인 프롬프트) |
| user | ~/.claude.json 전역 | 나만, 모든 프로젝트 |
{
"mcpServers": {
"claude-code-docs": {
"type": "http",
"url": "https://code.claude.com/docs/mcp"
}
}
}
이 파일을 커밋하면 팀원이 클론 후 첫 실행 때 승인 프롬프트를 받고 같은 서버를 씁니다.
stdio 서버(로컬 프로세스)는 claude mcp add 이름 -- npx -y 패키지명 형식으로 등록합니다.
claude mcp remove claude-code-docs
/context로 소비량을 볼 수 있습니다.
슈퍼랩, Team Starter Kit을 빌드하라
지금부터는 따라하기가 아니라 빌드 미션입니다. Part A에서 익힌 메커니즘으로 팀에 바로 커밋할 수 있는 에셋 3종(커스텀 커맨드, 스킬, 스타터 킷 문서)을 만듭니다. 각 미션은 요구사항과 완성 기준(Definition of Done)만 제시합니다. 구현 경로는 자유입니다.
배경 지식 한 장: 커스텀 커맨드는 스킬로 통합되었습니다.
.claude/skills/이름/SKILL.md를 만들면 /이름 명령이 생기고
(구 .claude/commands/이름.md도 계속 동작), 스킬 디렉토리는 파일 감시로 즉시 반영됩니다.
단, 프로젝트에 skills 디렉토리를 처음 만드는 경우라면 세션을 재시작해야 감시가 시작됩니다.
/standup, 매일 쓰는 커맨드 스킬
10분
어제 커밋을 동적 컨텍스트 주입으로 읽어 스탠드업 초안을 만들어 주는
/standup 커맨드를 만듭니다. Slack에 붙여넣기 좋은 형식이 목표입니다.
.claude/skills/standup/SKILL.md 를 만들어 주세요. 요구사항:
1) frontmatter: description은 "일일 스탠드업 초안 생성", disable-model-invocation: true, argument-hint: "[오늘 할 일]"
2) 본문 맨 위에서 동적 컨텍스트 주입 문법 !`git log --oneline --since="1 day ago"` 로 어제 커밋을 주입
3) $ARGUMENTS 가 있으면 오늘 할 일로 정리하고, 없으면 커밋 흐름에서 추천
4) 출력 형식: ### 어제 / ### 오늘 / ### 블로커 3개 섹션의 마크다운, Slack에 붙여넣기 좋게
생성된 파일을 cat .claude/skills/standup/SKILL.md로 확인하고,
frontmatter와 !`...` 주입 라인이 요구사항대로인지 검토하세요. 이 프로젝트에
skills 디렉토리가 처음 생긴 것이므로 세션을 한 번 재시작(/exit 후 claude)합니다.
/standup "PR 리뷰 2건, 워크샵 랩 마무리"
### 어제
- feat: add greeting flair
- chore: settings lab scaffold
### 오늘
- PR 리뷰 2건
- 워크샵 랩 마무리
### 블로커
- 없음
막힐 때 열어보기, 완성본 SKILL.md
---
description: 일일 스탠드업 초안 생성. 어제 커밋과 오늘 할 일을 정리한다.
disable-model-invocation: true
argument-hint: "[오늘 할 일]"
---
## 어제의 커밋
!`git log --oneline --since="1 day ago"`
## 지시
위 커밋 목록을 사람이 읽기 쉬운 한 줄 요약으로 정리해 "### 어제" 섹션을 만드세요.
$ARGUMENTS 가 있으면 "### 오늘" 섹션의 항목으로 정리하고, 없으면 커밋 흐름을 보고 오늘 할 일을 추천하세요.
마지막에 "### 블로커" 섹션을 넣되 언급된 것이 없으면 "- 없음"으로 채우세요.
전체를 Slack에 붙여넣기 좋은 마크다운으로만 출력하세요.
release-notes, 격리 실행 스킬
12분
커밋 범위를 인자로 받아 릴리스 노트를 생성하는 스킬을 만듭니다. 이번에는
context: fork로 읽기 전용 Explore 에이전트에서 격리 실행시켜,
메인 컨텍스트를 지키면서 결과만 받아옵니다. Chapter 2의 서브에이전트와 이 챕터의 스킬이 만나는 지점입니다.
.claude/skills/release-notes/SKILL.md 를 만들어 주세요. 요구사항:
1) frontmatter: description "커밋 범위로 릴리스 노트 생성", disable-model-invocation: true,
argument-hint: "[커밋 범위]", context: fork, agent: Explore
2) 본문에서 !`git log --oneline --no-merges $ARGUMENTS` 로 해당 범위 커밋을 주입
3) 커밋을 Added / Changed / Fixed 로 분류한 마크다운 릴리스 노트를 작성하도록 지시
4) 대상 독자는 개발자가 아닌 사용자라는 점을 명시
/release-notes HEAD~2..HEAD
[Explore 에이전트로 포크 실행] # 프롬프트 아래 서브에이전트 패널에 표시
## Release Notes
### Added
- 인사 기능에 새로운 표현 추가
### Changed / Fixed
- ...
# 결과만 메인으로 반환, 탐색 과정은 격리 컨텍스트에서 소비
실행 중 프롬프트 아래 서브에이전트 패널과 /tasks에서 포크 실행을 관찰하세요.
스킬 파일 저장은 즉시 반영되므로(skills 디렉토리는 M1에서 이미 감시 시작) 재시작이 필요 없습니다.
막힐 때 열어보기, 완성본 SKILL.md
---
description: 지정한 커밋 범위의 변경 사항으로 릴리스 노트를 생성한다.
disable-model-invocation: true
argument-hint: "[커밋 범위]"
context: fork
agent: Explore
---
## 대상 커밋
!`git log --oneline --no-merges $ARGUMENTS`
## 지시
위 커밋들을 분석해 릴리스 노트를 작성하세요.
- 형식: "## Release Notes" 아래 "### Added", "### Changed", "### Fixed" 세 분류
- 각 항목은 커밋 메시지를 그대로 옮기지 말고, 개발자가 아닌 사용자가 이해할 문장으로 다시 쓰세요
- 해당 분류에 항목이 없으면 그 섹션은 생략하세요
agent 필드로 고르며, 생략하면 general-purpose입니다.
자유 빌드, 본인 팀의 반복 작업 하나
10분이번엔 요구사항도 직접 정합니다. 본인 팀에서 매주 반복하는 작업 하나를 골라 스킬로 만드세요. 좋은 후보는 "매번 비슷한 지시문을 복사해 붙여넣는 일"입니다.
| 아이디어 | 핵심 재료 |
|---|---|
| /pr-desc, PR 설명 초안 | !`git diff main...HEAD --stat` 주입 + 팀 PR 템플릿 |
| /commit-msg, 커밋 메시지 컨벤션 | !`git diff --cached` 주입 + Conventional Commits 규칙 |
| /review-checklist, 리뷰 체크리스트 | 팀 체크리스트를 본문에 내장 (참조형, 플래그 없이) |
| /test-plan, 테스트 시나리오 초안 | $ARGUMENTS로 대상 기능, 정상/엣지/예외 3분류 지시 |
| /translate-ko, 기술 문서 한국어화 | $ARGUMENTS 파일 경로 + 용어집을 supporting file로 |
.claude/skills/[스킬이름]/SKILL.md 를 만들어 주세요.
- 목적: [이 스킬이 해결하는 반복 작업]
- 트리거: [내가 직접 /명령으로만 vs Claude가 관련 상황에서 자동으로]
- 입력: [$ARGUMENTS로 받을 것 / !`...`로 주입할 실시간 데이터]
- 출력 형식: [정확한 섹션 구조나 예시]
만든 뒤 이 스킬을 스스로 한 번 호출해서 결과가 형식에 맞는지 검증까지 해 주세요
검증은 "What skills are available?"로 목록 노출을 확인하고, 직접 호출해 출력 형식을 봅니다. trigger 설계가 애매하면 M1의 판단 기준(내가 타이밍을 정하는 액션 → disable-model-invocation)을 다시 적용하세요.
/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official
/reload-plugins
skill-creator로 방금 만든 스킬을 평가해 주세요. 테스트 케이스 3개를 만들어 스킬이 있을 때와 없을 때를 비교해 주세요
skill-creator는 테스트 케이스 작성, 격리 실행, 채점, 스킬 유무 벤치마크까지 자동화하는 공식 플러그인입니다. 시간이 남는 분만 진행하세요.
패키징과 공유, 킷을 팀의 것으로
5분80분의 산출물(설정, Hook, 스킬 3종)을 온보딩 가능한 스타터 킷으로 패키징합니다. 문서화도 Claude에게 시킵니다.
.claude 디렉토리 전체(settings.json, hooks, skills)를 훑고, 새 팀원이 5분 안에 이해할 온보딩 README.md를 프로젝트 루트에 만들어 주세요. 각 스킬의 사용 예시 한 줄씩 포함해 주세요
cd ~/claude-lab/ch4
echo ".claude/settings.local.json" >> .gitignore
git add -A && git commit -m "feat: team starter kit (settings, hooks, skills)"
git log --oneline | head -3
| 경로 | 방법 | 적합한 경우 |
|---|---|---|
| 프로젝트 커밋 | .claude/를 저장소에 커밋 (지금 한 것) | 한 저장소에서 함께 일하는 팀 |
| 플러그인 | skills + hooks + agents를 플러그인으로 묶어 마켓플레이스 배포 | 여러 저장소, 여러 팀에 배포 |
| Managed | 관리 설정 경로에 배포 (Chapter 3) | 조직 표준으로 강제 |
.claude-plugin/plugin.json을 추가하면 그 폴더가 플러그인으로 로드되어
agents, hooks, MCP 서버까지 함께 묶을 수 있습니다. 팀 데모 시간에 오늘 만든 스킬 하나를 시연해 보세요.
마무리, 학습 목표 체크리스트
Chapter 4의 학습 목표를 스스로 점검하세요. 미달성 항목은 진행자에게 질문하거나 강의 자료의 해당 Part를 다시 확인합니다.
| 목표 | 확인 질문 | 관련 |
|---|---|---|
| Layers | 5단 우선순위와 팀/개인 설정 분리를 체험했는가 | A1 |
| Permissions | allow/ask/deny와 prefix/글롭/exact 패턴을 대조 관찰했는가 | A2 |
| Hooks | PostToolUse 피드백 루프(exit 2)를 단독+세션에서 검증했는가 | A3 |
| MCP | 서버 수명주기(add/list/사용/remove)와 3스코프를 이해했는가 | A4 |
| Command Skill | 동적 주입 + $ARGUMENTS로 커맨드 스킬을 빌드했는가 | M1 |
| Fork Skill | context: fork로 격리 실행 스킬을 빌드했는가 | M2 |
| Own Asset | 본인 팀의 반복 작업 하나를 스킬로 만들었는가 | M3 |
| Share | 스타터 킷을 커밋하고 공유 경로 3가지를 아는가 | M4 |