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

의도(intent)를 코드와 가깝게 유지하세요.

Page content

의결 기록은 AI 지원 소프트웨어 개발에서 누락된 기억 레이어입니다. 이는 구축된 내용뿐만 아니라 그 이유까지 포착하며, AI 도구가 코드를 작성할 때 이러한 구별이 결정적인 중요성을 갖게 됩니다.

Decision records — ADR, PDR, DDR — connecting intent to code

의결 기록은 누락된 기억 레이어입니다

AI 기반 프로그래밍은 코드를 생성하는 비용을 낮추고, 리팩토링을 쉽게 만들며, 버리는 속도를 빠르게 함으로써 소프트웨어 개발의 경제성을 변화시킵니다. 이는 유용합니다. 그러나 코드가 생성되기 쉬워짐에 따라 희소 자원이 더 이상 타이핑이 아닌 판단력이 되므로 위험하기도 합니다.

팀이 DynamoDB 대신 PostgreSQL을 선택한 이유는 무엇입니까? 제품이 AI가 생성한 이메일을 발송하기 전에 인간의 검토를 요구하는 이유는 무엇입니까? 인터페이스가 제안을 직접 적용하는 대신 사이드 패널에 표시하는 이유는 무엇입니까? 왜 6개월 전에 더 단순한 접근 방식이 거부되었습니까? 코드는 존재하는 것을 보여줄 수 있지만, 그것이 존재하는 이유를 설명하는 경우는 드뭅니다.

의결 기록은 중요한 선택, 그 배경 컨텍스트, 고려된 대안, 그리고 팀이 수용한 결과를 포착하는 짧고 버전 관리되는 문서를 제공하여 이 문제를 해결합니다. AI 지원 코드베이스에서 이러한 기록은 단순한 문서를 넘어, 향후 변경 사항을 수행하기 전에 인간과 AI 코딩 에이전트가 모두 읽을 수 있는 내구성 있는 프로젝트 기억이 됩니다. 실용적인 운영 규칙은 간단합니다: 의결 기록을 리포지토리의 마크다운 파일로 유지하고, 코드처럼 검토하며, 향후 AI 도구가 변경 사항을 제안하거나 구현하기 전에 이를 읽도록 합니다.

의결 기록이란 무엇입니까?

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

AI 기반 프로그래밍에는 다음 세 가지 유형이 특히 유용합니다:

기록 유형 포착 대상 예시
ADR 아키텍처 및 기술적 결정 PostgreSQL을 주요 데이터베이스로 사용
PDR 제품 동작 및 범위 결정 AI 생성 이메일은 초안 상태로 유지해야 함
DDR 디자인 및 상호작용 결정 AI 제안을 사이드 패널에 표시

ADR, PDR, DDR을 함께 사용하면 시스템의 구조뿐만 아니라 제품의 의도와 사용자 경험 뒤의 추론까지 설명할 수 있습니다. 이 조합은 중요합니다. AI 에이전트는 코드를 읽을 수 있지만, 코드 자체로는 좋은 결정을 내릴 충분한 컨텍스트가 포함되어 있지 않기 때문입니다. 의결 기록은 AI 시스템에 검토되고, 내구성 있으며, 인간이 승인한 프로젝트 의도의 출처를 제공합니다.

아키텍처 결정 기록(ADR)

아키텍처 결정 기록은 기술적이고 구조적인 결정을 포착합니다. 결정이 시스템의 형태(경계, 종속성, 운영 모델 또는 장기적인 유지 관리성)에 영향을 미치는 경우 ADR을 사용하십시오.

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

  • 주요 데이터베이스로 PostgreSQL 선택
  • 백그라운드 처리를 위해 이벤트 기반 아키텍처 사용
  • 애플리케이션을 모듈식 단일체(Monolith)로 유지
  • 메시지 큐 도입
  • GraphQL 대신 REST 선택
  • 웹 애플리케이션을 위해 서버 사이드 렌더링 사용
  • 모든 백그라운드 작업이 멱등성(Idempotent)을 갖도록 요구
  • 특정 인증 및 권한 부여 모델 채택

