NINI
49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
# Architecture Decision Records
|
|
|
|
## 철학
|
|
이 템플릿의 핵심 가치는 사용자의 의도를 보존하면서도, 조사와 피드백을 통해 Markdown 문서 품질을 단계적으로 높이는 것이다. 빠르게 초안을 만들되, 근거 없는 최종본을 만들지 않는다.
|
|
|
|
---
|
|
|
|
### ADR-001: Markdown-first 문서 산출
|
|
**결정**: 모든 중간 산출물과 최종 산출물은 Markdown으로 작성한다.
|
|
|
|
**이유**: Markdown은 버전 관리, 리뷰, 재사용, 자동 변환에 적합하고 AI Agent가 구조를 안정적으로 다루기 쉽다.
|
|
|
|
**트레이드오프**: PDF, DOCX, 슬라이드 같은 최종 배포 형식은 별도 변환 단계가 필요하다.
|
|
|
|
### ADR-002: PRD를 단일 요구사항 원천으로 사용
|
|
**결정**: `docs/PRD.md`를 문서 목적, 독자, 범위, 톤, 키워드의 기준으로 삼는다.
|
|
|
|
**이유**: 단계가 길어질수록 AI Agent가 임의로 목표를 확장할 위험이 있다. 단일 원천을 두면 초안과 최종본을 같은 기준으로 평가할 수 있다.
|
|
|
|
**트레이드오프**: PRD가 빈약하면 후속 산출물도 흐려진다. 필요한 경우 PRD 보강을 먼저 요청해야 한다.
|
|
|
|
### ADR-003: ResearchNote를 출처 장부로 사용
|
|
**결정**: 웹 조사 결과와 출처 검증은 `docs/ResearchNote.md`에 먼저 정리한 뒤 문서에 반영한다.
|
|
|
|
**이유**: 최종 문서에서 어떤 주장에 어떤 근거가 사용되었는지 추적할 수 있다.
|
|
|
|
**트레이드오프**: 짧은 문서라도 조사 단계가 하나 추가된다. 대신 사실 오류와 출처 누락 위험을 줄인다.
|
|
|
|
### ADR-004: 피드백 지점은 blocked 상태로 표현
|
|
**결정**: 사용자 검토가 필요한 step은 `blocked` 상태와 구체적인 `blocked_reason`을 기록한다.
|
|
|
|
**이유**: Harness 실행기가 사용자 개입이 필요한 지점을 명확히 멈출 수 있다.
|
|
|
|
**트레이드오프**: 사용자가 피드백을 작성한 뒤 상태를 `pending`으로 되돌려 재실행해야 한다.
|
|
|
|
### ADR-005: 초안과 최종본 분리
|
|
**결정**: 초안은 `drafts/`, 최종본은 `final/`에 저장한다.
|
|
|
|
**이유**: 사용자 검토 흔적과 최종 납품물을 명확히 분리할 수 있다.
|
|
|
|
**트레이드오프**: 파일 수가 늘어난다. 대신 리뷰와 회귀 확인이 쉬워진다.
|
|
|
|
### ADR-006: Gemini CLI의 context/Skill/Command/Hook/Subagent 구조 사용
|
|
**결정**: 이 템플릿은 Gemini CLI의 `GEMINI.md`, `.agents/skills`, `.gemini/settings.json`, `.gemini/commands`, `.gemini/hooks`, `.gemini/agents` 구조를 기준으로 한다.
|
|
|
|
**이유**: Gemini CLI는 프로젝트 지침을 `GEMINI.md`로 읽고, `SKILL.md` 기반 Agent Skills를 on-demand로 활성화하며, custom slash command와 lifecycle hook, local subagent를 `.gemini/` 아래에서 구성한다. 템플릿의 의도를 Gemini CLI 네이티브 구조에 맞추면 실행 맥락과 재사용성이 좋아진다.
|
|
|
|
**트레이드오프**: 다른 CLI 전용 구성과 직접 호환되지 않는다. 대신 Gemini CLI의 headless execution, custom commands, hooks, subagents를 기준으로 문서 작성 자동화가 명확해진다.
|