---
name: sync-user-docs
description: 코드 변경 후 사용자 문서(docs/guides, docs/api, docs/index.md, docs/glossary.md 등)를 코드 기반으로 동기화합니다.
argument-hint: "[패키지명]"
user-invocable: false
---

# Sync User Docs — 편집증적 사용자 문서 동기화

코드 변경 사항을 감지하여 프레임워크 **사용자** 대상 문서를 **코드 기반으로** 동기화한다. import 경로, 클래스 시그니처, 코드 예시, 용어 정의 등이 실제 코드와 일치하는지 검증하고 수정한다. **코드에는 존재하지만 문서에 없는 공개 API·모듈·패키지를 감지하여 문서를 신규 생성하거나 기존 문서에 섹션을 추가한다.**

> **원칙**: 코드가 유일한 진실의 원천(source of truth). 부정확한 문서 하나가 프레임워크 전체의 신뢰를 무너뜨린다. 의심의 눈으로 **모든** 항목을 검증한다. **반드시 서브에이전트에서 실행**하여 self-confirmation bias를 방지한다.

## 대상 문서

| 문서 | 역할 | 동기화 포인트 |
|------|------|-------------|
| `docs/guides/*.md` | 튜토리얼/사용 가이드 | import 경로, 코드 예시, 클래스 시그니처, 데코레이터 사용법 |
| `docs/api/**/*.md` | API 레퍼런스 (mkdocstrings) | `:::` 디렉티브의 모듈 경로, 섹션 구조 |
| `docs/api/index.md` | API 레퍼런스 목차 | 패키지 목록, 링크 |
| `docs/index.md` | 랜딩 페이지 | 코드 예시, 패키지 테이블, 의존성 그래프 |
| `docs/glossary.md` | 용어 사전 | 용어 정의, 코드 예시 |
| `docs/error-hierarchy.md` | 에러 계층 구조 | 에러 클래스 목록, 상속 관계 |
| `docs/di-container.md` 등 심화 가이드 | 심화 설명 | import 경로, 코드 예시, 클래스 시그니처 |
| `mkdocs.yml` | 빌드 설정 | `nav` 섹션, mkdocstrings `paths` |

---

## Phase 1: 변경 감지 + 커버리지 매트릭스

### 1-1. 변경 범위 결정

```bash
git diff --name-only HEAD~1..HEAD
# 또는 커밋 전이면:
git diff --name-only
git diff --cached --name-only
```

변경된 파일에서 영향받는 패키지를 추출한다.

### 1-2. 커버리지 매트릭스 (필수)

변경 유형 분류 **전에**, 전체 패키지 대비 문서 커버리지를 점검한다. 이 단계는 "변경된 패키지"뿐 아니라 **기존에 누락된 문서**도 감지하기 위한 것이다.

```bash
# 1. 전체 패키지 목록 수집
ls -d core/*/src plugins/*/src | sed 's|/src||' | sort

# 2. 문서 커버리지 대조 — 각 패키지에 대해 아래 문서 존재 여부 확인
#    - docs/guides/{패키지-주제}.md (가이드)
#    - docs/api/core/{패키지명}.md 또는 docs/api/plugins/{패키지명}.md (API 레퍼런스)
#    - docs/index.md 패키지 테이블에 해당 패키지 행 존재
#    - docs/glossary.md에 해당 패키지의 핵심 용어 존재
#    - mkdocs.yml nav에 해당 패키지 관련 항목 존재
```

**커버리지 매트릭스 출력 형식:**

| 패키지 | 가이드 | API 레퍼런스 | index.md | glossary | mkdocs nav |
|--------|--------|------------|----------|----------|-----------|
| spakky | O | O | O | O | O |
| spakky-opentelemetry | **X** | O | O | **X** | O (api만) |
| ... | ... | ... | ... | ... | ... |

**X 표시된 항목은 Phase 2에서 반드시 신규 생성 대상에 포함한다.** 변경된 패키지가 아니더라도, 커버리지 매트릭스에서 누락이 발견되면 동기화 대상이다.

### 1-3. 변경 유형 분류

