donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/CLAUDE.md
T

33 KiB
Raw Permalink Blame History

LLM Wiki — Claude Code 운영 규칙

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

1. 이 저장소의 목적

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

최상위 원칙

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

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

메타 정보

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

핵심 흐름

캡처:  /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 참조).
  • 템플릿 (출력 형식 정의):
  • 진행 중 프로젝트 노트 (raw/project-notes/):

3. Obsidian 규약 (필수)

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

4. 메타데이터 표준

모든 wiki/ 문서 frontmatter:

---
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 등). 슬러그는 구현 내용 을 48 단어로 표현해야 한다. 계층 정보는 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/.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 확인

출력 (외부 공개용)

  1. 외부 공개용은 반드시:
    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 링크로 근거를 댄다. 비유는 의도적 단순화로 표시하고 사실로 인용하지 않는다.

문서 승급 단계

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 문서에서만 파생된다.
Reference in New Issue View Git Blame Copy Permalink