Claude Code 설정하기: 일일 사용을 위한 12단계 규칙서

~/.claude/
├── CLAUDE.md          # 단일 규칙서
├── lessons.md         # 반복하지 말아야 할 실수 (CLAUDE.md에 의해 임포트됨)
...

*
!.gitignore
!settings.json
...

cd ~/.claude && git init && git add -A && git commit -m 

## 0. 우선순위 (Precedence)
이 파일은 스킬(skills), 플러그인(plugins), 슬래시 명령어(slash commands) 및 리포지토리의 CLAUDE.md 파일을 무효화합니다.
해당 파일들은 프로젝트 사실 정보(테스트 명령어, 코드 스타일 등)를 추가할 수 있습니다. 충돌이 발생하면 이 파일이 우선권을 가집니다.

그 다음은 기본 구조입니다:

## 1. 기본 설정 (Defaults) — 간결하게 작성; 요청 없이 절대 푸시하지 않기; '완료'가 무엇을 의미하는지 구축 전에 명시하기
## 2. 레인 (Lanes) — 🟢 / 🟡 / 🔴
## 3. 릴레이 (Relay) — 단계들
...

작게 유지하세요. 모든 세션마다 로드됩니다. 한 줄이 무엇을 바꾸는지 설명할 수 없다면 삭제하세요.

## 단계 3: 레인 (Lanes)

오탈자가 결제 흐름 변경과 같은 처리를 받아서는 안 됩니다. Claude는 모든 답변의 첫 줄에 레인을 표시해야 합니다:

`🔴 전체 · 버그 (환불이 영수증을 두 번 전송)`은 Claude가 작업의 규모를 이해했는지 한눈에 알게 해줍니다.

## 단계 4: 릴레이 (The relay)

🔴 작업은 12단계로 진행됩니다. 각 단계에는 **하나**의 소유 스킬(owner skill)이 있으며, 일부 단계에는 제가 결정하는 **중지점(STOP)**이 있습니다:

| # | 단계 (Step) | 소유자 (Owner) | 
| :---: | :--- | :--- |
| 1 | 질문 하나씩, 추천 답변과 함께 → **중지점 (STOP)** | `grill-me` |
| ... | 
🟡는 가벼운 버전(빠른 질문 후 3 → 4 → 5 → 9)을 실행합니다. 🟢은 모든 것을 건너뜁니다.

여기에 있는 스킬 중 네 개는 저의 것(`openspec-plan`, `plan-check`, `build-check`, `step-back`)이며, 각각 60줄 미만입니다. 이 네 가지 모두 시작 키트(starter kit)에 포함되어 있으며, 계획 스킬은 `plan`이라고 불립니다. 예를 들어, 전체 `plan-check`는 다음과 같습니다:

제 12단계가 필요하지 않습니다. **각 단계에 이름과 소유자, 그리고 명확한 중지점(STOP)이 필요**합니다.

## 단계 5: 스킬 (Skills), 작업당 하나의 소유자

서로 다른 출처의 스킬들은 서로 **경쟁**합니다. 저는 세 개의 TDD 스킬과 두 개의 브레인스토머러가 각각 자신이 먼저 실행되어야 한다고 주장했습니다. 그래서 이 규칙서는 라우팅 테이블을 가지고 있습니다: 작업당 하나의 소유자(owner)를 지정하고, 나머지 모두는 물러나거나 소유자에 의해 호출됩니다. 또한 겹치는 6개의 디자인 스킬(`settings.json`의 `skillOverrides`)도 비활성화했습니다.

전체 구성은 한 번에 다음과 같습니다:

-   **계획(Plan):** `superpowers:brainstorming`, `grill-me`, `grill-with-docs`, `openspec-plan`, `plan-check`, `design-an-interface`, `improve-codebase-architecture`, `zoom-out`, `explain-this`, `source-driven-development`, `new-feature`
-   **구축(Build):** `tdd` (`rigorous-coding-workflow`가 여기에 의존), `bug-fix` (먼저 빠르고 성공/실패 루프를 구축), `ponytail`, `ponytail-review`, `ponytail-audit`, `ponytail-debt`, `context-packaging`, `handoff`
-   **검토(Review):** `build-check`, `pre-merge-review`, `security-auditor` (읽기 전용), `security-repro`, `infection-gate`, `phpstan-gate`, `step-back`. `pr-review-toolkit`과 Codex는 **요청할 때만** 두 번째 의견을 제공합니다.
-   **배포(Ship):** `commit-push-pr`, `release-readiness`, `knowledge-capture`, `retro`, `daily-work`, 그리고 Addy Osmani의 `shipping-and-launch`, `ci-cd-and-automation`, `observability-and-instrumentation`, `performance-optimization`, `deprecation-and-migration`
-   **코드 이해(Understand code):** graphify와 코드 검토 그래프 MCP. 규칙은 그래프를 먼저, grep을 나중에입니다.
-   **나의 스택(My stack):** 워드프레스 에이전트 스킬들(`wp-plugin-development`, `wp-rest-api`, `wp-block-development`, `wp-playground`, `wp-phpstan`, `wp-plugin-directory-guidelines`)과 `plugin-audit`

특별한 것들은 몇 줄씩 설명합니다:

**🎨 UI/UX는 게이트가 있는 파이프라인입니다.** `ui-ux-pro-max`가 방향(팔레트, 유형, 패턴)을 선택하고 → `impeccable`이 잘 구축하며 → `break-ui`가 최악의 경우 데이터(80자 이름, 빈 목록, 이모지)를 공급하고 → `impeccable-audit` + `axe-a11y-audit`가 통과해야 합니다. 추가 항목: `review-animations`, `animation-vocabulary`, `mobile-native`, 그리고 실시간 디버깅을 위한 Chrome DevTools MCP.