| 카테고리 | 패턴 | 동기화 대상 |
|---------|------|-----------|
| **공개 인터페이스 변경** | ABC 기반 인터페이스/데코레이터 추가·수정·삭제, `__all__` 변경 | guides, glossary, index.md |
| **모듈 경로 변경** | 파일 이동·이름 변경, 패키지 구조 변경 | api docs (`:::` 디렉티브), guides (import 경로) |
| **패키지 추가·삭제** | `pyproject.toml` 신규, 패키지 디렉토리 추가·삭제 | api/index.md, index.md (패키지 테이블), mkdocs.yml (nav, paths) |
| **데코레이터 시그니처 변경** | `@Pod`, `@Aspect`, `@EventHandler` 등 파라미터 변경 | guides (코드 예시), glossary (용어 정의) |
| **에러 클래스 변경** | 에러 클래스 추가·삭제·이름 변경 | error-hierarchy.md |
| **의존성 변경** | `pyproject.toml` dependencies 변경 | index.md (의존성 그래프) |
| **문서 커버리지 누락** | 1-2 매트릭스에서 X로 표시된 항목 | 해당 문서 신규 생성 또는 기존 문서에 섹션 추가 |

코드와 이미 일치하는 카테고리는 건너뛴다.

## Phase 2: 문서별 동기화 (Write 에이전트)

각 문서를 순차적으로 동기화한다.

> **중요**: 이 Phase는 sync-docs 라우터의 Write 서브에이전트 프롬프트에 포함되어 실행된다.

### 2-1. docs/guides/*.md (튜토리얼)

**대상**: 변경된 패키지와 관련된 가이드 문서

서브에이전트에게 전달할 컨텍스트:
- 변경된 파일 목록과 diff
- 현재 가이드 문서 내용
- 패키지의 `src/` 디렉토리에서 공개 인터페이스 목록

**검증 항목**:

1. **import 경로**: 모든 `from ... import ...` 문이 실제 모듈 경로와 일치하는가
2. **클래스/함수 시그니처**: 생성자 파라미터, 메서드 시그니처가 코드와 일치하는가
3. **데코레이터 사용법**: 파라미터 이름·타입·기본값이 코드와 일치하는가
4. **코드 예시 실행 가능성**: 예시가 현재 API와 호환되는가 (import 경로, 메서드명, 파라미터)
5. **교차 참조 링크**: 다른 가이드·API 문서·용어 사전 링크가 유효한가

**동기화 규칙**:
- 코드에서 제거된 API를 사용하는 예시는 현재 API에 맞게 수정
- 모듈 이동 시 모든 import 경로를 일괄 수정
- 시그니처 변경 시 관련 코드 예시를 업데이트
- 새로 추가된 주요 기능은 기존 가이드의 적절한 위치에 추가 (기존 스타일에 맞춰)
- **코드에 존재하지만 가이드에 전혀 다뤄지지 않는 패키지·기능은 기존 가이드 스타일을 참고하여 신규 가이드를 생성** (mkdocs.yml nav에도 반영)

### 2-2. docs/api/**/*.md (API 레퍼런스)

mkdocstrings가 `:::` 디렉티브에서 코드를 자동 렌더링하므로, 디렉티브의 모듈 경로가 핵심이다.

**검증 항목**:

1. **`:::` 디렉티브 경로**: 각 디렉티브가 참조하는 모듈이 실제로 존재하는가
2. **섹션 구조**: 코드에서 제거된 모듈의 디렉티브가 남아있지 않은가
3. **새 모듈 누락**: 코드에 추가된 공개 모듈이 API 문서에 반영되었는가

**검증 방법**:

```bash
# API 문서에서 모든 ::: 디렉티브 추출
grep -rh "^:::" docs/api/ | sed 's/^::: //'
# 각 모듈 경로가 실제 존재하는지 확인
```

**동기화 규칙**:
- 모듈 이동/이름 변경 시 `:::` 디렉티브 경로 수정
- 모듈 삭제 시 해당 디렉티브와 섹션 제거
- 모듈 추가 시 기존 문서 스타일에 맞춰 섹션과 디렉티브 추가
- 패키지 추가/삭제 시 `docs/api/core/` 또는 `docs/api/plugins/` 파일 추가/삭제

### 2-3. docs/api/index.md (API 목차)

**검증 항목**:

1. Core/Plugins 패키지 목록이 실제 패키지와 일치하는가
2. 각 패키지 링크가 유효한가
3. 패키지 설명이 `pyproject.toml`의 description과 일치하는가

