Wiki 자동화 운영 가이드 (사용자 매뉴얼)

버전: 1.0
작성일: 2026-04-28
대상: DAP 위키 운영자, 신입 온보더

📚 목차

개요
자동화 아키텍처
스크립트 사용 가이드
스킬 사용 가이드
Troubleshooting
FAQ
신입 온보딩

개요

DAP 위키 자동화 파이프라인은 3계층 아키텍처로 구성됩니다:

Layer 1 (Hooks): 파일 변경 시 자동 실행 (즉시 반응, < 1초)
Layer 2 (Scripts): 배치 처리 (정기 실행, < 1초)
Layer 3 (Skills): LLM 기반 자동화 (사용자 호출, < 10초)

자동화 아키텍처

┌─────────────────────────────────────────────────────────┐
│  사용자 작업 (raw/ 파일 추가, Concept 수정 등)          │
└────────────────┬────────────────────────────────────────┘
                 │
        ┌────────┴─────────┬────────────┐
        ▼                  ▼            ▼
    Layer 1:        Layer 2:         Layer 3:
    Hooks           Scripts          Skills
    (자동)          (정기/수동)       (사용자 호출)
    
    3개:           3개:             3개:
    - Frontmatter  - wiki-lint      - /ingest
    - Wikilink     - update-index   - /lint
    - Log생성      - process_query  - /query

데이터 흐름

raw/ 원본 수집
  ├─ /ingest (Skill) → sources/ 골격 생성
  ├─ Hooks 검증: Frontmatter, Wikilink
  ├─ log.md 자동 기록
  │
  ├─ user: concepts/ 수정
  ├─ Hooks 검증 (자동)
  ├─ /lint (Skill) → 자동 수정
  │
  └─ /query (Skill) → 3+ sources → insights/ 저장
     ├─ process_query_results.py
     ├─ Contradiction 감지
     └─ log.md 기록

스크립트 사용 가이드

1. wiki-lint.py (Wiki 건강 체크)

목적: 전체 위키의 메타데이터 & 링크 검증

위치: .claude/scripts/wiki-lint.py

기본 사용법

# 1. 검증만 (dry-run)
python3 ./.claude/scripts/wiki-lint.py
 
# 2. 자동 수정 (dry-run으로 미리 확인)
python3 ./.claude/scripts/wiki-lint.py --auto-fix
 
# 3. 실제 적용
python3 ./.claude/scripts/wiki-lint.py --auto-fix --apply
 
# 4. 수동 검토 가이드 출력
python3 ./.claude/scripts/wiki-lint.py --review-guide

옵션 설명

옵션	설명
`--auto-fix`	Major 이슈 자동 수정 모드 (dry-run)
`--apply`	`--auto-fix` 결과를 실제 파일에 적용
`--review-guide`	Manual review 필요한 항목 출력

결과 해석

[REPORT] AUTO-FIX REPORT
Files checked: 24
Files to fix: 3

[FIXES APPLIED]
- wiki-quality-standards.md
  ✓ Fixed source_count: 3 → 3
- example-page.md
  ✓ Fixed updated: 2026-04-27 → 2026-04-28

[OK] Applied fixes to 3 file(s)

자동 수정 항목:

✅ Frontmatter 누락 필드 추가
✅ updated 날짜 자동 갱신
✅ source_count 불일치 수정

수동 검토 필요:

⚠️ Orphan 페이지 (역링크 0개)
⚠️ Contradiction 섹션 존재
⚠️ Stale 데이터 (6개월 이상)

Cron 설정 (OS 레벨 자동 실행) ⚠️

중요: 이 설정은 Claude Code 세션과 무관하게 OS 수준에서 매주 자동 실행됩니다.

등록 방법 (터미널에서 직접 실행):

# 1. crontab 편집
crontab -e
 
# 2. 다음 줄을 편집기에 추가
0 17 * * 5 cd /Users/a03298/Documents/dap-wiki-vault && python3 ./.claude/scripts/wiki-lint.py --auto-fix --apply
 
# 3. 저장 & 종료 (vim: :wq, nano: Ctrl+X → Y)
 
# 4. 등록 확인
crontab -l

작동 원리:

세션 연결: 필요 없음 ✅
실행 시점: 매주 금요일 17:00 (OS Cron 데몬이 자동 실행)
저장 위치: /var/spool/cron/crontabs/a03298
세션 종료 후: 정상 작동 ✅

2. update-index.py (Index 갱신)

목적: wiki/index.md 자동 갱신 (페이지 카탈로그)

