> For the complete documentation index, see [llms.txt](https://judy-valentine.gitbook.io/judy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://judy-valentine.gitbook.io/judy/technical-notes/claude-code/claude-code-2.md). # Claude Code 하네스 엔지니어링 가이드 Claude Code를 프로젝트에 맞게 **설정·권한·훅·지시문**을 조합해 최적의 작업 환경을 구성하는 단계별 가이드입니다. *** ### 왜 필요한가? Claude Code를 설치 직후 그대로 쓰면 매번 같은 상황이 반복됩니다. * 파일 편집할 때마다 승인 요청 * bash 명령마다 승인 요청 * 프로젝트 컨텍스트를 매 세션마다 다시 설명 * 알림이 없어서 Claude가 멈춰있는 걸 모르고 시간 낭비 \*\*하네스(Harness)\*\*는 이 문제를 해결하는 설정 레이어입니다. 모델을 감싸는 권한·훅·지시문 설정을 한 번 구성하면, 이후 모든 세션에서 프로젝트에 맞는 환경이 자동 적용됩니다. *** ### 개념 정리 #### 하네스란? 하네스는 Claude Code의 **모델 외부 설정 계층** 전체를 가리킵니다. 모델이 "두뇌"라면, 하네스는 두뇌가 작동하는 "환경"입니다. #### 하네스 구성 요소 | 구성 요소 | 파일/위치 | 역할 | | ------------ | --------------------------------- | ------------------------- | | **설정 파일** | `~/.claude/settings.json` | 전역 권한, 허용 도구, 모델, 훅 정의 | | **프로젝트 설정** | `.claude/settings.json` (프로젝트 루트) | 프로젝트별 설정 오버라이드 | | **지시문** | `CLAUDE.md` (프로젝트 루트) | 프로젝트 컨텍스트, 코딩 규칙, 워크플로 지시 | | **권한 모드** | `Shift + Tab` 순환 | 파일 편집·bash 명령 승인 정책 | | **훅(Hooks)** | `settings.json` 내 `hooks` 키 | 특정 이벤트 발생 시 자동 실행할 명령 | #### 전역 설정 vs 프로젝트 설정 | 항목 | 전역 (`~/.claude/`) | 프로젝트 (`.claude/`) | | ------ | ----------------- | ----------------- | | 적용 범위 | 모든 프로젝트 | 해당 프로젝트만 | | Git 추적 | ❌ | ✅ (팀 공유 가능) | | 우선순위 | 기본값 | **전역보다 우선** | | 용도 | 개인 환경 설정 | 프로젝트 규칙 강제 | *** ### 설치 및 설정 #### 1단계: 전역 설정 디렉토리 확인 `~/.claude/` 디렉토리가 있는지 확인합니다. ```bash ls -la ~/.claude/ ``` 없으면 생성합니다. ```bash mkdir -p ~/.claude ``` #### 2단계: 전역 settings.json 생성 기본 설정 파일을 생성합니다. ```bash nano ~/.claude/settings.json ``` 최소 설정 템플릿을 붙여넣습니다. ```json { "allowedTools": ["Read", "Glob", "Grep"], "model": "claude-sonnet-4-20250514" } ``` * `allowedTools`: 승인 없이 자동 실행할 도구 목록 * `model`: 사용할 모델 지정 **nano 저장 방법:** 1. `Ctrl + O` → `Enter` → `Ctrl + X` #### 3단계: 권한 모드 설정 Claude Code 실행 후 `Shift + Tab`으로 권한 모드를 순환합니다. | 모드 | 파일 편집 | bash 명령 | 용도 | | ------------------- | ----- | ------- | -------------- | | Normal | 물어봄 | 물어봄 | 처음 쓸 때 | | **Accept Edits On** | 자동 ✅ | 물어봄 | **일반 개발 (추천)** | | Plan Mode | 계획만 | 계획만 | 큰 변경 전 검토 | **Accept Edits On**을 추천합니다. 파일 편집은 자동 승인하되, bash 명령은 확인 후 실행하므로 안전성과 생산성의 균형이 가장 좋습니다. #### 4단계: 훅(Hooks) 추가 `settings.json`에 `hooks` 키를 추가합니다. 훅은 Claude Code의 특정 이벤트에 외부 명령을 자동 실행합니다. ```json { "allowedTools": ["Read", "Glob", "Grep"], "model": "claude-sonnet-4-20250514", "hooks": { "Notification": [ { "matcher": "permission_prompt", "hooks": [ { "type": "command", "command": "terminal-notifier -title 'Claude Code' -subtitle '권한 승인 필요' -message '터미널로 돌아가세요' -sound Glass -activate com.googlecode.iterm2" } ] } ] } } ``` JSON 문법을 검증합니다. ```bash cat ~/.claude/settings.json | python3 -m json.tool ``` 에러 없이 정렬된 JSON이 출력되면 성공입니다. #### 5단계: CLAUDE.md 작성 프로젝트 루트에 `CLAUDE.md` 파일을 생성합니다. Claude Code는 세션 시작 시 이 파일을 자동으로 읽습니다. ```bash nano CLAUDE.md ``` 프로젝트 컨텍스트를 작성합니다. ```markdown # 프로젝트 지시문 ## 기술 스택 - TypeScript + Next.js 15 - PostgreSQL + Prisma ORM ## 코딩 규칙 - 함수명은 camelCase - 컴포넌트는 PascalCase - 테스트 파일은 `*.test.ts` 형식 ## 금지 사항 - any 타입 사용 금지 - console.log 커밋 금지 ``` `CLAUDE.md`에 포함할 내용: | 항목 | 예시 | 효과 | | ----- | ---------------------- | --------------- | | 기술 스택 | "TypeScript + Next.js" | 프레임워크에 맞는 코드 생성 | | 코딩 규칙 | "camelCase 사용" | 프로젝트 컨벤션 준수 | | 금지 사항 | "any 타입 금지" | 실수 방지 | | 워크플로 | "커밋 전 lint 실행" | 작업 순서 강제 | #### 6단계: 전체 설정 검증 Claude Code를 새로 실행하고 동작을 확인합니다. ```bash claude ``` 확인 항목: * `CLAUDE.md` 내용이 세션에 반영되는지 (프로젝트 규칙을 따르는지 확인) * 권한 모드가 원하는 상태인지 (`Shift + Tab`으로 확인) * 훅이 정상 작동하는지 (bash 명령 실행 시 알림 발생 여부) *** ### 커스터마이징 #### 허용 도구 확장 `allowedTools`에 도구를 추가하면 해당 도구 실행 시 승인을 건너뜁니다. ```json { "allowedTools": ["Read", "Glob", "Grep", "Edit", "Write", "Bash"] } ``` | 도구 | 위험도 | 설명 | | ---------------------- | -------- | ------------------------------ | | `Read`, `Glob`, `Grep` | 낮음 ✅ | 읽기 전용, 안전 | | `Edit`, `Write` | 중간 ⚠️ | 파일 수정, Accept Edits On 모드에서 자동 | | `Bash` | **높음** ❌ | 임의 명령 실행, 신중하게 추가 | #### 훅 매처 종류 | 매처 | 발생 시점 | 용도 | | ------------------- | ------------ | --------- | | `permission_prompt` | 권한 승인 요청 시 | 알림, 로깅 | | `idle_prompt` | 작업 완료 후 대기 시 | 복귀 타이밍 알림 | #### 프로젝트별 설정 분리 팀 프로젝트에서 `CLAUDE.md`와 `.claude/settings.json`을 Git에 커밋하면 팀원 전체가 동일한 하네스 설정을 공유합니다. ```bash git add CLAUDE.md .claude/settings.json git commit -m "Add Claude Code harness configuration" ``` 개인 환경(알림 소리, 모델 선호 등)은 `~/.claude/settings.json`에, 프로젝트 규칙(코딩 규칙, 허용 도구 등)은 `.claude/settings.json`에 분리합니다. *** ### 트러블슈팅 #### CLAUDE.md 내용이 반영 안 돼요 **체크 1: 파일 위치 확인** ```bash ls -la CLAUDE.md ``` * `CLAUDE.md`는 **프로젝트 루트**(Claude Code를 실행하는 디렉토리)에 있어야 합니다 * 하위 디렉토리에 있으면 인식하지 못합니다 **체크 2: 파일명 대소문자** * `CLAUDE.md` ✅ (전체 대문자) * `claude.md` ❌ (소문자 불가) #### settings.json 설정이 안 먹어요 **체크 1: JSON 문법 오류** ```bash cat ~/.claude/settings.json | python3 -m json.tool ``` * 에러 메시지 나오면 해당 줄 수정 * 흔한 실수: 마지막 항목 뒤 쉼표, 따옴표 누락, 괄호 짝 불일치 **체크 2: 프로젝트 설정과 충돌** ```bash cat .claude/settings.json ``` * 프로젝트 설정이 전역 설정을 덮어쓸 수 있습니다 * 두 파일에 같은 키가 있으면 프로젝트 설정이 우선합니다 **체크 3: Claude Code 재시작** 설정 변경 후 기존 세션에는 반영되지 않을 수 있습니다. Claude Code를 종료하고 새로 실행합니다. #### 훅이 실행 안 돼요 **체크 1: 훅 명령어 직접 실행** ```bash terminal-notifier -title "테스트" -message "작동 확인" ``` * 명령어 자체가 실패하면 훅 문제가 아닌 도구 문제입니다 * 도구 설치 여부부터 확인합니다 **체크 2: 매처 이름 오타** * `permission_prompt` ✅ * `permision_prompt` ❌ (s 하나 빠짐) *** ### 정리 * **하네스** = `settings.json` + `CLAUDE.md` + 권한 모드 + 훅의 조합 * **전역 설정**(`~/.claude/`)은 개인 환경, **프로젝트 설정**(`.claude/`)은 팀 규칙용 * **Accept Edits On** 모드가 일반 개발에 가장 적합한 권한 설정 * `CLAUDE.md`에 프로젝트 컨텍스트를 명시하면 매 세션마다 설명할 필요 없음 * 훅으로 알림·로깅 등 이벤트 기반 자동화를 추가 *** ### 관련 공식 문서 * Claude Code 설정: * Claude Code Hooks: * CLAUDE.md 작성법: ### Ref * 룰을 벗어나지 않게 {% embed url="" %} {% embed url="" %}