AI 기반 소프트웨어 개발을 위한 의사결정 기록

코드의 의도를 가깝게 유지하세요.

Page content

AI를 활용한 소프트웨어 개발에서 의사결정 기록은 누락된 기억 계층입니다. 기록의 대상은 무엇이가구축되었는가가 아니라, 왜 그렇게 결정되었는가에 초점을 맞춥니다. AI 도구가 코드를 작성하게 될 때 이 구분은 매우 중요해집니다.

의사결정 기록 — ADR, PDR, DDR — 의도와 코드를 연결하기

의사결정 기록은 누락된 기억 계층입니다

AI 주도 프로그래밍은 코드를 생성하는 비용을 낮추고, 리팩토링을 용이하게 하며, 폐기를 빠르게 함으로써 소프트웨어 개발의 경제성을 변화시킵니다. 이는 유용합니다. 하지만 위험하기도 합니다. 코드를 생산하기가 쉬워지면 희소한 자원은 더 이상 타이핑이 아니기 때문입니다. 희소한 자원은 판단력입니다.

왜 팀은 PostgreSQL을 DynamoDB 대신 선택했을까요? 왜 제품은 AI가 생성한 이메일을 전송하기 전 인간 리뷰를 요구할까요? 왜 인터페이스는 제안 사항을 직접 적용하는 대신 옆 패널에 표시할까요? 왜 6개월 전 더 단순한 접근 방식이 거절되었을까요? 코드는 존재하는 것을 보여줄 수 있지만, 그것이 왜 존재하는지는 거의 설명하지 않습니다.

의사결정 기록은 중요한 선택, 그 배경이 되는 맥락, 고려된 대안, 그리고 팀이 수용한 결과를 포착하는 짧고 버전 관리가 되는 문서를 제공함으로써 이 문제를 해결합니다. AI 보조 코드베이스에서 이러한 기록은 단순히 문서에 그치지 않고, 인간과 AI 코딩 에이전트 모두에게 미래의 변경 사항을 만들기 전에 읽을 수 있는 지속 가능한 프로젝트의 기억이 됩니다. 실용적인 운영 규칙은 간단합니다: 의사결정 기록을 저장소 내의 Markdown 파일로 유지하고, 코드처럼 검토하며, AI 도구가 변경 사항을 제안하거나 구현하기 전에 읽을 수 있도록 하십시오.

의사결정 기록이란 무엇인가?

의사결정 기록은 의미 있는 결정에 대한 서면 기록으로, 네 가지 기본 질문에 답하도록 구조화됩니다: 우리는 무엇을 결정했는가, 왜 그렇게 결정했는가, 어떤 대안을 고려했는가, 어떤 결과를 수용했는가? 가장 일반적인 형태는 아키텍처 의사결정 기록(Architecture Decision Record, ADR)입니다. ADR은 기술적 결정을 문서화하는 데 널리 사용되며, 같은 패턴은 아키텍처를 넘어 제품 및 디자인 작업으로도 확장될 수 있습니다.

AI 주도 프로그래밍을 위해 특히 유용한 세 가지 유형은 다음과 같습니다:

기록 유형 포착 내용 예시
ADR 아키텍처 및 기술적 결정 PostgreSQL을 기본 데이터베이스로 사용
PDR 제품 동작 및 범위 결정 AI 생성 이메일은 초안으로 유지되어야 함
DDR 디자인 및 인터랙션 결정 AI 제안 사항을 옆 패널에 표시

통합적으로 볼 때, ADR, PDR, DDR는 시스템의 구조뿐만 아니라 제품의 의도와 사용자 경험 뒤의 추론을 설명합니다. 이 조합이 중요한 이유는 AI 에이전트가 코드를 읽을 수 있지만, 코드만으로는 좋은 결정을 내리는 데 필요한 충분한 맥락이 포함되어 있지 않기 때문입니다. 의사결정 기록은 AI 시스템이 프로젝트의 의도를 파악할 수 있는 검토된, 지속 가능한, 인간 승인된 출처를 제공합니다.

아키텍처 의사결정 기록 (ADR)

아키텍처 의사결정 기록은 기술적 및 구조적 결정을 포착합니다. 결정이 시스템의 형태—경계, 종속성, 운영 모델, 또는 장기적 유지보수성에 영향을 미칠 때 ADR을 사용하십시오.

ADR으로 기록할 가치가 있는 결정의 예는 다음과 같습니다:

  • 기본 데이터베이스로 PostgreSQL 선택
  • 백그라운드 처리를 위한 이벤트 기반 아키텍처 사용
  • 애플리케이션을 모듈식 모놀리스(modular monolith)로 유지
  • 메시지 큐 도입
  • GraphQL 대신 REST 선택
  • 웹 애플리케이션을 위한 서버 사이드 렌더링 사용
  • 모든 백그라운드 작업이 멱등(idempotent)해야 함을 요구
  • 특정 인증 및 인가 모델 채택

ADR은 전체 아키텍처 문서가 아닙니다 — 의도적으로 작으며, 특정 시점의 중요한 결정을 하나씩 기록합니다. 좋은 ADR은 아키텍처적 기억상실을 방지합니다: 없이는 미래의 공헌자들이 같은 트레이드오프를 다시 발견하거나, 오래된 논쟁을 다시 열거나, 중요한 제약 사항을 실수로 해제할 수 있습니다.

