llm-wiki/CLAUDE.md

# LLM Wiki — Claude Code 운영 규칙

이 파일은 **운영 규칙**만 담습니다. 개념 설명, 공식 문서 요약, 프로젝트 본문, 면접 답변, 블로그 초안은 절대 여기에 두지 않습니다.

---

## 1. 이 저장소의 목적

원본 자료(`raw/`)를 **검증된 실무 기술 문서**로 변환하고, 그로부터 외부 산출물을 파생하는 **파이프라인**입니다.

### 최상위 원칙

```text
raw 자료는 증거다.
wiki/concepts와 wiki/projects는 검증된 실무 기술 문서(canonical)이다.
interview / portfolio / blog는 canonical에서 파생된 산출물이다.
```

자세한 위계와 파생 규칙은 §15.

### 메타 정보

- 주된 도메인: 백엔드 / 인프라
- 그 외 주제도 허용. 단, 모든 문서는 동일한 규칙을 따라야 함.
- 최종 사용처: 면접, 이력서, 포트폴리오, README, 블로그.

### 핵심 흐름

```text
캡처:  /daily | /branch                  → raw/
변환:  raw/                              → /ingest → wiki/concepts + wiki/projects (canonical)
품질:  wiki/*                            → /tag · /lint · /sync · /query (+ 브랜치 게이트: /depth · /coverage)
파생:  wiki/concepts + wiki/projects     → /interviewize · /blogify · /explain · (wiki/portfolio 수동)
```

파생 산출물(`wiki/interview/`, `wiki/portfolio/`, `wiki/blog/`)은 **반드시** canonical 경유. raw 또는 daily/branch에서 직접 가지 못함.

---

## 2. 디렉터리 역할

| 위치 | 역할 |
|------|------|
| `CLAUDE.md` | 이 파일. 운영 규칙만. |
| `raw/` | 가공 전 원본 자료. 출처 보존. |
| `wiki/` | 정리된 재사용 가능 지식. |
| `templates/` | 출력 형식 정의. |
| `.claude/commands/` | 반복 작업 자동화 — **캡처**: `/daily`, `/branch`, `/branch-spec`, `/project`, `/project-spec` · **변환/품질**: `/ingest`, `/tag`, `/lint`, `/sync`, `/query`, `/depth`, `/coverage`, `/migrate-claims` · **출력**: `/projectize`, `/interviewize`, `/blogify`, `/explain`. |

### 주요 문서 wikilinks

운영 규칙(본 파일)과 함께 사용되는 핵심 문서들. Obsidian Graph에서 이 hub와 연결되어야 함:

- **Hub / 로그**: [[wiki/llm-wiki]] (vault MOC), [[wiki/log]]
- **메타 규약 / Rules (필수 정독, top-level `rules/` — Claude / Antigravity / codex-cli 공유 SSOT)**:
  - [[rules/linking-rules]] — Mandatory upward link 표 + 다중 부모 + 양방향 작성 패턴 + Hub/MOC 명명 컨벤션 (named hub, `index.md` 금지) + 검증 체크리스트. 모든 raw/wiki 문서가 따르는 single source of truth.
  - [[rules/naming-conventions]] — 파일·디렉토리·branch prefix·다이어그램 명명 규칙.
  - [[rules/tag-taxonomy]] — `tags:` 5계층 허용 어휘 + 동의어 정책.
  - [[rules/diagram-standards]] — **컨퍼런스급 다이어그램 표준 v2 (minimalist-first)** — Toss SLASH / Kakao if(dev) / Naver DEVIEW 수준. draw.io 아키텍처 + Mermaid sequence/ER 작성 시 정독. element budget (Vertex ≤ 10 / Edge ≤ 8 / Callout ≤ 1) + 8항 self-check (§14) 모두 만족 필수. `wiki-diagram-reviewer` 가 ≥95/100 점 채점.
  - [[rules/evidence-first-research]] — multi-doc 정독 시 verbatim quote + 명명된 실패 모드.
  - [[rules/reporting-standards]] — multi-doc 보고서 §0~§8 템플릿 + Output Split + Verdict 산식.
  - [[rules/advisory-depth]] — 7 Contracts (Goal/Assumption/Action chain · Exhaustive Options · Plan Gap · Direct-Response · Citation Discipline · Self-Grep · Forbidden Words).
  - [[rules/prose-style]] — 파생 산출물(interview/blog/portfolio) 한국어 윤문 + "쉬운 설명" 기준. 존댓말 · 적당히 긴 길이 · 개발 용어만 영어 · 전문 용어 한 줄 풀이 · 쉬운 요약 먼저 + 명명된 실패 모드. `/interviewize`·`/blogify` 가 참조.
  - [[rules/branch-depth-gate]] — 브랜치 노트가 *코딩 착수해도 되묻지 않을 만큼* 깊은지 판정하는 4축·깊이 사다리(L0~L3)·명명된 실패 모드. `/depth` 명령(`.claude/commands/depth.md`)과 `branch-depth-auditor` agent + 결정론 린터 `.claude/hooks/wiki_structure_lint.py`가 함께 집행.
  - [[rules/consistency-contract]] — 문서 간 일관성 계약: Single-Owner(결정·관심사당 owner 문서 정확히 1개) + Reference-Only(타 문서는 `[[owner]] D<n>` 포인터 + 1줄 요약만, 재진술 금지) + owner 변경 시 역참조 비차단 전파 알림. `/sync` 명령 + `wiki-consistency-auditor` agent + 결정론 검사기 `.claude/hooks/wiki_consistency_check.py` 가 집행.
  - [[rules/extraction-tiering]] — Tiered Extraction 계약: 4-Tier(T0 결정론 / T1 외부 구독 codex·agy / T2 haiku / T3 sonnet / T4 opus) + 5계명(외부 CLI = read-only 추출기 · 무검증 발췌 소비 금지 · engine funnel 필수 · opus 에 raw corpus 반입 금지 · fallback 사다리 기록). `extraction-broker` agent + `scripts/deep-research/deep_research/extract.py`(quote-verifier 내장)·`vote.py`(cross-vendor quorum 표) + `wiki_consistency_check.py --packets` 가 집행.
  - [[rules/subagent-input-contracts]] — controller가 dispatch *전에* 모을 입력을 agent/명령별 form schema로 고정(3-rule: Pre-fill · Missing→행동 명시 · No SSOT 이중화) + 명명된 실패 모드. `/branch-spec`(`.claude/commands/branch-spec.md`)이 이 계약을 소비해 빈 브랜치 노트를 *되묻지 않을 수준*으로 채움(근거 없으면 자동조사 → 실패 시 `UNSUPPORTED_DECISION` 라벨 → 끝에 `/depth` + `/coverage` 자동 게이트, 루프 천장 2회).
