Doctrine

---
name: doctrine
description: Use when a decision has no rule or precedent to stand on — 구현·계획 중 "구체적으로 뭘 어떻게 해야 할지 모르겠고 선례도 못 찾겠는" 지점에서 실행 교리(rules) 신설·보강을 유저에게 요구하고, 받은 답을 룰로 정착시킨다. Triggers on implement Rules 갭 보고 루프가 보고하고 멈춘 시점, opord·campaign 의 추정 과업 도출에 근거 교리가 없을 때, "이거 룰로 박아두자" 류 유저 지시. Does NOT trigger on 조항이 있는데 못 찾은 경우(§2 확증이 걸러낸다), 재발하지 않는 일회성 판단, 스킬·하네스 md 정비(improve-skill), 원인·처방이 이미 선 상태에서 반영만 남은 경우(implement).
---

# Doctrine — 룰 구축 요구

**계획 스킬이 계획 단계의 하네스라면 `.claude/rules/`는 실행 단계에서 참고하는 교리다.** 이 스킬은 교리가 없어 결정이 설 자리가 없을 때, 추측으로 채우는 대신 **유저에게 교리 구축을 요구하고 받은 답을 룰로 정착시킨다.**

`implement` Rules 갭 보고 루프는 보고하고 멈춘다 — 유저 답으로 구현은 이어지지만 그 답이 룰이 되는 경로가 없다("rules 고도화 후속으로 예약한다 — 형태는 그 시점에 유저와 결정"). 이 스킬이 그 종점이다.

## 1. 진입

세 경로 전부 같은 절차(§2~§5)를 탄다.

- **실행 중 갭** — `implement` Rules 갭 보고 루프가 보고하고 멈춘 자리. 유저 답으로 구현은 바로 잇고, doctrine 은 그와 병행해 §2~§5 를 진행한다 — 룰 반영 완료는 구현 재개의 선행 조건이 아니다 (반영 시점은 §5 가 정한다).
- **계획 단계 교리 점검** — `opord` §3-4·`campaign` §2-1 의 **추정 과업 도출**(명시 안 됐지만 rules·아키텍처가 딸려 붙이는 것)에서 근거 교리가 없을 때. **계획을 멈추지 않는다** — 요구를 계획 스킬의 질문 라운드에 실어 보내고, 그 자리에서 안 서면 가정으로 박아 초안을 낸다(opord 1-라). 교리 자체가 얇아 추정 과업을 하나도 못 뽑는 수준이면 그 사실을 먼저 보고한다 — 계획이 헛돈다.
- **유저 직접 호출** — "이거 룰로 박아두자" 류 지시. §2 확증은 그대로 밟는다.

## 2. 갭 확증 — 요구 전 게이트

**"선례를 못 찾겠다"와 "안 찾았다"를 구분한다.** 넷을 전부 훑고 빈손일 때만 갭이다. 하나라도 걸리면 갭이 아니라 못 찾은 것이고, 찾은 것을 따른다.

1. **`.claude/rules/` 전문** — path 매칭 자동 로드는 경로가 안 맞으면 안 뜬다. 로드된 것만 보지 말고 전 파일을 grep 한다
2. **CLAUDE.md 계층** — 루트 + 해당 경로의 child (`Domain/CLAUDE.md`·`Repository/CLAUDE.md`)
3. **`docs/` 정본** — `docs/spec/`·`coding-style-and-philosophy.md`·`화면단위구조.md`·`domain-context-map.md`
4. **동종 컴포넌트** — 형제가 같은 문제를 어떻게 풀었나. 선례는 문서가 아니라 코드에도 산다

```bash
grep -rn "<결정 키워드>" .claude/rules \
  docs/spec docs/coding-style-and-philosophy.md docs/화면단위구조.md docs/domain-context-map.md
grep -rn --include=CLAUDE.md "<결정 키워드>" .
```