ADR은 전체 아키텍처 문서가 아닙니다. 이는 의도적으로 작으며, 특정 시점의 중요한 하나의 결정을 기록합니다. 좋은 ADR은 아키텍처 기억상실증을 예방합니다. ADR이 없으면 향후 기여자들은 동일한 트레이드오프를 다시 발견하거나, 오래된 논쟁을 재개하거나, 중요한 제약 조건을 우연히 해제할 수 있습니다.

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

제품 결정 기록(PDR)

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

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

  • AI 생성 메시지는 인간이 검토할 때까지 초안 상태로 유지되어야 함
  • 무료 티어 사용자는 최대 세 개의 프로젝트를 생성할 수 있음
  • 삭제된 워크스페이스는 30일 동안 복구 가능
  • 팀 청구는 버전 1에서 범위 제외
  • 사용자는 지원에 연락하지 않고 데이터를 내보낼 수 있음
  • 낮은 신뢰도의 AI 요약은 숨기는 대신 경고를 표시

PDR은 제품이 코드에서 의도적이지 않게 보이는 선택일 때 특히 유용합니다. 코드에는 무료 사용자를 위한 프로젝트 제한이 세 개로 설정되어 있을 수 있으며, PDR이 없으면 AI 도구는 해당 숫자를 마법 상수(magic constant)로 간주하여 변경을 제안할 수 있습니다. PDR이 있으면 AI는 해당 제한이 가격 전략, 온보딩 비용 또는 지원 부하와 연관되어 있으며, 이를 변경하려면 신속한 편집이 아닌 의도적인 제품 결정이 필요하다는 것을 알 수 있습니다.

디자인 결정 기록(DDR)

디자인 결정 기록은 사용자 경험, 상호작용, 시각적, 콘텐츠 디자인 결정을 포착합니다. 결정이 사용자와 제품의 상호작용, 정보 제시 방식, 또는 향후 작업 전반에 디자인 원칙 적용 방식에 영향을 미치는 경우 DDR을 사용하십시오.

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

  • 제출 시에만 검증하는 대신 인라인 검증 사용
  • 에디터 내부가 아닌 사이드 패널에 AI 제안 배치
  • 고급 설정을 위해 점진적 공개(Progressive Disclosure) 사용
  • 파괴적 작업 전에 확인 요구
  • “비활성” 및 “활성” 대신 “초안” 및 “게시됨” 사용
  • 모바일 화면에서 주요 작업 가시성 유지

디자인 의도는 구현 중에 쉽게 손실됩니다. 개발자가 흐름을 단순화하거나, AI 에이전트가 기술적으로 작동하지만 의도된 상호작용 모델을 깨는 컴포넌트를 생성할 수 있습니다. 예를 들어, DDR은 다음과 같이 기록할 수 있습니다: “사용자가 변경 사항을 수락하기 전에 생성된 텍스트와 자신의 초안을 비교해야 하므로, AI 작성 제안은 문서 내부가 아닌 옆에 표시합니다.” 이 기록은 단순히 복사할 레이아웃이 아닌, 보존해야 할 원칙을 향후 기여자에게 제공합니다.

AI와 함께 의결 기록이 더 중요한 이유

AI 코딩 도구는 강력하지만, 종종 상태(stateless)이거나 프로젝트 역사에 부분적으로만 인지합니다. 도구는 파일을 검사하고, 패턴을 추론하며, 변경 사항을 생성할 수 있지만, 어떤 결정이 의도적인지, 우연한지, 이미 논쟁되어 해결되었는지 자동으로 알지 못합니다. 이는 여러 가지 뚜렷한 위험을 초래합니다.

AI는 해결된 논쟁을 재개할 수 있습니다

팀이 이미 모듈식 단일체를 사용하기로 결정했다면, AI 에이전트는 고립되어 볼 때 깔끔해 보이기 때문에 서비스를 추출하는 것을 제안할 수 있습니다. ADR이 없으면 AI는 팀이 이미 해당 경로를 고려하고 거부했다는 내구성 있는 방법을 알지 못하며, 그 결과 낭비된 노력이나 시스템 일관성의 미묘한 회귀가 발생합니다.

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

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

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