- **Claude Code 자동화** (`.claude/`) — narrative 스타일, `tools:`/`model:` frontmatter:
  - `.claude/skills/wiki-workflow/SKILL.md` — 문서 작업 진입점. 사용자 의도에 따라 적절한 agent dispatch.
  - `.claude/agents/wiki-doc-author.md` — 새 raw 문서 생성 또는 기존 비-template 문서 마이그레이션 (category-aware, mode: create | migrate).
  - `.claude/agents/wiki-source-summarizer.md` — URL → raw 자료 (verbatim quote + self-grep).
  - `.claude/agents/wiki-link-verifier.md` — orphan / broken wikilink / Cluster 누락 감사 (read-only).
  - `.claude/agents/wiki-research-lane.md` — 다수 raw 정독 → 합성 권고 (read-only).
  - `.claude/agents/extraction-broker.md` — bulk 발췌 브로커 (haiku, read-only) — 외부 구독 CLI 드라이버(`extract.py`) 구동 + 실패분 자가 재발췌 + 검증된 digest 만 반환 (`rules/extraction-tiering.md` T1+T2). **Claude Code 전용** — 3-플랫폼 포팅 대상 아님 (T2 haiku 브로커는 Claude 모델 계층; Codex/Antigravity 에선 오케스트레이터가 `extract.py` 를 직접 호출).
  - `.claude/agents/wiki-adversarial-reviewer.md` — 리서치/감사 draft falsification (KEEP/DOWNGRADE/REJECT 권고, read-only).
  - `.claude/agents/wiki-diagram-reviewer.md` — `.drawio` 다이어그램 채점 (≥95/100 PASS, read-only).
  - `.claude/agents/wiki-decision-researcher.md` — 기술 결정 alternatives 조사 (read-only; WebSearch + 사용자 승인 → **dispatch 요청 방출**, `wiki-source-summarizer` × N×2 실 dispatch 는 controller 가 수행 → 비교 매트릭스 + 조건부 권고).
  - `.claude/agents/project-readiness-auditor.md` — project-note(hub) 완성도 의미 게이트 (read-only, ca-skeleton caliber 판정). **Claude Code 전용** — Codex/Antigravity 포팅 없음(`/project`·`/project-spec` 파이프라인은 3-플랫폼 패리티 예외). **투자 파이프라인(`/invest-*` 6개 명령 + invest 템플릿)도 Claude Code 전용 — Codex/Antigravity 포팅 대상 아님** (개인 투자 관리용, `/project` 파이프라인과 동일한 3-플랫폼 예외).