AI 주도 프로그래밍에서 ADR은 더욱 큰 무게를 가집니다. AI 도구는 종종 로컬 최적화에는 능숙하지만, 더 큰 아키텍처적 제약 사항을 위반하는 기술적으로 타당한 변경 사항을 제안할 수 있습니다. ADR은 AI에게 명확한 경계를 제공합니다: “이 시스템은 이렇게 형성되어야 합니다.”

제품 의사결정 기록 (PDR)

제품 의사결정 기록은 제품 동작, 범위, 사용자 대면 의도를 포착합니다. ADR보다 덜 일반적이지만, 종종만큼이나 가치 있습니다 — 제품 결정은 티켓, 로드맵 도구, 채팅 스레드, 회의 노트, 사람들의 기억에 걸쳐 산재해 있기 때문에 인간이 잊기 쉽고 AI 도구가 신뢰하게 추론하기 거의 불가능합니다.

결정이 제품이 무엇을 하는지, 누구를 위해 하는지, 의도적으로 범위를 벗어나는 것이 무엇인지, 또는 사용자 대면 기능이 어떻게 작동해야 하는지에 영향을 미칠 때 PDR을 사용하십시오. 예시는 다음과 같습니다:

  • AI 생성 메시지는 인간이 검토하기 전까지 초안으로 유지되어야 함
  • 무료 티어 사용자는 최대 3개 프로젝트 생성 가능
  • 삭제된 워크스페이스는 30일 동안 복구 가능
  • 팀 бил링(billing)은 버전 1의 범위 밖임
  • 사용자는 지원팀에 문의하지 않고 데이터를 내보낼 수 있음
  • 낮은 신뢰도의 AI 요약은 숨겨지는 대신 경고 표시

PDR은 제품 선택이 코드에서 자의적으로 보이는 경우 특히 유용합니다. 코드에는 무료 사용자를 위한 3개 프로젝트 제한이 포함되어 있을 수 있고, PDR이 없으면 AI 도구가 그 숫자를 마법 상수(magic constant)로 취급하여 변경을 제안할 수 있습니다. PDR이 있으면, AI는 제한이 가격 전략, 온보딩 비용, 또는 지원 부하와 관련되어 있으며 변경에는 빠른 편집이 아니라 신중한 제품 결정을 필요로 한다는 것을 볼 수 있습니다.

디자인 의사결정 기록 (DDR)

디자인 의사결정 기록은 사용자 경험, 인터랙션, 시각적, 콘텐츠 디자인 결정을 포착합니다. 결정이 사용자가 제품과 상호작용하는 방식, 정보가 제시되는 방식, 또는 디자인 원칙이 미래 작업에 어떻게 적용되어야 하는지에 영향을 미칠 때 DDR을 사용하십시오.

기록할 가치가 있는 디자인 결정의 예는 다음과 같습니다:

  • 제출 시에만 검증하는 대신 인라인 검증 사용
  • AI 제안 사항을 에디터 안에 바로 넣는 대신 옆 패널에 배치
  • 고급 설정에 대해 점진적 공개(progressive disclosure) 사용
  • 파괴적인 작업 전 확인 요구
  • “비활성"과 “활성” 대신 “초안"과 “게시됨” 사용
  • 모바일 화면에서 주요 작업이 항상 보이도록 유지

디자인 의도는 구현 동안 쉽게 잃어지기 쉽습니다. 개발자가 플로우를 단순화하거나, AI 에이전트가 기술적으로 작동하지만 의도된 인터랙션 모델을 깨는 컴포넌트를 생성할 수 있습니다. 예를 들어, DDR은 이렇게 기록할 수 있습니다: “사용자가 변경 사항을 수용하기 전에 생성된 텍스트와 자신의 초안을 비교해야 하므로, AI 작성 제안 사항은 문서 안에 있는 것이 아니라 옆에 표시합니다.” 그 기록은 미래의 공헌자들에게 복제할 레이아웃이 아니라 보존할 원리를 제공합니다.

왜 AI를 사용할 때 의사결정 기록이 더 중요한가

AI 코딩 도구는 강력하지만, 종종 상태(stateless)이거나 프로젝트 역사를 부분적으로만 인식합니다. 파일 점검, 패턴 추론, 변경 사항 생성은 할 수 있지만 — 어떤 결정이 의도적인지, 어떤 것은 우연인지, 이미 논쟁과 해결되었는지를 자동으로 알지 못합니다. 이것은 여러 가지 별개의 리스크를 만듭니다.

AI가 해결된 논쟁을 다시 열 수 있습니다

팀이 이미 모듈식 모놀리스 사용을 결정했다면, AI 에이전트는 여전히 서비스가 격리되어 볼 때 깔끔해 보이므로 서비스 추출을 제안할 수 있습니다. ADR이 없으면, AI는 팀이 이미 해당 경로를 고려하고 거절했다는 것을 알 수 있는 지속 가능한 방법이 없으며, 그 결과 노력 낭비 또는 시스템 일관성의 미묘한 회귀(regression)가 발생합니다.

AI가 로컬 최적화로 전역을 손상시킬 수 있습니다

