문서 동기화
문서는 조용히 표류합니다. README가 이동한 파일을 언급해도 아무 것도 실패하지 않습니다. 스택된 PR 단계 또는 완료된 기능 이후, PR이 열리기 전에 이 스킬을 실행하세요.
이 스킬의 계약에는 커밋이 포함됩니다. 허락 없이 커밋할 수 있으며, 항상 **현재 브랜치(main이 아님)**에 커밋합니다.
건너뛰어야 할 때
- 문서가 참조하는 항목이 변경되지 않은 경우(순수 내부 로직). 여전히 PR의 테스트 섹션에 "문서 확인됨, 표류 없음"을 작성하여 리뷰어가 실행되었음을 알리세요.
- 사용자가 명시적으로 아직 문서 커밋을 원하지 않는 경우.
인벤토리: docs/DOCS.md
범위 내 문서 목록은 AGENTS.md가 아닌 docs/DOCS.md에 있습니다. 이렇게 하면 항상 켜져 있는 컨텍스트가 동기화할 때마다 커지지 않습니다.
# 문서 인벤토리
| 경로 | 소유 항목 | 생성기 |
|---|---|---|
| README.md | 소개, 설정, 환경 변수, 레이아웃 | |
| AGENTS.md | 에이전트 규칙 + 프로젝트 게이트 | |
| packages/api/README.md | 엔드포인트, 스크립트, 환경 변수 | |
| docs/api/openapi.json | API 참조 | `pnpm generate:openapi` |
## 고정됨 (동기화로 편집되지 않음)
- docs/plans/
## 표류 검사
<!-- 실제로 발생한 실수당 하나의 grep, 이유를 설명하는 주석 포함 -->
첫 실행: 인벤토리를 구축하세요. 루트 및 패키지별 README.md / AGENTS.md / CLAUDE.md, 기여자 문서, API 문서(OpenAPI 설명, llms.txt), 스킬 및 규칙 디렉토리, 환경 변수 참조(.env.example, 구성 스키마)를 스캔하세요. 각 문서가 소유한 항목을 기록하세요.
매 실행: 인벤토리에 없는 문서를 찾으면 같은 커밋에 추가합니다.
절차
- 감사. 브랜치를 기준(base)과 비교(
git diff <base>...HEAD --stat)하여 문서가 언급할 수 있는 변경 사항(경로, 패키지 이름, 라우트, 명령어 및 스크립트, 환경 변수, 내보낸 API, 동작, 규칙)을 나열합니다. - 검증. 인벤토리의 각 문서에 대해 코드와 대조하여 모든 구체적인 주장을 확인합니다: 각 파일이 해당 경로에 존재하는지, 각 명령어가 매니페스트에 있는지, 각 환경 변수가 실제로 읽히는지, 각 라우트와 내보내기가 설명된 대로 존재하는지. 코드를 읽으세요; 이전에 작성한 문구를 포함하여 문구를 신뢰하지 마세요.
- 편집. 표류를 수정합니다. 코드가 수행하는 작업을 설명하고, 문서를 더 좋게 보이게 하기 위해 동작을 지어내지 마세요. 코드와 문서가 불일치하고 어느 쪽이 잘못되었는지 알 수 없는 경우 추측하지 말고 플래그를 지정하세요.
- 재생성. 인벤토리에 나열된 각 생성기 명령어를 실행합니다. 생성된 문서를 수동으로 편집하지 마세요.
- 표류 검사 실행
docs/DOCS.md에 나열된 표류 검사를 실행합니다. 동기화에서 반복될 가능성이 있는 실수(예: 이전 경로, 이름이 변경된 명령어)를 발견하면 그에 대한 grep을 추가하고 이유를 설명하는 주석을 포함하세요. - 커밋. 경로별로 파일을 스테이징하고,
git add -A는 사용하지 마세요. 현재 브랜치에 하나의 원자적 커밋을 만듭니다:docs(<범위>): <변경 사항>과 <무엇> 동기화. - 푸시 브랜치가 이미 원격을 추적하는 경우(
git pull --rebase먼저 실행).main에는 푸시하지 마세요.
규칙
- 고정된 기록:
docs/plans/에 있는 디자인, 계획 및 핸드오프는 당시 결정된 사항의 스냅샷입니다. 그렙에서 나타날 수 있습니다; 이는 예상된 것이며 표류가 아닙니다. 동기화에서 이를 편집하지 마세요. - 스파이크와 프로토타입은 삭제됩니다 방향성이 출시되거나 폐기되면 참조용으로 보관하지 않고 삭제됩니다. 프로덕션이 더 잘 알게 되면 스파이크의 결론은 저장소에서 가장 신뢰할 수 없는 텍스트입니다. 여전히 알 가치가 있는 것은 출시된 코드의 문서로 이동합니다.
- 크기 예산: 문서 라인은 PR 예산에 포함됩니다. 동기화로 인해 단계가 500줄을 초과하면 스택 맨 위에 문서 전용 단계로 랜딩하세요(
stacked-prs참조). - 포인터 파일은 작게 유지됩니다.
AGENTS.md를 가리키는CLAUDE.md또는GEMINI.md는 그 상태를 유지해야 합니다. 내용을 복사하지 마세요.