joungmin
25be18063e
- 설계서 218-gemma-real-integration/README.md → Approved + AC 체크박스 채움 + 실제 구현/테스트 파일 경로 추적성 갱신
- fn-gemma_llm_service.md → Approved (v2)
- reference/215-ai-frame-suggest.md → v0.3.0 (commit da60dd1 핀)
- guides/ai-help-onboarding.md → 적용 버전 v0.3.0 + RAM 4GB 요구사항 명시
- docs/README.md 인덱스 v0.3.0 표기
AC-7 (실 단말 E2E) 만 DEFER — 사용자 실기 검증 결과로 별도 갱신.
Refs #218
90 lines
4.6 KiB
Markdown
90 lines
4.6 KiB
Markdown
# life-helper 문서 아키텍처 (Documentation Map)
|
|
|
|
이 프로젝트의 문서는 **Diátaxis** 프레임워크 + **ADR** + **설계서(Design Spec)** 를
|
|
결합한 구조를 따른다. 모든 페르소나는 문서를 만들거나 참조할 때 이 지도를 기준으로 한다.
|
|
|
|
## 디렉토리 구조
|
|
|
|
```
|
|
docs/
|
|
README.md ← (이 파일) 문서 지도 · 인덱스
|
|
design/ ← 설계서: 구현 "전"에 작성하는 필수 산출물 (Design-First 게이트)
|
|
_TEMPLATE.md 기능 설계서 템플릿
|
|
_FN_TEMPLATE.md 함수별 설계서 템플릿
|
|
<issue-id>-<slug>/ 기능 1개(이슈 1개)당 폴더
|
|
README.md 기능 설계서 (전체 설계 + 함수 명세 표)
|
|
fn-<name>.md 복잡한 함수만 개별 함수 설계서
|
|
adr/ ← Architecture Decision Records: 가로지르는 결정 기록
|
|
_TEMPLATE.md
|
|
NNNN-<title>.md
|
|
reference/ ← 레퍼런스: 구현된 모듈/함수/설정 사양 (구현 "후" 동기화)
|
|
guides/ ← How-to / 사용 가이드 / 튜토리얼 (사용자·운영자 대상)
|
|
pipeline/ ← 개발 프로세스 문서 (큐 프로토콜·런북)
|
|
```
|
|
|
|
## Diátaxis 사분면 매핑
|
|
|
|
| 사분면 | 목적 | 여기서 위치 |
|
|
|--------|------|-------------|
|
|
| **Tutorials** (학습) | 처음 사용자가 따라하기 | `guides/` (getting-started) |
|
|
| **How-to** (문제해결) | 특정 작업 수행 | `guides/` |
|
|
| **Reference** (정보) | 정확한 사양 조회 | `reference/` |
|
|
| **Explanation** (이해) | 왜 이렇게 설계했나 | `design/`, `adr/` |
|
|
|
|
## 문서 종류와 책임
|
|
|
|
| 문서 | 작성 페르소나 | 시점 | 한 줄 |
|
|
|------|---------------|------|-------|
|
|
| 기능 설계서 `design/<id>/README.md` | **Architect** | 구현 **전** | 무엇을·어떻게 만들지의 청사진 |
|
|
| 함수 설계서 `design/<id>/fn-*.md` | **Architect** | 구현 **전** | 복잡 함수의 계약·알고리즘·테스트 |
|
|
| ADR `adr/NNNN-*.md` | **Architect** | 결정 시 | 되돌리기 어려운 선택과 근거 |
|
|
| 레퍼런스 `reference/*` | **Developer/Documenter** | 구현 **후** | 실제 코드 사양 |
|
|
| 가이드 `guides/*` | **Documenter** | 릴리스 시 | 사용/운영 방법 |
|
|
|
|
## 핵심 규칙 — Design-First (하드 게이트)
|
|
|
|
> **설계서 없이는 코드 없음.** 어떤 함수든 구현 전에 그 함수가 설계서로 덮여 있어야 한다
|
|
> (단순 함수: 기능 설계서의 함수 명세 표 / 복잡 함수: 개별 `fn-*.md`).
|
|
> Developer 는 설계서가 없으면 구현을 거부하고 Architect 단계로 반려한다.
|
|
> 자세한 기준은 `CLAUDE.md` §2 참조.
|
|
|
|
## 명명 · 추적성 규칙
|
|
|
|
- 설계서 폴더: `design/<issue-id>-<kebab-slug>/` (예: `design/45-trailing-stop/`).
|
|
- 함수 설계서: `fn-<function_name>.md` (예: `fn-calc_trailing_stop.md`).
|
|
- ADR: 4자리 일련번호 `adr/0001-<title>.md`, 번호 재사용 금지.
|
|
- 모든 설계서·ADR 상단에 **추적성 헤더**(Redmine 이슈, 관련 ADR, 구현 파일, 테스트)를 둔다.
|
|
- 코드 ↔ 설계서 양방향 링크: 설계서는 구현 파일 경로를, 코드 주석/문서는 설계서 경로를 가리킨다.
|
|
|
|
## 문서 수명주기
|
|
|
|
`Draft`(작성) → `Approved`(QA/Reviewer 통과 후) → `Superseded`(대체 시 상단 표기, 삭제 금지).
|
|
구현이 설계서와 달라지면 **코드가 아니라 설계서를 먼저 고치고** 다시 구현한다.
|
|
```
|
|
|
|
## 현재 발행된 문서 (인덱스)
|
|
|
|
### 설계서 (`design/`)
|
|
|
|
- [204-flutter-bootstrap](./design/204-flutter-bootstrap/) — Phase 1 MVP Drift 21 테이블 + 도메인 함수 + UI 4 화면
|
|
- [215-gemma-frame-suggest](./design/215-gemma-frame-suggest/) — Phase 2-A on-device Gemma 4 프레임 자동 생성
|
|
- [218-gemma-real-integration](./design/218-gemma-real-integration/) — OQ-1 실 Gemma 4 E2B + flutter_gemma 0.16.5 통합 (placeholder → 실 구현)
|
|
|
|
### ADR (`adr/`)
|
|
|
|
- [0001-dose-variants.md](./adr/0001-dose-variants.md) — Dose Variants 도입
|
|
- [0002-dose-variants-normalized.md](./adr/0002-dose-variants-normalized.md) — Dose Variants 정규화 방식
|
|
- [0003-on-device-llm-gemma.md](./adr/0003-on-device-llm-gemma.md) — On-device LLM (Gemma 4) 도입
|
|
|
|
### 레퍼런스 (`reference/`)
|
|
|
|
- [215-ai-frame-suggest.md](./reference/215-ai-frame-suggest.md) — AI 프레임 제안 모듈 사양 (#215 + #218, v0.3.0)
|
|
|
|
### 가이드 (`guides/`)
|
|
|
|
- [ai-help-onboarding.md](./guides/ai-help-onboarding.md) — AI 도움 켜기·끄기 사용자 가이드
|
|
|
|
### 파이프라인 (`pipeline/`)
|
|
|
|
- [QUEUE-PROTOCOL.md](./pipeline/QUEUE-PROTOCOL.md) — 8 페르소나 큐 프로토콜
|