其他技能
docs-sync
코드·설정·프리셋 변경 뒤 문서를 현행화한다. "문서 현행화", "README 갱신", "문서 최신화" 요청 시, 그리고 동작·경로·버전·수치를 바꾼 PR 을 올리기 직전에 사용. 문서의 주장을 실제 코드·명령 출력·공식문서와 대조해 정정하고, 다국어 짝 파일을 함께 갱신한다.
LeeYudok · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add LeeYudok/agents-scaffold --skill docs-sync技能说明
name: docs-sync description: 코드·설정·프리셋 변경 뒤 문서를 현행화한다. "문서 현행화", "README 갱신", "문서 최신화" 요청 시, 그리고 동작·경로·버전·수치를 바꾼 PR 을 올리기 직전에 사용. 문서의 주장을 실제 코드·명령 출력·공식문서와 대조해 정정하고, 다국어 짝 파일을 함께 갱신한다. user-invocable: true allowed-tools: Bash, Read, Grep, Glob, Edit, Write
문서 현행화 (docs-sync)
문서 stale 은 자동 게이트에 걸리지 않는다. 링크 체커는 깨진 링크만 보고, 테스트 스위트는 문서를 읽지 않는다. 그래서 절차로 잡는다.
원칙
- 주장 단위로 검증한다. 문서를 "읽고 자연스러운지" 보는 게 아니라, 문장이 담은 검증 가능한 주장(경로·버전·수치·동작·기본값)을 뽑아 실제와 대조한다.
- 근거 없이 고치지 않는다. 파일:라인, 명령 출력, 공식문서 URL 중 하나가 있어야 한다. 확인 못 한 건 지우지 말고 "미검증"으로 명시한다 — 조용히 삭제하면 정보가 사라진다.
- 낙관적 서술 금지. 부분만 동작하면 "동작한다"고 쓰지 않는다. 되는 범위와 안 되는 범위를 나눠 쓴다.
절차
1. 변경 범위 추출
git log --oneline <last-doc-commit>..HEAD
git diff --stat <last-doc-commit>..HEAD
문서에 영향 주는 변경만 추린다 — CLI 플래그·기본값, 파일/디렉터리 경로, 생성 산출물, 버전, 임계값·수치, 게이트 동작, 지원 범위.
2. 문서의 검증 가능한 주장 수집
대상: README*, AGENTS.md, CLAUDE.md, 각 디렉터리 README.md, 스킬/에이전트 문서.
grep -rn '`[^`]*/`\|버전\|기본값\|default\|v[0-9]\+\.[0-9]' README*.md docs/ 2>/dev/null
특히 낡기 쉬운 것: 디렉터리 트리 블록(신규 산출물 누락), 버전 표기, "자동으로 ~한다" 류 동작 서술, 지원 매트릭스.
3. 주장별 대조
| 주장 유형 | 검증 방법 |
|---|---|
| 경로·파일 존재 | ls / find — 실제 생성물 기준, 소스 트리 아님 |
| CLI 플래그·기본값 | <cmd> --help 실행. 문서 인용 금지, 출력이 근거 |
| 도구 버전 | <cmd> --version 실측 + 실측 일자 병기 |
| 동작("자동 로드한다") | 해당 도구 공식문서 URL. 없으면 "문서 근거 없음"으로 표기 |
| 수치·임계값 | 코드에서 grep 하거나 실제 산출물 측정(wc -c 등) |
| 게이트 동작 | 실제로 실행해서 exit code 확인 |
4. 다국어·짝 파일 동시 갱신 (필수)
한쪽만 고치면 나머지가 stale 이 되는데 어떤 게이트에도 안 걸린다.
ls README*.md # 다국어 README 전량
ls presets/lang-en/ 2>/dev/null # 언어 오버레이 존재 여부
- README 를 고쳤으면 존재하는 언어판 전부를 같은 커밋에서. 이 저장소 기준
README.md(영문) ·README.ko.md·README.zh.md·README.ja.md4종이다. .claude/**베이스 파일을 고쳤으면presets/lang-en/의 대응 파일도 같은 커밋에서.- 번역이 아니라 같은 사실의 각 언어판 — 수치·버전·경로·표 구조는 동일하게 유지한다.
- 언어별로 원문이 달라 일괄 치환이 깨진다. 파일마다
grep -n으로 교체 대상을 먼저 확인한다.
5. 게이트 실행
python3 .claude/scripts/knowledge_graph.py --check # 깨진 링크 0 확인
문서만 고쳤어도 테스트 스위트를 한 번 돌린다 — 문서에 인용된 명령·경로가 테스트와 어긋나 있으면 여기서 드러난다.
6. 보고
정정한 주장을 이전 → 이후 + 근거 형태로 나열한다. "README 를 갱신했다" 같은
요약만 남기지 않는다. 확인 못 해 "미검증"으로 남긴 항목도 함께 보고한다.
완료 기준
- 문서의 모든 검증 가능한 주장에 근거가 있거나 "미검증" 표시가 있다
- 다국어·오버레이 짝 파일이 같은 커밋에 포함됐다
- 링크 체커 0 broken, 테스트 스위트 통과
Learned warnings
- 낡은 서술을 삭제로 처리하면 "왜 없어졌는지" 추적이 끊긴다 — 실측 일자와 함께 "미검증"으로 남기는 편이 낫다.
- 디렉터리 트리 블록이 가장 자주 낡는다. 신규 산출물이 추가된 커밋에서 트리를 안 고치면 링크 체커도 못 잡는다(링크가 아니라 코드블록 안 텍스트라서).