모델은 코드베이스의 기존 패턴을 따를 수 있지만, 패턴은 원칙과 동일하지 않습니다. 기존 코드는 때때로 타협입니다. 때때로 과도기적입니다. 때때로 파일에서 보이지 않는 외부 제약 조건으로 인해 존재합니다. 의결 기록은 “이것이 작동하는 방식"과 “이렇게 구축된 이유” 사이의 차이를 설명합니다.

AI는 합리적이지만 잘못된 근거를 생성할 수 있습니다

AI는 의결 기록을 작성할 수 있지만, 실제 결정과 일치하지 않는 자신감 있는 설명을 발명할 수도 있습니다. 이것이 인간 검토가 비협상적인 이유입니다: AI는 기록의 초안을 생성할 수 있지만, 기록이 병합되기 전에 인간은 기록이 실제 결정, 대안, 결과를 정확하게 설명하는지 확인해야 합니다.

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

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

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

flowchart LR A[Prompt] --> B[Generate code] B --> C[Test] C --> D[Commit]

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

flowchart TB subgraph top[" "] direction LR A[Frame the problem] --> B[Identify existing decisions] --> C[Explore options and tradeoffs] --> D[Record the selected decision] end subgraph bottom[" "] direction LR E[Generate or modify code] --> F[Review code vs decisions] --> G[Merge implementation and memory] --> H[Use record to guide future work] end D --> E

이 프로세스는 리포지토리를 단순한 코드 저장소보다 더 많은 것으로 만듭니다. 이는 구현, 의도, 추론의 진실의 원천이 되며, 매번 결정이 내려질 때마다 가치가 누적되는 내구성 있는 아티팩트가 됩니다.

의결 기록과 코드형 문서(Docs as Code)

의결 기록은 코드형 문서 원칙을 따를 때 가장 잘 작동하며, 이는 코드와 동일한 리포지토리에 저장되고, 일반 마크다운으로 작성되고, 풀 리퀘스트에서 검토되며, 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 가이드 섹션을 포함하는 실용적인 마크다운 템플릿입니다:

# Decision: Short title

Status: Proposed | Accepted | Superseded | Deprecated
Date: YYYY-MM-DD
Type: Architecture | Product | Design
Owners: Team or names

## Context

Describe the problem, constraints, goals, user needs, technical facts,
and business factors that led to this decision.

## Decision

State the decision clearly.

## Alternatives considered

### Option 1

Pros:
- ...

Cons:
- ...

## Consequences

Describe what becomes easier, what becomes harder, and what risks
or follow-up work this creates.

## AI guidance

When an AI assistant works in this area, it should:
- Preserve ...
- Avoid ...
- Prefer ...
- Ask for review when ...

## Links

- Related issues:
- Related pull requests:
- Related files:
- Supersedes:
- Superseded by:

“AI 가이드” 섹션은 선택적이지만, AI 기반 프로그래밍에서는 매우 가치 있습니다 — 이는 의결 기록을 코드베이스의 동일한 영역에서 작업하는 향후 에이전트를 위한 내구성 있는 지시로 변환합니다.

의결 기록에 무엇이 포함되어야 합니까?

모든 선택이 기록을 받을 자격이 있는 것은 아니며, 모든 작은 구현 세부 사항이 의결 기록이 되면 프로세스는 노이즈로 붕괴됩니다. 선택이 의미 있고 나중에 중요할 것으로 예상될 때 의결 기록을 생성하십시오.

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

  • 시스템의 여러 부분에 영향을 미치는
  • 제품 약속을 인코딩하는
  • 실제 논쟁을 해결하는
  • 장기적인 트레이드오프를 도입하는
  • 비즈니스, 규정 준수 또는 운영 제약 조건에 의존하는
  • 나중에 다시 발견하는 데 비용이 많이 드는
  • 향후 AI 도구가 합리적으로 잘못 이해할 수 있는
  • 향후 기여자가 부주의하게 역전하고 싶어할 수 있는

나쁜 후보에는 작은 리팩토링 선택, 명백한 버그 수정, 임시 실험, 로컬 네이밍 결정, 지속적인 결과가 없는 구현 세부 사항이 포함됩니다. 좋은 경험 법칙은 간단합니다: 결정을 역전하는 것이 논의가 필요하다면, 그 결정을 기록하십시오.

