fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00
parent 6c53ded9cb
commit d71669eb59
2329 changed files with 138239 additions and 172816 deletions
@@ -1 +0,0 @@
-../vault/00-system/rules/linking-rules.md
@@ -0,0 +1,241 @@
+---
+title: LLM Wiki Linking Rules
+source_type: meta
+status: stable
+tags: [meta, linking-rules]
+last_reviewed: 2026-05-25
+---
+
+# LLM Wiki Linking Rules
+
+본 문서는 **모든 raw / wiki 문서가 따라야 하는 연결 규칙**을 정의한다. 템플릿(`templates/*.md`)이 이 규칙을 강제하도록 설계되어 있고, 본 문서는 그 규칙의 single source of truth.
+
+> Layer: `templates/` — 메타 규약. 본 문서는 다른 문서를 만들 때 참고하는 정책.
+
+## 1. 핵심 원칙 — Project as the Sole Root
+
+> **모든 raw 문서는 예외 없이 branch 또는 project로 upward link 의무.** "자기 충족" 문서 없음.
+
+```
+raw/project-notes/<project>                    ← 유일한 entry point (root)
+            │
+            ▼
+raw/branch-notes/<branch>                      ← project의 직접 자식 (모든 branch)
+            │ (선택, 하위 작업 있을 때만)
+            ▼
+raw/branch-notes/<sub-branch>                  ← 부모 branch 있는 경우
+            │ (선택)
+            ▼
+raw/branch-notes/<sub-sub-branch>              ← 더 깊은 자식
+
+Leaves (branch에 매달림):                      Sources (branch에서 인용 + branch로 upward 연결):
+- raw/errors/<incident>                        - raw/official-docs/<x>
+- raw/interviews/<question>                    - raw/company-tech-blogs/<x>
+- raw/lectures/<lecture>
+- raw/job-postings/<posting>
+- raw/blog-topics/<topic>
+```
+
+**중요**: "root branch" 라는 별도 개념은 **없다**. 모든 branch 는 동등한 `raw/branch-notes/` 1차 시민이며, `parent_branch` 필드가 비어있느냐 (= project 직접 자식) 채워져 있느냐 (= 다른 branch 의 자식) 로 위치가 결정된다. `raw/project-notes/<project>` 가 유일한 cluster root.
+
+자료(공식 문서·기업 블로그·강의)도 **혼자 존재하지 않는다.** 어느 branch 의 구현 결정 근거로서 보관됨. 따라서 자료도 branch 또는 project로 upward link 의무.
+
+## 2. Mandatory Upward Link 표
+
+각 문서가 만들어질 때 **최소한 만족해야 하는 link 의무**.
+
+| 문서 종류 | Mandatory Upward Link | Mandatory 추가 |
+|---|---|---|
+| `raw/project-notes/<p>` | (root — upward 면제) | — |
+| `raw/branch-notes/<b>` — project 직접 자식 (`parent_branch:` 비어있음) | `[[raw/project-notes/<project>]]` | Sources 1개+ (단순 셋업·실험 0개 허용, §5) |
+| `raw/branch-notes/<b>` — 다른 branch 의 자식 (`parent_branch:` 채워짐) | `[[raw/branch-notes/<parent-branch>]]` (`parent_branch` frontmatter 와 일치) | Sources 1개+ |
+| `raw/errors/<e>` | `[[raw/branch-notes/<관련 branch>]]` 또는 `[[raw/project-notes/<p>]]` | 해결 근거 1개+ |
+| `raw/interviews/<q>` | `[[raw/branch-notes/<관련 branch>]]` 또는 `[[raw/project-notes/<p>]]` | — |
+| `raw/lectures/<l>` | `[[raw/branch-notes/<학습 동기 branch>]]` 또는 `[[raw/project-notes/<p>]]` | — |
+| `raw/job-postings/<p>` | `[[raw/branch-notes/<관련 branch>]]` 또는 `[[raw/project-notes/<p>]]` | — |
+| `raw/blog-topics/<t>` | `[[raw/branch-notes/<관련 branch>]]` 또는 `[[raw/project-notes/<p>]]` | canonical 전환 후보 명시 |
+| `raw/daily-notes/<date>` | 그날 작업한 branch-notes 전부 (양방향 nav) | — |
+| `raw/official-docs/<x>` | `[[raw/branch-notes/<...>]]` 1개+ 또는 `[[raw/project-notes/<p>]]` (foundational 조사 시) | URL 필수 |
+| `raw/company-tech-blogs/<x>` | 동일 — branch 또는 project | URL 필수 |
+| `wiki/projects/<project-slug>/<topic>.md` (nested, §11) | `[[raw/project-notes/<project-slug>]]` + `[[raw/branch-notes/<...>]]` 1개+ | `wiki/concepts/` 1개+ |
+| `wiki/concepts/<c>` | (canonical, no upward) | `[[raw/official-docs/...]]` 또는 `[[raw/company-tech-blogs/...]]` 1개+ + 관련 `wiki/projects/` (Project Application) |
+| `wiki/interview/<q>` | `wiki/concepts/` 또는 `wiki/projects/` 1개+ | — |
+| `wiki/portfolio/<t>` | `wiki/projects/` 필수 | — |
+| `wiki/blog/<post>` | `wiki/concepts/` 또는 `wiki/projects/` 1개+ | — |
+
+`wiki/concepts/` 만 upward 의무에서 제외됨 — canonical 일반 개념은 특정 프로젝트에 종속되지 않을 수 있음. 단 `## Project Application` 섹션에서 적용된 wiki/projects를 가리키는 것은 권장.
+
+## 3. 다중 부모 / Multi-parent
+
+같은 자료가 여러 branch에서 인용될 수 있음. 이 경우:
+
+1. `frontmatter` 의 `related_branches:` 에 모든 branch 이름 나열
+2. 본문에 `## Parent / 활용 branch` 표를 두고 각 branch + "이 자료가 정당화하는 결정" 한 줄로 기록
+
+예: `raw/official-docs/keycloak-oidc-rfc.md`
+
+```yaml
+---
+related_branches: [feature-keycloak-oauth2-proxy-oidc-flow, feature-keycloak-nginx-auth-request-integration]
+related_projects: [keycloak-patterns]
+---
+```
+
+```markdown
+## Parent / 활용 branch
+
+| Branch | 이 자료가 정당화하는 결정 |
+|---|---|
+| [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]] | provider=keycloak-oidc 설정의 RFC 근거 |
+| [[raw/branch-notes/feature-keycloak-nginx-auth-request-integration]] | nginx auth_request 통합의 OIDC handshake 흐름 근거 |
+```
+
+## 4. Parent canonical + generated Cluster reverse view
+
+v2 graph contract에서 child의 `project` / `parent_branch` frontmatter와 `## Branch Contract Packet`이 **canonical Parent edge**다. Hub의 Cluster는 이 edge에서 생성된 reverse view이며, 새 v2 문서에서 수기로 자식 소유권을 선언하지 않는다. Work Item의 decision/dependency edge는 `DEC-...@revision` / `WI-...` pinned ref로 기록한다.
+
+Hub의 자식 목록은 다음 marker **사이만** 생성·교체한다. 검사기도 이 블록만 reverse view로 대조한다.
+
+```markdown
+<!-- GENERATED: children:start -->
+- [[raw/branch-notes/<child>]]
+<!-- GENERATED: children:end -->
+```
+
+기존 문서의 수기 `## Cluster`는 legacy 내비게이션으로 보존하되, v2로 승급할 때 marker 블록으로 이관한다. marker/table이 없는 legacy 문서는 strict graph failure가 아니라 `LEGACY_GRAPH_CONTRACT` migration warning + skip으로 처리한다.
+
+Legacy 표현 예시:
+
+각 hub 문서 (`raw/project-notes/`, 자식 branch 를 가진 모든 branch) 는 본문에 `## Cluster / 묶음` 섹션을 두고 자식들을 카테고리별로 명시:
+
+```markdown
+## Cluster / 묶음
+
+### Sub-branches (세부 작업)
+- [[raw/branch-notes/<sub-1>]] — <한 줄 요약>
+
+### Sources / 근거 자료
+- [[raw/official-docs/<...>]]
+- [[raw/company-tech-blogs/<...>]]
+
+### Errors (이 branch 작업 중 발생)
+- [[raw/errors/<...>]]
+
+### Interview prep (이 작업에서 나올 면접 질문)
+- [[raw/interviews/<...>]]
+
+### Lectures (이 작업을 위해 학습)
+- [[raw/lectures/<...>]]
+
+### Blog topics / job-posting tie-ins (이 작업에서 글감)
+- [[raw/blog-topics/<...>]]
+- [[raw/job-postings/<...>]]
+- [[wiki/blog/<...>]]  (derived 시)
+```
+
+→ Obsidian 그래프뷰에서 branch가 자기 cluster의 entry point로 시각화됨. v2에서는 위 목록을 generated marker 블록 안에만 둔다.
+
+## 5. Sources 섹션 강제 — branch 는 근거 없이 만들지 않는다
+
+`raw/branch-notes/<b>` (모든 branch) 는 **최소 1개의 외부 근거**(`[[raw/official-docs/...]]` 또는 `[[raw/company-tech-blogs/...]]` 또는 `[[raw/lectures/...]]`)를 `## Sources / 근거` 표에 명시해야 한다.
+
+근거 자료가 raw 에 아직 없다면 **branch-note 작성 전에** `raw-source-template` (공식·기업 블로그) 또는 `lecture-note-template` (강의) 로 raw 에 등록 후 link.
+
+### prefix 별 Sources 강도
+
+| Prefix | Sources 강도 |
+|---|---|
+| `feature-` | **필수, 최소 1개+** (이상적으로 공식 문서 1 + 기술 블로그 1, 그리고 검토한 대안의 자료 포함) |
+| `fix-` | **필수, 최소 1개+** (재현/원인 분석의 근거) |
+| `chore-` | **권장**, 0개 허용. 0개일 경우 본문에 "외부 근거 불필요 이유" 한 줄 (예: "로컬 docker-compose 셋업, 표준 절차") |
+| `experiment-` | **권장**, 0개 허용. 동일하게 본문에 사유 한 줄 |
+
+## 6. Daily-note 의 역할
+
+`raw/daily-notes/<date>` 는 **시간축 hub**. 공간축 hub(project/branch)와 직교한다.
+
+- 매일 작성한 daily-note는 그날 작업한 모든 branch-notes를 명시
+- branch-note도 작업한 날짜의 daily-notes를 `## 관련 일일 노트` 섹션에 양방향으로 명시
+- daily-note에서 파생된 에러·인터뷰·면접·강의 노트는 해당 branch에 매달리되, daily-note 본문에도 짧게 인덱스 가능 (선택)
+
+## 7. Derived layer (wiki/interview · wiki/portfolio · wiki/blog) 파생 룰
+
+CLAUDE.md §15 강제. 다음 규칙은 그 강제의 짧은 요약:
+
+- `wiki/interview/<q>` 는 **canonical (`wiki/concepts/` 또는 `wiki/projects/`)** 에서만 파생. raw에서 직접 파생 금지.
+- `wiki/portfolio/<t>` 는 `wiki/projects/` 에서만 파생.
+- `wiki/blog/<post>` 는 `wiki/concepts/` 또는 `wiki/projects/` 에서만 파생.
+
+영감의 출처(예: `raw/blog-topics/`, `raw/job-postings/`, `raw/interviews/`)는 derived 문서의 본문에 link 가능하지만, **사실 근거(Sources)는 canonical에서만 가져옴**.
+
+## 8. 검증 체크리스트 (수동 운영, 자동화는 유보)
+
+다음 항목은 작성자가 직접 체크. 자동화(`/lint`)는 후속 라운드에 결정.
+
+문서 작성 직후 — 작성자 self-check:
+
+- [ ] frontmatter `related_branches` 또는 `related_projects` 가 채워졌는가
+- [ ] 본문에 `## Parent` 또는 그에 준하는 upward link 섹션이 있는가
+- [ ] branch-note라면 `## Sources / 근거` 가 최소 1개의 외부 자료 link를 포함하는가
+- [ ] hub 역할 문서 (`raw/project-notes/` 또는 자식 branch 를 가진 branch) 라면 `## Cluster / 묶음` 섹션이 카테고리별로 채워졌는가
+- [ ] derived 문서(`wiki/interview` · `wiki/portfolio` · `wiki/blog`)는 canonical(`wiki/concepts` / `wiki/projects`) link 1개+ 가 있는가
+- [ ] Obsidian 그래프뷰에서 이 문서가 cluster에 시각적으로 연결되어 보이는가
+
+> **결정론 집행기**: 위 옵시디언 링크 문법(broken target / dangling anchor / backtick 래핑)은 `.claude/hooks/wiki_structure_lint.py`의 C2 검사가 기계적으로 강제한다 (`--all --links-only`로 vault 전수, zero-tolerance).
+> basename 후보가 2개 이상인 non-full-path link는 `AMBIGUOUS_WIKILINK`다. v2 graph는 `.claude/hooks/wiki_graph_contract_check.py`가 `MISSING_PROJECT_BINDING`, `MISSING_INHERITED_DECISION`, `STALE_INHERITANCE_REVISION`, `CONFLICTS_WITH_PROJECT_DECISION`, `UNDECLARED_OVERRIDE`, `MISSING_EXPECTED_EDGE`, `DUPLICATE_DECISION_OWNER`를 검출하며, 공개 `wiki_consistency_check.py --all` 출력에 병합된다. `MISSING_EXPECTED_EDGE`는 batch/post-sync에서만 판정하여 단일 파일 pre-write 생성 순환을 차단하지 않는다.
+
+## 9. Obsidian 그래프 활용 지침
+
+- **Tags**: frontmatter `tags:` 는 카테고리 분류 + Obsidian Tag pane 활용. 핵심 5~7개 이내 권장.
+- **Local graph**: 각 문서에서 Local graph view로 직접 연결된 1차/2차 노드만 확인하면 cluster의 entry point 역할 검증 가능.
+- **Global graph**: 프로젝트별로 hub-spoke 패턴이 시각적으로 보여야 정상. 한 자료가 그래프상 고립된 점으로 보이면 upward link 누락 신호.
+
+## 10. 어긋난 자료의 처리 / Drift handling
+
+- 어떤 raw 문서가 branch나 project로 연결되지 않은 상태로 발견되면 → 즉시 upward link 추가 또는 (가치 없으면) 보관 폴더 별도 이동
+- branch가 사라지거나 머지된 후에도 해당 branch에 연결된 자료는 raw에 영구 보관 — branch-note 자체는 `status_label: merged` 또는 `abandoned` 로 표시되어 보존됨
+- 실제 작업·근거가 없는 미치환 scaffold는 삭제하지 않고 `raw/archive/<원래-category>/`로 이동한다. frontmatter에 `status_label: abandoned`와 `archive_reason:`을 남기며, `raw/archive/`는 active graph의 upward link·Cluster 생성 대상에서 제외한다.
+- `wiki/concepts/` 처럼 upward 면제 문서가 너무 많은 raw를 끌어안고 있다면, 해당 wiki/concepts/ 와 가까운 wiki/projects/ 를 새로 만들어 cluster 분리
+
+## 11. 카테고리별 템플릿 매핑
+
+| 카테고리 | 필수 템플릿 |
+|---|---|
+| `raw/project-notes/` | `project-template.md` (구조화 + 아키텍처 hub) — **아키텍처 다이어그램 (`.drawio.svg`) + 시퀀스 다이어그램 (Mermaid) 필수** |
+| `raw/diagrams/<project-slug>/` | **draw.io** XML 파일 저장 경로 (프로젝트 단위, 아키텍처 전용). 명명: `architecture-{viewpoint}-YYYY-MM-DD.drawio` 또는 `.drawio.svg` |
+| `raw/diagrams/<project-slug>/archived/` | 폐기된 다이어그램 보관 (삭제 대신 이동) |
+
+### Diagram-tool 분리 (엄격)
+
+- **아키텍처 / 컴포넌트 구성도 / 배포 / 데이터 흐름** → **draw.io XML** (`raw/diagrams/` 별도 파일)
+- **시퀀스** → **Mermaid `sequenceDiagram`** (본문 inline code block, 별도 파일 X)
+- **ER (선택)** → **Mermaid `erDiagram`** (본문 inline)
+- 시스템 아키텍처를 Mermaid `graph TD/LR` 로 작성 **금지** — 도구 일관성을 위해 draw.io 강제.
+
+### Diagram 컨퍼런스급 표준 (필수)
+
+다이어그램 작성 시 [[rules/diagram-standards]] 정독 — Toss SLASH / Kakao if(dev) / Naver DEVIEW 수준의 컨퍼런스급 다이어그램 기준. self-check 모두 만족해야 발표 가능 수준.
+
+## 12. Hub / MOC 명명 컨벤션
+
+- **Named hub 패턴 (Obsidian-native)**: 모든 hub/MOC 파일은 **의미 있는 고유 이름**을 사용. `index.md` / `_index.md` (Hugo·Jekyll 등 static-site 컨벤션) 사용 **금지** — wikilink 가 `[[index]]` 처럼 의미 없는 노드로 보이고 Graph view 라벨이 무력화됨.
+- **계층별 위치**:
+  - `wiki/llm-wiki.md` — 전체 vault 의 Map of Content (MOC). 진입점.
+  - `wiki/projects/<project-slug>.md` — 해당 project 의 wiki 하위 hub. 옆에 `wiki/projects/<project-slug>/` 폴더가 존재할 때 그 폴더 안 sub-doc 들의 MOC 역할 (folder-note 패턴).
+  - 다른 sub-directory hub 가 필요하면 동일 패턴 (`<dir-slug>.md` + `<dir-slug>/` 폴더 sibling).
+- **wikilink 표기**: hub 파일명이 vault 내에서 고유하므로 basename 만으로 참조 가능 — `[[ca-tmpl]]`, `[[llm-wiki]]`. 다른 디렉토리에 동명 파일이 생긴다면 그 때 full path 로 disambiguate.
+- **Folder-note 시각화**: Obsidian Folder Notes 플러그인 설치 시 sibling `<slug>.md` 가 `<slug>/` 폴더의 "표지" 역할로 보임. 플러그인 없이도 wikilink + Graph 동작은 동일.
+| `raw/branch-notes/` | `branch-note-template.md` |
+| `raw/daily-notes/` | `daily-note-template.md` |
+| `raw/errors/` | `error-note-template.md` |
+| `raw/interviews/` | `interview-prep-template.md` |
+| `raw/job-postings/` | `job-posting-template.md` |
+| `raw/blog-topics/` | `blog-topic-template.md` |
+| `raw/lectures/` | `lecture-note-template.md` |
+| `raw/official-docs/` | `raw-source-template.md` (source_type=official-doc) |
+| `raw/company-tech-blogs/` | `raw-source-template.md` (source_type=company-tech-blog) |
+| `wiki/concepts/` | `concept-template.md` 또는 `source-summary-template.md` |
+| `wiki/projects/<project-slug>/<topic>.md` (nested) | `wiki-project-template.md` — sibling `wiki/projects/<project-slug>.md` (named MOC) 와 1:N |
+| `wiki/interview/` | `interview-template.md` |
+| `wiki/portfolio/` | `portfolio-template.md` |
+| `wiki/blog/` | `blog-template.md` |