문서 업데이트 (docs-update)
문서는 조용히 부패합니다: 아무것도 실패하지 않고, 텍스트가 더 이상 사실이 아닐 뿐입니다. 이 스킬은 최근 변경 사항이 영향을 미쳤어야 할 문서를 찾아 일치시킵니다.
아래 명령어는 ~/.claude/skills/docs-update/scripts/를 전체 경로로 표시합니다. 적힌 그대로 실행하세요 - 앞에 ~를 유지하고 확장하지 마십시오. 권한 규칙은 리터럴 명령 문자열과 일치하므로, /home/<사용자>/.claude/... (틸데가 확장된 형태), python3 ~/..., 상대 경로, cd를 먼저 수행하는 방식은 각각 다른 문자열이며, 각각 다시 프롬프트를 표시합니다. 틸데 경로는 "비공식적으로 적힌 절대 경로"가 아닙니다. 권한 규칙에게 그것은 경로 그 자체입니다.
문서는 변경 사항과 함께 제공되며, 그 후가 아닙니다. 기능 브랜치에 있다면, 해당 브랜치에 문서를 커밋하여 병합이 문서를 함께 가져가도록 하세요. 문서 후속 PR은 아무도 작성하지 않는 문서 PR입니다.
1. 범위 선택
우선 순위:
사용자가 말한 대로. "전체 검사", "v2.1 이후", "이 브랜치만" - 그대로 사용하세요. 전체 검사는 --full이며 모든 것을 읽습니다; 오랜 공백 후나 이 스킬을 리포지토리에 처음 적용할 때 적합한 선택입니다.
문서가 자신의 마지막 업데이트 지점을 기록하는 경우:
~/.claude/skills/docs-update/scripts/docscheck.py markers
문서에 마지막 업데이트: <날짜|sha>가 있으면, 해당 지점부터(--since) 해당 문서의 범위를 지정합니다. 문서 간에 일치하지 않으면 각자 자신의 범위를 가지며, 단일 답변은 없습니다.
그 외의 경우, git에서 파생:
~/.claude/skills/docs-update/scripts/docscheck.py scope
마지막으로 병합된 브랜치를 선호하며(브랜치 단위 작업이 사람들이 의도한 단위임), 그 다음으로 마지막 커밋을 사용합니다. --since <ref>로 재정의할 수 있습니다.
이 세션에서 수행된 작업은 스크립트가 볼 수 없는 경우입니다. 이 세션이 변경 사항을 만들었다면 이미 파일을 알고 있습니다. 사전 세션 참조를 --since로 전달하거나, 자신의 편집 목록에서 작업하세요.
scope는 kind=code와 kind=doc-already-touched를 분리합니다. 두 번째 목록이 중요합니다: 해당 문서는 변경과 함께 업데이트되었으므로, 부재가 아닌 정확성을 확인하세요.
2. 변경 사항이 실제로 도달하는 문서 찾기
~/.claude/skills/docs-update/scripts/docscheck.py impacted
변경된 각 코드 파일에 대해, 이 명령은 정확히 해당 경로를 명명하는 문서를 보고합니다. 변경한 파일을 인용하는 문서는 더 이상 사실이 아닐 가능성이 가장 높은 문서이며, 모든 문서를 다시 읽는 것보다 훨씬 좋은 출발점입니다.
의도적으로 전체 경로만 일치시킵니다. 상위 디렉토리도 일치시키는 것이 더 관대해 보이지만 쓸모가 없습니다: 모노레포에서 apps/web-nuxt/는 62개 중 55개 문서에 나타나므로, 모든 것이 모든 것에 영향을 미칩니다.
result=none은 정상이며 "할 일이 없다"는 뜻이 아닙니다. 즉, 어떤 문서도 이러한 경로를 명명하지 않으므로 주제로 판단해야 합니다. 이것이 3단계입니다.
3. 주제로 판단, 리포지토리 자체 문서 분류 체계 사용
impacted는 경로 인용을 찾습니다. 파일을 명명하지 않고 변경한 동작을 설명하는 문서를 찾을 수 없습니다. 따라서 변경 사항을 읽고 그것이 의미하는 바를 질문하세요.
먼저 이 리포지토리가 문서를 구성하는 방식을 파악하세요 - brain/, docs/, CONTEXT.md, ADR 디렉토리 등 - 그리고 그 구조를 따르고 새로운 것을 만들지 마세요. 프로젝트 스킬이 문서를 다루는 경우(.claude/skills/*), 이 스킬보다 우선합니다.
일반적인 매핑:
| 변경 사항 | 문서 |
|---|---|
| 새로운 사용자 대상 기능 | 기능 문서 + 해당 인덱스/카탈로그 행; README 기능 목록 |
| 기존 동작 변경 | 해당 기능의 문서 |
| 스키마, 인증, 빌드, 스토리지, 실시간, 제공자 | 해당 아키텍처 문서 |
| 명확하지 않은 결정, 또는 리뷰에서 드러난 결정 | 결정/ADR 로그, 그 이유와 함께 |
| 새로운 용어 | 용어집 |
| 새로운 또는 변경된 환경 변수, 명령어, 스크립트 | README 및 설정/운영 문서 |
| 새로운 의존성 | 스택/기술 목록 문서 (수동 유지보수되며 항상 잊혀짐 - 매니페스트 diff 확인) |
| 사용자 대상 변경 사항 | CHANGELOG [Unreleased] |
두 가지 함정:
- 산문에 내장된 파생 사실. "현재 버전은 2.16.2입니다"라고 말하거나 기술 스택을 나열하는 문서는 다른 곳에서 이동된 복사본입니다. 산문을 신뢰하지 말고 진실의 원천(매니페스트, 버전 파일)을 diff하세요.
- 역사적이거나 미래 지향적인 문서. CHANGELOG 항목, TODO 및 ROADMAP은 삭제되었거나 작성되지 않은 파일을 인용합니다. "수정"하지 마세요.
4. 인용이 여전히 유효한지 확인
~/.claude/skills/docs-update/scripts/docscheck.py links
두 가지 종류:
kind=link- 대상이 사라진 상대 마크다운 링크. 항상 실제 문제입니다.kind=source- 더 이상 존재하지 않는 인라인 코드 경로, 일반적으로 파일이 이동되었거나 이름이 변경되었기 때문입니다. 내러티브 문서는 제외되며, 중괄호 확장,<자리표시자>, 글로브 및 gitignore된 빌드 출력은 필터링되므로, 남은 것은 살펴볼 가치가 있습니다.
범위 내의 것을 수정하세요. 리포지토리 다른 곳에서 발견된 사항은 보고할 가치가 있지만, 조용히 작업 범위를 전체 검사로 확장하지 마세요.
5. 작성
작성하는 모든 것에 unslop 적용
추가하거나 변경하는 모든 줄에 unslop 스킬을 적용하세요. 문서화는 slop이 가장 큰 피해를 입히는 곳입니다: 무언가를 배우려는 사람들이 읽고, 신규자가 가장 먼저 접하며, 채팅 메시지와 달리 남아 있습니다.
특히 문서에서 나타나는 특징:
- 서론을 장황하게 늘어놓는 시작. "이 문서는 다음에 대한 개요를 제공합니다...", "이 섹션에서는 다음을 탐구할 것입니다...". 삭제하고 사실로 시작하세요.
- 코드를 산문으로 다시 설명하기. "
getUser함수는 사용자를 가져옵니다." 문장이 식별자를 영어로 확장한 것이라면 가치가 없습니다. 코드가 말할 수 없는 부분을 작성하세요: 제약 조건, 이유, 주의 사항. - 빈 강조어: 포괄적인, 강력한, 매끄러운, 강력한, 유연한, 간단히, 쉽게, 그냥. "그냥 X를 실행하세요"는 X가 간단하지 않을 때마다 거짓입니다.
- 답변이 확실할 때의 애매한 표현: "일반적으로", "전형적으로", "정상적으로는". 어떤 것이 확실하거나 이름을 지정할 수 있는 것에 의존합니다 - 이름을 지정하세요.
- 참고-그것-채우기: "다음 사항에 유의하는 것이 중요합니다", "참고하세요", "명심하세요". 그 뒤의 문장이 내용입니다; 그것만 제공하세요.
- 위의 페이지를 요약하는 요약 섹션. 문서에 재요약이 필요하다면 너무 깁니다.
- 이름을 반복하는 설명 열.
| --verbose | 자세한 출력을 활성화합니다 |행은 한 줄을 소모하고 아무것도 가르치지 않습니다. - 세 가지 규칙 채우기 - 처음 두 개와 다르지 않은 리듬을 위해 추가된 세 번째 예제.
파일에 맞추기, slop에 맞추지 않기
파일의 기존 어조에 맞추세요: 시제, 밀도, 항목이 한 줄인지 산문인지. 한 섹션이 갑자기 다르게 읽히는 문서는 일관되게 간결한 문서보다 나쁩니다.
이 두 규칙은 기존 문서 자체가 조잡할 때만 충돌합니다. 그런 경우: 구조와 밀도는 일치시키되, 채우기는 일치시키지 말고, 다른 부분을 건드리지 않은 섹션은 다시 작성하지 마세요. 문서 업데이트가 전체 파일을 다시 스타일링하는 것은 검토 불가능한 diff이며, 실제로 중요한 변경을 묻습니다. 문서 전체에 산문 정리가 필요하다면 그렇게 말하고 별도의 작업으로 제안하세요.
나머지
- 코드를 다시 설명하지 말고 소스 경로를 링크하여, 다음 변경이 산문을 조용히 모순시키는 대신 링크를 끊도록 하세요.
- 현재 사실을 현재 시제로 설명하세요. 문서는 변경 로그가 아닙니다: "X를 Y로 교체했습니다"는 CHANGELOG에, "시스템은 Y를 사용합니다"는 문서에 속합니다.
- 문서에 마지막 업데이트 표시가 있다면 이동하세요.
6. 보고
- 사용된 범위와 그 이유
- 업데이트된 문서 및 각 문서에서 변경된 사항
- 확인되었지만 의도적으로 남겨둔 문서
- 범위 밖에서 발견되었지만 나열만 하고 수정되지 않은 끊어진 링크 또는 인용
- 사용자 없이 판단할 수 없었던 사항