P7-7.2 장애 기록과 다음 반복 계획¶

Section ID: P7-7.2 Version: v2026.07.22

배포 프로젝트의 마지막 단계는 배포 성공 화면을 보고 끝내는 일이 아닙니다. 이 저장소처럼 dev에서 쓰고 main에서 배포하는 구조에서는, 실패도 어느 단계에서 끊겼는가를 기록해야 다음 반복이 쉬워집니다.

목적은 배포가 끝난 뒤 성공 화면만 남기는 것이 아니라, 브랜치 반영 실패, 로컬 빌드 실패, Pages 반영 실패, 공개 페이지 확인 실패를 분리해 기록하는 데 있습니다.

장애 기록에서 다음 반복으로¶

• 정적 사이트 프로젝트에서 어떤 실패를 기록해야 하는가?
• 배포 실패와 콘텐츠 실패를 왜 구분해야 하는가?
• 개선 계획은 어떻게 우선순위를 붙이면 좋은가?

정적 문서 배포 프로젝트의 실패 유형과 우선순위 기록에 집중합니다. 즉, 실패를 원인 추정과 다음 조치로 남기는 습관까지를 먼저 닫고, Part 7 전체에서 쌓은 검토 기록을 마지막 회고 형식으로 다시 묶습니다.

Part 7의 마지막 회고는 이 절에서 실패 범주와 다음 조치를 함께 남기는 형식으로 닫힙니다. 브랜치 반영 실패, 빌드 실패, Pages 반영 실패, 공개 확인 실패를 같은 말로 묶지 않고 다음 조치까지 남기는 회고 기준을 여기서 고정합니다.

Part 7에서 회고(retrospective), 배포(deployment), 검토(review)의 구분이 다시 흐려지면 이 절과 개념사전으로 돌아와 기준을 다시 잡는 편이 좋습니다.

판단 기준¶

• 배포 프로젝트의 실패 유형을 몇 가지 범주로 정리할 수 있습니다.
• 실패 기록을 원인 추정과 다음 조치까지 연결해 적을 수 있습니다.
• 정적 문서 프로젝트에도 운영 회고가 필요하다는 점을 설명할 수 있습니다.

실패 유형을 나누어 보기¶

AiBook 같은 정적 문서 배포 프로젝트에서 흔한 실패는 크게 네 가지로 나눌 수 있습니다.

이 구분이 중요한 이유는 해결 책임과 다음 행동이 다르기 때문입니다.

• 브랜치 반영 실패는 어느 브랜치가 독자에게 공개되는가를 다시 확인해야 합니다.
• 빌드 실패는 로컬 재현이 중요합니다.
• Pages 반영 실패는 CI 로그 확인이 중요합니다.
• 공개 확인 실패는 공개 페이지 실제 확인이 중요합니다.

실패 기록을 쓰기 전에 먼저 가를 판단 기준을 표로 고정하면 다음과 같습니다.

여기에 한 가지를 더 붙이면 Part 7 전체가 더 잘 묶입니다. 각 프로젝트에서 이미 남긴 검토 요약, 평가 기록, 수정 필요 상태, 보류 상태 같은 기록을 마지막 실패 회고 문서에서 다시 받아 적을 수 있어야 합니다. 그래야 Part 7의 각 실습이 따로 끝나지 않고 하나의 공통 회고 템플릿으로 모입니다.

같은 회고 구조는 Part 3에서 다뤘던 검토 기록 언어와도 자연스럽게 이어집니다.

AiBook 배포 실패 기록 예시¶

프로젝트 회고 문서를 다음 형식으로 남기는 예를 듭니다.

이 표는 단순하지만 Part 7의 배포 프로젝트에서 사실상 운영 회고 템플릿 역할을 합니다.

예를 들어 메인 페이지는 열리지만 수정한 Section 링크가 404인 장면을 만나면, 빠르게는 배포가 덜 됐나 보다라고 넘기기 쉽습니다. 하지만 그 판단만으로는 다음 행동이 흐려집니다. 이 장면에서는 먼저 공개 URL은 열리므로 전체 배포 실패는 아니다, 문제는 특정 진입 경로에서 재현된다, 따라서 nav 경로나 상대 링크를 먼저 확인해야 한다는 식으로 실패 범주를 좁혀야 합니다. 사례를 이렇게 읽어야 회고가 감상문이 아니라 실제 수정 순서가 됩니다.

