Software Engineering Guide
12.3

View in English

12.3 템플릿

이 템플릿은 복사해 붙일 수 있는 출발점입니다. 어느 템플릿이든 위키, 저장소, 티켓 시스템에 옮기고 대괄호 안의 자리 표시자를 채우십시오. 이탤릭체 메모와 인라인 주석은 각 절에 무엇이 들어가야 하는지 설명하며, 절을 채운 뒤 삭제하십시오. 템플릿은 가볍게 유지하십시오. 완성하는 것보다 건너뛰는 것이 빠른 템플릿은 쓰이지 않을 것입니다. 조직에 맞게 제목과 절을 조정하되 각 부분의 의도는 보존하십시오.

아래에서 쓰는 몇 가지 관례:

  • [대괄호] 안의 텍스트는 바꿔야 할 자리 표시자입니다.
  • 이탤릭체 또는 <!-- 주석 --> 안의 텍스트는 삭제할 안내입니다.
  • 완성된 문서는 질문에 답하면서 가능한 한 짧게 유지하십시오.

아키텍처 결정 기록 (ADR)

# ADR [NNNN]: [결정의 짧은 제목]

- 상태: [제안됨 | 수락됨 | 폐기됨 | ADR-XXXX로 대체됨]
- 날짜: [YYYY-MM-DD]
- 결정자: [이름 또는 역할]
- 자문: [이름 또는 역할]

## 맥락

<!-- 이 결정을 이끄는 문제, 힘, 제약은 무엇인가?
     사실과 요구 사항을 중립적으로 진술한다. 미래의 독자가 결정이
     왜 필요했는지 이해하는 데 필요한 것만 포함한다. -->

## 결정

<!-- 선택을 한두 개의 분명한 문장으로 진술한다. "우리는 ...할 것이다" -->

## 검토한 대안

<!-- 저울질한 현실적 선택지와 각각이 왜 선택되었거나 선택되지 않았는지
     나열한다. 여기에는 적어도 두 개의 대안이 나타나야 한다. -->

- 선택지 A: [요약]. [이유]로 기각됨.
- 선택지 B: [요약]. [이유]로 기각됨.
- 선택한 선택지: [요약]. [이유]로 선택됨.

## 결과

<!-- 결정의 좋고 나쁜 정직한 결과. -->

- 긍정적: [얻은 이점]
- 부정적: [수용한 비용, 위험, 한계]
- 후속: [이 결정이 촉발하는 이전, 새 작업, 결정]

## 관련 문서

<!-- 관련된 이전 ADR, RFC, 티켓, 문서 링크. -->

RFC / 설계 문서

# RFC: [제목]

- 작성자: [이름]
- 상태: [초안 | 리뷰 중 | 승인됨 | 거절됨 | 구현됨]
- 리뷰어: [이름 또는 역할]
- 작성일: [YYYY-MM-DD]
- 최종 갱신: [YYYY-MM-DD]
- 티켓 / 추적: [링크]

## 요약

<!-- 한 문단: 무엇을 제안하며 왜 중요한가. 독자는 이 절만으로
     본질을 파악할 수 있어야 한다. -->

## 문제와 동기

<!-- 어떤 문제를 풀고 있는가? 누가 영향을 받는가? 아무것도 하지 않으면
     어떻게 되는가? 관련 배경과 제약을 포함한다. -->

## 목표와 비목표

- 목표: [가능하면 측정 가능한 성공의 모습]
- 비목표: [범위 확대를 막기 위해 명시적으로 범위 밖인 것]

## 제안하는 설계

<!-- 문서의 핵심. 접근, 아키텍처, 데이터 모델, 인터페이스, 핵심 흐름을
     기술한다. 도움이 되는 곳에는 다이어그램을 쓴다. 그것이 무엇인지만이
     아니라 어떻게 동작하는지 설명한다. -->

## 검토한 대안

<!-- 다른 접근과 그것이 왜 선택되지 않았는지. 독자에게 설계 공간이
     탐색되었음을 보여 준다. -->

## 영향과 위험

- 보안과 프라이버시: [함의와 완화]
- 성능과 규모: [기대 부하와 행동]
- 운영 가능성: [모니터링, 실패 모드, 롤아웃, 롤백]
- 비용: [인프라나 라이선스 영향]
- 하위 호환성: [이전과 폐기]