위치: .claude/scripts/update-index.py

기본 사용법

# Index 갱신
python3 ./.claude/scripts/update-index.py
 
# 결과 확인
head -50 wiki/index.md

결과 예시

| 파일 | 타입 | 생성 | 수정 | 설명 |
|------|------|------|------|------|
| wiki-quality-standards | concept | 2026-04-27 | 2026-04-28 | 위키 품질 기준 정의 |
| dap-wiki-data-pipeline | concept | 2026-04-27 | 2026-04-27 | 데이터 흐름 설계 |
| example-test-article | source | 2026-04-28 | 2026-04-28 | 테스트 아티클 |

Cron 설정 (OS 레벨 월말 자동 갱신) ⚠️

등록 방법:

# 1. crontab 편집
crontab -e
 
# 2. 다음 줄을 편집기에 추가 (매월 마지막 날 자정)
0 0 28-31 * * [ "$(date -d tomorrow +\%d)" = "01" ] && cd /Users/a03298/Documents/dap-wiki-vault && python3 ./.claude/scripts/update-index.py
 
# 또는 간단히: 매월 28일 자정 (월별 다양성 고려)
0 0 28 * * cd /Users/a03298/Documents/dap-wiki-vault && python3 ./.claude/scripts/update-index.py
 
# 3. 저장 & 종료
 
# 4. 등록 확인
crontab -l

작동 원리:

세션 연결: 필요 없음 ✅
실행 시점: 매월 28일 자정 (또는 마지막 날)
저장 위치: /var/spool/cron/crontabs/a03298

3. process_query_results.py (Query 결과 처리)

목적: 질문/답변 → Insight 페이지 자동 저장 + Contradiction 감지

위치: system/scripts/process_query_results.py

기본 사용법

# Dry-run (미리보기)
python3 system/scripts/process_query_results.py \
  --question "데이터 품질과 거버넌스의 관계는?" \
  --answer "데이터 품질은 거버넌스의 핵심입니다..." \
  --sources "wiki/concepts/wiki-quality-standards.md,wiki/concepts/data-quality-and-governance.md,wiki/concepts/dap-wiki-automation-rules.md" \
  --dry-run
 
# 실제 저장
python3 system/scripts/process_query_results.py \
  --question "데이터 품질과 거버넌스의 관계는?" \
  --answer "데이터 품질은 거버넌스의 핵심입니다..." \
  --sources "wiki/concepts/wiki-quality-standards.md,wiki/concepts/data-quality-and-governance.md,wiki/concepts/dap-wiki-automation-rules.md" \
  --create-insight \
  --update-log

옵션 설명

옵션	설명
`--question`	사용자 질문 (필수)
`--answer`	합성된 답변 (필수)
`--sources`	출처 (쉼표 구분, 필수)
`--create-insight`	Insight 페이지 생성 여부
`--update-log`	log.md 자동 업데이트
`--dry-run`	실제 저장 없이 미리보기

결과 해석

{
  "status": "success",
  "sources_count": 3,
  "insight_created": true,
  "insight_path": "wiki/insights/2026-04-28-data-quality-governance.md",
  "contradictions": [],
  "message": "Insight 저장됨: 2026-04-28-data-quality-governance.md"
}

스킬 사용 가이드

1. /ingest (소스 수집 자동화)

목적: raw/ 파일 → sources/ 골격 자동 생성

기본 작업 흐름

raw/articles/, raw/youtube/, raw/pdfs/에 파일 추가

# raw/articles/my-article.md (frontmatter 포함)
---
title: "제목"
author: "저자"
published: 2026-04-28
url: https://example.com/article
tags:
  - tag1
  - tag2
---
 
# 본문...

Claude와 /ingest 대화

사용자: /ingest raw/articles/my-article.md
Claude: 
- Mode B 적용 (자동 skeleton 생성)
- sources/my-article.md 생성 (frontmatter + TODO 플레이스홀더)
- /lint 검증 권장

검증 & 완성

python3 ./.claude/scripts/wiki-lint.py --auto-fix --apply
# Claude: sources/my-article.md 상세 내용 Edit으로 채우기

지원 Mode

Mode	설명	입력	출력
A	raw/ 직접 저장	파일 경로	sources/ 골격
B	URL 수집	웹 URL	raw/ + sources/
C	자연어 검색	”공부방 운영 글”	후보 5개 → 사용자 선택
D	NotebookLM	2개 이상 URL	insights/ (합성 분석)

2. /lint (위키 건강 체크 & 수정)