flowchart TD
  A["공개 페이지 진입 시 특정 Section 링크가 404"]
  B["빠른 판단: 배포 전체가 실패했을 수 있음"]
  C["공개 메인 페이지와 다른 링크는 정상"]
  D["실패 범주를 공개 확인 실패로 좁힘"]
  E["nav 경로와 실제 파일 경로를 대조"]
  F["다음 조치: 문제 링크 직접 추적 후 경로 수정"]

  A --> B
  A --> C
  C --> D
  D --> E
  E --> F

바로 쓰는 실패 기록 템플릿¶

배포 프로젝트를 마친 뒤 바로 채울 수 있는 최소 템플릿은 아래 정도로 시작할 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

### 실패 기록
- 날짜:
- 문제:
- 범주:
- 가능한 원인:
- 독자 영향:
- 우선순위:
- 다음 조치:

### 회고 요약
- 가장 먼저 고칠 문제:
- 이번 반복에서 미루는 문제:
- 다음 배포 전에 추가할 점검:

여기서도 중요한 점은 코드 식별자를 그대로 외우는 것이 아닙니다. 실패 기록은 실패 사건 한 건의 기록이고, 회고 요약은 그 사건들을 이번 반복의 우선순위로 다시 묶은 요약으로 읽으면 됩니다.

이 템플릿의 핵심은 실패했다에서 멈추지 않는 것입니다. 적어도 어떤 종류의 실패였는가, 독자에게 어떤 영향이 있었는가, 다음에 무엇을 먼저 할 것인가까지는 같이 적어야 합니다.

예를 들어 수정한 Section 링크가 404였던 경우는 다음처럼 바로 채울 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

### 실패 기록
- 날짜: 2026-07-18
- 문제: 수정한 Section 링크가 404
- 범주: 공개 확인 실패
- 가능한 원인: 목차 경로 설정과 실제 파일 경로 불일치
- 독자 영향: 독자 흐름이 끊긴다
- 우선순위: 1
- 다음 조치: 공개 URL에서 문제 링크를 다시 따라가고, 목차 경로 설정과 대상 경로를 함께 다시 확인한다

### 회고 요약
- 가장 먼저 고칠 문제: 독자가 바로 만나게 되는 404 링크
- 이번 반복에서 미루는 문제: 수식 렌더링 미세 조정
- 다음 배포 전에 추가할 점검: 공개 URL에서 핵심 링크 3개 직접 클릭

Python 예제¶

예제는 실패 표를 실제 회고 기록 구조로 바꾸는 것입니다. 예제에서는 막연한 문제 목록 대신, AiBook 배포 흐름에서 실제로 만날 수 있는 신호를 넣고 어디서 확인할지, 무슨 명령으로 재현할지, 무엇을 먼저 고칠지를 같이 정리합니다.

• 문제 상황: 배포 이후 생긴 문제를 다시 읽고 다음 조치를 정리한다.
• 입력: 실패 항목 목록
• 기대 출력: 우선순위가 붙은 실패 기록, 즉시 확인 경로, 개선 계획
• 확인할 개념:
• 실패는 범주별로 나누어 남겨야 한다
• 가능한 원인, 확인 위치, 다음 조치가 함께 있어야 한다
• 우선순위가 붙어야 다음 반복으로 이어진다

운영 사건 예시를 코드 안에 직접 쓰지 않고 p7-7-deployment-incidents.csv · CSV 미리보기에 둡니다. Python 코드는 그 CSV를 읽어 우선순위별 회고 기록과 개선 계획을 만드는 단계부터 시작합니다.

입력 파일¶

• 파일 경로: p7-7-deployment-incidents.csv · CSV 미리보기
• 한 행의 의미: 배포 이후 관찰된 실패 사건 하나
• 핵심 열: incident_id, date, problem, category, signal, possible_cause, check_locations, priority, immediate_checks, next_action