생성된 리팩토링이 한 파일은 더 깔끔하게 만들면서도 시스템 경계를 위반할 수 있습니다. UI 변경이 컴포넌트 복잡도를 줄이면서 의도된 사용자 경험을 약화시킬 수 있습니다. 제품 변경이 구현을 단순화하면서 가격 또는 컴플라이언스 가정을 깨뜨릴 수 있습니다. 의사결정 기록은 AI가 좁은 범위의 신호에 따라 행동하기 전에 더 큰 참조 프레임을 제공합니다.

AI가 코드는 보존하지만 의도는 잃을 수 있습니다

모델은 코드베이스의 기존 패턴을 따를 수 있지만, 패턴은 원칙과 같지 않습니다. 때로는 기존 코드가 타협입니다. 때로는 과도기적입니다. 때로는 파일에서 보이지 않는 외부 제약 사항 때문에 존재합니다. 의사결정 기록은 “이것이 작동하는 방식"과 “이것이 왜 이런 방식으로 만들어졌는가” 사이의 차이를 설명합니다.

AI가 그럴듯하지만 틀린 근거를 생성할 수 있습니다

AI는 의사결정 기록을 작성할 수 있지만, 실제 결정과 맞지 않는 자신감 있어 보이는 설명을 발명할 수도 있습니다. 이것이 인간 리뷰가 비협상 가능한 이유입니다: AI가 기록의 첫 번째 초안을 생성할 수 있지만, 기록이 병합되기 전에 실제 결정, 대안, 결과를 정확히 묘사하는지 인간이 검증해야 합니다.

더 넓은 방법론의 일부로서 의사결정 기록

의사결정 기록은 단순히 문서가 아닙니다 — 경량 아키텍처 거버넌스, 문서로서의 코드(Docs as Code), AI 증강 지식 관리 워크플로, 제품 발견, 디자인 근거, AI 거버넌스, 코드 리뷰의 교차점에 있는 더 넓은 작업 방식의 일부입니다. 더 큰 프로세스를 설명하는 유용한 방법은 의사결정 중심 개발(Decision-Oriented Development)입니다.

대부분의 AI 주도 프로그래밍 워크플로는 생성-검토-커밋 루프에 좁게 초점을 맞춥니다:

flowchart LR A[프롬프트] --> B[코드 생성] B --> C[테스트] C --> D[커밋]

그 사이클은 진지한 시스템 작업에는 너무 얇습니다. 더 강한 워크플로는 저장소를 코드와 의도의 저장소로 취급합니다 — 여기서 다이어그램은 Mermaid를 사용하며, Markdown 의사결정 기록 내부에서도 잘 작동하는 경량 포맷입니다:

flowchart TB subgraph top[" "] direction LR A[문제 정형화] --> B[기존 의사결정 식별] --> C[옵션 및 트레이드오프 탐색] --> D[선택된 의사결정 기록] end subgraph bottom[" "] direction LR E[코드 생성 또는 수정] --> F[코드 vs 의사결정 검토] --> G[구현 및 기억 병합] --> H[기록을 사용하여 미래 작업 안내] end D --> E

이 프로세스는 저장소를 코드 저장소를 넘어선 것으로 만듭니다. 구현, 의도, 추론의 진실의 원천이 되며 — 만든 모든 의사결정으로 가치가 쌓이는 지속 가능한 아티팩트가 됩니다.

의사결정 기록과 Docs as Code

의사결정 기록은 Docs-as-code 원칙을 따를 때 가장 잘 작동하며, 이는 코드와 같은 저장소에 저장되어야 한다는 것을 의미합니다. 순수 Markdown으로 작성되고, 풀 리퀘스트에서 검토되며, Git으로 버전 관리되고, 관련 이슈 및 풀 리퀘스트에 링크되며, 인간과 AI 도구 모두 검색할 수 있어야 합니다. 이는 중요한 결정을 채팅, 위키 페이지, 슬라이드 덱, 또는 회의 노트에 저장하는 것보다 훨씬 더 신뢰할 수 있습니다 — 그러한 도구는 토론에는 여전히 유용할 수 있지만, 승인된 결정은 항상 코드에 가깝게 유지되어야 합니다. AI 개발에서 스펙, 테스트, 코드를 동기화 유지하기는 이 동일한 “기록으로 돌아가는” 습관을 요구사항 및 디자인 결정 ID를 테스트 및 풀 리퀘스트에 연결하는 완전한 추적 가능성 모델로 확장합니다.

잘 조직된 의사결정 기록의 저장소 구조는 다음과 같을 수 있습니다:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

더 작은 프로젝트의 경우, 더 평평한 구조도 동일하게 잘 작동합니다. 정확한 폴더 조직 일관성보다 중요하지 않으며 — 기록은 쉽게 찾을 수 있고, 쉽게 검토할 수 있고, AI 도구가 코드베이스에 행동하기 전에 컨텍스트로 로드하기 쉬워야 합니다. Go 팀의 경우, 이 docs/decisions/ 구조는 Go 프로젝트 구조: 관행 및 패턴에서 설명한 cmd/, internal/, api/ 레이아웃과 자연스럽게 병행되며, 아키텍처 결정 및 API 참조를 위한 docs/를 추천합니다.

실용적인 의사결정 기록 템플릿

유용한 의사결정 기록 템플릿은 사람들이 실제로 사용할 수 있을 만큼 짧아야 합니다. 다음은 선택적이지만 가치 있는 AI 가이드 섹션을 포함하는 실용적인 Markdown 템플릿입니다:

# 결정: 짧은 제목

