Apply ch-bootstrap convention (partial)

Existing life-helper already has the Redmine project (id=12), 8 persona categories, and Gitea remote, so this commit applies only the local-side pieces of the cloud-handson convention: - .claude/settings.json (safe-but-maximal permissions: allow-all + deny dangerous) - .claude/agents/ (8 persona subagents: planner/architect/designer/developer/reviewer/qa/release/documenter) - .claude/workflows/persona-pipeline.js - CLAUDE.md (Design-First hard gate) - docs/ skeleton (Diátaxis + ADR + design templates + QUEUE-PROTOCOL) - scripts/enqueue.sh - .env.example .gitignore: switched .claude/ blanket-ignore to .claude/settings.local.json so the new settings/agents/workflows actually commit. .env and nutrition/ stay ignored. Existing root SoT files (huberman-protocols.md, habit-*.md, data-model.md, schema/) are untouched. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-11 15:59:39 +09:00
parent 3141bf005f
commit 957dd90725
19 changed files with 692 additions and 3 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,63 @@
+# 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`(대체 시 상단 표기, 삭제 금지).
+구현이 설계서와 달라지면 **코드가 아니라 설계서를 먼저 고치고** 다시 구현한다.
+```
--- a/docs/adr/_TEMPLATE.md
+++ b/docs/adr/_TEMPLATE.md
@@ -0,0 +1,24 @@
+<!-- ADR 템플릿. 복사해서 adr/NNNN-<kebab-title>.md (4자리 일련번호). -->
+
+# ADR-NNNN: <제목>
+
+> **상태**: Proposed <!-- Proposed | Accepted | Superseded by ADR-XXXX -->
+> **날짜**: <YYYY-MM-DD> · **결정자**: [AI] Architect · **관련 이슈**: #<id>
+
+## 맥락 (Context)
+무엇이 이 결정을 강제하는가. 배경·제약·요구.
+
+## 결정 (Decision)
+우리는 무엇을 하기로 했는가. (명확한 한 문단)
+
+## 근거 (Rationale)
+왜 이 선택인가. 핵심 트레이드오프.
+
+## 결과 (Consequences)
+- **긍정**: ...
+- **부정 / 비용**: ...
+- **후속 작업**: ...
+
+## 검토한 대안 (Alternatives Considered)
+- **<대안 A>** — 기각 사유: ...
+- **<대안 B>** — 기각 사유: ...
--- a/docs/design/_FN_TEMPLATE.md
+++ b/docs/design/_FN_TEMPLATE.md
@@ -0,0 +1,51 @@
+<!-- 함수별 설계서 템플릿. 복잡 함수마다 design/<issue-id>-<slug>/fn-<function_name>.md 로 작성.
+     작성: [AI] Architect, 구현 전 필수. -->
+
+# 함수 설계서: `<function_name>` (#<issue-id>)
+
+> **부모 설계서**: ./README.md · **상태**: Draft <!-- Draft|Approved|Superseded -->
+> **작성**: [AI] Architect · **구현**: <file:function 또는 TBD> · **테스트**: <경로 또는 TBD>
+
+## 1. 시그니처
+```
+<returnType> <function_name>(<params>)   # 언어 확정 후 정확히 기재
+```
+
+## 2. 책임 (단일 책임, 1줄)
+이 함수가 하는 단 하나의 일.
+
+## 3. 입력
+| 파라미터 | 타입 | 제약/검증 | 설명 |
+|----------|------|-----------|------|
+| `<p>` |  |  |  |
+
+## 4. 출력
+- **반환**: 타입 / 의미.
+- **부수효과**: (있으면 — I/O·상태변경 명시) / 없으면 **순수 함수**.
+
+## 5. 동작 / 알고리즘
+1. ...
+2. ...
+
+## 6. 에러 & 실패 모드
+| 조건 | 처리 | 반환/예외 |
+|------|------|-----------|
+|  |  |  |
+
+## 7. 엣지케이스
+- 경계값(0, 음수, 빈값, 최대), 동시성, 부분 실패.
+
+## 8. 복잡도 / 성능
+- 시간/공간 복잡도. 호출 빈도(예: 시세 폴링 루프 내부인가?).
+
+## 9. 의존성
+- 호출하는 함수/모듈, 외부 API, 설정 키.
+
+## 10. 테스트 케이스
+- [ ] 정상: <입력 → 기대 출력>
+- [ ] 경계: ...
+- [ ] 실패: ...
+
+## 11. 추적성
+- 인수조건: #<issue-id> 의 "<항목>".
+- 관련 ADR: <ADR-NNNN 또는 없음>.
--- a/docs/design/_TEMPLATE.md
+++ b/docs/design/_TEMPLATE.md
@@ -0,0 +1,66 @@
+<!-- 기능 설계서 템플릿. 복사해서 design/<issue-id>-<slug>/README.md 로 작성.
+     작성: [AI] Architect, 구현 전 필수. 빈 섹션 금지 — 해당 없으면 "해당 없음" 명시. -->
+
+# 설계서: <기능명> (#<issue-id>)
+
+> **상태**: Draft <!-- Draft | Approved | Superseded -->
+> **작성**: [AI] Architect · **최종수정**: <YYYY-MM-DD>
+> **추적성** — Redmine: #<issue-id> · 관련 ADR: <ADR-NNNN 또는 없음>
+> · 구현 파일: <경로 또는 TBD> · 테스트: <경로 또는 TBD>
+
+## 1. 목적 (Why)
+이 기능이 푸는 문제. Planner 의 목표 1줄 인용.
+
+## 2. 범위 (Scope)
+- **포함**: ...
+- **제외 (out of scope)**: ...
+
+## 3. 인수조건 (Acceptance Criteria)
+<!-- Planner 가 확정한 검증 가능한 항목. QA 가 이걸로 판정한다. -->
+- [ ] ...
+- [ ] ...
+
+## 4. 컨텍스트 & 제약
+- 의존성: 거래소 API / DB / 알림 / 외부 라이브러리.
+- 제약: 성능, 레이트리밋, 리스크(돈), 보안.
+- 가정: ...
+
+## 5. 아키텍처 개요
+- 모듈/파일 구조 (목록).
+- 데이터 흐름 (텍스트 다이어그램).
+- **I/O ↔ 순수 전략 로직 경계** 명시 (테스트 가능성).
+
+```
+<여기에 ASCII 흐름도>
+```
+
+## 6. 데이터 모델
+- 입력 / 출력 / 저장 구조, 타입, **경계 검증 규칙**.
+
+## 7. 함수 명세 (Function Specs)
+<!-- 모든 함수를 나열. "복잡?" = 복잡이면 fn-<name>.md 개별 설계서 필수. -->
+
+| 함수 | 책임(1줄) | 시그니처(잠정) | 입력 | 출력 | 에러/실패 | 복잡? |
+|------|-----------|----------------|------|------|-----------|-------|
+| `<name>` |  |  |  |  |  | 단순 / **복잡** |
+
+> 복잡 기준: 분기/상태기계, 외부 I/O, 리스크(주문·잔고) 경로, 비자명 알고리즘.
+> → 해당 함수는 `fn-<name>.md` 작성. 단순(게터·포매터 등)은 이 표로 충분.
+
+## 8. 흐름 / 알고리즘
+- 핵심 시나리오 단계별. 상태 전이.
+
+## 9. 엣지케이스 & 에러 처리
+- 경계값, 실패 모드, 재시도/백오프.
+- **안전한 기본값**(API 실패 시 거래 중단 등).
+
+## 10. 테스트 계획
+- 단위/통합 케이스 목록 (각 인수조건에 매핑).
+- 모킹/드라이런 전략 (거래소 API 등).
+
+## 11. 리스크 & 대안 검토
+- 선택한 접근 vs 대안, 트레이드오프.
+- 되돌리기 어려운 결정 → **ADR 로 분리** (`adr/NNNN-*.md`).
+
+## 12. 미해결 질문 (Open Questions)
+- ...
--- a/docs/pipeline/QUEUE-PROTOCOL.md
+++ b/docs/pipeline/QUEUE-PROTOCOL.md
@@ -0,0 +1,42 @@
+# Queue Protocol — 모든 페르소나 공통 규약
+
+작업 큐 = Redmine 이슈. 각 페르소나는 자기 단계 이슈를 처리하고 git/Redmine 에 남긴 뒤 다음으로 넘긴다.
+
+## 0. 환경 로드
+```bash
+set -a; . ./.env; set +a
+RK="$REDMINE_API_KEY"; RB="$REDMINE_URL"; PROJ="$REDMINE_PROJECT"
+# 카테고리 id 는 이름으로 조회(프로젝트마다 id 다름):
+catid(){ curl -s -H "X-Redmine-API-Key: $RK" "$RB/projects/$PROJ/issue_categories.json" \
+  | python3 -c "import sys,json;[print(c['id']) for c in json.load(sys.stdin)['issue_categories'] if c['name']=='$1']"; }
+```
+
+## 1. 큐 매핑
+- 현재 단계 = 카테고리 `01-Planner`…`08-Documenter`,`09-Done`.
+- 수명주기 = 상태 신규(대기)/진행/완료/거절.
+
+## 2. 내 작업 꺼내기
+```bash
+DEV=$(catid 03-Developer)
+curl -s -H "X-Redmine-API-Key: $RK" "$RB/issues.json?project_id=$PROJ&category_id=$DEV&status_id=1&sort=id:asc&limit=1"
+# 시작 시 상태 진행(2):
+curl -s -H "X-Redmine-API-Key: $RK" -H "Content-Type: application/json" -X PUT "$RB/issues/<ID>.json" -d '{"issue":{"status_id":2}}'
+```
+
+## 3~4. 결과 남기기 (필수 3가지)
+- (a) git 커밋+push (`[<Persona>] #<ID> ...`)
+- (b) Redmine 저널 노트(역할 태그)
+- (c) 다음 단계 전진: 카테고리=다음이름의 id, 상태 신규(1)
+```bash
+NEXT=$(catid 04-QA)
+curl -s -H "X-Redmine-API-Key: $RK" -H "Content-Type: application/json" -X PUT "$RB/issues/<ID>.json" \
+  -d "{\"issue\":{\"category_id\":$NEXT,\"status_id\":1,\"notes\":\"[<Persona>] ...\"}}"
+```
+
+## 5. 게이트 반려
+- QA(04)/Reviewer(06) 실패 → `03-Developer`. Developer 설계서 누락 → `02-Architect`. 사유를 노트에.
+
+## 6. 종료 (Documenter)
+- `09-Done` + 상태 완료(5) + done_ratio 100.
+
+원칙: 자기 역할 범위만, 모든 변경 git 추적, 비밀(.env) 노출 금지.