# 문서 작성 원칙

**작성일**: 2025-10-13
**수정일**: 2026-03-05 (SSOT 관리 기준 명시)
**참고**: AGENTS.md, 311_backend_coding_principles.md
**상위 원칙**: [0_VALUE Writing Principles](../../../../0_VALUE/02_Governance/writing-principles.md)

---

## 0. SSOT 관리 기준

- 문서 작성 상세 원칙의 SSOT는 본 문서(`312_writing-principles.md`)다.
- 상위 공통 원칙의 SSOT는 `0_VALUE/02_Governance/writing-principles.md`다.
- 본 문서는 robeing 프로젝트에 필요한 구체화 문서다.
- 원칙 충돌 시 상위 원칙을 먼저 검토하고, 예외가 필요하면 사용자에게 먼저 보고한 뒤 본 문서에 예외를 기록한다.
- 하위 폴더 `README.md`와 개별 문서는 원칙 본문을 반복하지 않고 SSOT 링크만 둔다.
- `상위 원칙` 링크는 문서를 해석하는 데 직접 필요한 최소 SSOT만 둔다. 관련 없는 원칙 문서를 관성적으로 모두 나열하지 않는다.
- 동일 원칙을 여러 문서에 복제하지 않는다. 필요 시 본 문서를 수정하고 참조 링크만 갱신한다.
- 실행/코드 정책(예: 폴백·예외 처리 최소화, 원인 경로 직접 수정)은 `AGENTS.md`를 SSOT로 본다.
- 본 문서의 리서치/시나리오 원칙은 문서화 표현 기준이며, 코드 동작 정책을 대체하지 않는다.

---

## 1. 문서 종류별 규칙

### 트러블슈팅 문서

**경로**: `DOCS/journey/troubleshooting/`
**파일명**: `yymmdd_주제.md` (예: 251013_coldmail_ir_analyzer_fix.md)
**규칙**:
- 주제별 파일 분리 (날짜 중복 허용)
- 시간순 작성
- 교훈 섹션 필수
- 크기 제한: 섹션 4 참조
- **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업을 troubleshooting 문서에 기록하면 다음 작업 시 계획이 어수선해짐. 남은 작업은 반드시 `plans/` 문서의 "남은 작업" 섹션에만 기록

**필수 헤더**:
```markdown
# 제목

**날짜**: 2025-10-13
**작성자**: happybell80
**관련 파일**: `경로/파일명.py`

---
```

### 아키텍처 문서

**경로**: `DOCS/300_architecture/`
**파일명**: `3NN_주제.md` (예: 311_backend_coding_principles.md)
**규칙**:
- 작성일/수정일 명시
- 섹션 번호 사용
- 표, 다이어그램 권장
- 코드 예시 (올바름/금지) 포함

### 계획 문서

**경로**: `DOCS/journey/plans/`
**파일명**: `yymmdd_주제.md`
**용도**: 미래 계획, 아이디어만 (아직 구현 안 됨)

**규칙** (⚠️ **핵심 원칙 - 절대 위반 금지**):
- **구현 완료 시 즉시 `journey/plans/archive/`로 이동** (필수, 지연 금지) - `plans/`에는 미구현 계획만 남김
- **모든 구현 완료 섹션은 즉시 삭제** - "→ 상세: troubleshooting/yymmdd_*.md" 링크로만 대체 (상세 완료 사항 나열 금지)
- **배포/테스트 완료 후 바로 archive 이동** - troubleshooting 문서 작성과 동시에 또는 그 직후 즉시 처리
- **구현 코드 파일 금지** - SQL 마이그레이션 파일(.sql), 코드 파일(.py, .js 등) 등 실제 구현 파일은 `plans/`에 두지 않고 해당 서비스 코드베이스에 위치
- **명확한 행동강령만 기록** - 불확실한 표현("예상", "가능", "고려", "검토", "추후", "나중", "필요시", "선택", "옵션", "또는", "아마", "것 같", "추정") 금지
- **여지가 있는 내용은 아이디어 폴더로 이동** - 불확실한 아이디어는 `journey/ideas/`에 기록
- **아키텍처/Phase/필요작업만** - 장황한 구현 코드 예시 최소화
- **Phase별 분리 가능**: 복잡한 계획은 Phase 1/2/3으로 분리 가능
- 크기 제한 및 초과 시 처리: 섹션 4 참조