상태: 제안됨 | 수락됨 | 대체됨 | 비추천
날짜: YYYY-MM-DD
유형: 아키텍처 | 제품 | 디자인
소유자: 팀 또는 이름

## 맥락

이 결정을 이끌어낸 문제, 제약 사항, 목표, 사용자 필요, 기술적 사실,
및 비즈니스 요인을 설명합니다.

## 결정

결정을 명확하게 서술합니다.

## 고려된 대안

### 옵션 1

장점:
- ...

단점:
- ...

## 결과

쉬워지는 것, 어려워지는 것, 그리고 이것이 만드는 리스크
또는 후속 작업을 설명합니다.

## AI 가이드

AI 어시스턴트가 이 영역에서 작업할 때, 다음과 같이 해야 합니다:
- 보존할 것: ...
- 피할 것: ...
- 선호할 것: ...
- 리뷰를 요청할 때: ...

## 링크

- 관련 이슈:
- 관련 풀 리퀘스트:
- 관련 파일:
- 대체한 기록:
- 대체된 기록:

“AI 가이드” 섹션은 선택 사항이지만, AI 주도 프로그래밍에서는 매우 가치 있습니다 — 의사결정 기록을 같은 코드베이스 영역에서 작업하는 미래 에이전트를 위한 지속 가능한 지침으로 변환하기 때문입니다.

의사결정 기록에 무엇을 포함할 것인가?

모든 선택이 기록할 가치가 있는 것은 아니고, 모든 작은 구현 디테일이 의사결정 기록이 되면 그 프로세스는 소음으로 붕괴됩니다. 선택이 의미 있고 나중에 중요할 가능성이 있을 때 의사결정 기록을 생성하십시오.

좋은 후보는 다음과 같은 결정입니다:

  • 시스템의 여러 부분에 영향을 미치는
  • 제품 약속을 인코딩하는
  • 진정한 논쟁을 해결하는
  • 장기적 트레이드오프를 도입하는
  • 비즈니스, 컴플라이언스, 또는 운영 제약 사항에 의존하는
  • 나중에 다시 발견하는 데 비용이 많이 드는
  • 미래 AI 도구가 그럴듯하게 틀릴 수 있는
  • 미래 공헌자가 쉽게 되돌리려 할 수 있는

나쁜 후보로는 작은 리팩토링 선택, 명백한 버그 수정, 임시 실험, 로컬 네이밍 결정, 지속적인 결과가 없는 구현 디테일이 포함됩니다. 좋은 경험칙은 단순합니다: 결정을 되돌리려면 논의가 필요하다면, 그 결정을 기록하십시오.

상태 값과 라이프사이클

의사결정 기록은 현재 지위를 signaled하기 위한 라이프사이클이 있어야 합니다. 가장 단순한 상태 값이 충분합니다.

제안됨 (Proposed) — 결정이 고려되고 있지만 아직 수락되지 않았습니다. 팀이 결정에 커밋하기 전에 풀 리퀘스트에서 논의를 원할 때 이 상태를 사용하십시오.

수락됨 (Accepted) — 결정이 활성이며 미래 작업을 안내해야 합니다. 가장 유용한 의사결정 기록은 대부분의 생애 동안 이 상태에 머물 것입니다.

대체됨 (Superseded) — 결정이 더 새로운 기록으로 대체되었습니다. 오래된 기록을 삭제하지 마세요; 역사를 위해 유지하고 새로운 결정에 링크하여 사고의 진화가 보일 수 있도록 하십시오.

비추천 (Deprecated) — 결정은 더 이상 권장되지 않지만 시스템의 기존 부분을 묘사할 수 있습니다. 이것은 코드가 데이터베이스에 새로운 접근 방식과 함께 기존 패턴이 존재하는 마이그레이션 중 특히 유용합니다.

중요한 원칙은 의사결정 기록이 추가 친화적(append-friendly)이어야 한다는 것입니다. 팀이 방향을 바꿀 때, 새로운 기록을 생성하고 오래된 것에 링크하는 것이 역사를 다시 써서 과거를 더 깔끔하게 보이게 하는 것보다 좋습니다.

AI가 의사결정 기록을 생성해야 하는 방식

AI는 의사결정 기록을 만드는 데 도움을 줄 수 있고, 이는 소프트웨어 개발에서 AI의 더 나은 사용 중 하나입니다 — 맥락에서 구조화된 문서를 초안 작성하는 데 빠르기 때문입니다. 토론, 아키텍처 리뷰, 또는 풀 리퀘스트 이후, AI 어시스턴트에게 기록 초안 작성을 요청할 수 있습니다:

이 풀 리퀘스트의 결정에 대한 아키텍처 의사결정 기록을 작성하십시오.
맥락, 대안, 결과, 및 AI 가이드를 포함하십시오.
docs/decisions/architecture 아래에 Markdown으로 저장하십시오.

제품 작업의 경우:

AI 생성 메시지가 사용자 검토 전까지 초안으로 유지되어야 하는 이유를
설명하는 제품 의사결정 기록을 작성하십시오.
사용자 영향, 범위 밖 동작, 트레이드오프, 및 AI 가이드를 포함하십시오.

그러나 AI 생성된 기록은 자동으로 신뢰하지 않아야 합니다. 인간 리뷰는 맥락이 정확한지, AI가 근거를 발명하지 않았는지, 나열된 대안이 실제인지, 결과가 정직한지, AI 가이드가 팀의 실제 의도와 일치하는지 검증해야 합니다. AI는 초안 어시스턴트입니다 — 의사결정의 소유자가 아닙니다.

