문서 및 개발 관리 컨벤션
이 문서는 구현, 공개 문서, 생성 API 참조, LLM용 산출물을 일치시키기 위한 기준 문서입니다. 컨벤션의 코딩 규칙을 보완하며, 패키지별 소유권이나 릴리스 규칙을 대체하지는 않습니다.
1. 문서 소유권
| 영역 | 소유자 및 편집 규칙 | 검증 |
|---|---|---|
docs/en/**, docs/ko/** 가이드·개념 문서 | 사람이 작성하는 원문입니다. 공개 내용은 영문·국문 페이지의 의미를 함께 맞춥니다. | pnpm docs:build |
docs/api/generated/** | 생성 API 참조입니다. TypeScript export와 JSDoc을 먼저 고치고, 출력물을 직접 고치지 말고 다시 생성합니다. | pnpm docs:api, pnpm docs:sync |
llmsData/** 및 생성 LLMS 파일 | 파생 학습·컨텍스트 산출물입니다. 정식 설명의 원문으로 취급하지 않습니다. | generator가 지원하면 pnpm llms:sync-docs --changed-files <paths> |
| README와 패키지 README | 발견과 진입을 위한 문서입니다. 설명을 중복하기보다 권위 있는 가이드 또는 API 페이지로 연결합니다. | 관련 빌드와 링크 검증 |
생성 파일도 리뷰할 수 있지만, 동작 수정은 생성물만 고치지 않고 원문, generator, 또는 export에 반영합니다.
2. 변경 분류
구현 전 변경을 다음 중 하나로 분류합니다.
- 공개 API — export type/JSDoc, API 참조 입력, 사용 예제, 그리고 호환성이 깨질 때의 migration 안내를 갱신합니다.
- 동작 또는 패턴 — canonical guide, 실행 가능한 예제, 문서의 동작을 증명하는 테스트를 함께 갱신합니다.
- 내부 유지보수 — 명령, 소유권, 실패 모드, 기여자 판단 기준이 바뀔 때만 개발자 문서를 갱신합니다.
- 생성물 갱신만 수행 — 원문 변경과 generator 명령을 커밋에 밝히며, 생성물을 독립 기능처럼 설명하지 않습니다.
관련 없는 문서 재작성과 동작 변경을 한 커밋에 섞지 않습니다. 문서만 독립적으로 리뷰할 수 있으면 docs(<area>): 커밋을 사용합니다.
3. 필수 개발 루프
기능과 유지보수 작업은 다음 순서를 따릅니다.
- 공개 type, 상태 전이, tool schema, 문서화된 invariant 중 하나로 원본 계약을 정합니다.
- 계약을 만족하는 최소 구현을 만듭니다.
- 사용자가 관찰할 수 있는 동작이면 집중 테스트와 실행 가능한 예제를 추가·갱신합니다.
- 권위 있는 가이드와 발견 링크를 갱신합니다. 공개 페이지의 번역은 의미를 동등하게 유지하며, 임시 공백은 PR 또는 handoff에 명시합니다.
- 커밋 전 아래의 변경 비례 검증 게이트를 실행합니다.
문서는 미래 계획이 아니라 현재 동작을 설명해야 합니다. 구현이 미완이면 사용할 수 있는 것처럼 쓰지 말고, 제한과 필요한 증명을 적습니다.
4. 검증 게이트
| 변경 | 최소 게이트 | 해당할 때 추가 |
|---|---|---|
| 사람이 작성한 문서 | pnpm docs:build | pnpm llms:sync-docs --changed-files <paths> |
| 공개 TypeScript API | pnpm type-check | pnpm docs:api && pnpm docs:sync |
| 런타임 동작 또는 프레임워크 패턴 | 집중 패키지 테스트와 pnpm type-check | pnpm test, example build |
| 예제 앱 또는 브라우저 통합 | pnpm --filter example build | 사용자 소유 자격 증명으로 수동 증명, 비밀값 커밋 금지 |
| 릴리스·패키지 도구 | pnpm verify:package-exports, pnpm verify:package-tarballs | pnpm verify:private-tools |
pnpm docs:full은 전체 문서 파이프라인입니다. 광범위한 API 또는 문서 릴리스에는 사용하고, 집중 개발 중에는 위의 좁은 명령으로 빠르게 피드백을 받습니다.
패키지 빌드, runtime export 로딩, 배포 archive 내용, lint, 테스트, 예제 앱, 문서, private tooling을 모두 포함한 저장소 전체 pre-merge 검증은 pnpm verify:all로 실행합니다.
5. 리뷰 및 handoff 기록
문서에 영향을 주는 PR 또는 handoff에는 다음을 적습니다.
- 바뀐 권위 문서와 영향을 받는 생성물;
- 주장을 증명하는 구현·예제·테스트;
- 실행한 명령과 결과;
- 미번역 페이지, 사용할 수 없는 외부 자격 증명, 남은 수동 증명.
이 기록으로 문서 리뷰를 마지막 서식 작업이 아니라 소유권이 명확한 개발 관리 활동으로 만듭니다.