DAP 위키 자동화 규칙 (Phase 2-2)
Phase 2-2 Deliverable
마스터 플랜을 실행 가능하게 만드는 자동화 규칙
Hooks, Scripts, Skills의 3계층 자동화 아키텍처를 정의합니다. 목표: 인간의 수동 작업 → 70% 자동화로 전환
자동화의 3계층 아키텍처
Layer 1: Hooks (Immediate, Event-Driven)
↓
Write/Edit 파일 → 자동 검증 + 처리
Layer 2: Scripts (Scheduled, Batch)
↓
Cron 또는 수동 트리거 → 자동 처리
(lint, index update, metadata 갱신)
Layer 3: Skills (LLM-Powered, Interactive)
↓
사용자 명령어 → 복잡한 synthesis 수행
(ingest, query, project)
Layer 1️⃣: Hooks (즉시 반응)
목표: 파일 수정 시마다 자동으로 검증 + 처리
Hook 1: Frontmatter 검증 (Edit/Write 후)
트리거: wiki/**/*.md 파일 변경
자동화 내용:
1. Frontmatter 필드 존재 여부 확인
- 필수 필드 누락? → 경고 + 제안
2. Date 필드 일관성 검사
- created > updated? → 오류
- published > harvested? → 오류
- updated를 현재 날짜로 자동 갱신
3. source_count = len(sources) 검사
- 불일치? → 자동 수정
4. URL 형식 검사
- HTTP(S) 또는 "internal"? → 아니면 경고
구현 방식:
.claude/hooks/post-edit-frontmatter.sh- Trigger: Edit/Write 도구 사용 후
- Runtime: 1-2초 (synchronous)
UX:
사용자: 페이지 수정 후 저장
시스템: ✅ Frontmatter valid
⚠️ source_count auto-corrected: 2→3
✅ updated 필드 auto-set: 2026-04-27
Hook 2: Wikilink 검증 (Edit/Write 후)
트리거: wiki/**/*.md 본문 또는 frontmatter에 wikilink 추가/수정
자동화 내용:
1. Broken link 감지
- [[concepts/non-existent-page]] → 오류
- [[99-Archive/sources/file_without_space]] → 경고 (파일명 규칙)
2. 링크 방향 검증 (Project ↔ Zettel)
- Zettel에서 ? → 오류
- Project에서 ? → OK
3. Cross-ref 완성도 확인
- 새 concept 생성인데 아무도 링크 안 함? → 알림
구현 방식:
.claude/hooks/post-edit-wikilinks.sh- Trigger: Edit/Write 후
- Runtime: 2-3초
UX:
사용자: [[concepts/new-concept]] 생성
시스템: 📝 Note: This page has no backlinks yet.
→ Add to or link from
Hook 3: Log 항목 자동 생성 (Create/Delete 시)
트리거: 새 파일 생성 또는 삭제
자동화 내용:
1. 파일 생성 시
- 파일 경로 → 페이지 타입 자동 감지 (sources, concepts, etc.)
- log.md에 자동 항목 생성:
## [YYYY-MM-DD] ingest | page-name
- File:
- Type: [concept/source/project/insight/entity]
2. 파일 삭제 시
- log.md에 기록:
## [YYYY-MM-DD] delete | page-name
- Reason: [사용자 확인 필요]
구현 방식:
.claude/hooks/post-create-log.sh- Trigger: Write/Delete 도구 사용
- Runtime: 0.5초
Layer 2️⃣: Scripts (정기 배치)
목표: 자동화된 Lint, Index 업데이트, 메타데이터 갱신
Script 1: Wiki Lint (자동화 부분)
실행 주기: 주 1회 (금요일) 또는 수동 /lint 스킬
자동화 범위:
✅ Frontmatter 검증 (Major)
- 필수 필드 존재 여부
- Date 필드 논리
- source_count 일치
✅ Link 검증 (Major)
- Broken links 감지
- Project ↔ Zettel 양방향 위반
- Orphan 페이지 목록화
✅ Metadata 검증 (Medium)
- valid_as_of 6개월 초과
- Stale data 플래그
⚠️ Manual Review 항목
- Orphan 페이지 판단 (keep/link/delete)
- Contradiction 섹션 해결
- Low-relevance sources 검토
구현 방식:
.claude/scripts/wiki-lint.py- 실행:
/lint스킬 또는 Cron (금요일 17:00) - Output: lint-report.md + 경고 목록
Report 포맷:
# Lint Report 2026-04-27
## 🔴 Major Issues (자동 수정 필요)
- Broken: [[concepts/wrong-page]] in [sources/page]
- source_count: 3 → 2 (auto-corrected)
## 🟠 Medium Issues (검토 후 수정)
- Stale: [[concepts/older-concept]] (valid_as_of: 2025-01-01)
- Orphan: [[concepts/new-concept]] (no backlinks)
## 🟡 Info (권장사항)
- Missing section: "관련 개념" in [[sources/page]]
- Citation needed: "AWS Glue provides..." (no source)Script 2: Index 자동 업데이트
실행 주기: 월 1회 (말일) 또는 즉시 (파일 생성 시)
자동화 내용:
1. wiki/index.md 테이블 자동 갱신
- Sources: 목록 추출
- Concepts: 목록 추출
- Projects: 상태별 분류
- Insights: 목록 추출
2. 카운트 자동 계산
- Total sources
- Total concepts
- Total projects (active/paused/done)
- Total insights
3. 최근 업데이트 자동 기록
- 지난 24시간: [recent list]
- 지난 주: [weekly list]
- 지난 달: [monthly list]
구현 방식:
.claude/scripts/update-index.py- 실행: 월말 자동 또는
/project-workflow스킬 - Input: wiki/ 폴더 파일 목록
- Output: wiki/index.md 업데이트
Script 3: Frontmatter 일괄 갱신
실행 주기: 분기 1회 (새로운 필드 추가 시)
자동화 내용:
1. 모든 페이지의 frontmatter 스캔
- 누락된 필드 감지
- 새 필드 추가 (template 기준)
2. Date 필드 일관성 검사
- created > updated인 경우 수정
- updated를 현재 날짜로 설정할 필요 시 플래그
3. 폐지된 필드 제거
- Phase 2-3에서 스키마 변경 시, 구 필드 제거
구현 방식:
.claude/scripts/batch-update-frontmatter.py- 실행: 수동 트리거 (변경 사항 발생 시)
- Runtime: 10-30초
Layer 3️⃣: Skills (LLM-Powered)
목표: 인간 판단이 필요한 복잡한 작업 자동화
Skill 1: /ingest (확장)
현재 상태: 기본 ingest 가능
확장 계획:
✅ Mode B (URL): WebFetch + 마크다운 변환 + frontmatter 자동 생성
⏳ Mode C (자연어 검색):
- WebSearch → 후보 3-5개 제시
- 사용자 선택 → Mode B 처리
⏳ Mode D (NotebookLM):
- 2개 이상 URL → 외부 API 호출
- Synthesis 결과 → wiki/insights/에 저장
자동화 포인트:
- Frontmatter 자동 생성 (source_type, harvested, tags 기반)
- raw/ + sources/ 페이지 연쇄 생성
- log.md 자동 기록
Skill 2: /query (기존 유지)
기능: 위키에서 질문에 답하는 합성
자동화 기회:
- Query 결과 → wiki/insights/에 자동 저장 (사용자 확인 후)
- 기존 페이지와 모순 발견 시 → ⚠️ Contradiction 플래그
Skill 3: /lint (기존 + 확장)
현재: 위키 건강 체크
확장:
- Major 이슈 자동 수정 (frontmatter, source_count 등)
- Medium 이슈 보고서 생성
- Info 이슈 제안
Skill 4: /project-workflow (기존 유지)
기능: 프로젝트 작업 완료 후 동기화 자동화
자동화 내용:
- log.md 기록
- 부모 프로젝트 업데이트
- index.md 행 추가
- 양방향 링크 검증
자동화 우선순위 (구현 순서)
Phase 2-2 즉시 구현 (현재)
- ✅ Layer 1 Hook 1: Frontmatter 검증
- ✅ Layer 1 Hook 2: Wikilink 검증
- ✅ Layer 2 Script 1: Lint (자동화 부분)
- ✅ Layer 3 Skill 1: /ingest (Mode B 확장)
Phase 2-3 (구현 로드맵)
- Layer 1 Hook 3: Log 자동 생성
- Layer 2 Script 2: Index 자동 갱신
- Layer 2 Script 3: Frontmatter 일괄 갱신
- Layer 3 확장: Mode C, D, Query→Insight
Phase 3 (검증)
- 모든 Hooks + Scripts 통합 테스트
- 스킬 호환성 검증
- 성능 + 안정성 평가
자동화 규칙 (Decision Tree)
언제 자동화를 적용하는가?
✅ 자동화 적합
- 반복적 + 기계적 작업 (날짜 갱신, 카운트 검증 등)
- 오류 가능성 높음 (broken links 감지 등)
- 시간 소비 많음 (lint 스캔, index 갱신)
⚠️ 자동화 검토
- 인간 판단 필요 (orphan 페이지 keep/delete)
- Nuance가 중요한 작업 (synthesis, query)
→ Solution: 자동화 + 인간 검토 (2단계)
❌ 자동화 부적합
- 창의적 작업 (concept 정의, narrative 작성)
- 초고 불명확한 상황 (새로운 edge case)
→ Solution: 사용자 직접 + 가이드 제공
구현 기술 스택
Hook 구현
- 언어: Bash / Python
- 위치:
.claude/hooks/ - Trigger: Edit/Write/Create/Delete 도구
- Runtime: Synchronous (< 5초)
Script 구현
- 언어: Python 3.8+
- 위치:
.claude/scripts/ - 실행: Cron (자동) 또는 수동 호출
- Input: wiki/ 폴더, CLAUDE.md 설정
- Output: .md 파일 또는 보고서
Skill 구현
- 언어: CLAUDE.md 하네스 + LLM
- 위치:
.claude/skills/ - Trigger: 사용자 명령어 (
/skill-name) - 특징: Stateful (대화 컨텍스트 유지)
성공 지표
자동화 투자 대비 효과
| 항목 | Before | After | 개선도 |
|---|---|---|---|
| Frontmatter 오류 | 월 3-5건 | 월 0-1건 | 70% 감소 |
| Broken links | 월 2-4건 | 월 0건 | 100% 제거 |
| Lint 소요시간 | 30분 | 10분 | 67% 단축 |
| Index 업데이트 | 월 20분 | 자동 | 100% 자동화 |
| 수동 작업 비율 | 60% | 20% | 70% 감소 |
다음 단계
Phase 2-3: 구현 로드맵
- 4주 스프린트 계획
- 각 자동화 항목의 상세 구현 스펙
- 테스트 계획 + 검증 기준
관련 개념
- dap-wiki-operations-guide — 운영 가이드 (자동화 기반)
- wiki-quality-standards — 검증 기준 (자동화 규칙의 근거)
- wiki-operations-management-processes — 프로세스 (자동화 대상)