AI가 의사결정 기록을 읽어야 하는 방식

관행의另一半은 행동하기 전에 기록을 읽도록 AI에게 지시하는 것입니다. AI 어시스턴트에게 변경 사항 구현을 요청하기 전에, 다음과 같은 지침을 포함하십시오:

이 기능을 수정하기 전에 docs/decisions를 읽으십시오.
적용 가능한 아키텍처, 제품, 또는 디자인 의사결정 기록을 식별하십시오.
수락된 결정을 따르십시오. 제안된 변경 사항이 의사결정 기록과
충돌되면, 코드를 변경하기 전에 충돌을 설명하십시오.

더 큰 작업의 경우, 기록의 역할이 프로젝트의 기억임을 강화하십시오:

의사결정 기록을 프로젝트의 기억으로 사용하십시오.
새로운 대체 결정을 제안하지 않고 수락된 결정을 되돌리지 마십시오.
코드를 생성할 때, 구현에 영향을 미친 의사결정 기록을 설명하십시오.

이것은 AI의 역할을 “그럴듯한 코드 예측"에서 “문서화된 제약 시스템 안에서 작동"으로 변경합니다 — 복잡하거나长寿한 프로젝트의 신뢰성에 대한 상당한 개선입니다.

풀 리퀘스트 내 의사결정 기록

의사결정 기록은 별도의 프로세스가 아니라 정상적인 풀 리퀘스트 리뷰의 일부가 되어야 합니다. 단순한 PR 체크리스트 항목이 습관을 가시적으로 만듭니다:

## 의사결정 기록 체크리스트

- [ ] 이 PR은 상당한 아키텍처, 제품, 또는 디자인 결정을 도입하지 않습니다.
- [ ] 이 PR은 상당한 결정을 도입하며 새로운 의사결정 기록을 포함합니다.
- [ ] 이 PR은 이전 결정을 변경하며 대체 기록을 포함합니다.
- [ ] 관련 기존 의사결정 기록이 고려되었습니다.
- [ ] AI 생성 코드가 수락된 의사결정 기록을 따릅니다.
- [ ] AI 생성 의사결정 기록이 인간에 의해 검토되었습니다.

이 체크리스트는 단순하지만, 코드만이 풀 리퀘스트에서 중요한 아티팩트가 아님을 팀에게 상기시킴으로써 행동을 변화시킵니다. 또한 AI 생성 변경 사항가 이전에 결정된 것을 조용히 위반할 때 그것을 자연스럽게 발견할 수 있게 합니다.

의사결정 기록과 아키텍처 거버넌스

전통적인 아키텍처 거버넌스는 종종 너무 무겁고, 너무 느리며, 구현과 너무 연결이 끊어져서 실패합니다 — 중앙 승인 보드, 대량의 초기 문서, 가이드하기보다 차단하는 게이트키핑 프로세스. 의사결정 기록은 개발 워크플로에 직접 통합되는 더 가벼운 대안을 제공합니다.

모든 변경에 중앙 아키텍처 보드를 요구하지도, 팀이 학습하고 적응하는 것을 차단하지도 않습니다. 대신, 시간에 걸쳐 검토, 참조, 그리고 구축될 수 있는 결정의 흔적을 만듭니다. 이것은 진화적 아키텍처를 지원합니다: 아키텍처는 변경될 수 있지만, 기억을 무시하는 것이 아니라 기억과 함께 변경됩니다. 팀은 왜 만들어졌는지 다시 발견할 필요 없이 오래된 결정을 재검토할 수 있으며, 이것은 더 건강하고 정직한 형태의 거버넌스입니다:

  • 거대한 문서 대신 작은 기록
  • 별도의 승인 시극 대신 코드 근처에서 검토
  • 부족 지식 대신 역사적 맥락
  • 숨겨진 가정 대신 명시적 트레이드오프

의사결정 기록과 제품 관리

제품 작업도 의사결정 기억이 필요하며, 의사결정 기록의 가치가 종종 과소평가되는 영역입니다. 로드맵은 어떤 일이 일어날 수 있는지를 말합니다. 티켓은 다음에 무엇을 빌드할지를 말합니다. 분석은 사용자가 무엇을 했는지를 말합니다. 그 어느 것도 제품 동작이 왜 존재하는지를 완전히 설명하지는 않습니다.

제품 의사결정 기록은 그 공백을 채우며, 가격 및 패키징 결정, 권한 모델, 제한 및 쿼터, AI 안전 및 리뷰 플로우, 온보딩 선택, 사용자 역할 정의, 협업 규칙, 데이터 보존 정책, 및 기능 범위 경계에 특히 유용합니다. 구현된 후, 제품 결정은 코드에서 눈에 보이지 않게 됩니다 — 나중에, 누군가는 코드만 보고 “왜 이렇습니까?“라고 묻습니다. PDR은 인간과 AI 도구 모두가 찾고 사용할 수 있는 형태로 답을 제공합니다.

의사결정 기록과 디자인 시스템