## 테스트 및 롤아웃 계획

<!-- 변경을 어떻게 검증하고 안전하게 릴리스할 것인가. -->

## 열린 질문

<!-- 리뷰어가 의견을 주기를 바라는 미해결 사안. -->

사후 검토 / 인시던트 리뷰 (비난 없음)

# 사후 검토: [인시던트 제목]

- 인시던트 ID: [ID]
- 인시던트 날짜: [YYYY-MM-DD]
- 작성자: [이름]
- 상태: [초안 | 최종]
- 심각도: [SEV1 | SEV2 | SEV3]

> 이 리뷰는 비난이 없습니다. 개인이 아니라 시스템과 기여 요인에
> 초점을 맞춥니다. 목표는 배우고 재발을 막는 것입니다.

## 요약

<!-- 두세 문장: 무슨 일이 있었는지, 영향, 해결을 비전문가도 읽을 수
     있게. -->

## 영향

- 기간: [시작 시각부터 복구 시각까지, 시간대 포함]
- 영향받은 사용자: [범위와 수]
- 비즈니스 영향: [매출, SLA, 평판, 기타]

## 타임라인

<!-- 타임스탬프가 있는 사실적 사건 순서. 탐지, 에스컬레이션, 핵심 행동,
     복구를 포함한다. -->

- [HH:MM] [사건]
- [HH:MM] [사건]

## 기여 요인

<!-- 인시던트로 이어진 조건의 사슬. 단일 근본 원인보다 "기여 요인"을
     선호한다. -->

## 탐지와 대응

- 어떻게 탐지되었나? [알림, 고객 보고 등]
- 대응에 무엇이 도움이 되었나?
- 대응을 무엇이 늦췄나?

## 잘된 것

<!-- 효과적이었던 행동과 작동한 안전장치를 인정한다. -->

## 행동 항목

<!-- 구체적이고, 소유자가 있고, 기한이 있다. 예방, 탐지, 완화를
     다룬다. 일반 백로그에서 추적한다. -->

| 행동 | 소유자 | 기한 | 유형 (예방/탐지/완화) | 티켓 |
|------|--------|------|------------------------|------|
| [행동] | [이름] | [날짜] | [유형] | [링크] |

## 얻은 교훈

<!-- 더 넓은 조직이 가져가야 할 것. -->

위협 모델 (STRIDE 기반)

# 위협 모델: [시스템 또는 기능 이름]

- 작성자: [이름]
- 날짜: [YYYY-MM-DD]
- 리뷰어: [보안 담당자, 소유자]
- 범위: [무엇이 다뤄지고 다뤄지지 않는가]

## 시스템 개요

<!-- 시스템, 그 목적, 사용자에 대한 간략한 설명. -->

## 자산

<!-- 보호할 가치가 있는 것: 데이터, 자격 증명, 기능, 평판.
     각각의 민감도를 적는다. -->

## 신뢰 경계와 데이터 흐름

<!-- 구성 요소, 데이터 저장소, 외부 주체, 신뢰가 바뀌는 경계를
     기술하거나 도식화한다. -->

## 위협 (STRIDE)

<!-- 각 요소에 대해 STRIDE 범주를 고려한다. 믿을 만한 각 위협, 그
     위험, 완화나 수용한 위험을 기록한다. -->

| 위협 | STRIDE 범주 | 영향받는 요소 | 위험 (L/M/H) | 완화 | 상태 |
|------|-------------|---------------|--------------|------|------|
| [위협] | 위장 (Spoofing) | [요소] | [위험] | [통제] | [열림/완화됨/수용됨] |
| [위협] | 변조 (Tampering) | [요소] | [위험] | [통제] | [상태] |
| [위협] | 부인 (Repudiation) | [요소] | [위험] | [통제] | [상태] |
| [위협] | 정보 공개 (Information disclosure) | [요소] | [위험] | [통제] | [상태] |
| [위협] | 서비스 거부 (Denial of service) | [요소] | [위험] | [통제] | [상태] |
| [위협] | 권한 상승 (Elevation of privilege) | [요소] | [위험] | [통제] | [상태] |

## 가정과 의존성

<!-- 의존하는 보안 가정과 신뢰하는 외부 통제. -->

## 열린 문제와 후속

<!-- 더 작업이 필요한 위협, 티켓으로 추적. -->