CLAUDE.md 는 `--include` 로 따로 훑는다 — child 가 `Presentations/<Scene>/`·`Services/<프레임워크>/` 아래에도 산다. `*/CLAUDE.md` 같은 1-depth glob 은 루트 바로 밑 둘만 잡고 나머지를 조용히 빠뜨린다.

이 명령은 1~3 만 덮는다. **4 는 따로 훑는다** — 코드 선례는 문서와 어휘가 달라 같은 검색어로 안 잡힌다. 형제 타입명·프로토콜명을 지목해 grep 하고, 어디를 봐야 할지부터 모를 면적이면 code-analyzer 로 위임한다. 네 번째를 건너뛴 채 "부재"를 확정하지 않는다.

확증되면 갭의 종류를 판정한다 — 처방이 갈린다.

| 종류 | 신호 | 처방 |
|---|---|---|
| **부재** | 조항도 선례도 없다 | 신설 또는 기존 룰에 절 추가 |
| **충돌** | 두 조항이 다른 답을 낸다 | 우선순위를 명시하는 보강 |
| **모호** | 조항은 있는데 두 구현이 다 성립 | 판정 기준을 박는 보강 |
| **선례 분기** | 형제들이 서로 다르게 했다 | 정본을 정하는 신설·보강 |

## 3. 재발성 게이트 — 룰이 될 자격

**이 결정이 다시 오나.** 한 번 쓰고 마는 판단은 룰이 아니다 — 그 자리에서 정하고 끝낸다. 근거는 상상이 아니라 관측이어야 한다: 같은 유형의 컴포넌트가 이미 여럿이거나, 반복될 작업 유형(새 Scene·새 Repository·새 위젯 종류 등)에 걸리거나, 짝지어진 두 위치를 만드는 결정이거나.

재발 근거가 없으면 **요구하지 않는다.** 룰은 후속 작업 전부에 곱해지는 레버리지라, 한 번짜리 판단을 교리로 올리면 다음 사람이 근거 없는 제약을 물려받는다 (YAGNI).

## 4. 요구 — 유저에게 내미는 것

**추측으로 채우지 않되, 유저가 고르기만 하면 되게 재료를 갖춰 낸다.** 다섯을 담는다:

1. **막힌 결정** — 무엇을 정해야 하나, 한 줄
2. **확증 근거** — §2 에서 어디를 봤고 무엇이 없었나 (경로·grep 결과). 갭 종류도 함께
3. **성립하는 선택지와 파급** — 각 안이 동종 컴포넌트 몇 개·어느 경로에 걸리나
4. **기본안** — 하나를 추천하고 근거를 단다. 유저가 다른 답을 주면 그 답이 정본이다
5. **반영 시점** — 지금 별도 커밋 / 원 작업 끝내고 별도 사이클 / 후속 이슈로 떼기 (§5). 여기서 함께 받는다 — 룰 문안을 쓴 뒤 다시 묻지 않는다

**묻는 자리는 여기 하나다.** 계획 단계 진입이면 이 다섯을 계획 스킬의 질문 라운드 항목으로 넘긴다 — 별도 반문 라운드를 열지 않는다. 룰 내용과 반영 시점은 서로 독립이라 한 번에 물을 수 있고, 나눠 물으면 계획·구현을 두 번 멈추게 된다.

## 5. 반영 — 목적지와 시점

**목적지는 결정의 성격이 정한다.** 어디에 쓰느냐가 곧 언제 로드되느냐라, 잘못 잡으면 조항이 필요한 자리에서 안 뜬다.

| 결정의 성격 | 목적지 |
|---|---|
| 코드를 이렇게 쓴다 — 작성·구현 규칙 | `.claude/rules/` — 기존 파일의 `paths:` 가 그 경로를 덮으면 보강, 안 덮으면 신설 |
| 여기에 무엇이 있고 어떻게 얽힌다 — 모듈의 구조·개념·도메인 지식 | 그 모듈의 child CLAUDE.md (`Domain/CLAUDE.md`·`Repository/CLAUDE.md`) |
| 경로와 무관하게 상시 — 절대 규칙·짝지어진 두 위치 | 루트 CLAUDE.md 해당 절 |