디자인 시스템은 종종 컴포넌트, 토큰, 및 사용 규칙을 문서화하지만, 시스템이 왜 그렇게 작동하는지는 거의 문서화하지 않습니다. 디자인 의사결정 기록이 이 공백을 채웁니다. 컴포넌트 라이브러리가 “파괴적인 작업에는 확인 다이얼로그를 사용하십시오"라고 말할 수 있지만, DDR은 근거를 설명합니다: “사용자가 종종 공유된 팀 데이터로 작업하고, 실수 삭제의 복구 비용이 높기 때문에 파괴적인 작업에는 확인을 요구합니다.”

그 근거는 특정 컴포넌트를 넘어 중요합니다. 그것은 미래의 디자이너, 개발자, AI 도구가 새로운 상황에서 원리를 올바르게 적용하는 데 도움이 됩니다. DDR이 없으면, AI 에이전트는 더 효율적으로 보이기 때문에 확인을 건너뛰는 더 빠른 인터랙션을 생성할 수 있습니다. DDR이 있으면, 에이전트는 안전 속성을 보존하는 것이 의도적이고 비협상 가능하다는 것을 인식할 수 있습니다.

의사결정 기록이 스펙 주도 개발을 어떻게 지원하는가

스펙 주도 개발은 시스템이 무엇을 해야 하는지 설명합니다. 의사결정 기록은 팀이 왜 그 방향을 선택했는지 설명하며, AI 보조 작업에 대해 이 구분은 중요하게 작용합니다.

기능 스펙은 AI 생성 이메일이 초안으로 저장되어야 한다고 말할 수 있습니다. 제품 의사결정 기록은 자동 전송이 왜 거절되었는지, 어떤 리스크가 고려되었는지, 어떤 미래 변경이 새로운 결정을 요구하는지 설명합니다. 디자인 스펙은 옆 패널 인터랙션을 설명할 수 있지만, 해당 DDR은 인라인 AI 편집이 명시적으로 왜 거절되었는지, 그리고 사용자 제어 보장이 워크플로 속도보다 더 중요하게 가중된 이유를 설명합니다. 아키텍처 스펙은 서비스 경계를 정의할 수 있고, 그 ADR은 팀이 왜 더 단순하거나 더 분산된 대안 대신 그 경계를 선택했는지 설명합니다.

스펙은 구현을 안내합니다. 의사결정 기록은 판단을 보존합니다. 함께, 그들은 AI 코딩 에이전트에게 지침과 컨텍스트를 모두 제공합니다 — “무엇"과 “왜” — 이는 복잡한,长寿한 시스템에 대해 그 조합을 그렇게 효과적으로 만드는 것입니다. 스펙 주도 툴체인을 채택할 때, 각 옵션이 그 컨텍스트를 어떻게 표면화하는지 비교하십시오; GitHub Spec Kit vs Kiro vs Claude Code SDD 워크플로는 주요 세팅 간 휴대성, 리뷰 게이트, 저장소 기반을 분해합니다. 그 도구들이 구현하는 도구 중립적 5단계 프로세스에 대해서는, 요구사항에서 코드로의 스펙 주도 개발 워크플로를 참조하십시오. 대부분의 SDD 도구는 그 루프의 “출시” 절반만 깔끔하게 처리합니다; OpenSpec 거절 제안: 의사결정 기억 관행은另一半 — 에이전트가 동일한 아이디어를 다시 제안하기 전에 확인하도록 충분히 지속 가능한 방식으로 거절된 결정을 기록하는 것을 다룹니다.

의사결정 기록은 스펙이 아닙니다

의사결정 기록은 스펙과 관련이 있지만, 다른 목적을 제공합니다. 스펙은 “시스템은 X를 해야 한다"고 말하지만, 의사결정 기록은 “이 제약 사항과 트레이드오프 때문에 Y 대신 X를 선택했습니다"라고 말합니다. 그 “Y 대신"이 가치 있는 부분입니다. AI 도구는 종종 요청된 결과로 가는 그럴듯한 경로를 찾아서 솔루션을 생성하지만, 의사결정 기록은 이미 탐색, 평가, 거절된 그럴듯한 경로가 어떤 것인지를 알려줌으로써 변화를 줄이고 AI 보조 작업의 품질을 향상시킵니다.

의사결정 기록은 테스트의 대체재가 아닙니다

테스트는 행동을 검증하고, 의사결정 기록은 의도를 설명합니다. 둘 다 필요하며 함께 작동합니다. 테스트는 AI 생성 이메일이 초안으로 저장되어야 한다는 것을 강제할 수 있지만, 제품 의사결정 기록은 사용자가 AI 생성 통신이 시스템을 나가기 전에 검토해야 하기 때문에 이것이 요구된다는 것을 설명합니다. 테스트는 행동을 보호합니다. 의사결정 기록은 의미를 보호합니다. 함께, 그들은 미래의 변경을 더 안전하고 예측 가능하게 만듭니다.

의사결정 기록은 코드 주석의 대체재가 아닙니다

코드 주석은 로컬 구현 디테인을 설명하고, 의사결정 기록은 더 넓은 결정을 설명합니다. 놀라운 라인, 엣지 케이스, 워크어라운드, 단순화할 수 없는 함수에 주석을 사용하십시오. 아키텍처가 왜 존재하는지, 제품 동작이 왜 존재하는지, 인터랙션 패턴이 왜 존재하는지, 팀이 왜 한 방향을 다른 방향보다 선택했는지에 대해 의사결정 기록을 사용하십시오. 설명이 몇 줄에만 영향을 미친다면, 주석이 올바른 도구입니다. 시스템의 방향에 영향을 미친다면, 의사결정 기록이 올바른 도구입니다.