상태 값과 라이프사이클

의결 기록은 현재 지위를 나타내기 위해 라이프사이클이 있어야 합니다. 가장 간단한 상태 값이 충분합니다.

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

Accepted(승인됨) — 결정이 활성화되어 향후 작업을 안내해야 합니다. 가장 유용한 의결 기록은 대부분의 생애를 이 상태에 보낼 것입니다.

Superseded(대체됨) — 결정이 더 새로운 기록으로 대체되었습니다. 오래된 기록을 삭제하지 마십시오; 역사적 기록으로 유지하고 더 새로운 결정으로 연결하여 사고의 진화가 가시적으로 유지되도록 합니다.

Deprecated(비권장됨) — 결정이 더 이상 권장되지 않지만 시스템의 기존 부분을 여전히 설명할 수 있습니다. 이는 코드베이스에 새로운 접근 방식과 함께 오래된 패턴이 존재하는 마이그레이션 중 특히 유용합니다.

중요한 원칙은 의결 기록이 부가(Append) 친화적이어야 한다는 것입니다. 팀이 방향을 변경할 때, 과거를 더 깔끔하게 보이게 만들기 위해 역사를 다시 작성하는 대신 새 기록을 생성하고 오래된 기록과 연결하십시오.

AI가 의결 기록을 생성하는 방법

AI는 의결 기록 생성을 돕을 수 있으며, 이는 소프트웨어 개발에서 AI의 더 나은 사용 중 하나입니다 — 컨텍스트에서 구조화된 문서를 신속하게 작성하는 데 뛰어납니다. 논의, 아키텍처 검토, 또는 풀 리퀘스트 후에 AI 어시스턴트에게 기록을 작성하도록 요청할 수 있습니다:

Draft an Architecture Decision Record for the decision in this pull request.
Include context, alternatives, consequences, and AI guidance.
Save it as Markdown under docs/decisions/architecture.

제품 작업의 경우:

Draft a Product Decision Record explaining why AI-generated messages
must remain drafts until reviewed by the user.
Include user impact, out-of-scope behavior, tradeoffs, and AI guidance.

그러나 AI가 생성한 기록은 자동으로 신뢰해서는 안 됩니다. 인간 검토는 컨텍스트가 정확한지, AI가 근거를 발명하지 않았는지, 나열된 대안이 실제인지, 결과가 정직한지, AI 가이드가 팀의 실제 의도와 일치하는지 확인해야 합니다. AI는 작성 보조 도구입니다 — 결정의 소유자가 아닙니다.

AI가 의결 기록을 읽는 방법

실습의 다른 절반은 행동하기 전에 기록을 읽도록 AI에 지시하는 것입니다. AI 어시스턴트에게 변경 사항을 구현하도록 요청하기 전에 다음과 같은 지시를 포함하십시오:

Before modifying this feature, read docs/decisions.
Identify any Architecture, Product, or Design Decision Records that apply.
Follow accepted decisions. If your proposed change conflicts with a decision
record, explain the conflict before changing code.

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

Use the decision records as project memory.
Do not reverse accepted decisions without proposing a new superseding decision.
When you generate code, explain which decision records influenced the implementation.

이는 AI의 역할을 “합리적인 코드 예측"에서 “문서화된 제약 조건 시스템 내부에서 작동"으로 변경하며 — 복잡하거나 장기간의 프로젝트에 대한 신뢰성에서 상당한 개선입니다.

풀 리퀘스트에서의 의결 기록

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

## Decision record checklist

- [ ] This PR does not introduce a significant architecture, product, or design decision.
- [ ] This PR introduces a significant decision and includes a new decision record.
- [ ] This PR changes a previous decision and includes a superseding record.
- [ ] Relevant existing decision records were considered.
- [ ] AI-generated code follows the accepted decision records.
- [ ] AI-generated decision records were reviewed by a human.