**부분 완료 문서 처리** (⚠️ **핵심 원칙**):
- **부분 완료 문서는 `plans/`에 유지** - 전체 완료 시에만 archive로 이동
- **완료된 섹션은 삭제하고 troubleshooting 링크로만 대체** - "→ 상세: troubleshooting/yymmdd_*.md" 형식 (상세 완료 사항 나열 금지)
- **미구현 항목만 "남은 작업" 섹션에 남기기** - 아키텍처/Phase/필요작업만 기록

**구분** (⚠️ **명확히 구분 필수**):
- `plans/`: 미구현 계획만 (will do) - 부분 완료 포함, **구현 완료 섹션 절대 금지**, **남은 작업 기록 위치**
- `plans/archive/`: 전체 구현 완료된 계획 (참고용 보관)
- `troubleshooting/`: 구현 완료 + 문제 해결 (did + learned), **남은 작업 기록 절대 금지** (남은 작업을 troubleshooting에 기록하면 다음 작업 시 계획이 어수선해짐)

### 인덱스 README.md

**경로**: `DOCS/journey/research/`, `DOCS/journey/ideas/` 등 폴더 내부
**파일명**: `README.md`
**용도**: 해당 폴더의 문서 인덱스 및 목차 역할

**규칙**:
- **인덱스/목차 역할만** - 문서 목록과 간단한 설명
- **상세 내용은 링크로 참조** - 트러블슈팅, 계획 등 실제 문서로 링크
- **핵심 키워드만** - 각 문서의 핵심만 간단히 나열
- **README 본문 상세 금지** - `상태/목표/필요작업/결론`의 상세 본문은 원문 문서에만 작성
- **README 중복 금지** - 특정 계획 문서의 본문 3~5줄 요약 템플릿(상태/목표/참고)을 반복 복사하지 않음
- 중복 작성 금지: 섹션 2 핵심 원칙 참조
- 크기 제한: 섹션 4 참조

**예시**:
```markdown
## 성능 비교 테스트
- [하이브리드 의도 분류 성능 비교](../troubleshooting/260103_하이브리드_의도_분류_성능_비교_테스트.md)
  - 초기: FastPath 49.6%, 제로샷 임베딩 23.4%
  - 개선: 제로샷 임베딩 70.2% (+46.8%p)
```

**금지 사례**: 상세 내용 재작성, 코드/테스트 결과 상세 재현, "교훈" 섹션 전체 복사

### 아이디어 문서

**경로**: `DOCS/journey/ideas/`
**규칙**:
- **미구현 아이디어만 유지**: 구현 결과가 troubleshooting·plans에 정리되면 ideas 문서 삭제(또는 `deprecated/`로 이동)
- **핵심만 기록**: 간단한 흐름·배경만 남기고 상세 구현 내용은 계획/트러블슈팅으로 이동

### 리서치 문서

**경로**: `DOCS/journey/research/`
**규칙**:
- 원인 확정이 해결안 제시보다 우선이다.
- 원인 분석 정확도 목표는 100%로 둔다. 불확실하면 "미확정"으로 기록한다.
- 해결 포인트는 단일 경로로 좁히고, 비대상 프로젝트 영향은 0을 기준으로 분리한다.
- 사실/해석/결론을 분리해 기록한다.
- 출처 URL(또는 내부 문서 경로)과 확인 시점을 명시한다.
- 구현 코드 복붙 대신 파일 경로·핵심 위치 참조를 사용한다.
- README에는 원칙 본문을 반복하지 않고, 본 섹션(SSOT) 링크만 둔다.

### 시나리오 문서

**경로**: `DOCS/journey/scenarios/`
**규칙**:
- 문서 상단에 `상태: 완료 / 부분 / 미구현`을 명시
- 구현 완료 시 대응되는 troubleshooting·plans 링크를 함께 표기
- UX 흐름만 기록하고 내부 구현 세부 설명은 링크로 참조
- 사용자/운영자 행동 기준으로 작성 (`누가`, `언제`, `무엇을 하려다`, `어디서 막히는지`)
- 기술 용어보다 체감 결과를 우선 기록 (`기다림`, `재시도`, `업무 지연`, `실행 실패`)
- 한 문서는 반드시 `문제` → `문제 상황(현재 체감)` → `해결 후 기대 상황` 3축으로 쓴다.
- `실패 장면 1개`와 `개선 후 장면 1개`를 같은 맥락으로 짝지어 기록한다.

