wiki-code — 코드 프로젝트 Wiki 관리 스킬

코드베이스와 프로젝트 문서를 Raw Source로 보고 .wiki/ 레이어를 관리한다. 파일을 추측해서 바로 열지 말고, qmd로 위치를 찾은 뒤 필요한 원문만 읽는다.

전제 조건

• 현재 작업 디렉토리가 코드 프로젝트 루트여야 함
• 먼저 qmd status와 qmd collection list로 현재 상태와 컬렉션 등록 여부를 확인
• qmd CLI를 기본 경로로 사용하고, MCP가 있으면 검색 보조로 사용
• 고정된 MCP 서버명을 추정하지 말고, 현재 세션에 실제로 노출된 도구만 사용
• qmd search 결과로 나온 URI만 사용하고, 경로를 손으로 추측해서 만들지 않음
• 이 저장소에서는 docs, skills, agents.md 같은 실제 인덱스 경로를 사용
• qmd에 해당 프로젝트가 컬렉션으로 등록되어 있어야 함

  qmd status
  qmd collection list
  

• 미등록 시 먼저 등록:

  qmd collection add . --name 프로젝트명 --mask "**/*.{md,ts}"
  qmd update && qmd embed
  

Wiki 위치

[프로젝트 루트]/
├── .wiki/                    ← LLM이 소유·관리하는 위키 레이어
│   ├── WIKI-AGENTS.md        ← 운영 규칙 (세션 시작 시 먼저 읽기)
│   ├── wiki-index.md         ← 전체 위키 카탈로그
│   ├── wiki-log.md           ← 작업 타임라인 (append-only)
│   ├── concepts/             ← 아키텍처 패턴·도메인 개념
│   ├── entities/             ← 모듈·서비스·컴포넌트·문서 페이지
│   ├── synthesis/            ← 데이터 흐름·의사결정·트레이드오프
│   └── diagrams/             ← Mermaid 다이어그램 (.md)
└── (소스 코드/문서 — 읽기 전용 Raw Source)

.gitignore에 .wiki/ 추가 여부는 사람이 결정. 팀 공유 시 추적, 개인용이면 무시.

---

INIT — 최초 1회

.wiki/WIKI-AGENTS.md가 없을 때 실행.

1. 프로젝트 구조 파악:

   qmd search "readme" -c 프로젝트명
   qmd search "workflow" -c 프로젝트명
   

2. .wiki/ 폴더와 하위 구조 생성
3. WIKI-AGENTS.md 생성 (이 스킬 내용 기반, 프로젝트명·경로 채움)
4. wiki-index.md, wiki-log.md 초기화
5. 프로젝트 개요 페이지 생성: .wiki/entities/project-overview.md
6. 사람에게 첫 ingest 영역 확인

---

INGEST — 코드/문서 → 위키 추가

트리거: "wiki에 추가", "문서화해줘", 파일/모듈 언급

1. 소스 파악 — qmd로 관련 문서와 스킬 검색:

   qmd search "기능 또는 문서명" -c 프로젝트명
   

   검색 결과에서 나온 실제 URI만 qmd get에 넣는다. 대표 루트는 skills/.../skill.md, docs/..., agents.md
2. 요약 확인 — 기능·인터페이스·의존성 3~5줄 후 사람 확인
3. entities/ 페이지 생성/업데이트
4. concepts/ 업데이트 — 아키텍처 패턴, 워크플로우 개념 반영
5. diagrams/ 생성 (필요 시) — Mermaid로 흐름 시각화
6. wiki-index.md 갱신 + wiki-log.md 기록

페이지 형식

---
tags: [wiki, entities|concepts|synthesis|diagrams]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [소스 파일 경로]
related_files: [직접 연관된 문서/스킬 파일]
---

# 문서/스킬명
> 한 줄 요약

## 역할
## 주요 인터페이스
## 의존성
## 데이터 흐름
## 연결된 위키 페이지
- [[관련 페이지]]
## 원본 소스
- `skills/.../skill.md`
- `docs/...`
- `agents.md`

---

QUERY — 구조 질문 답변

트리거: "어떻게 동작해?", "~의 흐름 설명해줘", "~와 ~의 관계는?"

1. wiki-index.md 읽기 → 관련 페이지 파악
2. 관련 위키 페이지 읽기
3. 필요 시 qmd로 실제 문서/스킬 참조:

   qmd search "질문 내용" -c 프로젝트명
   

4. 인용 포함 답변 (출처: 파일 경로 + 줄 번호)
5. 가치 있는 답변 → .wiki/synthesis/YYYY-MM-DD-주제.md 저장 제안

---

DRIFT — 변경 감지 후 위키 갱신

트리거: "wiki 업데이트해줘", "변경사항 반영해줘"

1. git diff --name-only 로 변경 파일 추출
2. 변경 파일의 related_files를 가진 위키 페이지 검색
3. 해당 위키 페이지 업데이트
4. 새 문서/스킬이 감지되면 자동 INGEST 제안

---

LINT — 위키 점검

트리거: "wiki 점검", "lint", "문서 정합성 확인"

점검 항목

1. 드리프트 탐지: git log vs wiki updated 날짜 비교
2. 고아 페이지: wiki-index.md에 없는 페이지
3. 깨진 소스 링크: 삭제된 파일 참조 여부
4. 모순: 같은 문서/스킬에 대해 다른 설명
5. 미문서화 항목: qmd에는 있는데 위키 페이지 없는 것

---

qmd 컬렉션 관리 명령

# 현재 프로젝트 등록
qmd collection add . --name 프로젝트명 --mask "**/*.{md,ts}"

# 컨텍스트 설명 추가
qmd context add qmd://프로젝트명/ "프로젝트 한 줄 설명"
qmd context add qmd://프로젝트명/docs/ "프로젝트 문서"
qmd context add qmd://프로젝트명/skills/ "프로젝트 스킬"

# 인덱스 갱신
qmd update

# 하이브리드 검색
qmd query "워크플로우" -c 프로젝트명

# 특정 파일 읽기: qmd search 결과 URI를 그대로 사용

현재 세션 예시

이 저장소에서는 peach-harness 컬렉션과 qmd://peach-harness/ 접두사를 사용합니다.

qmd search "peach-setup-harness" -c peach-harness
qmd get qmd://peach-harness/skills/peach-setup-harness/skill.md
qmd get qmd://peach-harness/docs/03-워크플로우.md
qmd get qmd://peach-harness/agents.md

---

핵심 원칙

• 소스 코드는 절대 수정 금지 — 읽기만 (Raw Source)
• .wiki/ 하위에만 쓰기
• Drift 감지: 코드 변경 후 반드시 DRIFT 또는 LINT 실행
• qmd CLI가 기본 진입점: MCP가 있으면 검색 보조로만 사용
• 언어: 한국어 (코드·기술용어는 영어 유지)
• 다이어그램: 복잡한 흐름은 반드시 Mermaid로 시각화