diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index 5c2450b..ac7dba9 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -57,6 +57,32 @@ - `plans/archive/`: 구현 완료된 계획 (참고용 보관) - `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned) +### 인덱스 README.md + +**경로**: `DOCS/journey/research/`, `DOCS/journey/ideas/` 등 폴더 내부 +**파일명**: `README.md` +**용도**: 해당 폴더의 문서 인덱스 및 목차 역할 + +**규칙**: +- **인덱스/목차 역할만** - 문서 목록과 간단한 설명 +- **상세 내용은 링크로 참조** - 트러블슈팅, 계획 등 실제 문서로 링크 +- **중복 작성 금지** - 상세 내용을 README에 다시 작성하지 않음 +- **핵심 키워드만** - 각 문서의 핵심만 간단히 나열 +- 100줄 이하 유지 + +**예시**: +```markdown +## 성능 비교 테스트 +- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md) + - 초기: FastPath 49.6%, 제로샷 임베딩 23.4% + - 개선: 제로샷 임베딩 70.2% (+46.8%p) +``` + +**금지**: +- 트러블슈팅 문서의 상세 내용을 README에 다시 작성 +- 구현 코드나 테스트 결과 상세 재현 +- troubleshooting 문서의 "교훈" 섹션 전체 복사 + --- ## 2. 작성 규칙 @@ -242,11 +268,15 @@ - 엔드포인트, 환경변수, 사용 방법 - 자주 변하는 구체적 정보 -5. **`book/`**: 원칙 변경 시 업데이트 (필요시) +5. **인덱스 README.md** (journey/research/, journey/ideas/ 등): 인덱스 역할만 + - 문서 목록과 간단한 설명, 상세는 링크로 참조 + - 중복 작성 금지 (troubleshooting 내용 재작성 금지) + +6. **`book/`**: 원칙 변경 시 업데이트 (필요시) - 아키텍처 원칙이 바뀌면 반영 - `guidelines/`에 개발 가이드라인 추가/수정 -6. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시) +7. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시) - 새로운 작업 규칙이 생기면 반영 ### 문서 역할 구분 @@ -256,6 +286,7 @@ | `book/` | 항상성, 원칙, 철학 | 거의 변하지 않음 | | `journey/` | 진화 과정 (scenarios → ideas → research → plans → troubleshooting) | 계속 추가됨 | | 서비스 README.md | 현재 상태 (포트, 엔드포인트, 환경변수) | 자주 변함 | +| 인덱스 README.md (research/, ideas/ 등) | 문서 목차/인덱스, 상세는 링크 참조 | 새 문서 추가 시 | | `AGENTS.md` | 개발자별 룰, 운영 규칙 | 필요시 변경 | ### Journey 내부 흐름