이 파일은 단순 장애 메모가 아니라 관찰 신호, 확인 위치, 즉시 확인 명령까지 포함한 회고 원장입니다. Python 예제는 이 열들을 읽어 실패 기록과 개선 계획을 따로 재구성합니다.

실행 기록 기준¶

장애 기록의 밀도는 항목 수가 아니라 각 항목에 붙은 관찰 신호, 가능한 원인, 확인 위치, 우선순위, 다음 조치에서 나옵니다. 사건별 범주와 우선순위를 먼저 나누면 어떤 사건이 즉시 확인 대상인지 더 분명해집니다.

기록은 다음 기준으로 나눕니다.

1. CSV에서 category, signal, priority, next_action 열을 먼저 확인합니다.
2. 각 사건이 브랜치 반영, 빌드, Pages 반영, 공개 확인 실패 중 어디에 속하는지 표시합니다.
3. Python 예제를 실행해 우선순위 1 사건과 다음 반복 사건이 어떻게 나뉘는지 봅니다.
4. 즉시 확인 대상 사건 하나를 골라, 실제로 어디를 먼저 확인해야 하는지 한 문장으로 씁니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

# 배포 장애 기록을 우선순위와 범주로 정렬해 즉시 수정, 다음 반복 수정, 추후 추적 계획을 만드는 예제입니다.
import csv
from pathlib import Path

data_path = Path("docs/assets/part-07/chapter-07/p7-7-deployment-incidents.csv")
incident_rows = list(csv.DictReader(data_path.open(encoding="utf-8")))
대표_incident_ids = {f"deploy-{index:02d}" for index in range(1, 5)}
incident_rows = [
    row for row in incident_rows if row["incident_id"] in 대표_incident_ids
]

실패_기록 = []
for row in incident_rows:
    실패_기록.append({
        "사건 ID": row["incident_id"],
        "날짜": row["date"],
        "문제": row["problem"],
        "범주": row["category"],
        "관찰 신호": row["signal"],
        "가능한 원인": row["possible_cause"],
        "확인 위치": row["check_locations"].split("|"),
        "독자 영향": row["reader_impact"],
        "우선순위": int(row["priority"]),
        "즉시 확인 명령": row["immediate_checks"].split("|"),
        "다음 조치": row["next_action"],
    })

실패_기록.sort(key=lambda row: (row["우선순위"], row["날짜"]))

개선_계획 = []
for row in 실패_기록:
    if row["우선순위"] == 1:
        행동_구간 = "즉시 수정"
    elif row["우선순위"] == 2:
        행동_구간 = "다음 반복에서 수정"
    else:
        행동_구간 = "추후 추적"

    개선_계획.append({
        "사건 ID": row["사건 ID"],
        "문제": row["문제"],
        "범주": row["범주"],
        "행동 구간": 행동_구간,
        "확인 위치": row["확인 위치"],
        "다음 조치": row["다음 조치"],
    })

회고_요약 = {
    "실패 수": len(실패_기록),
    "우선순위 1 문제 수": sum(row["우선순위"] == 1 for row in 실패_기록),
    "우선순위 2 문제 수": sum(row["우선순위"] == 2 for row in 실패_기록),
    "범주 목록": sorted({row["범주"] for row in 실패_기록}),
    "즉시 확인이 필요한 사건": [row["사건 ID"] for row in 실패_기록 if row["우선순위"] == 1],
}

print("회고 요약 =", 회고_요약)
print("읽은 파일 =", str(data_path))
print("실패 기록 =")
for row in 실패_기록:
    print(row)
print("개선 계획 =")
for row in 개선_계획:
    print(row)

실행 결과 예시는 다음과 같습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

