Wiki Guide

위키 작성 가이드

이 위키는 코드를 읽어도 알 수 없는 것을 남기는 곳이다. 양식은 Backend 위키와 같고, 두 위키의 사례는 서로 링크로 잇는다. 지금 코드가 어떻게 동작하는지는 README와 레포 안 문서가 맡고, 위키에는 왜 그렇게 됐는지, 무엇을 재고 비교했는지, 그 결과 무엇을 배웠는지를 남긴다. 코드가 바뀌어도 "그때 무슨 일이 있었나"는 계속 맞는 기록이어야 한다.

무엇을 위키에 쓰나

위키에 쓴다	위키에 쓰지 않는다
장애·버그를 추적하고 고친 기록	패키지 구조, 메시지 계약, 설정 키 설명 (→ 모듈별 README, docs/, core/contracts.py)
기술·구조를 바꾼 결정과 그 근거(측정·PoC)	코드 주석으로 충분한 구현 설명
실측 결과(모델 비교·임계값 근거)처럼 코드에 숫자만 남은 것의 출처	회의록, 일정 (→ Notion)
팀이 같이 쓰는 용어와 결정 색인	근거 없는 일반론

사례 기록 양식

장애를 고친 기록이든 기술을 바꾼 기록이든 같은 뼈대를 쓴다. 해당 사항이 없는 절은 지우지 말고 "해당 없음"이나 "측정하지 않음"이라고 적는다. 빈칸이 보여야 다음에 채울 수 있다.

# <무엇이 문제였고 무엇으로 해결했나>

| 기간 | 2026-10-20 ~ 10-23 |
|---|---|
| 상태 | 해결 / 관찰 중 / 진행 중 |
| 유형 | 장애 · 성능 · 버그 · 전환 |
| 근거 | 이슈 #72 · PR #76~#80 |
| 영향 | 누가, 무엇을, 얼마 동안 못 했나 (한 줄) |

> 세 문장 요약: 무엇이 문제였고, 원인이 무엇이었고, 무엇을 바꿔서 어떻게 됐나.

|  | 전 | 후 |
|---|---|---|
| 핵심 지표 | 측정값 | 측정값 |

## 1. 증상과 영향
## 2. 타임라인
## 3. 측정과 가설
## 4. 원인
## 5. 검토한 선택지
## 6. 조치
## 7. 검증
## 8. 회고
## 9. 후속 조치
## 참고

절마다 쓰는 것

1. 증상과 영향: 처음 무엇이 보였나, 누가 어떤 영향을 받았나, 얼마나 지속됐나. 그래프나 로그 캡처가 있으면 여기에 둔다.

2. 타임라인: 날짜(필요하면 시각)와 사건을 표로 적는다. 발견, 첫 대응, 원인 확인, 수정 배포, 검증 완료. 하루 안에 끝난 일이면 생략해도 된다.

3. 측정과 가설: 바꾸기 전 기준선을 먼저 고정한다. 다음 순서로 적는다.

   • 질문
   • 가설
   • 예측 ("가설이 맞다면 X가 보여야 한다")
   • 실험
   • 결과

   틀린 가설도 지우지 않는다. 틀린 가설이 가장 많이 가르쳐 준다.

4. 원인: 근본 원인과 트리거를 나눠 적는다. 근본 원인은 원래 있던 약점이고, 트리거는 그 약점을 드러낸 사건이다. 필요하면 "왜?"를 다섯 번 묻는다.

5. 검토한 선택지: 결정 요인(무엇을 중요하게 봤나)을 먼저 적는다. 그다음 선택지마다 장단점과 실험 결과를 표로 적는다. 고르지 않은 선택지도 남긴다.

6. 조치: 무엇을 바꿨나. 이슈·PR 번호와 한 줄 설명을 표로 적는다.

7. 검증: 조치 뒤 같은 잣대로 다시 잰 값. 아직 재지 않았으면 "측정하지 않음"과 측정 계획을 적는다.

8. 회고: 잘된 점 / 아쉬운 점 / 운이 좋았던 점 / 다음에 한다면. 사람이 아니라 과정과 구조를 본다(blameless).

9. 후속 조치: 아직 남은 일을 표로 적는다. 항목, 유형(예방·완화·탐지), 상태, 이슈.

쓰는 원칙

• 숫자는 출처가 있어야 한다. 로그, GPU E2E 실측, PR 본문, 팀 설계 문서처럼 출처를 밝힌다. 기억에 의존한 수치는 쓰지 않고, 모르면 모른다고 적는다.
• 비난하지 않는다. "누가 실수했다"가 아니라 "무엇이 그 실수를 가능하게 했나"를 쓴다. 사람 이름은 쓰지 않는다.
• 그림은 근거로 쓴다. 전후 그래프, 대시보드 캡처, 구조도를 넣고, 그림 아래에 그림에서 무엇을 봐야 하는지 한 줄을 적는다.
• 당시 코드와 지금 코드가 다르면 끝에 "이후 변경" 한 줄을 남긴다. 본문은 당시 기준 그대로 둔다.

그 밖의 페이지

• 결정 로그: 결정 한 줄마다 상태(채택 / 대체됨 / 폐기 / 제안)와 근거 사례 기록 링크를 단다.
• 용어집: 도메인 용어와 코드 이름을 짝지어 둔다.

공통 규칙

• 공개 레포다. IP, 도메인, AWS 계정 ID, ARN, 인스턴스 ID·이름, 실제 버킷·큐·DB 이름, 비밀값, 사람 이름을 쓰지 않는다. 테스트 문서의 이름·주민번호는 예시 값이어도 실제 문서에서 나온 것이면 쓰지 않는다. 이미지에도 똑같이 적용한다. 필요하면 <NODE_IP>처럼 자리표시를 쓴다.
• 문체: 한다체로 쓴다. 문단은 짧게 쓰고, 비교는 표로 한다. 코드는 핵심만 15줄 이내로 발췌한다.
• 이미지: images/<페이지>/<이름>.png에 두고 다음처럼 넣는다.

  <p align="center"><img src="images/<페이지>/<이름>.png" width="80%" alt="설명"></p>
  <p align="center"><sub>이 그림에서 볼 것 한 줄</sub></p>

• 페이지 이름: 사례 기록은 한국어 제목을 그대로 쓴다. 공통 페이지는 영어 하이픈 표기를 쓴다.

참고한 양식

출처	가져온 것
팀 위키 초안 "VLM 표 추출 모델 교체 트러블슈팅"	증상 → 측정 → 원인 → 대안 검증 → 조치 → 검증 → 회고의 뼈대. 바꾸기 전 기준선부터 고정하는 습관. 전후 비교 표
Google SRE Book — Example Postmortem, Postmortem Culture	머리 표(상태·영향·근거), 근본 원인과 트리거 구분, 타임라인, 교훈의 "잘된 점 / 아쉬운 점 / 운이 좋았던 점", 후속 조치 표, 비난 없는 서술
MADR (Markdown Architectural Decision Records)	결정 요인, 검토한 선택지와 장단점, 검증 방법(Confirmation)
Brendan Gregg — Performance Analysis Methodology	측정 절의 질문 → 가설 → 예측 → 실험 → 분석 순서. 아무거나 바꿔 보는 방식(Drunk Man anti-method)을 경계하는 것
Diátaxis	설명·절차·레퍼런스를 한 페이지에 섞지 않는 원칙. 런북을 설명 페이지와 분리한 것
Michael Nygard ADR, Microsoft Engineering Playbook — Decision Log	결정 로그의 상태 값과 요약 표