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

18 KiB
Raw Permalink Blame History

name, description
name description
wiki-workflow 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

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계층(L1L5) 표 따라 57개 이내. 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 가 존재하는 파일을 가리키는지 확인
  • 향후 검토 필요 항목
Reference in New Issue View Git Blame Copy Permalink