회고 요약 = {'실패 수': 4, '우선순위 1 문제 수': 3, '우선순위 2 문제 수': 1, '범주 목록': ['Pages 반영 실패', '공개 확인 실패', '브랜치 반영 실패', '빌드 실패'], '즉시 확인이 필요한 사건': ['deploy-01', 'deploy-02', 'deploy-03']}
읽은 파일 = docs/assets/part-07/chapter-07/p7-7-deployment-incidents.csv
실패 기록 =
{'사건 ID': 'deploy-01', '날짜': '2026-07-18', '문제': '수정한 Section의 최신 Version이 공개 페이지에 보이지 않음', '범주': '브랜치 반영 실패', '관찰 신호': '로컬 파일에는 v2026.07.18이 보이지만 공개 페이지에는 이전 Version이 보인다', '가능한 원인': 'main 미반영 또는 Pages workflow 진행 중', '확인 위치': ['git branch', 'main 반영 상태', 'GitHub Actions workflow'], '독자 영향': '독자가 최신 수정 내용을 볼 수 없음', '우선순위': 1, '즉시 확인 명령': ['git branch --show-current', '.github/workflows/deploy.yml 확인'], '다음 조치': '현재 브랜치와 main 반영 여부를 먼저 확인하고, 그다음 Pages workflow 진행 상태를 본다'}
{'사건 ID': 'deploy-02', '날짜': '2026-07-18', '문제': '로컬에서 mkdocs strict build가 실패함', '범주': '빌드 실패', '관찰 신호': 'nav 또는 링크 오류 때문에 빌드가 중간에 멈춘다', '가능한 원인': 'mkdocs.yml nav 경로 또는 문서 링크 불일치', '확인 위치': ['mkdocs.yml', '오류 난 Section', '상대 링크'], '독자 영향': '배포 자체가 진행되지 못함', '우선순위': 1, '즉시 확인 명령': ['.venv/bin/python -m mkdocs build'], '다음 조치': '로컬 빌드를 재현하고, 오류 메시지가 가리키는 nav 경로와 링크 대상을 같이 수정한다'}
{'사건 ID': 'deploy-03', '날짜': '2026-07-18', '문제': '공개 페이지에서 수정한 Section 링크가 404를 반환함', '범주': '공개 확인 실패', '관찰 신호': '메인 페이지는 열리지만 수정한 Section 진입에서 404가 난다', '가능한 원인': '목차 경로와 실제 파일 경로가 일치하지 않음', '확인 위치': ['공개 URL', '목차 링크', '대상 파일 경로'], '독자 영향': '독서 흐름이 끊김', '우선순위': 1, '즉시 확인 명령': ['공개 URL 직접 확인', 'mkdocs.yml 링크 경로 점검'], '다음 조치': '공개 URL에서 문제 링크를 직접 따라가고, nav 경로와 실제 파일 경로를 함께 대조한다'}
{'사건 ID': 'deploy-04', '날짜': '2026-07-18', '문제': '공개 페이지는 열리지만 최신 본문이 일부만 반영된 것처럼 보임', '범주': 'Pages 반영 실패', '관찰 신호': '홈은 최신인데 특정 Section만 이전 본문처럼 보인다', '가능한 원인': '배포 artifact 반영 지연 또는 캐시된 페이지 확인', '확인 위치': ['Pages deploy 상태', '공개 Section 메타데이터', '재방문 시점'], '독자 영향': '배포 상태 판단이 흔들리고 잘못된 회고가 남을 수 있음', '우선순위': 2, '즉시 확인 명령': ['공개 URL 재확인', '잠시 뒤 다시 확인'], '다음 조치': '배포 완료 시각과 공개 페이지 상태를 함께 적고, 지연 뒤 한 번 더 재확인한다'}
개선 계획 =
{'사건 ID': 'deploy-01', '문제': '수정한 Section의 최신 Version이 공개 페이지에 보이지 않음', '범주': '브랜치 반영 실패', '행동 구간': '즉시 수정', '확인 위치': ['git branch', 'main 반영 상태', 'GitHub Actions workflow'], '다음 조치': '현재 브랜치와 main 반영 여부를 먼저 확인하고, 그다음 Pages workflow 진행 상태를 본다'}
{'사건 ID': 'deploy-02', '문제': '로컬에서 mkdocs strict build가 실패함', '범주': '빌드 실패', '행동 구간': '즉시 수정', '확인 위치': ['mkdocs.yml', '오류 난 Section', '상대 링크'], '다음 조치': '로컬 빌드를 재현하고, 오류 메시지가 가리키는 nav 경로와 링크 대상을 같이 수정한다'}
{'사건 ID': 'deploy-03', '문제': '공개 페이지에서 수정한 Section 링크가 404를 반환함', '범주': '공개 확인 실패', '행동 구간': '즉시 수정', '확인 위치': ['공개 URL', '목차 링크', '대상 파일 경로'], '다음 조치': '공개 URL에서 문제 링크를 직접 따라가고, nav 경로와 실제 파일 경로를 함께 대조한다'}
{'사건 ID': 'deploy-04', '문제': '공개 페이지는 열리지만 최신 본문이 일부만 반영된 것처럼 보임', '범주': 'Pages 반영 실패', '행동 구간': '다음 반복에서 수정', '확인 위치': ['Pages deploy 상태', '공개 Section 메타데이터', '재방문 시점'], '다음 조치': '배포 완료 시각과 공개 페이지 상태를 함께 적고, 지연 뒤 한 번 더 재확인한다'}