**시나리오 핵심 원칙(요약)**:
1. 사용자(인간) 시점으로 쓴다.
2. 기술 설명보다 체감 불편을 먼저 쓴다.
3. 해결 뒤 달라질 상태를 명확히 쓴다.

---

## 2. 작성 규칙

### 핵심 원칙 (최우선)

**"핵심만 간결하게 정리"** - 문서의 모든 내용은 이 원칙을 준수해야 함
- 불필요한 설명, 중복 내용, 장황한 문장 제거
- 필요한 정보만 간결하게 기록
- 관련 정보는 링크로 참조 (중복 작성 금지, 같은 내용이면 새 파일 생성하지 말고 기존 파일 수정)

### 링크 작성 원칙 (필수)

- 같은 저장소 문서 링크는 상대경로 Markdown 링크를 사용합니다.
  - 예: `[문서명](./파일.md)`, `[상위 문서](../README.md)`
- 다른 저장소 문서 링크는 GitHub 절대 URL을 사용합니다.
  - 예: `https://github.com/<org>/<repo>/blob/<branch>/...`
- 로컬 절대경로(`/home/...`, `C:\\...`)와 위키링크(`[[...]]`)는 GitHub 렌더링 호환성 이슈가 있어 기본 문서 본문에서 사용하지 않습니다.
- 문서 추가/수정 시 링크 클릭 동작을 반드시 확인한 뒤 커밋합니다.
- 트러블슈팅/실행 기록 문서는 필요 시 문서 상단에 `tags: [tag1, tag2, ...]` 형식의 태그를 둡니다.
- 같은 계열 사건이 이어질 때는 기존 문서를 덮어쓰지 말고 새 문서로 분리한 뒤, 문서 하단에 `전후 관계 문서` 또는 `관련 문서` 링크를 둡니다.
- 원칙은 `기존 문서 보존 + 새 사건은 새 문서 + 관련 문서끼리 링크`입니다.
- 같은 목적의 상위 문서가 있으면 문서 상단에 `상위 원칙` 링크를 둡니다.
- 동일 목적 문서는 파일명을 상위 SSOT basename에 맞춥니다.

### 구조화된 정보 형식 (AI/사람 모두 읽기 좋게)

**권장 형식**:
- **표**: 비교, 목록, 역할 구분 등 구조화된 정보 표현
- **파일명:줄번호**: 코드 위치 명확히 참조
- **명확한 키워드**: 검색 가능하도록 핵심 단어 명시
- **목록/부제목**: 정보 계층 구조화

**금지 형식**:
- JSON/XML 같은 기계적 형식 (사람이 읽기 어려움)
- 암호화된 코드나 해시값 직접 노출

### 절대 금지 사항

| 금지 | 이유 |
|------|------|
| 핵심 없는 장황한 설명 | 핵심만 간결하게 정리 원칙 위반, 관련 문서 링크로 대체 |
| 전체 코드 블록 | 파일명:줄번호만 명시 (파일 참조 형식 섹션 참조) |
| 의사코드, 추측, 예측 ("아마", "것 같다") | 확인된 사실만 기록 |
| 이모지 사용 | 명시적 요청 시만 허용 |
| 민감정보 직접 기록 (API 키, 비밀번호, JWT Secret Key, 토큰, DB 연결 정보 등) | 보안 위험, 환경변수나 설정 파일로 분리하여 관리 |
| troubleshooting 문서에 남은 작업 기록 | 다음 작업 시 계획이 어수선해짐, 남은 작업은 반드시 `plans/` 문서에 기록 |

### 파일 참조 형식