### 2-4. docs/index.md (랜딩 페이지)

**검증 항목**:

1. **30초 시작하기 코드**: import 경로와 API 사용법이 현재 코드와 일치하는가
2. **주요 기능 코드 예시**: 각 섹션의 코드가 현재 API와 호환되는가
3. **패키지 구조 테이블**: Core/Plugins 패키지 목록이 실제와 일치하는가
4. **의존성 그래프 (Mermaid)**: 노드와 엣지가 실제 의존성과 일치하는가
5. **튜토리얼 테이블**: 가이드 목록과 링크가 `docs/guides/`와 `mkdocs.yml`에 일치하는가

### 2-5. docs/glossary.md (용어 사전)

**검증 항목**:

1. 각 용어의 코드 예시가 현재 API와 일치하는가 (import 경로, 시그니처)
2. 코드에서 제거된 개념이 용어 사전에 남아있지 않은가
3. 새로 추가된 핵심 개념이 누락되지 않았는가 (데코레이터, 스테레오타입, 스코프 등) — **누락 시 기존 스타일에 맞춰 용어 항목을 추가**

### 2-6. docs/error-hierarchy.md (에러 계층)

**검증 항목**:

1. 에러 클래스 목록이 코드의 실제 에러 클래스와 일치하는가
2. 상속 관계가 코드와 일치하는가
3. import 경로가 유효한가

### 2-7. 심화 가이드 (di-container.md, aop-guide.md, event-system.md, plugin-api.md)

guides와 동일한 검증 항목을 적용한다. 변경된 패키지와 관련된 문서만 검증한다.

### 2-8. mkdocs.yml

**검증 항목**:

1. **nav 섹션**: 패키지 추가/삭제 시 네비게이션 항목이 일치하는가
2. **mkdocstrings paths**: 패키지 추가/삭제 시 소스 경로가 포함되어 있는가

## Phase 3: 편집증적 팩트체크 (Verify 에이전트)

> **중요**: 이 Phase는 sync-docs 라우터의 Verify 서브에이전트 프롬프트에 포함되어 실행된다. Write와 별도의 fresh context에서 실행되므로 self-confirmation bias를 방지한다.

### 검증 범위: 수정된 문서만이 아닌 전체 대상 문서

Verify 에이전트는 **Phase 2에서 수정/생성된 문서만 검증하지 않는다.** 다음을 모두 검증한다:

1. **Phase 2에서 수정/생성된 문서** — Write의 수정이 정확한지
2. **Phase 1 커버리지 매트릭스에서 O로 표시된 기존 문서** — 기존 문서에 이미 존재하던 코드 drift (잘못된 import 경로, 변경된 시그니처, 삭제된 API 등)
3. **docs/index.md, docs/glossary.md, mkdocs.yml** — 변경과 무관하게 항상 전체 검증

이렇게 해야 "변경된 파일 주변만 검증"하여 기존 불일치를 놓치는 문제를 방지할 수 있다.

Phase 2에서 수정한 문서와 위 범위의 기존 문서를 **의심의 눈**으로 전수 검증한다. 체크리스트를 **전부** 순회하며 위반을 찾는다. 이슈를 발견하지 못했더라도 체크리스트를 전부 순회했음을 명시한다.

### 3-1. import 경로 검증

수정된 문서의 모든 Python 코드 블록에서 import 문을 추출한다:

```bash
# 문서에서 import 문 추출
grep -rhoP "from [a-z_.]+ import" docs/ | sort -u
# 각 모듈이 실제로 존재하는지 확인
```

각 import에 대해:

- [ ] `from X.Y.Z import W` → `X/Y/Z.py` (또는 `X/Y/Z/__init__.py`)가 존재하는가?
- [ ] 해당 모듈에서 `W`가 정의되어 있거나 `__all__`에 포함되어 있는가?
- [ ] import 경로가 **현재** 패키지 구조를 반영하는가? (과거 경로가 아닌가?)

### 3-2~3-8. 나머지 검증 항목