결과를 어떻게 읽는가¶

이 예제에서 중요한 점은 세 가지입니다.

1. 실패 기록 목록
   실패를 단순 사건 메모가 아니라 범주, 관찰 신호, 가능한 원인, 독자 영향, 우선순위가 있는 운영 기록으로 남깁니다.

2. 개선 계획
   같은 실패 목록이라도 즉시 수정, 다음 반복 수정처럼 행동 구간으로 나누면 다음 반복이 쉬워집니다. 즉, 실패 기록 목록이 무슨 일이 있었는지 남기는 회고 원장이라면, 개선 계획은 그 원장을 이번 주 작업표로 다시 옮겨 적은 실행 목록입니다.

3. 검토 요약
   우선순위 1 문제가 몇 개인지, 그리고 어떤 사건이 즉시 확인 대상인지 바로 보여 주므로 무엇을 먼저 고쳐야 하는지 한눈에 읽을 수 있습니다.

즉, 회고 문서는 과거 설명이 아니라 다음 반복을 여는 작업 목록이어야 합니다.

같은 관점으로 보면 텍스트 프로젝트의 검토 대상 문장, RAG 프로젝트의 근거 부족 질문, 에이전트 프로젝트의 보류 단계도 모두 무엇을 먼저 다시 볼 것인가를 정하는 실패 기록 재료가 됩니다. 즉, 최종 실패 기록 절의 역할은 새 실패 유형을 더 만드는 일이 아니라, 이미 각 프로젝트에서 남긴 기록을 실패 신호 -> 해석 경계 -> 다음 질문 순서로 다시 압축하는 데 있습니다.

결과 해석 기준¶

이번 결과에서는 실패 수보다 우선순위와 확인 위치가 붙었는가를 봅니다. 같은 배포 문제라도 독자가 바로 만나는 404와, 잠시 뒤 다시 확인할 공개 반영 지연은 같은 속도로 다룰 필요가 없습니다.

프로젝트 기록 예시¶

기록은 다음 형식으로 장애 기록을 압축할 수 있습니다.

왜 장애 회고 습관이 필요한가¶

Google SRE 책은 장애 회고 문화를 실패에서 배우는 문화로 다룹니다. 이 책의 Part 7 프로젝트 수준에서는 거대한 조직 절차까지 갈 필요는 없지만, 핵심 태도는 그대로 가져올 수 있습니다.

• 실패를 숨기지 않는다.
• 원인을 단정하기보다 가능한 설명을 적는다.
• 다음 반복에서 바꿀 것을 남긴다.

즉, 회고는 책임 추궁이 아니라 반복 가능한 개선 메모입니다.

프로젝트 규모와 무관하게 실패를 남겨야 다음 반복이 쉬워집니다.

개선 계획 우선순위 붙이기¶

개선 계획은 많아질수록 오히려 실행되지 않기 쉽습니다. 그래서 프로젝트 회고에서는 다음처럼 우선순위를 붙이는 편이 좋습니다.

1. 다시 발생하면 바로 보이는 문제
   예: 깨진 링크, 빌드 실패, main 미반영
