MAKITTDocs

문서 작성 가이드라인

docs/DOCS_GUIDE.md

문서 작성 가이드라인

개요

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

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

디렉토리 구조

docs/
├── DOCS_GUIDE.md        # 이 문서
├── milestone/           # 마일스톤 (전략 단위, Phase별 목표와 작업 목록)
│   └── {milestone-name}.md
├── spec/                # 기능 명세
│   ├── ongoing/         # 현재 진행 중인 spec
│   ├── finished/        # 완료된 spec
│   └── {feature-name}.md # 백로그/아이디어
├── domain/              # 서버 도메인 모델 정의
│   └── {domain-name}.md
├── hcs-asset/           # HCS 에셋 스펙 (빌더 컴포넌트 정의)
│   └── {asset-name}.md
└── research/            # 1회성 조사 자료
    ├── implementation/  # 현재 구현상황 분석
    └── customer/        # 고객 요구사항 분석

문서 유형별 작성 규칙

1. Spec 문서 (spec/)

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

frontmatter:

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

필수 포함 내용:

# {기능명}

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

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

## 유저 플로우
(Mermaid 다이어그램 또는 텍스트로 플로우 설명)

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

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

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

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

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

상태 흐름: draft → approved → in-progress → completed

완료된 spec은 삭제하지 않고 status: completed로 표기하여 히스토리를 유지한다.

Integration Test 문서:

Spec과 함께 Integration Test Guide를 반드시 작성한다. 파일명은 spec 파일명에 .test.md를 붙인다.

spec/ongoing/
├── onboarding-flow-completion.md        # Spec
└── onboarding-flow-completion.test.md   # Integration Test Guide

Test Guide에는 다음을 포함한다:

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

2. Domain 문서 (domain/)

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

  • 서버 com.makitt.core.domain.{name} 패키지 구조와 1:1 대응
  • 코드의 SSOT는 서버 코드이며, 이 문서는 참조용 스냅샷
  • DynamoDB Entity, OpenSearch Document, Key Builder 규칙 포함

3. HCS Asset 문서 (hcs-asset/)

빌더에서 사용하는 HCS 에셋(컴포넌트 조합)의 스펙을 정의한다.

  • 에셋별 TreeNode 구조, 데이터 바인딩, 이벤트 정의
  • 레퍼런스 사이트 기반으로 작성

4. Research 문서 (research/)

1회성 조사 자료. 자유 형식.

  • implementation/: 현재 코드베이스 구현 상황 분석
  • customer/: 고객 요구사항, 피드백 정리
  • 필요 시 하위 폴더 자유롭게 추가

공통 작성 규칙

  • 파일명: kebab-case (예: payment-settings.md)
  • 모든 문서는 Markdown 형식
  • 첫 줄은 # 제목
  • 문서는 한국어로 작성, 기술 용어는 원문 그대로
  • 다이어그램: 문서 내 Mermaid 코드블록 사용. 복잡한 경우 diagrams/에 .mmd 파일 분리