목적: Frontmatter, 링크, 메타데이터 자동 검증/수정

기본 작업 흐름

사용자: /lint (전체 위키 검증)
Claude:
1. wiki-lint.py --auto-fix 실행
2. Major 이슈 자동 수정
   - Frontmatter 누락 필드 추가
   - source_count 불일치 수정
   - updated 날짜 갱신
3. Manual review 필요 항목 보고
   - Orphan 페이지: keep/link/delete 의사결정
   - Contradiction: reconcile/deprecate/research
   - Stale data: update/keep+comment/delete

결과 액션

이슈	자동 수정	수동 검토
Frontmatter 누락	✅
source_count 불일치	✅
Broken link		⚠️
Orphan 페이지		⚠️
Contradiction		⚠️

3. /query (위키 검색 & Insight 생성)

목적: 위키에서 답변 검색 → 3+ sources 답변 저장

기본 작업 흐름

사용자: /query "데이터 품질과 거버넌스의 관계는?"
Claude:
1. Phase 0: 질문 타입 분류 (Factual/Synthetic/Exploratory 등)
2. Phase 1: Index-first 검색 (wiki/index.md + Grep)
3. Phase 2: 페이지 드릴다운 (1-hop 링크 확장)
4. Phase 3: 원본 재참조 (조건부)
5. Phase 4: 답변 합성 (인용 포함)
6. Phase 5: 파일링 판단 (3+ sources → insights/ 저장 여부)
7. Phase 6: log.md & index.md 업데이트

파일링 기준

저장 O (insights/):

Synthetic / Temporal / Exploratory 타입
3개 이상 페이지 합성
새 연결/패턴 발견
사용자 명시 요청

저장 X:

Factual (단일 페이지 완전 커버)
답변이 2-3문장 이내
1회성 맥락

자동화 옵션

# 처리 결과를 자동으로 저장하려면:
python3 system/scripts/process_query_results.py \
  --question "사용자 질문" \
  --answer "Claude 답변" \
  --sources "출처1,출처2,출처3" \
  --create-insight \
  --update-log

Troubleshooting

문제 1: wiki-lint 실행 후 파일이 수정되지 않음

증상: --apply 옵션을 사용했는데 파일이 변경되지 않음

원인:

권한 부족 (read-only 디렉토리)
YAML 형식 오류 (잘못된 frontmatter)

해결책:

# 1. 파일 권한 확인
ls -la wiki/concepts/my-file.md
 
# 2. 권한 변경
chmod 644 wiki/concepts/my-file.md
 
# 3. Frontmatter 형식 확인 (YAML 문법)
head -10 wiki/concepts/my-file.md

문제 2: process_query_results.py 실행 시 “Sources 부족” 에러

증상: "Sources 부족: 2개 (최소 3개 필요)"

원인: Insight 저장에는 최소 3개 이상의 sources 필요

해결책:

# 3개 이상 sources 제공
python3 system/scripts/process_query_results.py \
  --sources "wiki/concepts/file1.md,wiki/concepts/file2.md,wiki/concepts/file3.md" \
  --create-insight

문제 3: Broken Link 감지됨 (wiki-lint 수동 검토)

증상:

[Manual Review] Broken Link
- wiki/concepts/wiki-quality-standards.md
  references:

해결책:

# Option 1: 파일 경로 확인 후 수정
ls wiki/concepts/wiki-qua*
 
# Option 2: 링크 삭제 (irrelevant인 경우)
# wiki-quality-standards.md 열어서 broken link 제거
 
# Option 3: 링크 수정 (오타인 경우)
#  → [[wiki/concepts/wiki-quality-standards]]

문제 4: “Orphan Page” 경고

증상:

[Manual Review] Orphan Page (역링크 0개)
- wiki/concepts/my-concept.md

해결책 (의사결정 트리):

Orphan인가?
├─ 아직 작성 중 → Comment 추가: "# TODO: 링크 추가 필요"
├─ 다른 페이지에서 참조해야 함 → Related Pages에 역링크 추가
│  (예: concepts/related-concept.md에서  추가)
├─ 더 이상 필요 없음 → delete
└─ 독립적으로 유용함 → keep (문제 없음)

문제 5: Contradiction 감지됨

증상:

## ⚠️ Contradiction

[[concepts/etl-design-framework]] claims: "ETL은 변환 후 로드"
But [[99-Archive/sources/aws-glue-spec]] shows: "AWS Glue는 ELT 지원"

**Reconciliation**: [analysis needed]

해결책:

