설계 결정 (ADR)
되돌리기 비싼 기술 결정만 기록한다. 기획·일정·요구사항은 Linear Project에 있다.
목록
| # | 결정 | 결정일 | 상태 |
|---|---|---|---|
| 0001 | 분석은 in-process 큐 + LangGraph fan-out으로 돌린다 | 2026-07-22 | 넷 중 하나 뒤집힘 |
| 0002 | LLM 실행 추적은 Langfuse로 한다 | 2026-07-22 | active |
| 0003 | 전사 임베딩을 MVP에 넣는다 | 2026-07-23 | active · 이전 보류 결정을 뒤집음 |
| 0004 | 운영 배포는 EC2 한 대 + SSM CD | 2026-07-26 | active |
| 0005 | checkpoint 커넥션의 안정화 인자 넷을 줄이지 않는다 | 2026-07-28 | active |
| 0006 | 분석 동시 실행에 상한을 두지 않는다 | 2026-07-31 | active |
| 0007 | OpenAI는 Responses API로 부르되 서버에 상태를 안 남긴다 | 2026-08-03 | active |
이 목록에서 먼저 읽을 것
0001 — 결정 넷 중 하나(asyncio.Queue 기반 in-process 큐)가 APP-298에서 실제로 뒤집혔다. 지금은 큐도 소비자도 없고 BackgroundTasks가 응답 뒤에 돌리며, 겹치는 잡은 PgSingleFlight의 advisory lock이 막는다.
문서 전체를 superseded로 두지 않았다. 나머지 셋(LangGraph fan-out 3노드 · OpenAI · CachedPrompt 캐시 경계)은 그대로 살아 있어서, 뒤집힌 항목만 본문에 취소선으로 표시하고 대체 결정(0006)으로 링크했다. 결정 단위가 문서 단위보다 작을 때의 처리 방식이다.
0003 도 같은 성격이다 — 기획 v2에서 "MVP 보류"로 정했던 것을 뒤집은 기록이고, 왜 뒤집었나가 본문의 절반이다.
쓸지 말지
- 되돌리기 비싼가
- 다른 선택지가 실제로 있었나
- 6개월 뒤 "왜 이렇게 했지?" 소리가 나올까
→ 셋 다 yes일 때만. 라이브러리 하나 고른 것은 여기 쓰지 않는다.
규칙
- 파일명
NNNN-<kebab-case>.md. 번호는 순차, 재사용 금지 - 한 번 확정되면 본문을 수정하지 않는다. 결정이 바뀌면 새 ADR을 쓰고 이전 것에
Superseded by를 단다 - 결정 단위가 문서보다 작으면 0001처럼 해당 항목만 취소선 + 대체 링크
- 템플릿: TEMPLATE.md
여기 없는 것
작업 방식(하네스·에이전트 로스터·리뷰 skill)에 대한 결정은 scope: harness 로 분류해서 heymoa-ai/docs/decisions/에 남겨두었다. 제품 코드에 영향을 주지 않으므로 이 목록에 올리지 않는다.