15 KiB
title, source_type, status, tags, last_reviewed
| title | source_type | status | tags | last_reviewed | ||
|---|---|---|---|---|---|---|
| LLM Wiki Linking Rules | meta | stable |
|
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에서 인용될 수 있음. 이 경우:
frontmatter의related_branches:에 모든 branch 이름 나열- 본문에
## Parent / 활용 branch표를 두고 각 branch + "이 자료가 정당화하는 결정" 한 줄로 기록
예: raw/official-docs/keycloak-oidc-rfc.md
---
related_branches: [feature-keycloak-oauth2-proxy-oidc-flow, feature-keycloak-nginx-auth-request-integration]
related_projects: [keycloak-patterns]
---
## 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로 대조한다.
<!-- 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 / 묶음 섹션을 두고 자식들을 카테고리별로 명시:
## 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— siblingwiki/projects/<project-slug>.md(named MOC) 와 1:N | |wiki/interview/|interview-template.md| |wiki/portfolio/|portfolio-template.md| |wiki/blog/|blog-template.md|