**✏️ Pencil: 코딩하기 전에 디자인하다.** 제가 "목업(mock it up)"이라고 말할 때, `pen-design`은 [pen.dev](https://pen.dev) CLI를 사용하여 `.pen` 파일을 만들고 PNG 이미지를 `~/Documents/designs/<project>/<id>/`에 저장합니다. 이 도구는 절대로 덮어쓰지 않으며 (`design-v2`, `design-v3` 등), 실행 기록을 남깁니다. 재디자인의 경우, 현재 화면의 스크린샷이 `reference.png`로 들어갑니다. 그러면 이 PNG가 목표(target)가 됩니다: UI 기술들이 이를 향해 구축되며, `build-check`는 결과물의 스크린샷을 나란히 비교합니다. 제가 요청하지 않는 한 **절대** 실행되지 않습니다.

**🧪 E2E: "단위 테스트 통과" ≠ "작동함".** 사용자가 클릭할 수 있는 모든 요소에 대해 실제 사이트를 대상으로 Playwright 테스트가 수행됩니다. 수정 전에는 빨간색, 수정 후에는 초록색으로 표시됩니다. `playwright-core`가 이를 작성하고, `playwright-auth-state`가 로그인을 처리하며, `playwright-cli` / `playwright-cli-runner`는 탐색용입니다. `e2e-reviewer`는 기능이 손상된 상태에서도 통과할 수 있는 테스트를 스캔합니다.

**🔎 리서치 및 스크래핑, 필요할 때만.** `agent-reach`는 웹 및 소셜 리서치를 수행합니다. 이 쿼리들은 기기 외부로 나가기 때문에 민감한 정보가 유출되지 않으며, 소셜 로그인은 제가 요청할 때만 발생합니다. `scrapling`은 JS 기반이거나 봇 보호 페이지를 로컬에서 스크래핑하며, 일반 WebFetch가 실패했을 경우에만 작동합니다.

**🔐 동의 기반(Consent-gated).** 일부 도구는 예고 없이 실행되어서는 안 됩니다. `strix-local`(실시간 침투 테스트)은 오직 로컬 또는 소유한 호스트만을 대상으로 하며, 매번 "Attack <target> now? (y/n)"라고 묻습니다. `omniroute-session`(다른 모델을 통한 라우팅)은 항상 기기 전체가 아닌 별도의 세션에서만 실행됩니다.

**🏠 제품 계층(Product layer).** 제가 매일 작업하는 두 가지 제품(Fluent Forms 및 Fluent Player)의 경우, 수정 전에 실제 흐름 하나를 끝까지 추적하는 **추적 기술(trace skills)**을 추가합니다. 예를 들어 `trace-submission-flow`, `trace-payment-flow`, `trace-ui-api` 그리고 `trace-player-runtime-flow` 등이 있습니다. 총 18개가 존재합니다. 또한, 일반적인 소유자들 주변에 제품 래퍼(product wrappers)를 추가했습니다: `grill-change`, `ui-ux-skills`, `fluentform-pre-pr-review`, `fluentplayer-release-readiness` 등입니다. 이 패턴을 복사하세요: 일반적인 선반 위에, 여러분의 흐름 중 가장 자주 문제가 발생하는 부분에 대한 추적 기술 하나를 추가하는 것입니다.

## 6단계: 스킬 고정(Pin)하고 수정 사항 유지하기

GitHub에서 스킬을 복사하여 수정합니다. 그런데 업데이트를 하면 제가 수정한 내용이 사라집니다. 저의 해결책은 다음과 같습니다:

-   **`skills.lock`**: 각 스킬의 레포지토리와 고정된 커밋(pinned commit), 그리고 상태(`installed-upstream`, `installed-ondemand`, `consent-gated`, 또는 `skip`)를 기록합니다 (이유도 함께 기록하여 미래의 제가 다시 설치하지 않도록 합니다).
-   **`overlays/<name>.md`**: 여기에 제 수정 사항을 보관합니다. 예를 들어, 저의 `ponytail` 오버레이는 _"코드는 줄이고, 테스트 코드는 절대 줄이지 마라."_라고 적혀 있습니다.
-   **`bin/sync-skills.sh`**: 이 스크립트는 각 스킬을 고정된 커밋에서 가져와서 복사하고, 그 위에 오버레이를 추가합니다. 이 스크립트를 두 번 실행해도 두 번째는 아무 변화가 없습니다.

## 7단계: 계획은 레포지토리 외부에 존재하기

스킬들은 메모리를 공유하지 않으며, 긴 대화는 압축됩니다. 따라서 스킬들은 **파일**을 통해 작업을 인계합니다. 모든 🔴 변경 사항은 `~/Documents/openspec/<프로젝트>/changes/<id>/` 폴더를 갖게 됩니다 (스타터 키트는 더 간단한 `~/Documents/plans/<프로젝트>/<id>/`를 사용합니다):

**"변하지 않을 것(What won't change)"**은 "아무것도 망가뜨리지 않는다"는 말을 테스트 가능한 약속으로 바꿉니다. 폴더를 레포지토리 외부에 유지함으로써 계획이 실수로 PR에 올라가는 것을 막습니다.

## 8단계: 후크(Hooks): 규칙은 요청하고, 후크는 보장한다

가장 큰 교훈은 이겁니다: **`CLAUDE.md`의 규칙은 '요청'이고, 후크는 '보장'입니다.**

-   **`permissions.ask`**: `git push`와 `gh pr create`는 자동 모드에서도 항상 사용자에게 확인을 요청합니다. 이것이 가장 간단하면서도 가장 중요한 방어 장치입니다.
-   **리마인더 (Reminder) (`UserPromptSubmit`)**: 후크가 출력하는 모든 내용은 Claude의 컨텍스트에 추가되므로, 짧은 단락 하나만으로 매 프롬프트마다 규칙을 다시 한번 확립할 수 있습니다:

#!/bin/bash
  echo "<rules>Rulebook: ~/.claude/CLAUDE.md. First line: lane. Test first. Smallest change. Ask before push.</rules>"

-   **Scope guard** (`PostToolUse`): 편집 후, 파일이 계획의 `scope.txt`에 포함되어 있지 않으면 Claude에게 그 이유를 설명하고 나에게 물어보도록 합니다. 이는 **경고만 할 뿐 차단하지 않습니다(warns, never blocks)**. 왜냐하면 때로는 추가된 파일이 올바르기 때문입니다. 다만 조용히 넘어갈 수는 없습니다.
-   **Stop check** (`Stop`): Claude가 작업을 완료할 때 `git status`를 확인합니다. 소스 코드가 변경되었지만 테스트가 수행되지 않았다면, `{"decision": "block", "reason": "..."}`을 반환하고 Claude는 계속 작업해야 합니다. 이 기능은 새로운 문제마다 한 번씩 작동하므로 루프를 돌릴 수 없습니다.

저의 규칙서에는 어떤 규칙 뒤에 훅(hook)이 붙어 있는지 나열되어 있습니다. 그러면 어느 규칙은 보장되고 어느 규칙은 기대만 하는지 알게 됩니다.

전체 스크립트와 테스트는 [starter kit](https://github.com/dhrupo/claude-code-dev-os)에 있습니다.

## Step 9: 설정 테스트하기

훅(Hooks)은 코드입니다. 고장 난 scope guard는 아무것도 보고할 것이 없는 것과 똑같이 보일 수 있습니다. 그래서 `~/.claude/tests/`는 가짜 훅 입력을 각 스크립트에 파이프하여 출력을 확인합니다:

저는 140개의 단언(assertions)을 가진 7개의 테스트 파일을 가지고 있으며, `~/.claude`에 커밋하기 전에 매번 실행합니다. 또 다른 스크립트는 **컨텍스트 예산(context budget)**을 추적합니다. 이는 규칙서의 크기와 모든 기술 설명의 총합입니다. 이렇게 하면 비대화(bloat)가 느낌이 아니라 숫자로 나타납니다.

## Step 10: 검토를 통해 배우기

검토자가 내가 잡았어야 할 실제 버그를 발견하면, 저는 `lessons.md`에 한 줄을 추가합니다. 일반적인 패턴과 그것을 포착하는 확인 절차(check)입니다. 규칙서는 이 파일을 가져와서, 검토 단계는 모든 교훈을 diff와 비교하며 진행되므로, 놓친 부분이 나중에 변경 사항이 생겼을 때의 확인 절차로 바뀝니다.

같은 규칙은 Claude에게 **검토 결과에 맹목적으로 의존하지 않도록** 지시합니다. 발견된 각 항목에 대해 실제 코드를 확인한 후, 다음 중 하나를 결정합니다: 증거로 이의를 제기하거나(challenge it with evidence), 근본 원인을 수정하거나(fix the root cause), 범위를 벗어난 것으로 목록화하거나(list it as out of scope), 아니면 질문을 합니다.

## 제가 배운 것

1.  **우선순위가 있는 단일 규칙서(rulebook)**는 대부분의 'Claude가 나를 무시한다' 문제를 해결합니다.
2.  **작업당 하나의 소유자(owner).** 경쟁하는 기술들은 무작위적인 행동을 유발합니다.
3.  **규칙은 묻고, 후크(hook)가 강제합니다.** 건너뛰기 어려울 것 같은 모든 것에 후크를 배치하세요.
4.  **차단하는 것보다 경고하는 것을 더 많이 하세요.** 엄격한 후크는 비활성화되며, 그러면 아무것도 보호하지 못하게 됩니다.
5.  **결정하는 지점(범위, 계획, 푸시, PR)에서 멈추세요(STOP).** 그 사이의 모든 것은 스스로 작동하도록 두세요.
6.  **`~/.claude`를 코드로 취급하세요:** git 사용, 작은 커밋, 테스트 진행.

## 시작 체크리스트

-   [ ] `~/.claude` 디렉터리에 allowlist `.gitignore`와 함께 `git init` 실행
-   [ ] 우선순위 조항이 포함된 `CLAUDE.md` 파일 하나
-   [ ] 모든 답변의 첫 줄에 레인(Lanes) 명시
-   [ ] 이름 지정된 릴레이 단계(relay steps), 각기 다른 소유자 기술을 가지며, 명확한 STOP 지점 포함
-   [ ] 푸시 및 PR에 대한 `permissions.ask` 구현
-   [ ] 후크: 알림(reminder), 범위 보호(scope guard), 중지 확인(stop check) 등 각각 테스트를 갖춘 후크
-   [ ] 발견된 모든 버그 검토를 위한 `lessons.md` 파일