diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index ac7dba9..035ecbe 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -49,8 +49,8 @@ - **구현 완료 시 `journey/plans/archive/`로 이동** (필수) - **구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 - **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화 -- **시나리오/테스트/리포트 별도 파일 금지** - 하나의 파일에 통합 -- 100줄 이하 유지 +- **Phase별 분리 가능**: 복잡한 계획은 Phase 1/2/3으로 분리 가능 +- 100줄 이하 유지 (Phase별 분리 시 각 파일 100줄 이하) **구분**: - `plans/`: 미구현 계획만 (will do) @@ -181,13 +181,35 @@ ## 4. 파일 크기 제한 -### 규칙 -- 모든 문서: 100줄 이하 -- 초과 시: 주제별 분리 또는 참고/실행용 분리 +### 문서 유형별 크기 제한 -### 예외 -- 아키텍처 문서: 200줄까지 허용 (섹션 많은 경우) -- 단, 분리 가능하면 분리 우선 +| 문서 유형 | 크기 제한 | 비고 | +|----------|----------|------| +| 트러블슈팅 문서 | 100줄 이하 | 단일 이슈 중심, 초과 시 주제별 분리 | +| 계획 문서 | 100줄 이하 | Phase별로 분리 가능 | +| 인덱스 README.md | 100줄 이하 | 목차/인덱스 역할만 | +| 리서치 문서 | 200줄 이하 | 논문 요약 등 긴 내용 허용 | +| 아키텍처 문서 | 200줄 이하 | 섹션 많은 경우, 분리 가능하면 분리 우선 | + +### 초과 시 처리 방법 + +**트러블슈팅 문서**: +- 단일 이슈 중심으로 유지, 핵심만 간결하게 +- 초과 시: 불필요한 설명/중복 제거 또는 주제별 분리 + +**계획 문서**: +- Phase 1/2/3으로 단계별 분리 가능 +- 또는 관련 troubleshooting 문서로 링크 + +**리서치/아키텍처 문서**: +- 분리 가능하면 주제별 섹션 분리 +- 또는 관련 문서로 링크 참조 + +### 기존 문서 처리 + +- **기존 100줄 초과 문서는 과도적 예외로 인정** +- 신규 작성 시부터 위 원칙 적용 +- 기존 문서 수정 시 가능하면 원칙 준수하도록 간소화 권장 --- @@ -238,7 +260,7 @@ - [ ] 파일명:줄번호로 위치 명시 (전체 코드 블록 금지) - [ ] 확인된 사실만 기록 (추측/의사코드 제거) - [ ] 파일명 형식 준수 (yymmdd_주제.md) -- [ ] 100줄 이하 확인 +- [ ] 문서 유형별 크기 제한 확인 (트러블슈팅/계획: 100줄, 리서치/아키텍처: 200줄) - [ ] 교훈 섹션 작성 (트러블슈팅) 문서 작성 후: @@ -262,7 +284,7 @@ 3. **`journey/troubleshooting/`**: 구현 과정 기록 (만들면서/만든 후) - 문제 해결, 교훈, 테스트 결과 - - 하나의 파일에 통합 (시나리오/테스트/리포트 별도 파일 금지) + - 단일 이슈 중심으로 통합 (관련 이슈는 하나의 파일에, 초과 시 주제별 분리) 4. **서비스 README.md**: 핵심 사항 업데이트 (만든 후) - 엔드포인트, 환경변수, 사용 방법