docs: 문서 작성 원칙 모순 해결

- 크기 제한 명확화: 문서 유형별로 표로 정리 (트러블슈팅/계획/인덱스 README: 100줄, 리서치/아키텍처: 200줄)
- 통합 vs 분리 기준 명확화: 문서 유형별 처리 방법 구분
- 기존 문서 처리 명시: 기존 초과 문서는 예외 인정, 신규부터 적용
This commit is contained in:
Claude-51124 2026-01-03 12:39:31 +09:00
parent 42eccf1342
commit 3d44042d46

View File

@ -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**: 핵심 사항 업데이트 (만든 후)
- 엔드포인트, 환경변수, 사용 방법