런북

# 런북: [과업 또는 시나리오 이름]

- 서비스: [서비스 이름]
- 소유자: [팀]
- 마지막 리뷰: [YYYY-MM-DD]
- 관련 알림: [알림 이름]

## 목적

<!-- 이 런북을 언제 쓰며 무엇을 달성하는가. -->

## 전제 조건

<!-- 시작하기 전에 필요한 접근, 도구, 권한. -->

## 탐지 / 증상

<!-- 운영자가 관찰하는 것: 알림, 오류 서명, 대시보드. -->

## 진단

<!-- 문제를 확인하고 원인을 좁히는 단계별 점검. 정확한 명령, 질의,
     대시보드 링크를 포함한다. -->

1. [단계와 기대 결과]
2. [단계와 기대 결과]

## 해결

<!-- 고치거나 완화하는 구체적이고 순서가 있는 단계. 위험하거나 되돌릴 수
     없는 단계와 성공을 검증하는 방법을 적는다. -->

1. [단계]
2. [복구 검증]

## 롤백

<!-- 해결이 상황을 악화시키면 행동을 되돌리는 방법. -->

## 에스컬레이션

<!-- 누구에게 연락하고 언제 에스컬레이션하는가. 2차 온콜, 소유 팀,
     벤더 연락처. -->

## 참고 자료

<!-- 대시보드, 관련 런북, 아키텍처 문서. -->

서비스 README / 서비스 카탈로그 항목

# [서비스 이름]

- 소유 팀: [팀]
- 온콜: [순환 링크]
- 등급 / 중요도: [1등급 | 2등급 | 3등급]
- 저장소: [링크]
- 상태: [활성 | 폐기 예정]

## 하는 일

<!-- 서비스의 책임과 소비자에 대한 한 문단. -->

## 아키텍처

<!-- 핵심 구성 요소, 의존성(상류와 하류), 설계 문서나 다이어그램
     링크. -->

## 인터페이스

- API / 엔드포인트: [명세 링크]
- 발행 / 소비하는 이벤트: [토픽]
- 데이터 저장소: [데이터베이스, 캐시, 버킷]

## 런타임과 배포

- 환경: [개발, 스테이징, 프로덕션]
- 배포 방법: [파이프라인 링크와 프로세스]
- 구성과 기능 플래그: [위치와 방법]

## 관측 가능성

- 대시보드: [링크]
- 알림: [링크]
- 로그: [찾는 곳]
- SLO: [링크]

## 운영

- 런북: [링크]
- 일반 작업: [확장, 재시작, 백필]
- 알려진 문제와 한계: [메모]

## 시작하기 (신규 기여자용)

<!-- 로컬에서 빌드, 테스트, 실행하는 방법. -->

## 연락처

- 슬랙 / 채팅 채널: [링크]
- 에스컬레이션: [경로]

SLO / 오류 예산 정책

# SLO 및 오류 예산 정책: [서비스 또는 여정 이름]

- 소유자: [팀]
- 발효일: [YYYY-MM-DD]
- 리뷰 주기: [예: 분기별]

## 서비스 수준 지표 (SLI)

<!-- 각 SLI를 정확히 정의한다: 측정되는 양, 측정 방법, 측정 위치
     (이상적으로 사용자의 관점). -->

| SLI | 정의 | 데이터 원천 |
|-----|------|-------------|
| 가용성 | [예: 성공한 요청 / 전체 요청] | [원천] |
| 지연 | [예: X ms 미만 요청의 비율] | [원천] |

## 목표 (SLO)

| SLI | 목표 | 측정 윈도 |
|-----|------|-----------|
| 가용성 | [예: 99.9%] | [예: 롤링 28일] |
| 지연 | [예: 95%가 300ms 미만] | [롤링 28일] |

## 오류 예산

<!-- 허용된 비신뢰성: 윈도에 걸친 100%에서 목표를 뺀 것. 예산을
     구체적 용어(예: 월 분)로 진술한다. -->

- 예산: [도출된 허용량]

## 예산이 소진되었을 때의 정책

<!-- 합의된 결과. 구체적이고 시행 가능하게 만든다. -->

- [예: 예산이 회복될 때까지 핵심이 아닌 기능 릴리스를 동결한다.]
- [예: 다음 계획 주기에 신뢰성 작업을 우선한다.]
- [예: 두 윈도 연속 위반하면 엔지니어링 리더십에 에스컬레이션한다.]

