문서 작성 가이드라인
docs/DOCS_GUIDE.md
문서 작성 가이드라인
개요
이 문서는 MAKITT 프로젝트의 문서 구조와 작성 규칙을 정의한다.
디렉토리 구조
docs/
├── DOCS_GUIDE.md # 이 문서 - 문서 작성 가이드라인
├── epic/ # Epic 문서 (실행 단위)
│ └── {epic-name}/
│ ├── definition.md # Epic 정의 (요구사항)
│ └── implementation.md # 구현 계획 (기술 상세)
├── spec/ # 기능 명세 (서비스 관점)
│ └── {feature-name}.md
├── milestone/ # 마일스톤 문서 (전략 단위)
│ └── {milestone-name}.md
└── reference/ # 참고 자료
문서 유형별 작성 규칙
1. Epic 문서 (epic/)
Epic은 구체적인 실행 단위로, definition.md와 implementation.md 두 파일로 구성된다.
1.1 definition.md (Epic 정의)
유저 관점의 요구사항과 acceptance criteria를 정의한다.
필수 포함 내용:
# {Epic 이름} ## 개요 이 epic이 해결하려는 문제와 달성 목표를 유저 관점에서 기술. ## 배경 - 현재 문제점 - 비즈니스 맥락 ## 유저 스토리 As a [유저 타입], I want [기능] so that [가치]. ## Acceptance Criteria ### AC1: {기준 제목} - [ ] Given: {사전 조건} - [ ] When: {유저 액션} - [ ] Then: {기대 결과} ### AC2: {기준 제목} - [ ] Given: ... - [ ] When: ... - [ ] Then: ... ## 범위 ### In Scope - 포함 항목 1 - 포함 항목 2 ### Out of Scope - 제외 항목 1 - 제외 항목 2 ## 성공 지표 - 지표 1: 목표값 - 지표 2: 목표값
Acceptance Criteria 작성 규칙:
- Given-When-Then 형식으로 작성
- 유저 관점에서 검증 가능한 조건으로 작성
- 기술 구현 세부사항 포함하지 않음
- 각 AC는 독립적으로 테스트 가능해야 함
1.2 implementation.md (구현 계획)
기술적 구현 계획과 상세 작업을 정의한다.
필수 포함 내용:
# {Epic 이름} - 구현 계획 ## 기술 접근 방식 선택한 기술적 접근 방식과 근거. ## 영향 범위 - 관련 레포지토리: makitt-client, makitt-server - 영향받는 모듈/컴포넌트 ## 작업 분류 ### Phase 1: {단계명} | 작업 | 설명 | 담당 | 예상 공수 | |------|------|------|----------| | Task 1 | 설명 | - | 1일 | | Task 2 | 설명 | - | 2일 | ### Phase 2: {단계명} | 작업 | 설명 | 담당 | 예상 공수 | |------|------|------|----------| | Task 1 | 설명 | - | 1일 | ## 기술 상세 ### 데이터 모델 ```json { "field": "type" }
API 설계
POST /api/v1/resource- 설명
UI 컴포넌트
- ComponentName: 설명
의존성
- 선행 작업: {epic 또는 작업}
- 외부 의존성: {라이브러리, API 등}
리스크
| 리스크 | 영향도 | 완화 방안 |
|---|---|---|
| 리스크 1 | 높음 | 방안 |
---
### 2. Spec 문서 (`spec/`)
서비스 관점의 기능 명세를 작성한다. **기술 구현 세부사항은 포함하지 않는다.**
**작성 규칙:**
- 유저/비즈니스 관점에서 기능을 설명
- 플로우, 상태, 규칙 중심으로 기술
- 다이어그램은 문서 내에 Mermaid로 포함
- 별도 .mmd 파일이 필요한 경우 `diagrams/` 디렉토리에 저장
**필수 포함 내용:**
```markdown
# {기능명} 기능 명세
## 개요
기능의 목적과 범위.
## 유저 플로우
```mermaid
flowchart TD
A[시작] --> B[단계1]
B --> C[단계2]
C --> D[완료]
상세 기능
{섹션 1}
- 기능 설명
- 규칙/제약 조건
{섹션 2}
- 기능 설명
- 규칙/제약 조건
상태 정의
| 상태 | 설명 | 전이 조건 |
|---|---|---|
| STATE_1 | 설명 | 조건 |
| STATE_2 | 설명 | 조건 |
에러 케이스
| 상황 | 에러 메시지 | 복구 방법 |
|---|---|---|
| 상황 1 | 메시지 | 방법 |
---
### 3. Milestone 문서 (`milestone/`)
비즈니스 목표 단위로 여러 epic을 묶는 전략 문서.
**필수 포함 내용:**
```markdown
---
id: {milestone-id}
status: backlog # backlog | active | completed
created: YYYY-MM-DD
target: YYYY-MM-DD
---
# {Milestone 제목}
## 목표
이 마일스톤이 달성하려는 비즈니스/기술 목표.
## 완료 조건
- [ ] 조건 1
- [ ] 조건 2
## Epics
| Epic | Status | Description |
|------|--------|-------------|
| [epic-name](../epic/epic-name/definition.md) | active | 간단 설명 |
## 리스크 및 의존성
- 리스크/의존성 항목
공통 작성 규칙
파일명
- kebab-case 사용 (예:
payment-settings.md,user-authentication.md) - 영문 소문자, 숫자, 하이픈만 사용
문서 형식
- 모든 문서는 Markdown 형식
- 첫 줄은 반드시
# 제목형식 - milestone 문서는 YAML frontmatter 포함
다이어그램
- 간단한 다이어그램: 문서 내 Mermaid 코드블록으로 포함
- 복잡한 다이어그램:
diagrams/디렉토리에.mmd파일로 분리 - 분리된 다이어그램은 문서에서 참조 경로 명시
상태 관리
- YAML frontmatter의
status필드로 관리 - 상태 종류:
backlog→active→completed - 파일을 이동하지 않고 status만 변경
언어
- 문서는 한국어로 작성
- 코드, 기술 용어는 원문 그대로 사용 가능
문서 워크플로
Epic 생성 시
epic/{epic-name}/디렉토리 생성definition.md작성 (요구사항, AC)- 리뷰 및 승인 후
implementation.md작성 - 관련 milestone에 epic 추가
Spec 생성 시
spec/{feature-name}.md파일 생성- 서비스 관점으로 기능 명세 작성
- 필요 시 epic의 definition.md에서 참조
Milestone 생성 시
milestone/{milestone-name}.md파일 생성- 비즈니스 목표와 완료 조건 정의
- 관련 epic들을 연결
폴더 구조 예시
docs/
├── DOCS_GUIDE.md
├── epic/
│ ├── multi-market-onboarding/
│ │ ├── definition.md
│ │ └── implementation.md
│ └── toss-payments-integration/
│ ├── definition.md
│ └── implementation.md
├── spec/
│ ├── global-shop-onboarding.md
│ └── checkout-flow.md
├── milestone/
│ └── henriette-4-market-launch.md
└── reference/
└── makitt-project-overview.md
금지 사항
- spec에 기술 구현 세부사항 포함 - spec은 서비스 관점, 기술 상세는 epic의 implementation.md에
- definition.md에 코드/API 상세 포함 - 유저 관점의 요구사항만
- Acceptance Criteria 없이 epic 생성 - 모든 epic은 검증 가능한 AC 필수
- 다이어그램 없이 복잡한 플로우 설명 - 플로우는 시각화 필수
- 파일명에 공백이나 특수문자 사용 - kebab-case만 사용