# docs/plans 문서 가이드 (최소 원칙)

> **작성일**: 2026-02-26
> **상태**: 최소 원칙 (정리 완료 후 보강 예정)
> **참조**: `docs/INDEX.md`, `CLAUDE.md`에 링크 예정

---

## 1. 파일 명명 규칙

```
[도메인]-[기능]-plan.md

예시:
  bending-preproduction-stock-plan.md
  quote-order-sync-improvement-plan.md
  document-system-work-log-plan.md
```

- 영문 소문자, 하이픈(`-`) 구분
- 접미사 `-plan.md` 고정
- 도메인 접두사 통일:

| 도메인 | 접두사 | 예시 |
|--------|--------|------|
| 견적 | `quote-` | quote-calculation-api-plan.md |
| 수주 | `order-` | order-location-management-plan.md |
| 품목/BOM | `item-`, `bom-` | item-master-data-alignment-plan.md |
| 절곡/생산 | `bending-` | bending-preproduction-stock-plan.md |
| 문서/서식 | `document-` | document-system-master-plan.md |
| 관리자(mng) | `mng-` | mng-menu-system-plan.md |
| 시스템/인프라 | `db-`, `tenant-` | db-backup-system-plan.md |
| 프론트엔드 | `react-` | react-api-integration-plan.md |
| 마이그레이션 | `[출처]-migration-` | kd-orders-migration-plan.md |

> 도메인 분류는 정리 완료 후 실제 남은 문서 기반으로 확정 예정

---

## 2. 문서 필수 섹션

| 섹션 | 필수 | 내용 |
|------|:----:|------|
| **목적** (상단 1줄) | ✅ | 왜 이 작업이 필요한가 |
| **현재 진행 상태** | ✅ | 마지막 완료 작업, 다음 작업, 진행률 |
| **대상 범위** | ✅ | Phase별 작업 항목 테이블 |
| **변경 이력** | ✅ | 날짜 + 변경 내용 |
| 참고 문서 | ⚪ | 관련 문서 링크 |
| 검증 결과 | ⚪ | 완료 시 작성 |

---

## 3. 상태 표기법

### 문서 상태 (인덱스용)

| 표기 | 의미 |
|------|------|
| 🟡 진행중 | 현재 작업중 |
| ⚪ 대기 | 미착수 / 선행조건 대기 |
| ✅ 완료 | 개발 완료 |

### 항목 상태 (문서 내부용)

| 표기 | 의미 |
|------|------|
| ⏳ | 대기 |
| 🔄 | 진행중 |
| ✅ | 완료 |
| ⚠️ | 컨펌 필요 |

### 진행률 표기

```
완료/전체 (%)
예: 5/8 (63%)
```

---

## 4. 문서 생명주기

```
생성 (PLANNED)     ← 개발 계획 수립
  ↓ 착수
진행 (ACTIVE)      ← 인덱스에 노출, 진행 상태 추적
  ↓ 개발 완료
완료 (COMPLETED)   ← 인덱스에서 완료 표기
  ↓ docs/ 구조화 시
정식 문서에 반영    ← plan의 설계 결정/구현 상세를 docs/ 정식 문서로 이관
```

- **plan 문서**: 개발 계획 수립 및 진행 추적 용도
- **완료 후**: 유용한 내용(설계 결정, 구현 상세)은 `docs/` 정식 문서에 반영
- **plan 파일 보관/삭제**: `docs/` 구조화 시 확정

---

## 5. 폴더 구조

```
docs/plans/
├── GUIDE.md              ← 이 가이드
├── index_plans.md        ← ACTIVE + PLANNED 문서 인덱스
├── [도메인]-*-plan.md    ← 현행 계획 문서
├── archive/
│   └── HISTORY.md        ← 완료 작업 요약 (기능별 섹션)
├── flow-tests/           ← JSON 테스트 케이스 (별도 관리)
└── SAM_ERP_Storyboard*/  ← 디자인 참조 (별도 관리)
```

---

## 6. 인덱스 관리

- 문서 생성/삭제 시 `index_plans.md` **동시 업데이트**
- **ACTIVE + PLANNED** 문서만 인덱스에 포함
- 도메인별 섹션으로 그룹핑
- 각 문서의 상태/진행률 표기

---

> **TODO (정리 완료 후 보강)**
> - 도메인 분류 체계 확정 (실제 남은 문서 기반)
> - 문서 간 관계 규칙 (상위/하위, 참조 관계)
> - 인덱스 관리 주기 및 방법
> - docs/ 전체 구조와의 연계 정책