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를 기준으로 문서 작성 자동화가 명확해진다.

3.1 KiB Raw Permalink Blame History