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로 기록할 가치가 있는 결정의 예는 다음과 같습니다.

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

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

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

제품 결정 기록

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

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

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

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

디자인 결정 기록

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

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

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

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

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

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

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]

이 사이클은 진지한 시스템 작업에는 너무 얇습니다. 더 강력한 워크플로우는 리포지토리를 코드와 의도의 저장소로 취급합니다. 여기의 다이어그램은 Markdown 결정 기록 내부에서도 잘 작동하는 경량 형식인 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

이 프로세스는 리포지토리를 단순한 코드 저장소 이상으로 만듭니다. 구현, 의도, 추론의 진실의 원천이 되며, 각 결정마다 가치가 축적되는 내구성 있는 아티팩트가 됩니다.

결정 기록과 코드로서의 문서

결정 기록은 코드로서의 문서 원칙을 따를 때 가장 잘 작동하며, 이는 코드와 동일한 리포지토리에 저장되고, 평문 마크다운으로 작성되며, 풀 리퀘스트에서 검토되고, Git로 버전 관리되며, 관련 이슈 및 풀 리퀘스트와 연결되고, 인간과 AI 도구 모두에서 검색 가능해야 함을 의미합니다. 이는 중요한 결정을 채팅, 위키 페이지, 슬라이드 덱, 회의록에 저장하는 것보다 훨씬 더 신뢰할 수 있습니다. 이러한 도구는 여전히 논의에 유용할 수 있지만, 수락된 결정은 항상 코드 근처에 존재해야 합니다.

잘 조직된 결정 기록의 리포지토리 구조는 다음과 같을 수 있습니다.

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) — 결정은 더 이상 권장되지 않지만 시스템의 기존 부분을 설명할 수 있습니다. 이는 코드베이스에 새로운 접근 방식과 함께 오래된 패턴이 존재하는 마이그레이션 동안 특히 유용합니다.

중요한 원칙은 결정 기록이 추가 친화적이어야 한다는 것입니다. 팀이 방향을 변경할 때, 역사를 더 깔끔하게 보이도록 재작성하기보다 새 기록을 만들고 이전 기록을 연결하십시오.

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

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 코딩 에이전트에게 지침과 컨텍스트 — “무엇"과 “왜” — 를 제공하며, 이것이 복잡하고 장기적인 시스템에 있어 이 조합을 매우 효과적으로 만드는 이유입니다.

결정 기록은 명세가 아닙니다

결정 기록은 명세와 관련되지만, 다른 목적을 수행합니다. 명세는 “시스템은 X를 수행해야 한다"고 말하지만, 결정 기록은 “우리는 이러한 제약과 트레이드오프 때문에 Y 대신 X를 선택했다"고 말합니다. 그 “Y 대신” 부분이 가치 있는 부분입니다. AI 도구는 종종 요청된 결과에 대한 타당한 경로를 찾아서 솔루션을 생성하지만, 결정 기록은 어떤 타당한 경로가 이미 탐색, 평가, 거부되었는지 알려줍니다. 이는 변경을 줄이고 AI 보조 작업의 품질을 향상시킵니다.

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

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

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

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

일반적인 실수

기록을 너무 늦게 작성

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

기록을 너무 길게 만들기

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

결과 없이 결정 기록

결과 섹션은 기록의 핵심입니다. 명시된 결과가 없는 결정은 종종 진정한 결정이 아니라 단순한 선호일 뿐입니다. 좋은 기록은 선택의 결과로 무엇이 더 어려워지거나 위험해지는지를 정직하게 인정합니다.

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

결정이 변경되면 새 기록을 만들고 이전 기록을 대체됨으로 표시하십시오. 현재 상태에 맞게 오래된 결정을 침묵으로 재작성하면 결정 기록을 가치 있게 만드는 역사적 컨텍스트가 파괴됩니다. 역사는 사고가 어떻게 진화했는지 보여주기 때문에 유용합니다.

검토 없이 AI가 생성한 기록 병합

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

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

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

경량 운영 모델

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

  1. 계획 또는 구현 중에 의미 있는 결정이 이루어지고 있는지 식별합니다.
  2. 논의에 기반하여 AI 어시스턴트에게 ADR, PDR 또는 DDR 초안을 작성하도록 요청합니다.
  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 엔지니어링에 관한 새 글을 받아보세요.