| name | wiki-lint |
| description | wiki-lint — Karpathy LLM Wiki 패턴의 정기 health check. docs/INDEX.md + LOG.md + dev-guide + ADR + memory 전반의 정합성을 14가지 체크 (orphan / stale / broken cross-reference / parent-sibling 비대칭 / Jira 상태 불일치 / memory drift / INDEX integrity 등) 로 검증합니다. 사용자가 'wiki 점검', 'docs 정합성 확인', 'INDEX 검사', 'orphan dev-guide', 'stale 확인', 'ADR drift', 'cross-reference 깨짐', 'wiki lint', 'docs lint', 'health check', 'memory drift', '문서 health score', '문서 위반 사항' 등을 요청하거나, /jira-complete 가 끝나면서 자동 chain 으로 호출 (high severity 만, non-blocking) 하거나, /jira-ingest --bootstrap 직후 baseline 측정을 위해 자동 호출될 때 트리거됩니다. jira-ingest 와 _wiki-schema.md SSoT 공유. 어느 프로젝트에서나 작동 (user-scope). 자동수정 가능 항목 (--fix 의도) 과 수동 검토 필요 항목을 분리해서 보고합니다. |
wiki-lint — Wiki 정기 health check (14 rules)
Karpathy LLM Wiki 패턴의 lint 단계 — periodic health-checks for contradictions, stale claims, orphan pages, missing concepts, broken cross-references.
jira-ingest 와 ~/.claude/skills/_wiki-schema.md SSoT 공유.
Read-only by default — --fix 의도가 명시될 때만 write 수행 (각 fix 전 사용자 승인).
Usage
/wiki-lint # 기본 — 의도는 자연어로 추론
/wiki-lint --subtasks # 의미 없음 (corpus-scoped). 부모/슬라이스 구분 무관 — 무시 + 경고
자연어 입력에서 추론하는 호출 의도 (플래그 없음):
| 사용자 의도 | 추론 모드 |
|---|
| "점검해줘" / "health check" | summary (high+medium 만, 상위 5건 미리보기) |
| "전체 점검" / "full lint" | full (모든 위반 + 권고) |
| "고쳐줘" / "auto-fix" / "자동 수정" | fix (✅ 표시된 것만 수정, 각 변경 사용자 승인) |
| "orphan 검출" / "L05 만" / "ADR 깨진 거 찾아줘" | specific rule (해당 ID 만) |
| "high 만" / "심각한 거" | severity 필터 (high 이상) |
| "최근 N일" / "이번 주" | since 인크리멘탈 (해당 기간 변경 파일만) |
| "STD-247 만" / "이 이슈 점검" | issue scope (해당 이슈 관련 체크만) |
| "JSON 으로" / "머신 출력" | JSON 모드 (CI 통합용) |
⛔ Guard — Wiki 자산 존재 확인
스킬 시작 직후 점검:
| 점검 | 부재 시 행동 |
|---|
docs/INDEX-SCHEMA.md | "Wiki 가 설정되지 않았습니다. /jira-ingest 로 먼저 wiki 셋업 진행해주세요" 안내 후 종료 |
docs/INDEX.md | "INDEX.md 가 비어있거나 부재 — /jira-ingest bootstrap 권고" 안내 후 종료 |
docs/LOG.md | (선택) — 없어도 lint 는 INDEX 기반 가능. 단 L03 (stale) 은 정확도 떨어짐 경고 |
세 가지 모두 정상이면 lint 진행.
§ 1. 정상 lint 절차
1-1. Schema 로딩
~/.claude/skills/_wiki-schema.md # SSoT 정책
docs/INDEX-SCHEMA.md # 프로젝트 schema
1-2. Inventory 수집
docs/INDEX.md 표 파싱 → issue_key → metadata 매핑docs/LOG.md 라인 파싱 → 시간순 이벤트- glob
docs/**/*.md → 실제 파일 inventory
docs/08-decision-log.md (있으면) → ADR-N 목록 추출memory/MEMORY.md + memory entries (있으면) → 인용 파일/클래스 목록- (옵션)
mcp__atlassian__getJiraIssue × N — L14 closure mismatch 시만
1-3. 14 Rule 실행
_wiki-schema.md § 11 의 매트릭스 기반. 각 rule 독립 try-catch — 한 rule 실패해도 다른 rule 계속.
L01 — Orphan (high, auto-fix ✅)
INDEX-SCHEMA 의 issue_guides pattern 매칭 파일이 INDEX 에 없는 경우.
for f in glob('docs/<ISSUE_PREFIX>-*-dev-guide.md'):
key = parse_key(f)
if key not in INDEX:
violations.append(L01, file=f, key=key)
auto_fix: jira-ingest 의 backfill 모드를 자연어로 chain ('STD-247 INDEX 에 누락 — 추가해줘')
L02 — Orphan reverse (high, manual)
INDEX 에 있는데 파일 부재. 자동 삭제 위험 → 사용자 결정.
L03 — Stale (medium, no-fix)
status=planned AND last_activity_in_LOG > 7d
last_activity 는 LOG.md 의 해당 KEY 가장 최근 라인 timestamp.
L05 — Xref ADR broken (high, no-fix, Levenshtein 제안)
for guide in INDEX.issue_guides:
for adr in guide.related_adrs:
if adr not in ADR_list:
candidates = top3_levenshtein(adr, ADR_list)
violations.append(L05, guide, adr, candidates)
L06 — Xref issue broken (medium, no-fix)
dev-guide 본문의 <ISSUE>-N 가 INDEX 에 없음 (삭제된 이슈 또는 오타).
L07 — Parent/sibling asymmetry (medium, auto-fix ✅)
for guide in INDEX:
if guide.parent:
parent = INDEX[guide.parent]
if guide.key not in parent.children:
violations.append(L07, type='missing_child', parent=parent.key, child=guide.key)
for sib in guide.siblings:
if sib in INDEX and guide.key not in INDEX[sib].siblings:
violations.append(L07, type='asymmetric_sibling', ...)
auto_fix: INDEX 표의 양방향 동기화 (jira-ingest rebuild-cross-refs 자연어 chain)
L08 — Frontmatter missing (low, auto-fix ✅)
신규 dev-guide (created ≥ 2026-05-14) 에 YAML frontmatter 없음.
auto_fix: 비공식 헤더 → frontmatter 변환 (사용자 확인 후).
L09 — Conflict (high, manual)
같은 ADR-N 을 두 dev-guide 가 다른 결정으로 인용. heuristic:
- 같은 ADR 을 인용한 dev-guide 쌍 추출
- 본문에서 "ADR-N 적용" vs "ADR-N 폐기" 같은 상반 키워드 동시 검출 시 경고
- false positive 많음 — 수동 검토만
L10 — Memory drift (high, manual)
memory/*.md 의 인용 파일/클래스가 실 코드에 없음:
- memory 본문에서 파일 경로 추출 (정규식:
[A-Za-z0-9/_\-.]+\.(java|vue|ts|js|py))
- 클래스명 추출 (CamelCase 휴리스틱)
- glob/grep 으로 실재 확인
- 부재 시 violation (사용자가 update / forget 결정)
L11 — INDEX integrity (low, auto-fix ✅)
- 표 정렬 깨짐 (key 내림차순 아님)
- 중복 row (같은 key 2회)
- ingest-managed 마커 begin/end 짝 안 맞음
- 빈 cell 가
- 가 아닌 다른 값
- auto_fix: jira-ingest rebuild 자연어 chain
L12 — LOG integrity (low, manual)
LOG 라인 형식 일탈. 드물고 위험 → 자동 수정 X.
L14 — Closure mismatch (medium, auto-fix ✅)
for guide in INDEX.issue_guides:
if guide.status == 'planned':
jira_status = atlassian.getJiraIssue(guide.key).status
if jira_status in ['QA', 'Done']:
violations.append(L14, guide, jira_status)
auto_fix: jira-ingest closure 자연어 chain ('STD-247 closure 처리')
Jira API 실패 시 해당 체크만 skip + 경고.
L15 — Coverage (low, auto-fix ✅)
sprint week 파일이 그 week 의 closed issue 를 ingest-managed 블록에 포함하는지.
auto_fix: 누락된 라인 append.
1-4. 결과 집계 + 출력
📋 Wiki Lint Report (<timestamp> KST)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ <N> checks passed
⚠️ <M> warnings / ❌ <K> errors
━━━ ❌ ERRORS ━━━
❌ L05 (Xref, high) — Broken ADR reference [3건]
• docs/STD-247-dev-guide.md:52 → ADR-099 (decision-log 에 없음)
Levenshtein 후보: ADR-029, ADR-060
• ...
━━━ ⚠️ WARNINGS ━━━
⚠️ L03 (Stale, medium) — 'planned' 상태 7일 초과 [4건]
STD-201 (10d), STD-198 (12d), STD-196 (15d), STD-195 (21d)
→ 진행 중이면 status=implementing 갱신, 폐기면 status=abandoned
━━━ 📊 SUMMARY ━━━
Health Score: 92 / 100
Total checks: 97
Auto-fixable: 4건 — '자동 수정해줘'
Manual review: 5건
권장 다음 단계:
1. 자동 수정 4건 처리
2. STD-201/198/196/195 status 결정
3. memory drift 검토
1-5. Auto-fix 모드 (사용자 의도 명시 시만)
사용자가 "고쳐줘" / "auto-fix" / "자동 수정" 의도 표명 시:
- ✅ 표시된 위반만 candidate
- 각 fix 별로 변경 plan 미리보기 (organize-claude-md Phase 6 패턴 차용)
- 사용자 승인 후 적용
- fix 결과를 LOG.md 에
[<ts> LINT-FIX <KEY>] rule=L07 action=symmetry-restored append
Auto-fix 가 다른 스킬을 chain 호출하는 경우 (대부분 jira-ingest):
- L01:
jira-ingest <KEY> (backfill 의도 자연어)
- L07:
jira-ingest --rebuild-cross-refs 의도 자연어
- L08:
jira-ingest <KEY> (refresh frontmatter)
- L11:
jira-ingest rebuild 의도 자연어
- L14:
jira-ingest <KEY> closure (Jira QA 신뢰)
- L15: 직접 sprint week 파일 ingest-managed 블록에 append (간단)
§ 2. 자동 트리거 — 2가지 chain 진입
본 스킬은 두 곳에서 자동 호출된다 (둘 다 high+medium 만, non-blocking):
2-1. /jira-complete §4.7 자동 chain
/jira-complete 의 §4.6 (CLAUDE.md 위생 체크) 직후 §4.7 으로 chain:
Skill('wiki-lint', '요약 점검해줘 — high 와 medium 만, non-blocking')
실패해도 jira-complete 자체 진행은 막지 않음.
2-2. /jira-ingest --bootstrap 끝 자동 chain
bootstrap 종료 직후 baseline health score 측정:
Skill('wiki-lint', '전체 점검 — baseline 확보')
첫 lint 결과를 LOG.md 에 [<ts> LINT baseline] score=92 errors=2 warnings=7 append.
§ 3. Error Handling
- 각 rule 독립 try-catch — 일부 실패해도 다른 rule 계속
- Jira API 실패 (L14) → 해당 체크만 skip + 경고
- INDEX.md / LOG.md 파싱 실패 → 사용자에게 손상 안내 + bootstrap 권고
- memory/ 디렉토리 부재 (L10) → 해당 체크 skip (정상)
§ 4. Context Cost
- 인크리멘탈 (
--since 7d 의도) 기본 권장 — 변경된 파일만 read
- full mode 는 100+ 파일 전체 read = ~500K char → batch 처리 (10 파일씩)
- LOG.md 전체 스캔 비용은 lint 단계에서만 (jira-ingest 는 LOG read 안 함)
§ 5. Notes
- 이 스킬은 read-only by default. write 는 사용자 명시
--fix 의도 + 각 변경 승인 후만.
- HARNESS_MODE 무관 (직교)
--subtasks 받지 않음 (corpus-scoped). 호출 시 무시 + 경고.- 정책은 모두
_wiki-schema.md SSoT 에서 관리
§ 6. JSON 출력 모드 (CI 통합용)
사용자가 "JSON" / "머신 출력" 의도 표명 시:
{
"timestamp": "2026-05-14T14:32:00+09:00",
"health_score": 92,
"total_checks": 97,
"violations": [
{
"rule_id": "L05",
"severity": "high",
"category": "xref",
"auto_fixable": false,
"file": "docs/STD-247-dev-guide.md",
"line": 52,
"evidence": "ADR-099 not in decision-log",
"suggestions": ["ADR-029", "ADR-060"]
}
],
"summary": {
"errors": 2,
"warnings": 7,
"auto_fixable_count": 4
}
}