- **Antigravity CLI 자동화** (`.agents/agents/<name>/agent.json`) — `.claude/`와 동일 10개 agent (단 `project-readiness-auditor`·`extraction-broker` 는 Claude 전용 — 3-플랫폼 포팅 대상 아님) (위 7개 + `branch-depth-auditor`·`coverage-auditor`·`wiki-consistency-auditor`) 의 Antigravity 포트. Antigravity CLI native subagent registry 형식 (workspace = `.agents/agents/<name>/agent.json`, global = `~/.gemini/antigravity-cli/agents/<name>/agent.json`). 각 `agent.json` 의 `config.customAgent.systemPromptSections[0].content` 가 system prompt, `toolNames` 로 도구 권한 제어 (read-only agent 는 `write_to_file`/`replace_file_content`/`multi_replace_file_content` 제외). **G1 Pre-Read Proof, G2 Post-Write Validator, G3 Output Schema with `{{ }}` placeholders, G4 Enumerated STOP Conditions** 4가지 hard gate가 system prompt 본문에 포함됨 (Gemini의 narrative 무시 / 자체 검증 건너뛰기 / NEEDS_CONTEXT 회피 / 출력 스키마 흐트러짐을 차단). 동일 `rules/`와 `templates/` 참조. **System prompt SSOT 는 `.agents/plugins/wiki-superpowers/agents/*.md`**. Antigravity CLI 가 직접 인식하는 것은 `.agents/agents/<name>/agent.json` 이므로, SSOT `.md` 를 편집하면 대응 `agent.json` 도 함께 갱신해야 반영됨(안 하면 변경 사항 미반영). ⚠️ **자동 생성기 `scripts/sync_automation.py` 는 현재 repo 에 없음**(2026-06-06 확인; `scripts/` 는 존재하나 `sync_automation.py` 만 부재 — 2026-07-14 재확인) — 복원 전까지 SSOT↔variant 동기화는 **수기**로 하고 3 플랫폼 패리티를 직접 유지한다.
- **Codex CLI 자동화** (`.codex/agents/`) — `.claude/`와 본문은 같은 agent. codex 환경에 맞춰 frontmatter 에서 `tools:`/`model:` 제거 + 본문 tool 표현 일반화. Codex 는 **native subagent 를 `.codex/agents/*.toml` 로 등록**(`developer_instructions` + `sandbox_mode`) — `.agents/plugins/wiki-superpowers/agents/<name>.md` 가 SSOT, `.toml` 은 그 대응 variant(생성기 부재 시 수기 동기화 — 위 ⚠️ 참조). 권한은 `.claude/agents/<name>.md` frontmatter `tools:` 에서 파생(`Edit`/`Write` → `workspace-write`, 없으면 `read-only`). 호출 패턴은 `.codex/agents/README.md` 참조. 동일 `rules/`와 `templates/` 참조.
- **Commands(슬래시 명령) 3-플랫폼 동기화** — `.claude/commands/*.md` 가 SSOT (현재 23개; 이 중 invest-* 6개 + `project`·`project-spec` 2개 = **8개는 Claude 전용 비동기화**, 나머지 15개가 mirror 대상). mirror 대상은 **Codex skills** (`.agents/skills/<cmd>/SKILL.md`, `$<cmd>`/`/skills` 호출) 와 **Antigravity workflows** (`.agents/workflows/<cmd>.md`, `/<cmd>` 슬래시) 로 복제. 인자는 placeholder 없이 자연어(각괄호 prose). ⚠️ **동기화 생성기 `scripts/sync_automation.py` (agents·commands 단일 생성기, `--check` drift 검사 포함) 는 현재 repo 에 없음**(2026-06-06 확인) — 복원 전까지 SSOT(`.claude/commands/*.md`) 편집은 대응 Codex skill + Antigravity workflow 파일에 **직접 반영**해 3 플랫폼 패리티를 유지한다.
- **Hooks / 프로젝트 지침 3-플랫폼** — 훅 스크립트 SSOT 는 `.claude/hooks/` 1벌(`wiki_claim_gate.py` claim 추적 게이트 + `wiki_structure_lint.py` 구조 린트, repo 루트는 파일 위치 기반 동적 해석). **Codex**: `.codex/hooks.json` 이 같은 스크립트를 PreToolUse(claim gate)/PostToolUse(structure lint)로 연결(대화형 codex 에서 hook trust 검토 후 active). `.codex/config.toml` 의 `project_doc_fallback_filenames = ["CLAUDE.md"]` 는 해당 디렉터리에 `AGENTS.md` 가 **없을 때만** 쓰이는 fallback 이다 — 루트 `AGENTS.md` 가 존재하는 현재 구조에선 발동하지 않으므로, Codex 는 `AGENTS.md`(CLAUDE.md 의 ≤150줄 요약)를 진입점으로 로드한다. CLAUDE.md 는 그 요약이 가리키는 모든 모델 공통 **운영-규칙 SSOT** 로 유지된다(Codex 가 CLAUDE.md 를 자동 지침으로 직접 선택한다고 가정 금지). **Antigravity**: `.agents/hooks.json` → global `wiki_hard_gate.py` 가 리포트 출력 품질(self-grep proof/금지어/Verdict 공식/adversarial review)을 강제. claim_gate·structure_lint 의 antigravity 포팅은 별도 follow-up (출력 `{decision:deny}` 어댑터 필요 — `docs/superpowers/notes/2026-06-04-phase2-antigravity-hook-coverage.md` 참조).
- **템플릿 (출력 형식 정의)**:
  - [[templates/concept-template]] — `wiki/concepts/` 일반 개념
  - [[templates/project-template]] — `raw/project-notes/` 프로젝트 hub (아키텍처·시퀀스 다이어그램 필수) → `wiki/projects/` 로 추출 (raw hub 전용)
  - [[templates/wiki-project-template]] — `wiki/projects/` canonical 실무 적용 문서 슬라이스 (raw hub에서 `/ingest`·`/projectize` 로 추출, `source_type: project`)
  - [[templates/interview-template]] — `wiki/interview/` 면접 답변
  - [[templates/raw-source-template]] — `raw/official-docs/`, `raw/company-tech-blogs/` 외부 자료 원본 발췌
  - [[templates/source-summary-template]] — `wiki/concepts/` 외부 자료 검증 요약
  - [[templates/daily-note-template]] — `raw/daily-notes/` 일일 노트
  - [[templates/branch-note-template]] — `raw/branch-notes/` 브랜치 작업 노트
  - [[templates/daily-task-develop-template]] — `raw/daily-tasks/develop/` 일일 개발 트랙 실습 과제 (사수→신입 과제 형식, 매일 아침 ~2h)
  - [[templates/daily-task-infra-template]] — `raw/daily-tasks/infra/` 일일 인프라/운영 트랙 실습 과제 (매일 아침 ~2h, 운영 회복력 anchor 포함)
  - [[templates/error-note-template]] — `raw/errors/` 트러블슈팅 기록
  - [[templates/interview-prep-template]] — `raw/interviews/` 면접 준비 원본 노트
  - [[templates/job-posting-template]] — `raw/job-postings/` 채용공고 → 블로그 글감
  - [[templates/blog-topic-template]] — `raw/blog-topics/` 채용공고가 아닌 블로그 글감 원석
  - [[templates/lecture-note-template]] — `raw/lectures/` 강의·강연 노트
  - [[templates/portfolio-template]] — `wiki/portfolio/` 포트폴리오 (canonical derived)
  - [[templates/blog-template]] — `wiki/blog/` 블로그 초안 (canonical derived)
  - [[templates/explainer-template]] — `wiki/explainer/` 1타강사 설명 문서 (canonical derived, **개인 이해용** — 외부 공개 아님). 0~4단 + 대안 5단(a~e) 틀 강제, "대안=문제를 다르게 정의한 답" 구조
  - [[templates/invest-field-card-template]] — `wiki/invest-concepts/` 분야 지식 카드(노드). `[[wiki/invest-concepts/field-map]]` 허브 하위. drivers vs linkages 분리 + 모든 관계 행 `[검증]/[가설]` 라벨 강제(뇌피셜 차단). 매일 `/invest-daily` "분야 관찰"이 카드 예측 vs 실측을 대조해 가설→검증 승격. invest 파이프라인 — **Claude 전용**(3-플랫폼 포팅 예외). 설계: `docs/superpowers/specs/2026-06-08-invest-field-map-design.md`
