73f5ffe834
- 기능 개발 시 문서화 흐름 (scenarios → plans → troubleshooting → README → book → AGENTS.md) - 문서 역할 구분 (항상성 vs 진화 vs 현재 상태 vs 룰) - Journey 내부 흐름 명시 - 312_문서_작성_원칙.md 섹션 8로 추가
271 lines
7.4 KiB
Markdown
271 lines
7.4 KiB
Markdown
# 문서 작성 원칙
|
|
|
|
**작성일**: 2025-10-13
|
|
**수정일**: 2025-12-02 (CLAUDE.md → AGENTS.md 참조 변경)
|
|
**참고**: AGENTS.md, 311_FastAPI_구조_원칙.md
|
|
|
|
---
|
|
|
|
## 1. 문서 종류별 규칙
|
|
|
|
### 트러블슈팅 문서
|
|
|
|
**경로**: `DOCS/journey/troubleshooting/`
|
|
**파일명**: `yymmdd_주제.md` (예: 251013_coldmail_ir_analyzer_fix.md)
|
|
**규칙**:
|
|
- 주제별 파일 분리 (날짜 중복 허용)
|
|
- 시간순 작성
|
|
- 교훈 섹션 필수
|
|
- 100줄 이하 유지
|
|
|
|
**필수 헤더**:
|
|
```markdown
|
|
# 제목
|
|
|
|
**날짜**: 2025-10-13
|
|
**작성자**: happybell80
|
|
**관련 파일**: `경로/파일명.py`
|
|
|
|
---
|
|
```
|
|
|
|
### 아키텍처 문서
|
|
|
|
**경로**: `DOCS/300_architecture/`
|
|
**파일명**: `3NN_주제.md` (예: 311_FastAPI_구조_원칙.md)
|
|
**규칙**:
|
|
- 작성일/수정일 명시
|
|
- 섹션 번호 사용
|
|
- 표, 다이어그램 권장
|
|
- 코드 예시 (올바름/금지) 포함
|
|
|
|
### 계획 문서
|
|
|
|
**경로**: `DOCS/journey/plans/`
|
|
**파일명**: `yymmdd_주제.md`
|
|
**용도**: 미래 계획, 아이디어만 (아직 구현 안 됨)
|
|
|
|
**규칙**:
|
|
- **구현 완료 시 `journey/troubleshooting/`으로 이동** (필수)
|
|
- **구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체
|
|
- **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화
|
|
- **시나리오/테스트/리포트 별도 파일 금지** - 하나의 파일에 통합
|
|
- 100줄 이하 유지
|
|
|
|
**구분**:
|
|
- `plans/`: 미구현 계획만 (will do)
|
|
- `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned)
|
|
|
|
---
|
|
|
|
## 2. 작성 규칙
|
|
|
|
### 핵심 원칙 (최우선)
|
|
|
|
**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함
|
|
- 불필요한 설명, 중복 내용, 장황한 문장 제거
|
|
- 필요한 정보만 간결하게 기록
|
|
- 관련 정보는 링크로 참조 (중복 작성 금지)
|
|
- **같은 내용인 경우 새로운 파일 생성하지 말고 기존 파일 수정하여 깔끔하게 정리**
|
|
|
|
### 절대 금지 사항
|
|
|
|
| 금지 | 이유 |
|
|
|------|------|
|
|
| 핵심 없는 장황한 설명, 중복 내용 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 |
|
|
| 쓸데없는 코드 작성 (전체 코드 블록) | 파일명:줄번호만 명시 |
|
|
| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 |
|
|
| 이모지 사용 | 명시적 요청 시만 허용 |
|
|
| 민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) | 보안 위험, 환경변수나 설정 파일로 분리하여 관리 |
|
|
|
|
### 파일 참조 형식
|
|
|
|
**올바름** (파일명:줄번호 + 간단 설명):
|
|
```markdown
|
|
- naverworks_briefing.py:58-74: 폴백 제거
|
|
- ir_analyzer.py:28: /api/query → /api/search
|
|
```
|
|
|
|
**금지** (전체 코드 복사, 추상적 표현):
|
|
```markdown
|
|
- naverworks_briefing.py에서 폴백 제거 ← 구체적 위치 없음
|
|
- ir_analyzer.py 파일 수정 ← 구체적 내용 없음
|
|
```python
|
|
# 전체 함수 코드 50줄 복사... ← 불필요
|
|
```
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 문서 구조
|
|
|
|
### 트러블슈팅 문서 구조
|
|
|
|
```markdown
|
|
# 제목
|
|
|
|
**날짜**, **작성자**, **관련 파일**
|
|
|
|
---
|
|
|
|
## 문제 상황
|
|
- 현상, 에러 메시지
|
|
|
|
## 해결 방안
|
|
- 파일명:줄번호 명시
|
|
- 수정 내용 간결히
|
|
|
|
## 구현 완료 (선택)
|
|
- 커밋 해시, 날짜
|
|
|
|
## 교훈 (필수)
|
|
- 왜 발생했는가
|
|
- 다음에 어떻게 방지할 것인가
|
|
```
|
|
|
|
### 아키텍처 문서 구조
|
|
|
|
```markdown
|
|
# 제목
|
|
|
|
**작성일**: 2025-10-13
|
|
**수정일**: 2025-10-13 (수정 이유)
|
|
|
|
## 1. 원칙
|
|
## 2. 규칙
|
|
## 3. 예시
|
|
## 4. 체크리스트
|
|
## 5. 참고
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 파일 크기 제한
|
|
|
|
### 규칙
|
|
- 모든 문서: 100줄 이하
|
|
- 초과 시: 주제별 분리 또는 참고/실행용 분리
|
|
|
|
### 예외
|
|
- 아키텍처 문서: 200줄까지 허용 (섹션 많은 경우)
|
|
- 단, 분리 가능하면 분리 우선
|
|
|
|
---
|
|
|
|
## 5. 교훈 작성 규칙
|
|
|
|
### 필수 항목
|
|
1. **원인**: 왜 문제가 발생했는가
|
|
2. **교훈**: 다음에 어떻게 방지할 것인가
|
|
3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_FastAPI_구조_원칙.md`, `312_문서_작성_원칙.md`)
|
|
|
|
### 올바른 예시
|
|
```markdown
|
|
## 교훈
|
|
|
|
### API 엔드포인트 검증 부족
|
|
- 구현 시 skill-rag-file API 스펙 미확인
|
|
- 추측으로 /api/query 사용, 실제는 /api/search
|
|
- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수
|
|
```
|
|
|
|
### 금지 예시
|
|
```markdown
|
|
## 교훈
|
|
|
|
에러가 발생했습니다. 다음에 조심하겠습니다.
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 비난조 문장 금지
|
|
|
|
### 금지 표현
|
|
- "잘못 작성됨"
|
|
- "버그가 많음"
|
|
- "엉망진창"
|
|
|
|
### 권장 표현
|
|
- "수정 필요"
|
|
- "개선 가능"
|
|
- "리팩토링 대상"
|
|
|
|
---
|
|
|
|
## 7. 체크리스트
|
|
|
|
문서 작성 전:
|
|
- [ ] **핵심만 간결하게 정리** (불필요한 설명/중복 제거, 링크로 대체)
|
|
- [ ] 파일명:줄번호로 위치 명시 (전체 코드 블록 금지)
|
|
- [ ] 확인된 사실만 기록 (추측/의사코드 제거)
|
|
- [ ] 파일명 형식 준수 (yymmdd_주제.md)
|
|
- [ ] 100줄 이하 확인
|
|
- [ ] 교훈 섹션 작성 (트러블슈팅)
|
|
|
|
문서 작성 후:
|
|
- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거
|
|
|
|
---
|
|
|
|
## 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: 코드 구조 원칙
|
|
- troubleshooting/ 폴더: 트러블슈팅 예시
|