**범위로 가르려 하면 안 갈린다** — `.claude/rules/domain-rules.md` 의 `paths:`(`Domain/**`·`Services/**`)와 `Domain/CLAUDE.md` 는 같은 모듈을 덮고, Repository 도 같다. 둘 다 스코프가 겹치는 게 정상이고, 가르는 건 위 표의 성격이다.

**한쪽이 아예 없으면 남은 쪽이 겸한다** — 전용 rules 파일이 없는 프레임워크는 그 child CLAUDE.md 가 구조와 작성 규칙을 함께 담는다 (`Services/StoreKitService/CLAUDE.md` 가 StoreKit 2 구현 불변식까지 담는 식). 신설로 가기 전에 그 경로에 child CLAUDE.md 가 있는지부터 본다 — 있으면 거기 보강이 기본이다. 작성 규칙 하나 때문에 광역 rules 파일에 넣으면(`domain-rules.md` 의 `paths:` 는 `Services/**` 를 덮는다) 무관한 작업마다 그 조항이 로드된다.

상시 적용 결정을 `.claude/rules/` 에 두면 `paths` 를 씌우는 순간 상시 로드가 아니게 된다 — 범위를 좁히는 대가로 조항이 침묵한다.

- **보강** — 해당 절에 조항을 더한다. 기존 조항과 충돌하면 고쳐 쓴다(덧붙이지 않는다 — 두 답이 공존하면 갭이 하나 더 생긴다)
- **신설** — `.claude/rules/<이름>.md`. frontmatter `description`(한 줄 요지)·`paths`(자동 로드 대상 glob) 필수. paths 를 빠뜨리면 파일은 있는데 영영 로드되지 않는다

조항은 **판정 가능한 문장**으로 쓴다. "적절히 처리한다"는 교리가 아니다 — 무엇이 걸리면 어느 쪽인지가 읽는 사람에게 같은 결론을 주어야 한다. 이유(why)를 한 줄 단다: 근거 없는 제약은 다음 사람이 우회한다.

**반영 시점 — 유저가 고른 것을 따른다.** 세 선택지는 §4-5 에서 이미 받아뒀다 — 지금 별도 커밋 / 원 작업 끝내고 별도 사이클 / 후속 이슈로 떼기. 그 작업의 상황(원 작업 규모·PR 경계·룰 변경 크기)에 달렸으니 세션이 단정하지 않고, 룰 md 를 썼다고 임의로 커밋하지 않는다.

지금 반영이 아닌 쪽을 고르면 **그 자리에서 기록을 남긴다** — §2 확증 근거·§4 선택지·유저가 고른 답을 원 작업 이슈의 코멘트로, 또는 후속 이슈로 (형태는 implement 플랜 갭 루프와 같다). `improve-skill` §5 의 하네스 누적 이슈는 쓰지 않는다 — 그쪽 intake 는 `triage-usage.py` actionable 신호 전용이라 다른 종류의 항목이 섞이면 triage 가 오염된다. 아무 데도 안 적고 미루는 예약만이 금지다. 잃어버리지 않는 것이 불변 조건이다.

## 6. Red Flags

- 유저가 그 자리에서 준 답이 **기존 조항의 적용일 뿐**인데 신설로 올리는 것 — 조항을 다시 읽는다
- 원 작업을 멈춘 채 룰 문안을 다듬는 것 — 요구·반영은 짧게, 구현으로 돌아간다

## 7. 종료 기록 — skill_end

한 갭 단위로 1회. `python3 .claude/hooks/log-record.py skill_end --name doctrine` (명령·compliance 규칙은 CLAUDE.md §1). §2·§3 에서 걸러 요구하지 않고 끝난 런도 종료다 — 걸러낸 것이 이 스킬의 이행이다.