| # | 영역 | 검증 포인트 |
|---|------|-----------|
| 3-2 | 시그니처 | 생성자 파라미터 이름·순서, 메서드 존재 여부, 파라미터 타입·기본값, 반환 타입 |
| 3-3 | 데코레이터 | 이름 존재 여부, 파라미터 시그니처 일치, import 경로 유효성 |
| 3-4 | 코드 예시 | 모든 import 포함 여부, 타입 힌트 일치, 동기/비동기 혼용 없음, 상속 타입 파라미터 정확 |
| 3-5 | mkdocstrings | `:::` 디렉티브 모듈 경로 해석 가능, 삭제된 모듈 잔존 없음, 새 모듈 누락 없음 |
| 3-6 | 내부 링크 | 파일 참조 존재, 앵커 참조 존재, API/가이드/용어사전 간 양방향 유효 |
| 3-7 | 용어·개념 | 정의와 실제 동작 일치, 삭제된 개념 잔존 없음, 에러 상속 관계 일치 |
| 3-8 | mkdocs.yml | nav 파일 경로 존재, mkdocstrings paths 완전, 새 패키지 반영 |

## Phase 4: 결과 보고

심각도별 분류: **Critical** (따라하면 실패) → **Warning** (오해 유발) → **Info** (동작 무관) → **미확인** (코드에서 확인 불가)

보고 포함 항목:
- 수렴 라운드 수 및 라운드별 이슈 수
- 심각도별 이슈 목록 (`[문서:라인] 문제 → 수정 내용`)
- 3회 반복 미해결 시 미해결 테이블 (문서, 이슈, 사유)
- 체크리스트 순회 결과 (영역별 검증/수정 건수)
- 변경 없음 시: "모든 체크리스트를 순회하였으며, 동기화가 필요한 불일치가 없습니다."

---

## 규칙

### 할루시네이션 제로 원칙

- **코드에서 직접 확인하지 않은 내용은 절대 작성하지 않는다.** "아마 이럴 것이다"로 빈 곳을 채우는 것은 부정확한 문서보다 나쁘다.
- **모든 수정의 근거를 소스 파일에서 확인한다.** import 경로, 클래스명, 메서드 시그니처, 파라미터 기본값 — 전부 실제 `.py` 파일을 읽고 대조한다.
- **확인할 수 없으면 수정하지 않고 "미확인"으로 보고한다.** 추측으로 채우지 않는다.
- **삭제는 추가보다 안전하다.** 코드에서 사라진 API의 문서는 제거한다. 코드에 새로 추가된 기능은 시그니처·import 경로·기본 사용법처럼 기계적으로 확인 가능한 부분만 작성한다. 동작 설명이 불확실하면 작성하지 않는다.
- **코드 예시는 import부터 검증한다.** `from X import Y`의 X가 실제 모듈 경로인지, Y가 해당 모듈에서 export되는 이름인지 확인한다.
- **기억에 의존하지 않는다.** 방금 읽은 코드라도 문서에 반영하기 전에 다시 확인한다. 확인 비용은 싸고, 오류 비용은 비싸다.

### 편집증적 검증

- Phase 3 체크리스트를 **전부** 순회한다. 이슈가 없어도 순회했음을 명시한다.
- Critical/Warning 이슈는 수렴 루프 내에서 **즉시 수정**하고, 최종 결과를 보고한다.
- 이슈 심각도를 **Critical / Warning / Info / 미확인** 4단계로 분류한다.
- **Critical**: 사용자가 문서대로 따라하면 실패하는 오류 (잘못된 import, 존재하지 않는 메서드, 틀린 시그니처)
- **Warning**: 오해를 유발할 수 있는 부정확 (오래된 설명, 누락된 파라미터)
- **Info**: 기능에 영향 없는 불일치 (스타일, 변수명 관례)
- **미확인**: 코드에서 확인할 수 없어 보류한 항목

### 일반 규칙

- **CHANGELOG.md는 수정하지 않는다** — 자동 생성 대상.
- 문서별 동기화는 **병렬 서브에이전트**로 실행한다.
- 문서 스타일은 기존 문서의 톤과 구조를 따른다 — 새로운 형식을 도입하지 않는다.
- 코드와 이미 일치하는 문서는 건드리지 않는다.
- **코드에 존재하지만 문서에 전혀 없는 패키지·기능은 기존 문서 스타일을 참고하여 신규 문서를 생성한다.**
- Mermaid 다이어그램 수정 시 `mermaid.md` 규칙을 준수한다.
- mkdocstrings 디렉티브 수정 시 기존 `options` 패턴을 유지한다.

$ARGUMENTS