## 예산이 건강할 때의 정책

<!-- 팀이 질 수 있는 추가 위험, 예컨대 더 빠른 롤아웃. -->

## 알림

<!-- 이 SLO에 묶인 소진율 알림과 임계값. -->

위험 등록부 항목

## 위험: [짧은 위험 제목]

- 위험 ID: [ID]
- 제기일: [YYYY-MM-DD]
- 소유자: [이 위험을 관리할 책임이 있는 이름 또는 역할]
- 범주: [보안 | 운영 | 컴플라이언스 | 재무 | 전달 | 벤더]
- 상태: [열림 | 완화 중 | 수용됨 | 종결됨]

### 설명

<!-- 위험을 원인 -> 사건 -> 결과로 진술한다. 무슨 일이 일어날 수 있고
     왜 중요한가. -->

### 평가

- 가능성: [낮음 | 중간 | 높음]
- 영향: [낮음 | 중간 | 높음]
- 전체 등급: [가능성 x 영향에서 도출]

### 현재 통제

<!-- 오늘 이 위험을 이미 줄이는 것. -->

### 완화 계획

<!-- 가능성이나 영향을 줄이는 계획된 행동, 소유자와 날짜 포함.
     위험을 수용한다면 누가 왜 수용했는지 기록한다. -->

| 행동 | 소유자 | 기한 | 상태 |
|------|--------|------|------|
| [행동] | [이름] | [날짜] | [상태] |

### 리뷰

- 다음 리뷰 날짜: [YYYY-MM-DD]
- 결정 / 메모: [수용 승인이나 변경]

프로젝트 한 장 요약 / 제품 개요서

# [프로젝트 또는 제품 이름]: 한 장 요약

- 후원자: [이름]
- 리드: [이름]
- 날짜: [YYYY-MM-DD]
- 상태: [아이디어 | 승인됨 | 진행 중 | 출하됨]

## 문제

<!-- 한 문단: 고객이나 비즈니스 문제, 그것이 실제이고 풀 가치가 있다는
     증거. -->

## 대상

<!-- 누가 이 문제를 겪으며 누가 해결로 이익을 얻는가. -->

## 제안하는 솔루션

<!-- 무엇을 만들거나 바꿀 것인지에 대한 짧은 설명. 구현 세부 사항이
     아니라 의도 수준으로 유지한다. -->

## 왜 지금인가

<!-- 나중이 아니라 지금 해야 하는 이유. -->

## 성공 지표

<!-- 효과가 있었음을 어떻게 알 것인가. 측정 가능한 성과를 선호한다. -->

- [지표와 목표]

## 범위

- 범위 안: [우리가 할 것]
- 범위 밖: [우리가 하지 않을 것]

## 위험과 열린 질문

<!-- 주된 불확실성과 의존성. -->

## 대략적 계획과 마일스톤

<!-- 높은 수준의 단계와 대략의 시기. -->

## 비용과 자원

<!-- 필요한 인력, 시간, 예산. -->

온콜 인계 메모

# 온콜 인계: [YYYY-MM-DD]

- 인계하는 사람: [이름]
- 인수하는 사람: [이름]
- 서비스: [이름]

## 전반적 상태

<!-- 한 줄: 조용함, 시끄러움, 또는 진행 중인 문제. -->

## 열린 인시던트

<!-- 다음 대응자가 알아야 할 활성 또는 최근 해결된 인시던트, 링크
     포함. -->

- [인시던트, 상태, 남은 것]

## 진행 중이거나 계획된 변경

<!-- 알림을 일으킬 수 있는 진행 중인 배포, 이전, 유지 보수 창, 실험. -->

## 시끄럽거나 불안정한 알림

<!-- 발동한 알림과 그 실제 의미, 다음 사람이 오도되지 않도록.
     임시 침묵과 그 만료를 적는다. -->

## 주시할 항목

<!-- 우려되는 방향으로 추세인 지표나 시스템. -->

## 대기 중인 후속 조치

<!-- 다음 교대에 넘기는 과업, 티켓 링크 포함. -->

## 메모

<!-- 그 밖에 유용한 것: 접근의 특이점, 벤더 문제, 맥락. -->

