From 73f5ffe8345bd80af47e3ffce40f05b07d0ce193 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Sat, 6 Dec 2025 17:54:07 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B0=9C=EB=B0=9C=20=EA=B3=BC=EC=A0=95?= =?UTF-8?q?=EC=97=90=EC=84=9C=20=EB=AC=B8=EC=84=9C=20=EC=A0=95=EB=A6=AC=20?= =?UTF-8?q?=EC=9B=90=EC=B9=99=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 기능 개발 시 문서화 흐름 (scenarios → plans → troubleshooting → README → book → AGENTS.md) - 문서 역할 구분 (항상성 vs 진화 vs 현재 상태 vs 룰) - Journey 내부 흐름 명시 - 312_문서_작성_원칙.md 섹션 8로 추가 --- .../312_문서_작성_원칙.md | 58 ++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/book/300_architecture/312_문서_작성_원칙.md b/book/300_architecture/312_문서_작성_원칙.md index 2fe7e39..125c980 100644 --- a/book/300_architecture/312_문서_작성_원칙.md +++ b/book/300_architecture/312_문서_작성_원칙.md @@ -207,7 +207,63 @@ --- -## 8. 참고 문서 +## 8. 개발 과정에서 문서 정리 원칙 + +### 기능 개발 시 문서화 흐름 + +새로운 기능을 만들 때 다음 순서로 문서를 작성/업데이트합니다: + +1. **`journey/scenarios/`**: UX 시나리오 작성 (만들기 전) + - 사용자 경험 관점에서 기능 정의 + - "어떤 기능을 만들지" 먼저 정의 + +2. **`journey/plans/`**: 구현 계획 작성 (만들기 전) + - 아키텍처/Phase/필요작업만 + - 구현 완료 시 `troubleshooting/`으로 이동 + +3. **`journey/troubleshooting/`**: 구현 과정 기록 (만들면서/만든 후) + - 문제 해결, 교훈, 테스트 결과 + - 하나의 파일에 통합 (시나리오/테스트/리포트 별도 파일 금지) + +4. **서비스 README.md**: 핵심 사항 업데이트 (만든 후) + - 엔드포인트, 환경변수, 사용 방법 + - 자주 변하는 구체적 정보 + +5. **`book/`**: 원칙 변경 시 업데이트 (필요시) + - 아키텍처 원칙이 바뀌면 반영 + - `guidelines/`에 개발 가이드라인 추가/수정 + +6. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시) + - 새로운 작업 규칙이 생기면 반영 + +### 문서 역할 구분 + +| 문서 종류 | 역할 | 변경 빈도 | +|----------|------|----------| +| `book/` | 항상성, 원칙, 철학 | 거의 변하지 않음 | +| `journey/` | 진화 과정 (scenarios → ideas → research → plans → troubleshooting) | 계속 추가됨 | +| 서비스 README.md | 현재 상태 (포트, 엔드포인트, 환경변수) | 자주 변함 | +| `AGENTS.md` | 개발자별 룰, 운영 규칙 | 필요시 변경 | + +### Journey 내부 흐름 + +``` +scenarios/ (UX 정의) + ↓ +ideas/ (아이디어 탐색) + ↓ +research/ (이론적 기반) + ↓ +plans/ (구현 계획) + ↓ +troubleshooting/ (실제 구현) +``` + +**참고**: 각 단계는 필수가 아니며, 필요에 따라 생략 가능 + +--- + +## 9. 참고 문서 - AGENTS.md: 전체 개발 가이드 - 311_FastAPI_구조_원칙.md: 코드 구조 원칙