이 체크리스트는 간단하지만, 풀 리퀘스트에서 중요한 아티팩트가 코드만이 아님을 팀에게 상기시킴으로써 행동을 변경합니다. 또한 AI가 생성된 변경 사항이 이전 결정을 침묵으로 위반하는 것을 자연스럽게 포착할 수 있습니다.

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

전통적인 아키텍처 거버넌스는 종종 너무 무겁고, 너무 느리며, 구현과 너무 단절되어 있어 실패합니다 — 중앙 승인 위원회, 대규모 사전 문서화, 차단하는 문지기 프로세스는 안내하지 않습니다. 의결 기록은 개발 워크플로우에 직접 통합되는 더 가벼운 대안을 제공합니다.

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

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

의결 기록과 제품 관리

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

제품 결정 기록은 이 격차를 메우며, 가격 및 패키징 결정, 권한 모델, 제한 및 할당량, AI 안전 및 검토 흐름, 온보딩 선택, 사용자 역할 정의, 협업 규칙, 데이터 보유 정책, 기능 범위 경계에서 특히 유용합니다. 일단 구현되면, 제품 결정은 코드에서 보이지 않게 됩니다 — 나중에 누군가는 코드만 보고 “왜 이렇게 작동합니까?“라고 묻습니다. PDR은 인간과 AI 도구 모두 찾고 사용할 수 있는 형태로 답을 제공합니다.

의결 기록과 디자인 시스템

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

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

의결 기록이 사양 기반 개발을 지원하는 방법

사양 기반 개발은 시스템이 무엇을 해야 하는지 설명합니다. 의결 기록은 팀이 왜 그 방향을 선택했는지 설명하며, 이 구별은 AI 지원 작업에서 상당히 중요합니다.

기능 사양은 AI 생성 이메일이 초안으로 저장되어야 한다고 말할 수 있습니다. 제품 결정 기록은 자동 발송이 거부된 이유, 고려된 위험, 그리고 어떤 향후 변경이 새로운 결정을 필요로 하는지 설명합니다. 디자인 사양은 사이드 패널 상호작용을 설명할 수 있지만, 해당 DDR은 인라인 AI 편집이 명시적으로 거부된 이유와 사용자 제어를 보존하는 것이 워크플로우 속도보다 더 중요하게 가중된 이유를 설명합니다. 아키텍처 사양은 서비스 경계를 정의할 수 있으며, 그 ADR은 팀이 더 단순하거나 더 분산된 대안 대신 왜 그 경계를 선택했는지 설명합니다.

사양은 구현을 안내합니다. 의결 기록은 판단력을 보존합니다. 함께 사용하면, AI 코딩 에이전트에게 지시와 컨텍스트 — “무엇"과 “왜” — 를 제공하며, 이는 복잡하고 장기간의 시스템에서 이 조합을 그렇게 효과롭게 만듭니다. 사양 기반 툴체인을 채택할 때, 각 옵션이 그 컨텍스트를 어떻게 표면화하는지 비교하십시오; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows는 주요 설정 전반의 이식성, 검토 게이트, 리포지토리 기반을 분해합니다. 이러한 도구가 구현하는 도구 중립적 5단계 프로세스에 대해서는 사양 기반 개발 워크플로우: 요구 사항에서 코드로를 참조하십시오.

의결 기록은 사양이 아닙니다

의결 기록은 사양과 관련이 있지만 다른 목적을 제공합니다. 사양은 “시스템은 X를 수행해야 한다"고 말하고, 의결 기록은 “우리는 이러한 제약 조건과 트레이드오프 때문에 Y 대신 X를 선택했다"고 말합니다. 그 “Y 대신” 부분이 가치 있는 부분입니다. AI 도구는 종종 요청된 결과에 대한 합리적인 경로를 찾아 솔루션을 생성하지만, 의결 기록은 이미 탐색, 평가, 거부된 합리적인 경로를告诉他们 — 전환을 줄이고 AI 지원 작업의 품질을 향상시킵니다.

의결 기록은 테스트의 대체물이 아닙니다

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

의결 기록은 코드 주석의 대체물이 아닙니다