충돌 분석:
1. 두 주장 모두 확인 (원문 검토)
2. 해결 방법 선택:
   a) 둘 다 참 → "ETL과 ELT 모두 지원" 으로 수정
   b) 하나만 참 → 잘못된 정보 수정
   c) 문맥 다름 → 각각 적용 범위 명시

FAQ

Q1: 자동화를 끄려면?

A: Hooks를 비활성화하려면:

# Hook 스크립트 제거 또는 이름 변경
mv .claude/hooks/post-edit-frontmatter.sh .claude/hooks/post-edit-frontmatter.sh.bak

Q2: wiki-lint가 너무 자주 실행되는데?

A: Cron 스케줄 조정:

# 현재: 매주 금요일 17:00
# 변경 예: 매월 마지막 금요일만
0 17 22-28 * 5 (매월 22-28일 금요일)
 
# 또는 수동 실행만
# Cron 제거 후 필요할 때만: python3 ./.claude/scripts/wiki-lint.py --auto-fix --apply

Q3: Insight가 자동으로 생성되지 않는데?

A: 확인사항:

3개 이상 sources? → --sources "file1,file2,file3" 확인
—create-insight 옵션? → 없으면 추가
Dry-run이었나? → --dry-run 제거

# 올바른 명령어
python3 system/scripts/process_query_results.py \
  --question "Q" \
  --answer "A" \
  --sources "file1.md,file2.md,file3.md" \
  --create-insight \
  --update-log

Q4: log.md가 너무 길어진 경우?

A: 이전 항목 정리 (연 단위로 보관):

# 1. 2026년 전 항목을 별도 파일로 저장
grep "## \[202[0-5]" wiki/log.md > wiki/log-archive-2020-2025.md
 
# 2. log.md에서 제거
# 수동으로 편집하거나 스크립트 사용
 
# 3. log.md는 현재 연도만 유지

Q5: 여러 명이 동시에 편집하면?

A: Git conflict 처리:

# 1. Push 전에 Pull
git pull
 
# 2. Conflict 발생 시
git status  # conflict 파일 확인
# 파일 열어서 <<<< ==== >>>> 표시 부분 수정
git add <파일>
git commit -m "merge: conflict resolved"
git push

신입 온보딩 (30분 가이드)

시간 배분

5분: 개요 (아키텍처 이해)
10분: 스크립트 데모 (wiki-lint, process_query)
10분: 스킬 데모 (/ingest, /query)
5분: 정기 작업 체크리스트

스텝 1: 아키텍처 이해 (5분)

핵심 개념 3가지:

1. Layer 1 (Hooks): 파일 저장 시 자동 검증
   - 사용자는 신경 쓸 필요 없음 (투명하게 작동)

2. Layer 2 (Scripts): 배치 처리 (명시적 실행)
   - wiki-lint: 주 1회 (금요일)
   - update-index: 월 1회 (월말)

3. Layer 3 (Skills): LLM 기반 (Claude와 대화)
   - /ingest: raw/ → sources/
   - /query: 검색 → insights/
   - /lint: 문제 감지 → 수정 제안

스텝 2: 스크립트 데모 (10분)

데모 1: wiki-lint 실행

# 1. Dry-run으로 확인
python3 ./.claude/scripts/wiki-lint.py --auto-fix
 
# 2. 결과 해석
# "Files to fix: 3" → Frontmatter, source_count 문제
# "Major 이슈 0" → 심각한 문제 없음
 
# 3. 실제 적용 (권한 확인 후)
python3 ./.claude/scripts/wiki-lint.py --auto-fix --apply

데모 2: process_query_results 사용

# 1. Dry-run으로 미리보기
python3 system/scripts/process_query_results.py \
  --question "위키 운영의 중요성" \
  --answer "정확한 메타데이터 유지..." \
  --sources "wiki/concepts/wiki-quality-standards.md,wiki/concepts/dap-wiki-automation-rules.md,wiki/concepts/dap-wiki-operations-guide.md" \
  --dry-run
 
# 2. 결과 확인 후 실제 저장
python3 system/scripts/process_query_results.py \
  --question "위키 운영의 중요성" \
  --answer "정확한 메타데이터 유지..." \
  --sources "wiki/concepts/wiki-quality-standards.md,wiki/concepts/dap-wiki-automation-rules.md,wiki/concepts/dap-wiki-operations-guide.md" \
  --create-insight \
  --update-log
 
# 3. log.md 확인
tail wiki/log.md

스텝 3: 스킬 데모 (10분)