**올바름** (파일명:줄번호 + 간단 설명):
```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
# 제목

**날짜**, **작성자**, **관련 파일**

---

## 문제 상황
- 현상, 에러 메시지

## 해결 방안
- 파일명:줄번호 명시
- 수정 내용 간결히

## 구현 완료 (선택)
- 커밋 해시, 날짜

## 교훈 (필수)
- 왜 발생했는가
- 다음에 어떻게 방지할 것인가

⚠️ **절대 금지**: "남은 작업" 섹션 추가 금지. 남은 작업은 반드시 `plans/` 문서에 기록
```

### 아키텍처 문서 구조

```markdown
# 제목

**작성일**: 2025-10-13
**수정일**: 2025-10-13 (수정 이유)

## 1. 원칙
## 2. 규칙
## 3. 예시
## 4. 체크리스트
## 5. 참고
```

### 시나리오 문서 구조
- 필수 섹션 3개: `문제` / `문제 상황(현재 체감)` / `해결 후 기대 상황`
- 필수 장면 2개: `실패 장면 1개` / `개선 후 장면 1개`
- 연결 문서: troubleshooting/plans/research 링크만 첨부 (구현 상세 복붙 금지)

---

## 4. 파일 크기 제한

### 문서 유형별 크기 제한

| 문서 유형 | 크기 제한 | 비고 |
|----------|----------|------|
| 트러블슈팅 문서 | 150줄 이하 | 단일 이슈 중심, 초과 시 주제별 분리 |
| 계획 문서 | 200줄 이하 | Phase별로 분리 가능 |
| 인덱스 README.md | 150줄 이하 | 목차/인덱스 역할만 |
| 리서치 문서 | 250줄 이하 | 논문 요약 등 긴 내용 허용 |
| 아키텍처 문서 | 250줄 이하 | 섹션 많은 경우, 분리 가능하면 분리 우선 |

### 초과 시 처리 방법

**트러블슈팅 문서**:
- 단일 이슈 중심, 핵심만 간결하게 (초과 시 불필요한 설명/중복 제거 또는 주제별 분리)

**계획 문서**:
- Phase 1/2/3으로 단계별 분리 가능
- 또는 관련 troubleshooting 문서로 링크

**리서치/아키텍처 문서**:
- 분리 가능하면 주제별 섹션 분리
- 또는 관련 문서로 링크 참조

### 기존 문서 처리

- **기존 100줄 초과 문서는 과도적 예외로 인정**
- 신규 작성 시부터 위 원칙 적용
- 기존 문서 수정 시 가능하면 원칙 준수하도록 간소화 권장

---

## 5. 교훈 작성 규칙

### 필수 항목
1. **원인**: 왜 문제가 발생했는가
2. **교훈**: 다음에 어떻게 방지할 것인가
3. **원칙**: 위반한 원칙이 있는가 (원칙 문서 참조: `311_backend_coding_principles.md`, `312_writing-principles.md`)

### 올바른 예시
```markdown
## 교훈

### API 엔드포인트 검증 부족
- 구현 시 skill-rag-file API 스펙 미확인
- 추측으로 /api/query 사용, 실제는 /api/search
- 교훈: 스킬 통합 전 API 문서 또는 코드 직접 확인 필수
```

### 금지 예시
```markdown
## 교훈

에러가 발생했습니다. 다음에 조심하겠습니다.
```

---

## 6. 비난조 문장 금지

### 금지 표현
- "잘못 작성됨"
- "버그가 많음"
- "엉망진창"

### 권장 표현
- "수정 필요"
- "개선 가능"
- "리팩토링 대상"

---

## 7. 체크리스트

문서 작성 전:
- [ ] **핵심만 간결하게 정리** (섹션 2 핵심 원칙 참조)
- [ ] 파일명:줄번호로 위치 명시 (섹션 2 파일 참조 형식 참조)
- [ ] 확인된 사실만 기록 (추측/의사코드 제거)
- [ ] 파일명 형식 준수 (yymmdd_주제.md)
- [ ] 문서 유형별 크기 제한 확인 (섹션 4 참조)
- [ ] 교훈 섹션 작성 (트러블슈팅, 섹션 5 참조)
- [ ] **troubleshooting 문서 작성 시: 남은 작업 섹션 추가 금지** (남은 작업은 반드시 `plans/` 문서에 기록)