코드 주석은 로컬 구현 세부 사항을 설명하고, 의결 기록은 더 넓은 결정을 설명합니다. 놀라운 줄, 경계 사례, 우회 방법, 단순화할 수 없는 함수에 대해 주석을 사용하십시오. 아키텍처가 존재하는 이유, 제품 동작이 존재하는 이유, 상호작용 패턴이 존재하는 이유, 팀이 다른 방향 대신 하나의 방향을 선택한 이유에 대해 의결 기록을 사용하십시오. 설명이 몇 줄에만 영향을 미친다면, 주석이 올바른 도구입니다. 시스템의 방향에 영향을 미친다면, 의결 기록이 올바른 도구입니다.

일반적인 실수

기록을 너무 늦게 작성하기

의결 기록은 결정이 내려졌을 때 작성되어야 하며, 모든 사람이 트레이드오프를 잊은 몇 달 후가 아닙니다. 풀 리퀘스트 중에 초안을 작성하는 것은 괜찮습니다. 구현 전에, 결정이 아직 적극적으로 논의되고 대안이 신선할 때 초안을 작성하는 것이 더 좋습니다.

기록을 너무 길게 만들기

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

결과 없이 결정 기록하기

결과 섹션은 기록의 핵심입니다. 명시된 결과가 없는 결정은 종종 실제 결정이 아닌 선호도에 불과합니다. 좋은 기록은 선택의 결과로 더 어려워지거나 위험해지는 것을 정직하게 인정합니다.

역사가 변경된 것처럼 오래된 기록 편집하기

결정이 변경되면, 새 기록을 생성하고 오래된 기록을 대체됨으로 표시하십시오. 현재 상태와 일치하도록 오래된 결정을 침묵으로 다시 작성하면 의결 기록을 가치 있게 만드는 역사적 컨텍스트가 파괴됩니다. 역사는 사고가 어떻게 진화했는지 보여주기 때문에 유용합니다. 컴파일된 지식 베이스는 다른 이름으로 동일한 문제에 직면합니다 — LLM 위키 유지 관리: 드리프트, 모순 및 검토는 이를 결정 드리프트라고 부르고, 위키 페이지에 동일한 대체-보다-덮어쓰기 규칙을 적용합니다.

검토 없이 AI 생성 기록 병합하기

AI는 세련되고 잘 구조화되었지만 미묘하게 잘못된 기록을 생성할 수 있습니다. AI 생성 의결 기록을 AI 생성 코드처럼 정확히 취급하십시오 — 주의深く 검토하고, 근거가 정확한지 확인하며, 결과 섹션이 팀이 실제로 수용한 것을 반영하는지 보장하십시오.

리포지토리 외부에 기록 숨기기

의결 기록이 별도의 위키 또는 문서 시스템에 존재하면, 코드 변경과 함께 업데이트될 가능성이 낮아지고 작업 컨텍스트를 로드하는 AI 코딩 도구에 의해 읽힐 가능성이 훨씬 낮아집니다. 리포지토리에 유지하는 것은 단순한 편의가 아닙니다 — 이는 AI 지원 개발에서 이 실습이 작동하게 만드는 것입니다.

경량 운영 모델

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

  1. 계획 또는 구현 중에 의미 있는 결정이 내려지고 있는지 식별합니다.
  2. 논의에 기반하여 ADR, PDR, DDR 초안을 작성하도록 AI 어시스턴트에게 요청합니다.
  3. 팀으로 초안을 검토하여 컨텍스트, 대안, 결과를 검증합니다.
  4. 기록을 리포지토리의 마크다운으로 커밋합니다.
  5. 관련 이슈 또는 풀 리퀘스트에서 이를 연결합니다.
  6. 해당 영역에서 향후 변경을 수행하기 전에 관련 기록을 읽도록 AI 코딩 도구에게 지시합니다.
  7. 결정이 변경되면 기록을 대체하여 오래된 기록을 역사로 보존합니다.

이는 새로운 관료제나 전용 문서화 역할이 필요하지 않습니다. 이는 작은 습관이 필요합니다: 생성되는 순간에 중요한 판단력을 코드가 필요한 곳 근처에 보존하는 것입니다.

ADR 예시

# Decision: Use PostgreSQL for primary application storage

