문서 작성 가이드라인

개요

MAKITT 프로젝트의 문서 구조와 작성 규칙을 정의한다. Spec-driven 개발 방식을 따른다. Spec이 기능의 정의이자 실행 단위이다.

주의: 이 docs/ 디렉토리는 프로젝트에서 진행한 모든 작업을 담고 있지 않다. 각 하위 레포(makitt-client, makitt-server, makitt-ai-agent 등)에도 자체 문서와 스펙이 존재하며, 이미 구현 완료되어 별도 spec 없이 진행된 기능도 많다. 여기 있는 문서만으로 프로젝트의 전체 범위를 판단하면 안 된다.

---

디렉토리 구조

docs/
├── DOCS_GUIDE.md        # 이 문서
├── spec/                # 기능 명세 (폴더 단위)
│   ├── ongoing/         # 현재 진행 중인 spec
│   ├── finished/        # 완료된 spec
│   └── argo/            # Argo 연동 spec 모음
├── domain/              # 서버 도메인 모델 정의 (작업할 때마다 유관 도메인 재정리)
├── handbook/            # HCS 설계 핸드북 (구조/컴포넌트/스타일/상태/프래그먼트 등)
├── api/                 # 서버-클라이언트 스키마 검증 도구
├── reference/           # 운영/검증 레퍼런스
└── knowhow/             # 기술 노하우 노트

---

문서 유형별 작성 규칙

1. Spec 문서 (spec/)

기능의 정의와 구현 계획을 하나의 폴더로 관리한다. Spec이 곧 실행 단위이다.

폴더 컨벤션

모든 spec은 자기 폴더를 갖는다. 폴더 이름 = spec 이름(kebab-case).

spec/ongoing/{spec-name}/
├── README.md            # Spec 본문 (필수)
├── README.test.md       # Integration Test Guide (필수)
└── {sub-doc}.md         # 선택: 긴 spec을 주제별로 쪼갤 때

• 한 기능 = 한 폴더. flat .md 배치 금지
• 보조 문서(아키텍처, IA/UX, 마이그레이션 노트, history 등)가 필요하면 같은 폴더 안에 둔다
• 큰 에픽은 Phase별 하위 문서로 분해 가능 (예: fragment-library-to-coverage/phase-2-server-foundation.md)

frontmatter

---
status: draft | approved | in-progress | completed
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

README.md 필수 섹션

# {기능명}

## 개요
기능의 목적과 범위.

## 배경
- 현재 문제점
- 비즈니스 맥락

## 유저 플로우
Mermaid 다이어그램 또는 텍스트.

## 상세 기능
### {섹션 1}
- 기능 설명
- 규칙/제약 조건

## Acceptance Criteria
### AC1: {기준 제목}
- [ ] Given: {사전 조건}
- [ ] When: {유저 액션}
- [ ] Then: {기대 결과}

## 구현 계획
### 영향 범위
- 관련 레포: makitt-client, makitt-server 등

### 작업 목록
| 작업 | 설명 |
|------|------|
| Task 1 | 설명 |

### 기술 상세
(데이터 모델, API 설계, UI 컴포넌트 등 필요한 만큼만)

Integration Test (README.test.md)

Spec과 함께 반드시 작성한다. 포함 내용:

• 사전 준비: 데이터 초기화, 서버 재시작, 환경 확인
• Test Case: 번호별 액션 → 기대 결과 테이블
• 알려진 제한사항: 미구현 부분, 수동 작업 필요 사항

상태 흐름

draft → approved → in-progress → completed

완료되면 폴더 전체를 spec/ongoing/ → spec/finished/ 로 이동하고 status: completed 로 표기.

---

2. Domain 문서 (domain/)

서버(makitt-server)의 도메인 모델을 정의하는 문서. 도메인 이름 당 하나의 파일.

• 서버 com.makitt.core.domain.{name} 패키지 구조와 1:1 대응
• 코드의 SSOT는 서버 코드이며, 이 문서는 참조용 스냅샷
• 작업할 때마다 유관 도메인 문서를 같이 최신화
• DynamoDB Entity, OpenSearch Document, Key Builder 규칙 포함

---

3. Handbook 문서 (handbook/)

HCS(Headless Component System) 설계 핸드북. 구조, 컴포넌트, 스타일, 데이터, 상태, 인터랙션, 폼, 전역 레이아웃, 프래그먼트, 토큰 스키마, 개발 가이드, 페이지 블루프린트 등 재사용 가능한 설계 레퍼런스를 담는다.

• spec이 아닌 설계 원리 + 사용 패턴 중심
• 번호 접두어(01-, 02- …)로 학습 순서 유지. 파일 추가/삭제 시 번호 재정렬
• 각 파일 최상단 # NN. 제목 은 파일명 번호와 일치시킨다

---

4. 기타 폴더

---

공통 작성 규칙

• 파일명: kebab-case (예: payment-settings.md)
• 폴더명: spec 이름 그대로 kebab-case
• 모든 문서는 Markdown 형식
• 첫 줄은 # 제목
• 문서는 한국어로 작성, 기술 용어는 원문 그대로
• 다이어그램: 문서 내 Mermaid 코드블록 사용. 복잡한 경우 diagrams/에 .mmd 파일 분리
• 다른 문서 참조 시 repo 루트 기준 절대 경로 표기 (예: docs/handbook/hcs/09-fragment.md)