일반적인 실수

기록을 너무 늦게 작성하기

의사결정 기록은 결정이 만들어질 때 작성되어야 하며, 모두가 트레이드오프를 잊은 몇 달 후에 작성되면 안 됩니다. 풀 리퀘스트 중 하나를 초안 작성하는 것은 괜찮습니다. 구현 전에, 결정이 여전히 적극적으로 논의되고 대안이 신선할 때 초안을 작성하는 것이 더 좋습니다.

기록을 너무 길게 만들기

의사결정 기록은 에세이가 아닙니다. 판단을 보존할 만큼 상세해야 하지만, 사람들이 실제로 읽을 만큼 짧아야 합니다. 완결성보다 명확성을 선호하십시오 — 읽히는 간결한 기록은 건너뛰어지는 포괄적인 기록보다 훨씬 가치 있습니다.

결과를 무시한 채 결정 기록하기

결과 섹션은 기록의 심장입니다. 명시된 결과가 없는 결정은 종종 진정한 결정이 아니라 단순한 선호입니다. 좋은 기록은 선택 결과로 인해 어려워지거나 위험해지는 것을 포함하여 트레이드오프를 정직하게 인정합니다.

과거가 변경된 것처럼 오래된 기록 편집하기

결정이 변경되면, 새로운 기록을 생성하고 오래된 것을 대체됨으로 표시하십시오. 현재 상태에 맞추기 위해 오래된 결정을 조용히 다시 쓰는 것은 의사결정 기록을 가치 있게 만드는 역사적 컨텍스트를 파괴합니다. 역사가 유용한 것은 정확히 사고가 어떻게 진화했는지를 보여주기 때문입니다. 컴파일된 지식 베이스는 다른 이름으로 동일한 문제를 직면하며 — LLM 위키 유지보수: 표류, 모순 및 리뷰는 그것을 의사결정 표류(decision drift)라고 부르며, 위키 페이지에 덮어쓰기보다 대체하는 같은 규칙을 적용합니다.

리뷰 없이 AI 생성 기록 병합하기

AI는 정교하고 잘 구조화되었지만 미묘하게 틀린 기록을 생성할 수 있습니다. AI 생성 의사결정 기록을 AI 생성 코드와 정확히 같은 방식으로 대우하십시오 — 신중하게 검토하고, 근거가 정확한지 검증하며, 결과 섹션이 팀이 실제로 수용한 것을 반영하는지 확인하십시오.

기록을 저장소 밖에서 숨기기

의사결정 기록이 별도의 위키 또는 문서 시스템에 있으면, 코드 변경과 함께 업데이트될 가능성이 적고, 작업을 위해 컨텍스트를 로드하는 AI 코딩 도구가 읽을 가능성이 훨씬 적습니다. 저장소에 유지하는 것은 단순한 편의가 아닙니다 — 그것은 AI 보조 개발을 위해 관행이 작동하게 만드는 것입니다.

경량 운영 모델

최소한의 오버헤드를 추가하는 실용적인 팀 프로세스는 다음과 같습니다:

  1. 계획 또는 구현 동안, 의미 있는 결정이 이루어지고 있는지 식별합니다.
  2. AI 어시스턴트에게 토론 기반 ADR, PDR, 또는 DDR 초안 작성을 요청합니다.
  3. 팀으로 초안을 검토하여 맥락, 대안, 결과를 검증합니다.
  4. 기록을 저장소에서 Markdown으로 커밋합니다.
  5. 관련 이슈 또는 풀 리퀘스트에서 링크합니다.
  6. 해당 영역에서 미래 변경을 만들기 전에 관련 기록을 읽도록 AI 코딩 도구에 지시합니다.
  7. 결정이 변경되면 기록을 대체하여, 역사를 위해 오래된 기록을 보존합니다.

이것은 새로운 관료제나 전담 문서화 역할을 요구하지 않습니다. 그것은 작은 습관을 요구합니다: 필요할 코드에 가깝게, 만들어지는 순간 중요한 판단을 보존하는 것입니다.

예시 ADR

# 결정: 기본 애플리케이션 스토리지를 위해 PostgreSQL 사용

상태: 수락됨
날짜: 2026-06-25
유형: 아키텍처
소유자: 플랫폼 팀

## 맥락

애플리케이션은 계정, 프로젝트, 권한, 감사 이벤트에 대한 지속 가능한 관계형 스토리지가 필요합니다.
팀은 빈번한 보고 쿼리와 권한 확인을 위한 강력한 일관성 요구 사항을 예상합니다.

## 결정

우리는 기본 애플리케이션 데이터베이스로 PostgreSQL을 사용할 것입니다.

## 고려된 대안

### DynamoDB

장점:
- 운영적으로 확장 가능
- 예측 가능한 키-값 액세스 패턴에 적합

단점:
- 관계형 쿼리에 대해 더 복잡
- 애드 혹(ad hoc) 보고에 더 어려움
- 현재 팀에게 덜 익숙

### MySQL

장점:
- 성숙한 관계형 데이터베이스
- 익숙한 운영 모델

단점:
- PostgreSQL이 JSON 지원, 인덱싱 옵션, 및 기존 전문성의 팀의 요구 사항과 더 잘 맞음