Status: Accepted
Date: 2026-06-25
Type: Architecture
Owners: Platform team

## Context

The application needs durable relational storage for accounts, projects,
permissions, and audit events. The team expects frequent reporting queries
and strong consistency requirements for permission checks.

## Decision

We will use PostgreSQL as the primary application database.

## Alternatives considered

### DynamoDB

Pros:
- Operationally scalable
- Good fit for predictable key-value access patterns

Cons:
- More complex for relational queries
- Harder for ad hoc reporting
- Less familiar to the current team

### MySQL

Pros:
- Mature relational database
- Familiar operational model

Cons:
- PostgreSQL better matches the team's needs for JSON support,
  indexing options, and existing expertise

## Consequences

PostgreSQL becomes a core operational dependency. The team must manage
migrations carefully and monitor query performance. In return, the
application gets strong relational modeling, mature indexing, and
flexible reporting support.

## AI guidance

When modifying persistence code, prefer relational modeling in PostgreSQL.
Do not introduce a second primary database without a superseding ADR.

PDR 예시

# Decision: AI-generated emails must remain drafts

Status: Accepted
Date: 2026-06-25
Type: Product
Owners: Product team

## Context

The product can generate email replies using AI. Sending email is a
high-trust action because mistakes may reach customers, partners, or
internal teams.

## Decision

AI-generated emails must be created as drafts. A human user must
review and send them.

## Alternatives considered

### Send automatically

Pros:
- Faster workflow
- Less user effort

Cons:
- Higher risk of incorrect or inappropriate messages
- Lower user trust
- Harder to recover from mistakes

### Ask for confirmation only after generation

Pros:
- Keeps the workflow simple
- Provides some user control

Cons:
- Still encourages shallow review
- Does not fit existing email client behavior as well as drafts

## Consequences

The workflow is slightly slower, but safer and more trustworthy.
Future automation can improve review speed, but must not bypass
human approval without a superseding PDR.

## AI guidance

When building email-generation features, create drafts by default.
Do not add automatic sending unless a new accepted PDR explicitly allows it.

DDR 예시

# Decision: Show AI writing suggestions in a side panel

Status: Accepted
Date: 2026-06-25
Type: Design
Owners: Design team

## Context

Users need help improving written content, but they also need to stay
in control of the final text. Inline AI edits can make it hard to
distinguish user-written content from generated suggestions.

## Decision

AI writing suggestions will appear in a side panel. Users can accept,
reject, or copy suggestions into the main editor.

## Alternatives considered

### Apply suggestions inline

Pros:
- Fast
- Feels integrated

Cons:
- Blurs authorship
- Makes review harder
- Can surprise users

### Show suggestions in a modal

Pros:
- Focused experience
- Easy to implement

Cons:
- Interrupts writing flow
- Harder to compare suggestion and original text

## Consequences

The side panel takes more screen space, especially on small screens.
However, it preserves user control and makes review clearer.

## AI guidance

When adding writing-assistance features, preserve separation between
user text and AI suggestions. Do not apply generated text directly
into the document without explicit user action.

제안된 프롬프트 라이브러리

이 프롬프트를 사용하여 의결 기록을 일상적인 AI 지원 개발의 일부로 만듭니다.

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

Read docs/decisions and identify any accepted decision records that apply
to this task. Summarize the constraints before proposing code changes.

새 ADR 초안 작성:

Draft an Architecture Decision Record for this technical decision.
Include context, decision, alternatives, consequences, and AI guidance.
Keep it concise and specific.

새 PDR 초안 작성:

Draft a Product Decision Record for this product behavior.
Include user impact, scope, alternatives, consequences, and AI guidance.

새 DDR 초안 작성:

Draft a Design Decision Record for this interaction pattern.
Include user problem, alternatives, tradeoffs, consequences, and AI guidance.

기존 결정에 대해 풀 리퀘스트 검토:

Review this pull request against the accepted decision records in docs/decisions.
Identify any conflicts, missing decision records, or decisions that should
be superseded.

결정 대체:

Create a new decision record that supersedes the existing one.
Preserve the historical rationale, explain what changed, and link both records.

관련 읽기

구독하기

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