문서 작성 후:
- [ ] 한 번 더 읽고 핵심 없는 부분/중복 제거 (섹션 2 핵심 원칙 참조)
- [ ] **troubleshooting 문서 검토: "남은 작업" 섹션이 있다면 삭제하고 `plans/` 문서로 이동**

### 원칙 실행 시: 선택적 독해·단계 압축 방지

원칙을 실행할 때 다음을 반드시 지킨다.

1. **체크리스트 강제 실행**: 해당 문서(예: 312 본문 270~276줄)의 체크리스트를 작업 시작 전에 읽고, 각 항목을 순서대로 확인한 뒤 실행한다. 사용자 지시(예: "푸시해")만 보고 단계를 건너뛰지 않는다.
2. **키워드 검색 후 전체 문장 읽기**: 원칙에서 키워드(예: "archive 이동")를 찾았으면 해당 줄만 보지 말고, 앞뒤 3줄을 포함해 조건절(예: "troubleshooting 문서 작성과 동시에")이 있는지 확인한 뒤 실행한다.
3. **완료 조건 명시적 확인**: "완료"라고 판단하기 전에, 해당 원칙에서 완료의 정의(필수 단계 목록)를 찾아 누락 단계가 없는지 확인한 뒤 완료 처리한다.

---

## 8. 개발 과정에서 문서 정리 원칙

### 기능 개발 시 문서화 흐름

새로운 기능을 만들 때 다음 순서로 문서를 작성/업데이트합니다:

1. **`journey/scenarios/`**: UX 시나리오 작성 (만들기 전)
   - 사용자 경험 관점에서 기능 정의
   - "어떤 기능을 만들지" 먼저 정의

2. **계획 문서** (`journey/plans/`): 구현 계획 작성 (만들기 전)
   - 아키텍처/Phase/필요작업만 기록 (섹션 1 참조)
   - 구현 완료 시 `plans/archive/`로 이동하고 troubleshooting 문서와 링크 연결

3. **트러블슈팅 문서** (`journey/troubleshooting/`): 구현 과정 기록 (만들면서/만든 후)
   - 문제 해결, 교훈, 테스트 결과 기록 (섹션 1 참조)
   - 크기 제한 및 초과 시 처리: 섹션 4 참조
   - **⚠️ 절대 금지: 남은 작업 기록** - 남은 작업은 반드시 `plans/` 문서에 기록

4. **서비스 README.md**: 서비스별 핵심 사항 업데이트 (만든 후)
   - 엔드포인트, 환경변수, 사용 방법 등 구체적 정보 기록

5. **인덱스 README.md**: 폴더별 문서 인덱스 업데이트 (만든 후)
   - 문서 목록과 간단한 설명 기록 (섹션 1 참조)

6. **`book/`**: 원칙 변경 시 업데이트 (필요시)
   - 아키텍처 원칙이 바뀌면 반영
   - `guidelines/`에 개발 가이드라인 추가/수정

7. **`AGENTS.md`**: 개발 원칙/운영 규칙 변경 시 업데이트 (필요시)
   - 새로운 작업 규칙이 생기면 반영

### 문서 역할 구분

| 문서 종류 | 역할 | 변경 빈도 |
|----------|------|----------|
| `book/` | 항상성, 원칙, 철학 | 거의 변하지 않음 |
| `journey/` | 진화 과정 (scenarios → ideas → research → plans → troubleshooting) | 계속 추가됨 |
| 서비스 README.md | 현재 상태 (포트, 엔드포인트, 환경변수) | 자주 변함 |
| 인덱스 README.md (research/, ideas/ 등) | 문서 목차/인덱스, 상세는 링크 참조 | 새 문서 추가 시 |
| `AGENTS.md` | 개발자별 룰, 운영 규칙 | 필요시 변경 |

### Journey 내부 흐름

```
scenarios/ (UX 정의)
    ↓
ideas/ (아이디어 탐색)
    ↓
research/ (이론적 기반)
    ↓
plans/ (구현 계획)
    ↓
troubleshooting/ (실제 구현)
```

**참고**: 각 단계는 필수가 아니며, 필요에 따라 생략 가능

---

## 9. 참고 문서

- AGENTS.md: 전체 개발 가이드
- 311_backend_coding_principles.md: 코드 구조 원칙
- troubleshooting/ 폴더: 트러블슈팅 예시
