sync-user-docs - SKILL.md Agent Skill

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. 변경 범위 결정

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

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

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

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

# 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 에이전트)

각 문서를 순차적으로 동기화한다. 모든 문서는 sync-docs/doc-format.md의 포맷·문서별 규칙·Verifier 10항목을 따른다.

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

문서	동기화 조건	필수 대조
`docs/guides/*.md`, 심화 가이드	관련 공개 API·사용법 변경, 커버리지 매트릭스 X	import 경로, 클래스/함수/데코레이터 시그니처, 코드 예시, 교차 링크. 누락된 패키지·기능은 기존 스타일로 신규 가이드 생성 + `mkdocs.yml` 반영
`docs/api/*/.md`	모듈 추가·삭제·이동, 패키지 변경	모든 `:::` 디렉티브의 실제 모듈 존재, 삭제 모듈 제거, 신규 공개 모듈 추가
`docs/api/index.md`	패키지 추가·삭제·설명 변경	core/plugins 패키지 목록, 링크, `pyproject.toml` description
`docs/index.md`	패키지 구조·주요 API·의존성 변경	시작 코드, 기능 예시, 패키지 테이블, Mermaid 의존 그래프, 튜토리얼 테이블
`docs/glossary.md`	핵심 개념·데코레이터·스코프·용어 변경	코드 예시, 제거된 개념, 신규 핵심 용어
`docs/error-hierarchy.md`	에러 클래스 추가·삭제·상속 변경	에러 클래스 목록, 상속 관계, import 경로
`mkdocs.yml`	문서/패키지 추가·삭제	nav 파일 존재, mkdocstrings paths 완전성

API 문서 검증 시 grep -rh "^:::" docs/api/ | sed 's/^::: //'로 디렉티브를 추출하고 각 경로를 실제 코드와 대조한다. 코드와 일치하는 카테고리는 건드리지 않는다.

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

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

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

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

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

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

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

3-1. import 경로 검증

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

# 문서에서 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 경로·기본 사용법처럼 기계적으로 확인 가능한 범위만 작성한다.
Phase 3 체크리스트를 전부 순회한다. 이슈가 없어도 순회 완료를 명시한다.
심각도: Critical(문서대로 따라하면 실패), Warning(오해 유발), Info(동작 무관), 미확인(코드에서 확인 불가).
Critical/Warning은 수렴 루프 내에서 즉시 수정하고 최종 결과를 보고한다.
CHANGELOG.md는 수정하지 않는다. 문서 스타일은 기존 톤과 구조를 따르고, Mermaid는 mermaid.md, mkdocstrings는 기존 options 패턴을 유지한다.

$ARGUMENTS