## 결과

PostgreSQL은 핵심 운영 종속성이 됩니다. 팀은 마이그레이션을 신중하게 관리하고
쿼리 성능을 모니터링해야 합니다. 대신, 애플리케이션은 강력한 관계형 모델링,
성숙한 인덱싱, 유연한 보고 지원을 얻습니다.

## AI 가이드

지속성 코드를 수정할 때, PostgreSQL에서의 관계형 모델링을 선호하십시오.
대체 ADR 없이 두 번째 기본 데이터베이스를 도입하지 마십시오.

예시 PDR

# 결정: AI 생성 이메일은 초안으로 유지되어야 함

상태: 수락됨
날짜: 2026-06-25
유형: 제품
소유자: 제품 팀

## 맥락

제품은 AI를 사용하여 이메일 응답을 생성할 수 있습니다. 이메일 전송은 실수가
고객, 파트너, 또는 내부 팀에 도달할 수 있기 때문에 높은 신뢰를 요구하는 작업입니다.

## 결정

AI 생성 이메일은 초안으로 생성되어야 합니다. 인간 사용자가 검토하고
전송해야 합니다.

## 고려된 대안

### 자동 전송

장점:
- 더 빠른 워크플로
- 더 적은 사용자 노력

단점:
- 부정확하거나 부적절한 메시지의 리스크 높음
- 사용자 신뢰도 낮음
- 실수로부터 복구하기 어려움

### 생성 후에만 확인 요청

장점:
- 워크플로를 단순하게 유지
- 일부 사용자 제어 제공

단점:
- 여전히 얕은 리뷰를 장려
- 초안만큼 기존 이메일 클라이언트 동작에 적합하지 않음

## 결과

워크플로는 약간 느리지만, 더 안전하고 더 신뢰할 수 있습니다.
미래의 자동화는 리뷰 속도를 개선할 수 있지만,
대체 PDR 없이 인간 승인을 우회해서는 안 됩니다.

## AI 가이드

이메일 생성 기능을 빌드할 때, 기본적으로 초안을 생성하십시오.
새로운 수락된 PDR이 명시적으로 허용하지 않는 한 자동 전송을 추가하지 마십시오.

예시 DDR

# 결정: 옆 패널에서 AI 작성 제안 표시

상태: 수락됨
날짜: 2026-06-25
유형: 디자인
소유자: 디자인 팀

## 맥종

사용자는 작성된 콘텐츠를 개선하는 도움이 필요하지만, 최종 텍스트의
제어권을 유지해야 합니다. 인라인 AI 편집은 사용자가 쓴 콘텐츠와
생성된 제안을 구별하기 어렵게 만들 수 있습니다.

## 결정

AI 작성 제안 사항은 옆 패널에 나타납니다. 사용자는 제안을
수락, 거절, 또는 메인 에디터에 복사할 수 있습니다.

## 고려된 대안

### 제안을 인라인으로 적용

장점:
- 빠름
- 통합된 느낌

단점:
- 저자ship을 흐리다
- 리뷰를 더 어렵게 만든다
- 사용자를 놀라게 할 수 있다

### 모달에서 제안 표시

장점:
- 집중된 경험
- 구현이 쉬움

단점:
- 작성 플로우를 방해
- 제안과 원본 텍스트 비교가 어려움

## 결과

옆 패널은 특히 작은 화면에서 더 많은 화면 공간을 차지합니다.
그러나, 그것은 사용자 제어를 보존하고 리뷰를 더 명확하게 만듭니다.

## AI 가이드

쓰기 지원 기능을 추가할 때, 사용자 텍스트와 AI 제안 사이의
분리를 보존하십시오. 명시적인 사용자 행동 없이 생성된 텍스트를
문서에 직접 적용하지 마십시오.

권장 프롬프트 라이브러리

의사결정 기록을 일상적인 AI 보조 개발의 일부로 만들기 위해 이 프롬프트를 사용하십시오.

기능 작업 전에 관련 기록 찾기:

docs/decisions를 읽고 이 작업에 적용되는 수락된 의사결정 기록을 식별하십시오.
코드 변경을 제안하기 전에 제약 사항을 요약하십시오.

새로운 ADR 초안 작성:

이 기술적 결정에 대한 아키텍처 의사결정 기록을 작성하십시오.
맥락, 결정, 대안, 결과, 및 AI 가이드를 포함하십시오.
간결하고 구체적으로 유지하십시오.

새로운 PDR 초안 작성:

이 제품 동작에 대한 제품 의사결정 기록을 작성하십시오.
사용자 영향, 범위, 대안, 결과, 및 AI 가이드를 포함하십시오.

새로운 DDR 초안 작성:

이 인터랙션 패턴에 대한 디자인 의사결정 기록을 작성하십시오.
사용자 문제, 대안, 트레이드오프, 결과, 및 AI 가이드를 포함하십시오.

기존 결정과 비교하여 풀 리퀘스트 검토:

docs/decisions의 수락된 의사결정 기록과 이 풀 리퀘스트를 검토하십시오.
충돌, 누락된 의사결정 기록, 또는 대체되어야 할 결정을 식별하십시오.

결정 대체:

기존 것을 대체하는 새로운 의사결정 기록을 생성하십시오.
역사적 근거를 보존하고, 무엇이 변경되었는지 설명하며, 두 기록을 링크하십시오.

관련 자료

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.