2. 독자 경험을 직접 해치는 문제
   예: 최신 내용 미반영, 모바일 가독성 저하
3. 나중에 구조적으로 키워야 할 문제
   예: 배포 자동 검증 강화, 모니터링 항목 추가

이렇게 나누면 회고가 단순 희망사항 목록으로 끝나지 않습니다.

이 우선순위는 다음 세 줄로 요약할 수 있습니다.

• 먼저 다시 보이는 실패를 고친다
• 다음으로 독자 경험을 해치는 문제를 고친다
• 그다음 구조적 개선을 계획한다

나쁜 실패 기록과 좋은 실패 기록¶

실패 기록도 자주 너무 짧거나 너무 감정적으로 끝납니다. 아래처럼 대비해 보면 기준이 분명해집니다.

좋은 기록은 완벽한 원인 분석이 없어도 괜찮습니다. 대신 관찰된 현상, 현재 가능한 원인 추정, 다음 조치, 우선순위가 함께 남아 있어야 다음 반복에서 바로 다시 잡을 수 있습니다.

여기서 가능한 원인은 확정 원인이라기보다 현재 기록 시점에 붙일 수 있는 가장 가까운 설명 후보입니다. 실제 원인은 추가 확인 뒤 바뀔 수 있으므로, 실패 기록에는 다음 검토 질문을 함께 남겨 두는 것이 중요합니다.

여기서 특히 중요한 점은 원인 확정을 너무 서두르지 않는 것입니다.

• 실패는 관찰되지만 원인은 아직 확정되지 않았을 수 있습니다.
• 검토 상태는 다음 검토 우선순위를 올리는 신호입니다.
• 적은 사례만 본 상태라면 실패 해석도 더 보수적으로 적는 편이 안전합니다.

프로젝트 회고 문장 예시¶

이번 AiBook 배포 프로젝트에서는 dev 작업, 로컬 빌드, main 반영, GitHub Pages 공개 확인을 서로 다른 단계로 기록했다. 그 결과 배포 성공 메시지 하나만으로는 충분하지 않고, 최신 Version 반영 여부와 Section 링크 정상 동작을 공개 URL에서 다시 확인해야 한다는 점이 분명해졌다. 다음 반복에서는 main 반영 여부, strict build 결과, 공개 페이지의 핵심 링크 점검을 우선순위 1 체크로 고정하는 편이 적절하다.

이 회고 문장도 같은 기준으로 읽으면 좋습니다. 성공 여부와 가능한 원인은 현재 반복의 관찰과 해석이고, 다음 반복에서는 실제 재현 결과에 따라 우선순위나 설명이 다시 조정될 수 있습니다.

직접 바꿔 보며 확인할 것¶

실패 기록을 우선순위로 다시 묶으려면 사건 우선순위와 범주를 직접 바꿔 보는 편이 좋습니다.

1. deploy-04의 우선순위를 2에서 1로 올려 봅니다. 관찰할 점: 회고 요약과 개선 계획에서 즉시 수정 항목 수가 어떻게 달라지는가?

2. deploy-03의 관찰 신호를 더 약한 표현으로 바꿔 봅니다. 관찰할 점: 같은 404 문제라도 회고 문장이 즉시 수정보다 재현 확인 필요 쪽으로 더 보수적으로 이동하는가?

핵심 확인 기준은 실패를 적는가가 아니라 같은 실패도 우선순위와 신호 강도에 따라 다음 반복 계획이 어떻게 달라지는가입니다.

체크리스트¶

이 다섯 칸이 비어 있으면 새 해결책을 더 붙이기 전에 실패 범주, 관찰 신호, 영향, 우선순위, 다음 조치를 먼저 정리해야 합니다.

출처와 참고 자료¶

• GitHub Docs, Creating a GitHub Pages site, 확인 날짜: 2026-06-29. https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
• Google, Monitoring Distributed Systems, Site Reliability Engineering Book, 확인 날짜: 2026-06-29. https://sre.google/sre-book/monitoring-distributed-systems/

이 절의 실패 기록 표는 Part 7 프로젝트 회고를 위해 구성한 자체 예시입니다.