- **진행 중 프로젝트 노트** (raw/project-notes/):
  - [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl 운영 계약 canonical SSOT
  - [[raw/project-notes/project-infra-overview]] — 사용자 본인 프로젝트 인프라 개요 (작성 중)

---

## 3. Obsidian 규약 (필수)

- 모든 문서 상단에 **YAML frontmatter** (`---` 블록).
- 문서 간 연결은 **`[[wikilink]]`** 사용. 상대경로 링크 금지.
- `concepts/`와 `projects/`는 서로 양방향 링크. 그래프뷰가 의미를 가져야 함.
- 파일명은 영문 kebab-case 권장 (예: `connection-pooling.md`). 한글 파일명도 허용하되 일관성 유지.

---

## 4. 메타데이터 표준

모든 `wiki/` 문서 frontmatter:

```yaml
---
title: 문서 제목
source_type: official-doc | company-tech-blog | personal-blog | lecture | project-note | error-note | job-posting | blog-topic | interview-prep | daily-note | branch-note | daily-task | project | concept | interview | portfolio | blog | explainer | llm-generated | invest-daily | invest-research | invest-ledger | invest-concept | invest-strategy | invest-plan
status: raw | draft | reviewed | verified | published-ready | stale | needs-confirmation
confidence: high | medium | low | unknown
tags: [backend, db, ...]
related_projects: [project-name]
last_reviewed: YYYY-MM-DD
---
```

**source_type 허용 어휘 (실제 templates 와 일치)**: raw 카테고리는 카테고리명을 그대로 source_type 으로 사용 — `lecture-note-template.md` → `source_type: lecture`, `error-note-template.md` → `source_type: error-note`, `interview-prep-template.md` → `source_type: interview-prep`. wiki 카테고리도 동일 (`concept-template.md` → `source_type: concept`, `blog-template.md` → `source_type: blog`). 이전에 사용되던 `error-log`, `interview-note`, `lecture-note` 는 deprecated. wiki/projects canonical 슬라이스는 `source_type: project` (`wiki-project-template.md`)를 쓰고, `project-note`는 `raw/project-notes/` 프로젝트 hub 전용이다.

**투자 도메인 source_type (Claude 전용 파이프라인):** `invest-daily`(raw/invest-daily/), `invest-research`(raw/invest-research/), `invest-ledger`(raw/invest-ledger/), `invest-concept`(wiki/invest-concepts/), `invest-strategy`(wiki/invest-strategy/), `invest-plan`(wiki/invest-plan/). 각 카테고리명을 그대로 source_type 으로 사용. 개인 투자 관리용이며 개발 프로젝트와 분리된 트리.

`raw/` 문서는 최소한 `title`, `source_type`, `url`(있다면), `tags`만 있어도 됨.

**예외 (구조적 파일):** `wiki/llm-wiki.md` (vault MOC), `wiki/log.md` 는 지식 문서가 아닌 hub/로그이므로 위 표준에서 면제됨. `title`만 있으면 됨.

---

## 5. 출처 신뢰도 기준

| source_type | 취급 방식 |
|-------------|----------|
| `official-doc` | 기준/정의로 사용 가능 |
| `company-tech-blog` | 사례/관점. **공식 best practice로 취급 금지** |
| `personal-blog` | 참고 자료 |
| `lecture` | 학습 자료 (강의·강연) |
| `project-note` | 포트폴리오 증거 후보 |
| `error-note` | 트러블슈팅 사실 기록 |
| `interview-prep` | 면접 준비 원본 노트 |
| `job-posting` | 채용공고 (블로그 글감 시드) |
| `blog-topic` | 채용공고가 아닌 작업·학습·트러블슈팅 기반 블로그 글감 원석. canonical 정제 전 raw 후보이며, `wiki/blog/` 직접 생성 근거가 아님 |
| `daily-note` | 그날의 혼합 기록. **그 자체는 wiki로 옮기지 않음**. `/ingest`가 promotable 항목만 추출 |
| `branch-note` | 단일 브랜치의 TODO·결정·진행 기록. **머지 후에도 raw에 영구 보관**, verified 결과만 `/ingest`로 wiki/projects/에 추출 |
| `daily-task` | 매일 아침 학습용 실습 과제 (develop / infra 두 트랙, 트랙별 1과제 ~2h, 사수→신입 형식). **raw에 영구 보관**, `done` + `actually-implemented`/`locally-verified` 등급 항목만 `/ingest`로 `wiki/concepts/` 또는 `wiki/projects/`에 추출. Hub: `[[raw/daily-tasks/README]]` |
| `concept` | wiki/concepts canonical 일반 개념 |
| `project` | wiki/projects canonical 실무 적용 문서 (검증된 내 프로젝트 사실, `verified` 지향) |
| `interview` | wiki/interview canonical 면접 답변 (derived) |
| `portfolio` | wiki/portfolio canonical (derived) |
| `blog` | wiki/blog canonical (derived) |
| `explainer` | wiki/explainer canonical 의 1타강사 설명 (derived). **개인 이해용 — 외부 공개 금지.** canonical 경유 필수, 새 claim 생성 금지(canonical 재구성만), 비유는 의도적 단순화이므로 사실 인용 불가 |
| `invest-daily` | 그날의 거시 자금흐름 조사. **수치마다 출처+조사시점 필수**. 영구 보관, `/invest-ingest`로 검증분만 추출 |
| `invest-research` | 특정 분야/자산 심층 조사. verbatim 인용 보존. canonical 정제 전 증거 |
| `invest-ledger` | 실제 매매 기록(사실). 영구 보관. wiki로 옮기지 않음 |
| `invest-concept` | wiki/invest-concepts canonical 투자 개념 |
| `invest-strategy` | wiki/invest-strategy canonical 전략 규칙. **면허 자문 아님 고지 필수** |
| `invest-plan` | wiki/invest-plan canonical 활성 투자 계획 |
| `llm-generated` | 검토 전 초안. **high confidence 금지** |

---

## 6. 프로젝트 증거 등급

프로젝트 관련 진술은 **항상** 다음 중 하나로 분류:

- `actually-implemented` — 코드에 존재함
- `locally-verified` — 로컬 또는 dev 환경에서 동작 확인
- `prod-verified` — 운영(prod) 환경 검증. 로그·측정값·인시던트·릴리즈 노트 등 근거 보유
- `documented-only` — 문서/README에만 존재
- `planned` — 계획만 있음
- `needs-confirmation` — 확인 필요

### 외부 공개 산출물 허용 등급

| 산출물 | 허용 등급 |
|--------|-----------|
| `wiki/interview/` | `actually-implemented` / `locally-verified` / `prod-verified` |
| `wiki/portfolio/` | `actually-implemented` / `locally-verified` / `prod-verified` |
| `wiki/blog/` | `wiki/concepts` 출처 + 위 3등급 |
| 이력서 / README | 가능하면 `prod-verified`, 아니면 `locally-verified`임을 본문에 명시 |

`documented-only` / `planned` / `needs-confirmation`은 외부 공개에 **절대 금지**.

---

## 7. 원본 보존 규칙

- 외부 URL은 링크만 두지 말고 **핵심 인용 3–5문장을 raw 문서 본문에 발췌 보존**.
- 가능하면 archive.org 스냅샷 URL을 frontmatter `archive_url`에 병기.
- 인용 시 출처와 원문을 분명히 구분 (예: `> 원문...`).

---

## 8. Stale 판정 기준

`/lint`는 다음을 stale 후보로 보고:

- `last_reviewed`가 **90일 초과** → `status: stale` 후보
- `confidence: low` + `last_reviewed` **30일 초과** → 재검토 필요
- `needs-confirmation` 상태로 **14일 이상** 방치된 문서 → 알림

---

## 9. 출력 언어

- 기본: **한국어**
- 코드, CLI 명령어, 공식 용어(예: `connection pool`, `idempotent`)는 원문 유지.
- 면접 답변용 문서는 말로 했을 때 자연스러운 문장으로.
- **파생 산출물(`wiki/interview/`·`wiki/blog/`·`wiki/portfolio/`) 본문의 문체·윤문은 [[rules/prose-style]] 를 따름** — 존댓말 · 적당히 긴 길이 · 개발 용어만 영어(나머지 한국어) · 전문 용어 첫 등장 시 한 줄 풀이 · 쉬운 요약 먼저. 윤문이 사실 등급을 바꾸지 않음.

---

## 10. 작업 우선순위

1. 사실 정확성 > 표현 매끄러움
2. 출처 명시 > 빠른 작성
3. 과장 방지 > 강한 어조
4. 재사용 가능성 > 단발성 완성도

---

## 11. 절대 금지

- 출처 없는 단정적 진술
- 공식 문서와 기술블로그 혼동 (예: "Netflix가 그렇게 하니까 공식이다")
- `documented-only` / `planned`를 `actually-implemented`처럼 표현
- LLM 생성 내용을 검증 없이 `high` confidence로 분류
- raw에만 자료를 넣고 wiki로 변환하지 않은 채 방치 (단, `raw/daily-notes/`·`raw/branch-notes/`·`raw/daily-tasks/`는 영구 보관 정책)
- `wiki/llm-wiki.md` (vault MOC) 갱신 누락
- 면접/이력서 문장에 검증 안 된 표현 사용
- **파생 산출물(`wiki/interview/`, `wiki/portfolio/`, `wiki/blog/`)을 canonical 경유 없이 생성**
- **raw 또는 daily/branch에서 외부 산출물 직접 생성**
- **원천 canonical 문서의 status가 `reviewed | verified | published-ready` 미만인 상태에서 파생 산출물 생성**
- **`/ingest`로 `wiki/interview/`·`wiki/portfolio/`·`wiki/blog/`에 문서 작성**
- **branch-note 슬러그에 numbered hierarchy 사용** (`feature-X-1`, `feature-X-1-2` 등). 슬러그는 **구현 내용** 을 4~8 단어로 표현해야 한다. 계층 정보는 frontmatter `parent_branch:` + `## Parent` 섹션으로만. 자세한 룰은 `rules/naming-conventions.md` §2.1.2~§2.1.6.
- **`develop-` prefix 사용** — 제거된 prefix. 기능 구현 작업은 규모 무관 `feature-`. 기존 `develop-*` 슬러그는 `wiki-doc-author` mode=migrate 로 점진적 rename 권고 (자동 mv 금지, wikilink 영향 검토 필요).
- **branch-note 의 §구현 가이드 (Implementation Specification) 에 *근거 없는 결정* 작성** — §15.5 참조. 모든 sub-section / row / cell 은 본 branch 의 `Decision ID` + `Supporting Claim ID` reference 필수. 근거 없는 detail (메커니즘 / 명명 / glob / algorithm) 은 `UNSUPPORTED_IMPL_DECISION` 라벨 + 사용자 trade-off 한 줄 *명시*. 라벨 누락 = 다음 작업자가 *근거 있는 결정 vs 임의 trade-off* 를 구분 불가.
- **branch-note §구현 가이드에 *본 branch 결정 범위 밖* cell 작성** — 도메인 특화 (ca-tmpl skeleton 범위 밖) 또는 다른 branch 결정 영역 (security/persistence/HTTP-standard 등) 의 detail 은 §구현 가이드에 *남기지 않음*. 별도 branch 또는 canonical SSOT 로 이관하고, 이관 history 만 별도 § "Audit & Findings" 등에 보존.

---

## 12. Hub / MOC 정책

- `wiki/llm-wiki.md` 는 vault 전체의 **Map of Content (MOC)** 수준. 모든 문서를 손으로 나열하지 않음.
- 상세 목록은 Obsidian Dataview 쿼리 또는 `/query` 명령으로 동적 생성.
- 새 카테고리 / 주요 허브 문서가 생기면 `wiki/llm-wiki.md` 업데이트.
- 다중 sub-doc 을 가진 nested 프로젝트는 sibling **named hub** (`wiki/projects/<slug>.md` + `wiki/projects/<slug>/` 폴더) 패턴 강제. `index.md` 사용 금지. 자세한 룰은 [[rules/linking-rules]] §12.

---

## 13. log.md 정책

- `wiki/log.md`에는 `/ingest`, `/tag`, `/lint` 실행 시 다음 형식으로 한 줄 추가:

```
YYYY-MM-DD HH:mm /command — input → output (간단 메모)
```

- 사람이 일일이 읽지 않음. 디버깅과 회고용.

---

## 14. 명령어 우선순위

명령어는 역할별로 3그룹:

### 캡처 (raw 입력)

- 하루 시작 시 → `/daily` (raw/daily-notes/YYYY-MM-DD.md 스캐폴딩)
- 새 브랜치 시작 시 → `/branch <name>` (raw/branch-notes/<name>.md 스캐폴딩)
- 새 프로젝트 시작 시 → `/project <slug>` (스캐폴딩) → `/project-spec <slug> <목표>` (깊은 조사 + readiness 게이트). project-note hub 를 ca-skeleton 수준으로 채운 뒤, §8.0 Branch 분해표를 `/branch`·`/branch-spec` 로 전개.
- 외부 자료 / 프로젝트 메모 → raw/ 해당 카테고리에 직접 작성

### 변환 / 품질 (raw → wiki)

여러 명령이 가능한 상황이면 다음 순서로 판단:

1. raw에 미변환 자료가 있으면 `/ingest` 우선. **`/ingest`의 목적지는 `wiki/concepts/` 또는 `wiki/projects/`로 제한** (파생 산출물 직접 생성 금지). `raw/daily-notes/`·`raw/branch-notes/`는 항목 단위 추출만.
2. 새 wiki 문서가 생기면 `/tag` 검토
3. 주간 1회 이상 `/lint` — canonical 우회·status 미달 파생 검사 포함
4. 문서 정리 시 `/sync` — 문서 간 모순·위임 동기화 (결정론 검사기 + 참조 엣지 의미 대조 + fix-plan, `rules/consistency-contract.md`)
5. 질의는 `/query`로 시작, 필요 시 raw 확인

### 출력 (외부 공개용)

6. 외부 공개용은 반드시:
   1. 원천 canonical 문서가 `reviewed | verified | published-ready` 상태
   2. `/lint` 통과
   3. 그 후 `/projectize` / `/interviewize` / `/blogify` 또는 `wiki/portfolio/` 수동 작성

---

## 15. 문서 위계 및 파생 규칙

§1의 최상위 원칙(`raw 자료는 증거 / canonical / 파생`)을 운영 규칙으로 풀어 쓴 섹션. 모든 명령은 이 섹션을 강제합니다.

### Canonical Layer (실무 기술 문서)

#### `wiki/concepts/` — 공식 개념 + 사례 + 트레이드오프

필수 요소:
- 공식 기준이 무엇인지
- 사례와 공식 기준의 차이
- 트레이드오프 / 한계
- 흔한 오해
- 프로젝트 연결 지점 (링크만, 본문에 "내가 했다" 금지)
- 출처

#### `wiki/projects/` — 실무 적용 문서

필수 요소:
- 문제 배경
- 검토한 선택지
- 결정 이유
- 실제 구현 내용
- 검증 수준 (로컬 / dev / prod 중 어디까지)
- 근거 (측정값 / 로그 / PR / 테스트)
- `documented-only` · `planned`인 것과 실제 구현된 것의 분리
- 면접·포트폴리오 말할 수 있는 범위

### Derived Layer (파생 산출물)

**canonical에서만 파생.** 다른 레이어(raw, daily, branch)에서 직접 파생 금지.

| 산출물 | 허용 원천 | Sources 필수 링크 |
|--------|-----------|---------------------|
| `wiki/interview/` | `wiki/concepts/` + `wiki/projects/` | `[[wiki/concepts/...]]` 또는 `[[wiki/projects/...]]` |
| `wiki/portfolio/` | `wiki/projects/` 중심, `wiki/concepts/` 보조 | `[[wiki/projects/...]]` (필수) |
| `wiki/blog/` | `wiki/concepts/` + `wiki/projects/` | 양쪽 모두 권장 |
| `wiki/explainer/` | `wiki/concepts/` + `wiki/projects/` | `[[wiki/concepts/...]]` (필수) + `[[wiki/projects/...]]` (있을 때) |

> **`wiki/explainer/` 의 특수 지위**: interview / portfolio / blog 와 달리 **외부 공개물이 아니라 개인 이해(학습) 산출물**이다. 따라서 §6 외부 공개 허용 등급·status 게이트(`reviewed` 이상)의 적용을 받지 **않는다** (draft 상태 canonical 에서도 파생 가능). 대신 두 가지를 반드시 지킨다: (1) **canonical 경유** — raw/daily/branch 에서 직접 생성 금지, (2) **새 claim 생성 금지** — canonical 의 교육적 재구성일 뿐이며 모든 사실은 canonical 링크로 근거를 댄다. 비유는 의도적 단순화로 표시하고 사실로 인용하지 않는다.

### 문서 승급 단계

```text
raw → draft → reviewed → verified → published-ready
```

| 단계 | 의미 | 파생 산출물 사용 |
|------|------|-------------------|
| `raw` | 원본 기록. 출처/날짜만 있어도 됨 | 불가 |
| `draft` | Claude Code가 변환한 초안 | 불가 |
| `reviewed` | 사람이 구조/표현/출처 확인 | 면접 참고만, 외부 산출물 X |
| `verified` | 코드 / 로그 / 테스트 / PR / 공식 문서 중 1개 이상 근거 보유 | interview / portfolio / blog 파생 가능 |
| `published-ready` | `/lint` 통과, 과장 제거 완료 | 이력서 / README / 외부 게시 가능 |

`stale`, `needs-confirmation`은 위 진행과 직교하는 상태 표시.

### 파이프라인 강제 (명령별 허용 범위)

| 명령 | 입력 허용 | 출력 허용 | 게이트 |
|------|-----------|-----------|--------|
| `/ingest` | `raw/*` | `wiki/concepts/` · `wiki/projects/` **만** | — |
| `/projectize` | `wiki/concepts/` | `wiki/projects/` **만** | 원천 status ≥ `reviewed` 권장 |
| `/interviewize` | `wiki/concepts/` · `wiki/projects/` **만** | `wiki/interview/` | 원천 status ∈ {`reviewed`, `verified`, `published-ready`} — 미달 시 **중단** |
| `/blogify` | `wiki/concepts/` · `wiki/projects/` **만** | `wiki/blog/` | 원천 status ∈ {`reviewed`, `verified`, `published-ready`} — 미달 시 **중단** |
| (수동) | `wiki/projects/` | `wiki/portfolio/` | 본문 등급은 §6 허용 범위만 |
| `/explain` | `wiki/concepts/` · `wiki/projects/` **만** | `wiki/explainer/` | status 게이트 없음(개인 이해용). 단 canonical 경유 + 새 claim 금지 + canonical Sources 링크 필수 |

`/lint`는 위 게이트가 우회되었는지 검사 (canonical Sources 누락, status 미달 파생, 비허용 등급 사용 등).

### 근거 기반 구현 명세 (branch-note 의 §구현 가이드 작성 원칙)

branch-note 의 `## 구현 가이드 / Implementation Specification` 섹션은 *결정 (Decisions)* 과 *검증 (Claims To Verify)* 사이의 **구현자가 임의로 정해야 했던 결정** 카탈로그. 결정이 *무엇* 을 할 것인가라면 본 §는 *어디에 어떻게* 구현될 것인가의 사전 명세 — 작성 목표는 다음 구현자가 *되묻지 않아도 코드를 작성할 수 있는 수준*.

**일률적 anchor list 강제 ❌** — branch 마다 구현 내용·범위가 다르므로 sub-section 은 *이 branch 의 결정과 근거에서 도출되는 것만* 작성한다. 대신 **3-rule meta principle** 만 모든 branch 에 동일 적용:

| Rule | 의미 |
|------|------|
| **R1. Reference 필수** | 각 sub-section / row / cell 은 본 branch 의 `Decision ID` + `Supporting Claim ID` 를 reference. 근거 없는 detail 금지 — 모든 구현 detail 은 결정 + 근거의 *도출* 이어야 함. |
| **R2. UNSUPPORTED_IMPL_DECISION 명시** | 근거 raw 가 *원칙* 만 권고하고 *detail* (메커니즘 선택 / 클래스·rule 명명 / glob 패턴 / algorithm / factory API 모양 등) 은 권고하지 않는 cell 은 `UNSUPPORTED_IMPL_DECISION` 라벨 + 사용자 trade-off 근거 한 줄. *근거 있는 결정 vs 사용자 임의 trade-off* 의 경계. |
| **R3. OUT_OF_BRANCH_SCOPE 정제** | 본 branch 결정 범위 밖 cell — 도메인 특화 (ca-tmpl skeleton 범위 밖) 또는 다른 branch 결정 영역 (security/persistence/HTTP-standard 등) — 은 §구현 가이드에 *남기지 않음*. 별도 branch 또는 canonical SSOT 로 이관. 이관 history 는 별도 § "Audit & Findings" 등에 보존. |

작성 형식 예시는 `[[raw/branch-notes/feature-boundary-validation-mapping-contract]]` 의 §구현 가이드 + §Audit & Findings 참조 — 정제된 in-scope 만 §구현 가이드에 남기고, audit 결과/이관 권고는 별도 §로 분리하는 패턴.

`/lint` 검사 항목 (2026-06-10 구현 — `.claude/commands/lint.md` §A1):
- §구현 가이드의 sub-section 에 Trace 표시 (Decision ID + Claim ID) 누락
- 근거 미명시 detail 의 `UNSUPPORTED_IMPL_DECISION` 라벨 누락
- 본 branch 결정 범위 밖 row 잔존 (`OUT_OF_BRANCH_SCOPE`)

### 실무 문서의 최종 품질 기준 (10항목)

`wiki/concepts/` 또는 `wiki/projects/` 문서가 `verified` / `published-ready`로 올라가려면 다음을 만족해야 합니다.

1. 문제 배경이 있다.
2. 공식 기준이 있다.
3. 선택지가 있다.
4. 결정 이유가 있다.
5. 구현 사실이 있다.
6. 검증 증거가 있다.
7. 한계가 있다.
8. 말하면 안 되는 범위가 있다.
9. 출처가 있다.
10. 재사용 산출물은 canonical 문서에서만 파생된다.