Docs CI 스킬 — 문서를 코드처럼 검증한다

문서 내용이 아니라 문서를 지키는 파이프라인을 만든다. 산출물은 GitHub Actions 워크플로우 + 드리프트 감지 스크립트 + docs/docs.yaml 매니페스트 규약.

입력

$ARGUMENTS

docs.yaml 매니페스트 (드리프트 감지의 계약)

docs 스위트의 모든 스킬이 쓰고, 이 스킬의 검사가 소비한다:

# docs/docs.yaml — 문서 ↔ 코드 매핑
docs:
  - path: docs/ARCHITECTURE.md
    covers: ["src/**"]          # 이 문서가 설명하는 코드 경로
    last_reviewed: 2026-07-27   # 마지막으로 사람이/에이전트가 검토한 날
  - path: docs/api/openapi.yaml
    covers: ["src/api/**", "src/routes/**"]
    last_reviewed: 2026-07-27
  - path: docs/ops/runbooks/
    covers: ["deploy/**", "monitoring/**"]
    last_reviewed: 2026-07-27
review_max_age_days: 90

드리프트 판정: covers 경로의 최신 커밋이 last_reviewed보다 새로우면 stale. review_max_age_days 초과도 stale.

설치하는 검사 (프로젝트에 맞게 선택)

검사	도구/방법	실패 정책
깨진 링크	lychee (lycheeverse/lychee-action)	내부 링크 깨짐 = fail, 외부 = warn
OpenAPI 스타일	redocly lint 또는 spectral lint	fail
API breaking 변경	oasdiff breaking base rev --fail-on ERR	fail + PR 코멘트
Code-first 명세 드리프트	CI에서 명세 재생성 → git diff --exit-code	fail
mermaid 문법	블록 추출 → mmdc -i x.mmd -o /dev/null	fail
문서 신선도	scripts/check-docs-freshness.sh (docs.yaml 기반)	warn (또는 이슈 생성)
문서-코드 동시 변경	src/api/** 변경 && docs/api/** 미변경 → PR 경고 코멘트	warn
CHANGELOG	conventional commits + git cliff (릴리스 시)	자동 생성
프리뷰 배포	docs 사이트 있으면 PR별 프리뷰 URL	—

CHANGELOG 자동화 주의: 커밋 형식이 [타입] 제목(rules/git-workflow.md)이면 conventional commits가 아니므로 git-cliff 커스텀 파서(commit_parsers) 설정 필요.

실행 절차

1. 프로젝트 진단: 어떤 문서/명세가 존재하나 (docs/, openapi.*, mermaid 블록, docs 사이트 생성기)
2. 존재하는 것에 맞는 검사만 선택 — OpenAPI 없는 프로젝트에 spectral 게이트 넣지 않기
3. docs/docs.yaml 생성/갱신 (기존 문서 스캔해서 covers 초안 작성 — 사용자가 다듬을 수 있게 주석 포함)
4. {project}/scripts/check-docs-freshness.sh 생성 — 템플릿 templates/check-docs-freshness.sh를 대상 프로젝트의 {project}/scripts/로 복사
5. .github/workflows/docs-ci.yml 생성 (템플릿: templates/docs-ci.yml에서 해당 프로젝트에 필요한 잡만) — 트리거 브랜치가 main 고정이므로 브랜치 전략에 맞게 조정 (develop 운용 시 추가)
6. 로컬에서 1회 실행해 결과 확인 후 보고: bash scripts/check-docs-freshness.sh

하네스 연동 (이 플러그인의 다른 컴포넌트와)

• TTH 모드: hooks/docs-sync.sh가 스토리 완료마다 변경 파일을 .docs-queue/에 적재 → ralph-loop가 docs-writer 스폰. docs-ci는 그 결과를 CI에서 다시 검증하는 마지막 층
• /docs sync 커맨드: docs.yaml 기반 stale 문서 목록을 보고 → 해당 영역의 docs-* 스킬로 갱신 위임

제약

• 워크플로우/스크립트/docs/만 생성. 앱 소스 수정 금지
• 설치 안 된 도구를 요구하는 검사는 continue-on-error 또는 조건부(if: hashFiles(...))로
• 기존 CI 워크플로우가 있으면 덮어쓰지 말고 별도 docs-ci.yml로 추가