데모 3: /ingest 사용

사용자: /ingest raw/articles/my-new-article.md
Claude:
1. 파일 분석
2. sources/my-new-article.md 자동 생성 (골격)
3. 상세 내용 작성 제안
4. /lint으로 검증 권장

데모 4: /query 사용

사용자: /query "DAP 위키의 자동화 레벨은?"
Claude:
1. wiki/index.md 검색
2. 관련 파일 드릴다운
3. 답변 합성
4. 3+ sources → insights/ 저장 제안
5. log.md 자동 기록

스텝 4: 정기 작업 체크리스트 (5분)

일일 (자동화됨, 특별 조치 불필요)

✅ Hook: Frontmatter 검증
✅ Hook: Wikilink 검증
✅ Hook: Log 생성

주간 (금요일)

python3 ./.claude/scripts/wiki-lint.py --auto-fix --apply
Manual review 항목 확인 (Orphan, Contradiction 등)
log.md 점검

월간 (월말)

python3 ./.claude/scripts/update-index.py
wiki/index.md 업데이트 확인
Deprecated 페이지 정리 (필요 시)

온보딩 마무리

최종 체크:

# 1. 권한 확인
ls -la .claude/scripts/*.py
 
# 2. Python 의존성 확인
python3 --version
pip list | grep yaml
 
# 3. 첫 번째 wiki-lint 실행
python3 ./.claude/scripts/wiki-lint.py --auto-fix
 
# 4. 문제 없으면 완료! ✅

다음 학습 자료:

dap-wiki-data-pipeline — 데이터 흐름
wiki-operations-management-processes — 운영 프로세스
wiki-quality-standards — 품질 기준

추가 리소스

문서	위치	설명
전체 프로젝트	dap-wiki-ops-master-plan	마스터 플랜
자동화 규칙	dap-wiki-automation-rules	3계층 아키텍처
운영 가이드	dap-wiki-operations-guide	신입 온보딩
데이터 흐름	dap-wiki-data-pipeline	파이프라인 설계
품질 기준	wiki-quality-standards	검증 규칙
테스트 보고서	`system/docs/Sprint4-Week4-Integration-Report.md`	성능 벤치마크

문의 & 피드백

질문 또는 개선 사항이 있으면:

Slack: wiki-automation
Jira: DAP-Wiki-Ops
직접 연락: PM (a03298@company.com)

마지막 업데이트: 2026-04-28
상태: ✅ Production Ready

JYP Garden

탐색기

Wiki 자동화 운영 가이드 (사용자 매뉴얼)

Wiki 자동화 운영 가이드 (사용자 매뉴얼)

📚 목차

개요

자동화 아키텍처

데이터 흐름

스크립트 사용 가이드

1. wiki-lint.py (Wiki 건강 체크)

기본 사용법

옵션 설명

결과 해석

Cron 설정 (OS 레벨 자동 실행) ⚠️

2. update-index.py (Index 갱신)

기본 사용법

결과 예시

Cron 설정 (OS 레벨 월말 자동 갱신) ⚠️

3. process_query_results.py (Query 결과 처리)

기본 사용법

옵션 설명

결과 해석

스킬 사용 가이드

1. /ingest (소스 수집 자동화)

기본 작업 흐름

지원 Mode

2. /lint (위키 건강 체크 & 수정)

기본 작업 흐름

결과 액션

3. /query (위키 검색 & Insight 생성)

기본 작업 흐름

파일링 기준

자동화 옵션

Troubleshooting

문제 1: wiki-lint 실행 후 파일이 수정되지 않음

문제 2: process_query_results.py 실행 시 “Sources 부족” 에러

문제 3: Broken Link 감지됨 (wiki-lint 수동 검토)

문제 4: “Orphan Page” 경고

문제 5: Contradiction 감지됨

FAQ

Q1: 자동화를 끄려면?

Q2: wiki-lint가 너무 자주 실행되는데?

Q3: Insight가 자동으로 생성되지 않는데?

Q4: log.md가 너무 길어진 경우?

Q5: 여러 명이 동시에 편집하면?

신입 온보딩 (30분 가이드)

시간 배분

스텝 1: 아키텍처 이해 (5분)

스텝 2: 스크립트 데모 (10분)

스텝 3: 스킬 데모 (10분)

스텝 4: 정기 작업 체크리스트 (5분)

일일 (자동화됨, 특별 조치 불필요)

주간 (금요일)

월간 (월말)

온보딩 마무리

추가 리소스

문의 & 피드백

그래프 뷰

목차