229 lines
18 KiB
Markdown
229 lines
18 KiB
Markdown
---
|
||
name: wiki-workflow
|
||
description: Use whenever the user asks for document creation, URL summarization, multi-document research, link auditing, brainstorming, or any work that touches this LLM Wiki repository — including creating raw notes (branch / error / interview-prep / job-posting / blog-topic / lecture / project-note), summarizing official-docs or company-tech-blogs from URLs, verifying wikilink integrity, extracting wiki/concepts or wiki/projects from raw, or organizing the Obsidian cluster. Required for any work that creates or evaluates more than one document in this wiki.
|
||
---
|
||
|
||
# Wiki Workflow (LLM Wiki — Obsidian)
|
||
|
||
본 skill 은 LLM Wiki 저장소의 **문서 생성·조직·검증 작업 진입점**. CLAUDE.md (저장소 루트) 가 운영 규칙 SSOT이고, 본 skill 은 그 규칙을 실행할 때 어떤 agent 를 dispatch 할지 결정한다.
|
||
|
||
## Reference rules (작업 시 정독)
|
||
|
||
본 skill 이 활성화되면 작업 성격에 따라 다음을 읽는다:
|
||
|
||
1. `CLAUDE.md` — 저장소 운영 규칙 SSOT (15 섹션)
|
||
2. `rules/linking-rules.md` — Mandatory upward link + 다중 부모 + 양방향 작성
|
||
3. `rules/naming-conventions.md` — 파일·디렉토리·식별자 명명 규칙
|
||
4. `rules/tag-taxonomy.md` — `tags:` 허용 어휘 (5계층)
|
||
5. `rules/evidence-first-research.md` — 다수 문서 정독 시 verbatim quote + 명명된 실패 모드. multi-doc research / audit 시 정독.
|
||
6. `rules/reporting-standards.md` — 다중 문서 리뷰 보고서 작성 시 §0~§8 템플릿 + Output Split + Verdict 산식.
|
||
7. `rules/advisory-depth.md` — 7 Contracts (Goal-Assumption-Action / Exhaustive Options / Plan Gap / Direct-Response / Citation Discipline / Self-Grep / Forbidden Marketing Words). 모든 advisory 작업에 적용.
|
||
8. `rules/extraction-tiering.md` — 4-Tier(T0 결정론 / T1 외부 구독 / T2 haiku / T3 sonnet / T4 opus) + 5계명. bulk 발췌·quorum 표결·/sync 팩킷 등 multi-doc 작업의 엔진 라우팅 시 정독.
|
||
9. 작업 카테고리에 해당하는 `templates/<category>-template.md`
|
||
|
||
## Claim Traceability Contract (HARD RULE)
|
||
|
||
Claude Code 에서 문서를 처음 생성할 때도 Antigravity 감사 기준과 동일하게 claim 단위 근거 추적을 강제한다.
|
||
|
||
1. `raw/official-docs/` 와 `raw/company-tech-blogs/` 문서는 `templates/raw-source-template.md` 의 `## Claims Extracted` 표를 반드시 채운다.
|
||
- `Claim ID` 는 해당 raw 문서 내부에서 안정적인 식별자여야 한다. 예: `KC-OIDC-C1`, `STRIPE-IDEMP-C2`.
|
||
- `Claim` 은 원문이 직접 말한 것만 쓴다. 내 해석은 `## 메모` 또는 `source-summary` 로 분리한다.
|
||
- `Does not prove` 에 이 자료만으로 증명되지 않는 범위를 적는다.
|
||
2. `raw/branch-notes/` 는 `## Decision Evidence Map` 을 반드시 가진다.
|
||
- 모든 중요한 구현 결정은 `Decision ID` 를 가진다.
|
||
- `Supporting Claims` 는 raw source 의 `Claim ID` 를 참조한다.
|
||
- 근거 없는 결정은 임의 보강하지 말고 `UNSUPPORTED_DECISION` 으로 표기한다.
|
||
3. 회사 기술 블로그는 기본값이 `company-case-study` 다. 공식 문서가 보강하지 않으면 “공식 best practice”, “표준”, “공식 지원”으로 승격하지 않는다.
|
||
4. `wiki/concepts/` 로 승격할 때 `## Claim-backed Knowledge` 에서 근거 Claim 과 Confidence 를 분리한다. 근거 없는 요약은 `INFERENCE` 또는 `needs-confirmation`.
|
||
5. 감사/리뷰 보고서가 `COMPLETE` 를 주장하려면 claim traceability 검사를 포함해야 한다. 최소한 `Claims Extracted`, `Decision Evidence Map`, `UNSUPPORTED_DECISION` 검사 결과를 보고한다.
|
||
|
||
## Dispatch Decision Tree
|
||
|
||
```text
|
||
User request arrives
|
||
│
|
||
▼
|
||
새 raw 문서 1개 생성 요청? (branch / error / interview-prep / job-posting / blog-topic / lecture / project-note)
|
||
├── YES → Dispatch `wiki-doc-author` with category + initial inputs.
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
URL (official-doc / company-tech-blog) 요약 요청?
|
||
├── YES → Dispatch `wiki-source-summarizer` with URL + parent branch/project.
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
다수 raw 문서 정독해서 wiki/concepts 또는 wiki/projects 추출 요청 (research / synthesis)?
|
||
├── YES → **bulk 발췌는 `extraction-broker`(T1 외부+T2 haiku) 1순위** (질문 + 파일 목록 전달)
|
||
│ → 검증된 digest 를 `wiki-research-lane`(synthesis, 필요 시 병렬 다중 lane) 또는 main 이 소비.
|
||
│ research-lane 의 직접 전수 정독은 broker 불가(드라이버 부재/외부 엔진 전멸) 시 fallback
|
||
│ (`rules/extraction-tiering.md` 사용법 표).
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
링크 정합성 / orphan 탐지 / 클러스터 감사 요청?
|
||
├── YES → Dispatch `wiki-link-verifier` with scope (전체 / 특정 카테고리 / 특정 프로젝트).
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
문서 간 모순 / 위임 동기화 / 일관성 정리 요청?
|
||
├── YES → `/sync` 절차 강제: ① 결정론 검사기(`wiki_consistency_check.py --all` 또는 `--impact <slug>`)
|
||
│ → ② `wiki-consistency-auditor` dispatch (참조 엣지 의미 대조)
|
||
│ → ③ fix-plan (owner-우선 해소, 승인 후 적용 — `rules/consistency-contract.md`).
|
||
│ 메인 에이전트의 수기 대조로 검사기/감사기 우회 금지.
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
리서치/감사 draft 의 findings 적대 검증 (≥5 findings) 요청?
|
||
├── YES → Dispatch `wiki-adversarial-reviewer` with master + per-file findings paths.
|
||
│ 결과의 KEEP/DOWNGRADE/REJECT 적용 후 최종 보고서 락인.
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
기존 문서들을 Claim ID 기반 template 구조로 마이그레이션 요청?
|
||
├── YES → `/migrate-claims` 절차를 따른다. Phase 순서 고정:
|
||
│ 1) raw source Claims Extracted
|
||
│ 2) branch-note Decision Evidence Map
|
||
│ 3) wiki Claim-backed Knowledge
|
||
│ 4) Controller Verification
|
||
│ Phase 1 없이 Phase 2 진행 금지.
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
기술 결정의 alternatives 를 신뢰도 있게 조사 ("이 브랜치 구현이 정확한가, 대안을 공식문서/블로그 근거로 다뤄줘")?
|
||
├── YES → Dispatch `wiki-decision-researcher` with decision topic + parent branch + constraints + N.
|
||
│ WebSearch → URL 후보 → 사용자 승인 → wiki-source-summarizer × N×2 dispatch → 비교 매트릭스 + 조건부 권고.
|
||
│ branch-note 의 ## 결정 사항 표 갱신 input 산출.
|
||
└── Continue.
|
||
│
|
||
▼
|
||
브랜치 노트 채움(스펙) 또는 구현 착수 수준 검증 요청?
|
||
├── 채움 → `/branch-spec <slug>` 절차 강제 (끝에 /depth + /coverage 자동 게이트).
|
||
│ `wiki-doc-author` 단독 dispatch 로 게이트 우회 금지.
|
||
├── 깊이 검증 → `/depth <slug>`: 1차 `wiki_structure_lint.py --file` + 2차 `branch-depth-auditor` dispatch.
|
||
├── 완전성 검증 → `/coverage <slug>`: 1차 결정론 사전검사 + 2차 `coverage-auditor` dispatch.
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
프로젝트 hub(raw/project-notes/) 채움/완성도 검증 요청?
|
||
├── YES → `/project-spec <slug>` 절차 강제 (1차 project 모드 린트 + 2차 `project-readiness-auditor`, 루프 천장 2회).
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
`.drawio` 아키텍처 다이어그램 채점/검증 요청?
|
||
├── YES → Dispatch `wiki-diagram-reviewer` with diagram path(s). PASS = ≥95/100.
|
||
│ 메인 에이전트 직접 채점 금지 (rubber-stamp 방지 — 이 agent 의 존재 이유).
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
파생 산출물 요청 (면접 답변 / 블로그 초안 / explainer / portfolio)?
|
||
├── YES → 해당 명령 절차 강제: `/interviewize` · `/blogify` · `/explain` · portfolio(수동).
|
||
│ 원천은 wiki/concepts·wiki/projects canonical 만. status ∈ {reviewed, verified, published-ready}
|
||
│ 미달 시 **중단** (explainer 만 status 면제 — 단 canonical 경유·새 claim 금지 유지).
|
||
│ raw / daily / branch 에서 직접 파생 절대 금지 (CLAUDE.md §11·§15).
|
||
└── NO → Continue.
|
||
│
|
||
▼
|
||
단일 lookup / 짧은 질문?
|
||
└── 메인 에이전트 직접 응답. 단 wikilink·인용은 본 규칙 준수.
|
||
```
|
||
|
||
## Subagent Lanes
|
||
|
||
| Agent | 용도 | 입력 (전부 채워서 dispatch — 누락 시 NEEDS_CONTEXT/BLOCKED 왕복) | 출력 |
|
||
|---|---|---|---|
|
||
| `wiki-doc-author` | 새 raw 문서 1개 작성 또는 비-template 문서 마이그레이션 | **mode(create\|migrate)** + category + initial fields + parent + **Sources/claim 근거** | 생성된 파일 경로 + 검증 결과 |
|
||
| `wiki-source-summarizer` | URL → raw 자료 (official-doc / company-tech-blog) | URL + **source_type** + parent (branch 또는 project) + **이 자료가 정당화하는 결정 한 줄** | 생성된 파일 + verbatim quote self-grep proof |
|
||
| `extraction-broker` | bulk 발췌 (T1 외부 CLI 구동 + 실패분 haiku 재발췌, read-only) | 질문 + 파일 목록 (+ 작업 성격: 구조화\|web성) | 검증된 digest (file:line 포인터, raw corpus 반입 없음) + engine funnel wiki-stats |
|
||
| `wiki-research-lane` | 다수 raw 정독 → 합성 (1차 input 은 broker 의 검증된 digest — 직접 전수 정독은 broker 불가 시 fallback) | 파일 슬라이스 + 연구 질문 + target output type | Evidence matrix + 추출 권고 + wiki-stats funnel |
|
||
| `wiki-link-verifier` | 클러스터 감사 | scope (전체/카테고리/프로젝트) | Orphan / 누락 Parent / 누락 Cluster / broken wikilink 매트릭스 |
|
||
| `wiki-adversarial-reviewer` | 리서치/감사 draft에 대한 falsification | master + per-file findings paths + **source corpus 경로** + **workspace 컨텍스트** | KEEP/DOWNGRADE/REJECT 매트릭스 + wiki-verdict 블록 + 재서술 권고 |
|
||
| `wiki-decision-researcher` | 기술 결정 alternatives 조사 (read-only — dispatch 는 controller 몫) | decision topic + parent branch + constraints + N (+ phase: discover\|synthesize) | 비교 매트릭스 + 조건부 권고 + **N×2 dispatch 요청**(controller 가 wiki-source-summarizer 실행) + branch-note 갱신 input |
|
||
| `branch-depth-auditor` | branch-note 깊이 의미 게이트 (`/depth` 2차) | 브랜치 노트 경로 1개 (1차 린터 PASS 후) | Findings 표 + Ready/Not-ready + wiki-verdict/wiki-stats 블록 |
|
||
| `coverage-auditor` | branch-note 완전성 게이트 (`/coverage` 2차) | 브랜치 노트 경로 (또는 project 모드 지시) + governing docs | Coverage 표 + Covered/Not-covered + wiki-verdict/wiki-stats 블록 |
|
||
| `wiki-consistency-auditor` | 참조 엣지 의미 대조 (`/sync` 2차) | **참조 엣지 목록**(citing 문서 / owner 문서 / D-id·§-id) + 양 노트 경로 | 엣지별 CONSISTENT/STALE_SUMMARY/CONTRADICTION/RESTATED + wiki-verdict/wiki-stats 블록 |
|
||
| `project-readiness-auditor` | project-note hub 완성도 의미 게이트 (`/project-spec` 2차, Claude 전용) | project-note 경로 1개 (project 모드 린트 PASS 후) | Findings 표 + Ready/Not-ready + wiki-verdict 블록 |
|
||
| `wiki-diagram-reviewer` | `.drawio` 다이어그램 컨퍼런스급 채점 | 다이어그램 경로(들) (+ 해당 project-note 경로) | 점수 0~100/diagram + PASS(≥95)/NEEDS_FIX/BLOCKED + wiki-verdict 블록 |
|
||
|
||
각 agent dispatch 시 필수로 다음을 input 으로 전달:
|
||
|
||
- 적용할 template 파일 경로
|
||
- 적용할 룰 파일들 (linking-rules / naming-conventions / tag-taxonomy)
|
||
- 작업 scope (단일 파일 / 슬라이스 / 전체)
|
||
- Claim traceability 요구사항:
|
||
- raw source 생성: `Claims Extracted` + `Usage Boundaries`
|
||
- branch-note 생성/검토: `Decision Evidence Map` + `Claims To Verify`
|
||
- concept/wiki 승격: `Claim-backed Knowledge`
|
||
- review/audit: `UNSUPPORTED_DECISION` 식별
|
||
|
||
## 공통 규칙 (모든 wiki 작업)
|
||
|
||
### 1. 언어
|
||
|
||
본문 산문은 사용자가 사용한 언어 (한국어). frontmatter 키·status_label 값·tag 값은 영문 유지.
|
||
|
||
### 2. 명명
|
||
|
||
`rules/naming-conventions.md` 의 카테고리별 규칙 엄격 준수. branch-note 의 prefix 는 **4종 (`feature-` / `fix-` / `chore-` / `experiment-`) 만 허용**. `develop-` 는 제거됨 — 기능 구현 작업은 규모 무관 `feature-`.
|
||
|
||
**branch-note 슬러그 — _구현 내용 기반 (HARD RULE)_**:
|
||
|
||
- 슬러그는 _그 branch 가 무엇을 구현/문서화하는지_ 4~8 단어 영문 kebab-case 로 명시.
|
||
- ✅ 좋은 예: `feature-keycloak-oauth2-proxy-oidc-flow`, `feature-keycloak-header-spoofing-defense`, `feature-domain-event-outbox-contract`, `fix-jwt-iss-claim-mismatch`
|
||
- ❌ 나쁜 예: `develop-anything` (제거된 prefix), `feature-project-x-3` (numbered hierarchy 금지), `feature_keycloak_oidc` (snake_case 금지), `Feature-Keycloak-OIDC` (CamelCase 금지)
|
||
- 계층 정보는 **slug 가 아니라** frontmatter `parent_branch:` 와 `## Parent` 섹션으로만 표현.
|
||
- 같은 큰 주제의 sub-branch 들이 인접 정렬되도록 공통 content prefix (예: `feature-keycloak-*`) 사용은 허용.
|
||
- 자세히: `rules/naming-conventions.md` §2.1.1~§2.1.6.
|
||
|
||
### 3. Tag
|
||
|
||
`rules/tag-taxonomy.md` 의 5계층(L1~L5) 표 따라 5~7개 이내. taxonomy 에 없는 신규 tag 사용 시 먼저 taxonomy 갱신.
|
||
|
||
### 4. Upward Link
|
||
|
||
모든 raw 문서는 예외 없이 branch 또는 project 로 upward link. `wiki/concepts/` 만 면제 (canonical hub). `rules/linking-rules.md` §2 참조.
|
||
|
||
### 5. Verbatim Quote
|
||
|
||
외부 자료(official-doc / company-tech-blog / lecture)에서 인용 시 byte-for-byte 복사. paraphrase 금지. 인용 후 `grep -nF` 또는 `sed -n` 으로 실제 source 에 존재하는지 검증 (`wiki-source-summarizer` 가 이를 자동 수행).
|
||
|
||
### 6. Cluster 양방향
|
||
|
||
hub (project-note / 자식 branch 를 가진 branch) 작성·갱신 시 `## Cluster` 섹션에 자식 명시. 자식 측은 `## Parent` 섹션으로 upward link. Obsidian backlink 가 자동 발견하지만 명시적 양방향이 그래프뷰 의미를 또렷하게 함.
|
||
|
||
### 7. Diagram (엄격한 도구 분리 + 컨퍼런스급 표준)
|
||
|
||
- **시스템 아키텍처 / 컴포넌트 구성도 / 배포 토폴로지 / 데이터 흐름** → **draw.io XML** (`raw/diagrams/<project-slug>/architecture-{viewpoint}-YYYY-MM-DD.drawio` 또는 `.drawio.svg`). 본문에선 `![[<path>.drawio]]` 또는 `![[<path>.drawio.svg]]` 로 embed.
|
||
- **시퀀스** → **Mermaid `sequenceDiagram`** (본문 inline ```mermaid``` code block, 별도 파일 X)
|
||
- **ER (선택)** → **Mermaid `erDiagram`** (본문 inline)
|
||
- **시스템 아키텍처를 Mermaid `graph TD`/`graph LR`로 작성 금지** — 도구 일관성 위반.
|
||
- **컨퍼런스급 표준 필수 정독**: `rules/diagram-standards.md` — Toss SLASH / Kakao if(dev) / Naver DEVIEW 수준 v2 minimalist. **8항 self-check** (§14) 모두 ✓ 해야 발표 가능 수준. Vertex ≤ 10 / Edge ≤ 8 / Callout ≤ 1 / 박스 라벨 ≤ 2줄 / 화살표 라벨 ≤ 5단어 / 80% 회색 + 강조 ≤ 2 / boundary 정보 있을 때만 / 5초 + 30초 룰.
|
||
- project-note 의 `architecture_review:` frontmatter 에 마지막 검토 날짜 기록.
|
||
|
||
## STOP Self-Check (송신 직전)
|
||
|
||
1. 새 파일 생성 시 frontmatter 필수 필드 채움 (title / source_type / status / tags / related_projects / created)
|
||
2. raw 문서라면 `## Parent` 섹션이 채워졌는지 (project-note 제외 — 자기가 root)
|
||
3. branch-note 라면 `## Sources / 근거` 가 최소 1개의 외부 자료 link 포함
|
||
4. hub 문서 (project / 자식 branch 를 가진 branch) 라면 `## Cluster` 섹션 자식 명시
|
||
5. 모든 wikilink 가 실제 파일 가리킴 (broken link 없음) — 새 파일 생성 시 placeholder 형 wikilink (`![[architecture-{YYYY-MM-DD}.drawio.svg]]` 같은) 절대 사용 금지. Obsidian 이 placeholder 그대로 파일 생성함.
|
||
6. tag 가 taxonomy 어휘에서 가져왔는가
|
||
7. 파일명이 naming-conventions 의 카테고리별 규칙 준수. **branch-note 슬러그가 구현 내용을 표현하는가? numbered hierarchy (`-1`, `-1-2`) 사용 금지** (§2 명명 참조).
|
||
8. 인용 (verbatim quote) 이 실제 source 에 grep 으로 존재 확인됨
|
||
9. **시스템 아키텍처 다이어그램은 draw.io XML 파일** (`raw/diagrams/...`) 에 작성됐는가? Mermaid `graph TD/LR` 로 아키텍처를 그렸으면 → draw.io 로 이관 필요 (FAIL).
|
||
10. **시퀀스 다이어그램은 Mermaid `sequenceDiagram`** code block 으로 작성됐는가? draw.io 로 그렸으면 → Mermaid 로 이관 필요 (FAIL).
|
||
11. raw source 라면 `## Claims Extracted` 와 `## Usage Boundaries` 가 존재하는가?
|
||
12. branch-note 라면 `## Decision Evidence Map` 의 모든 중요한 결정이 Claim ID 또는 `UNSUPPORTED_DECISION` 으로 연결됐는가?
|
||
13. wiki/concepts 라면 `## Claim-backed Knowledge` 에서 사실/추론/확인 필요가 분리됐는가?
|
||
14. 파생 산출물(wiki/interview·wiki/blog·wiki/portfolio) 생성이라면 — 원천 canonical 의 frontmatter `status` 가 `reviewed|verified|published-ready` 인지 **읽어서** 확인했는가? `## Sources` 에 `[[wiki/concepts/...]]` 또는 `[[wiki/projects/...]]` 링크가 있는가? (explainer 는 status 면제 — 단 canonical 경유 + 새 claim 금지 + canonical Sources 링크는 필수)
|
||
|
||
## 최종 보고 컨트랙트
|
||
|
||
모든 작업 종료 시 응답에 다음 포함:
|
||
|
||
- 생성·변경된 파일 목록
|
||
- 각 파일의 frontmatter 필수 필드 채움 여부
|
||
- Parent / Cluster / Sources 섹션 검증 결과
|
||
- 새로 추가된 wikilink 가 존재하는 파일을 가리키는지 확인
|
||
- 향후 검토 필요 항목
|