변경 요청 (규제 변경 통제용)

# 변경 요청: [변경 제목]

- 변경 ID: [ID]
- 요청자: [이름]
- 제출일: [YYYY-MM-DD]
- 유형: [표준 | 일반 | 긴급]
- 우선순위: [낮음 | 중간 | 높음]
- 상태: [제출됨 | 승인됨 | 거절됨 | 구현됨 | 종결됨]

## 변경 설명

<!-- 무엇이 왜 바뀌는가. 티켓이나 요구 사항을 참조한다. -->

## 영향받는 시스템과 구성 요소

<!-- 영향받는 서비스, 데이터, 환경, 사용자. -->

## 정당화와 비즈니스 영향

<!-- 변경의 이유와 하지 않았을 때의 영향. -->

## 위험 평가

- 위험 수준: [낮음 | 중간 | 높음]
- 변경이 실패했을 때의 잠재 영향: [설명]
- 보안, 프라이버시, 컴플라이언스에 미치는 영향: [설명]

## 구현 계획

<!-- 순서가 있는 단계, 책임 당사자, 시기. -->

## 테스트 및 검증 계획

<!-- 변경 전후에 성공을 어떻게 검증할 것인가. -->

## 철수 / 롤백 계획

<!-- 변경이 실패하면 되돌리는 방법과 복구 시간. -->

## 일정

- 제안하는 창: [시작과 종료, 시간대 포함]
- 예상 다운타임: [기간 또는 없음]

## 승인

| 역할 | 이름 | 결정 | 날짜 |
|------|------|------|------|
| 변경 소유자 | [이름] | [승인/거절] | [날짜] |
| 기술 리뷰어 | [이름] | [승인/거절] | [날짜] |
| 변경 자문 위원회 | [이름] | [승인/거절] | [날짜] |

## 구현 후 리뷰

<!-- 결과, 마주친 문제, 철수가 필요했는지. -->

데이터 보호 영향 평가 (DPIA) 개요

# 데이터 보호 영향 평가: [처리 활동 이름]

- 평가자: [이름]
- 날짜: [YYYY-MM-DD]
- 리뷰어: [DPO / 프라이버시 담당자]
- 상태: [초안 | 리뷰됨 | 승인됨]

## 1. 처리 설명

<!-- 어떤 개인 데이터가 어떻게, 누구에 의해, 어떤 목적으로 처리되는가.
     수집부터 삭제까지의 데이터 흐름을 포함한다. -->

- 정보 주체: [데이터가 누구에 관한 것인가]
- 데이터 범주: [개인 데이터의 유형, 특수 범주 표시]
- 목적: [데이터를 왜 처리하는가]
- 수령자와 처리자: [누가 데이터를 받거나 다루는가]
- 보존 기간: [데이터를 얼마나 보관하며 삭제 방법]
- 국제 이전: [목적지와 이전 메커니즘]

## 2. 필요성과 비례성

<!-- 처리가 목적에 필요한가? 가장 덜 침해적인 선택지인가? 적법한
     근거나 권한은 무엇인가? -->

- 적법한 근거 / 권한: [각 목적의 근거]
- 데이터 최소화: [각 필드가 왜 필요한가]
- 정확성과 보존 정당화: [메모]
- 정보 주체의 권리를 지원하는 방법: [열람, 삭제 등]

## 3. 협의

<!-- 협의한 이해관계자, 그리고 관련되는 경우 정보 주체. -->

## 4. 개인에 대한 위험

<!-- 프라이버시 위험을 식별하고 각각 등급을 매긴다. -->

| 개인에 대한 위험 | 가능성 | 심각도 | 전체 |
|------------------|--------|--------|------|
| [예: 민감한 데이터에 대한 무단 접근] | [L/M/H] | [L/M/H] | [등급] |

## 5. 위험을 줄이는 조치

<!-- 각 위험에 대해 완화와 그 뒤의 잔여 위험. -->

| 위험 | 조치 | 잔여 위험 | 수용자 |
|------|------|-----------|--------|
| [위험] | [통제] | [L/M/H] | [이름] |

## 6. 결과와 승인

- 잔여 위험 수용 가능: [예 | 아니오]
- 조치 승인자: [이름, 역할]
- 감독 기관과의 협의 필요: [예 | 아니오]
- 리뷰 날짜: [YYYY-MM-DD]