0907 운영 자동화/AI 워크플로우 심화 (3/N): 트러블슈팅 문서 자동화와 장애 회고 체계
✅ 1. 트러블슈팅 문서가 중요한 이유
- 운영 서비스에서는 기능 개발보다 “문제가 생겼을 때 얼마나 빨리 원인을 찾고 복구하느냐”가 더 중요할 때가 많습니다.
- 특히 1인 개발자는 과거에 해결했던 문제를 다시 만났을 때 기억에 의존하면 시간이 많이 낭비됩니다.
- 그래서 장애나 버그를 해결할 때마다 문제, 원인, 해결, 검증, 재발 방지를 문서로 남겨두는 것이 좋습니다.
문제 발생
↓
원인 분석
↓
수정
↓
검증
↓
문서화
↓
다음에 같은 문제 발생
↓
빠른 재대응➕ 1-1. 문서화가 없을 때 생기는 문제
같은 문제를 다시 처음부터 분석함
왜 그렇게 수정했는지 기억이 안 남
AI/Codex가 과거 맥락 없이 다시 잘못 수정할 수 있음
운영 장애 대응 경험이 포트폴리오로 남지 않음
재발 방지 작업이 누락됨- 트러블슈팅 문서는 단순 기록이 아닙니다.
- 운영 노하우를 축적하는 기술 자산입니다.
✅ 2. 어떤 문제를 문서화해야 할까?
- 모든 작은 버그를 트러블슈팅 문서로 만들 필요는 없습니다.
- 반복 가능성, 운영 영향, 분석 난이도가 높은 문제를 우선 기록하면 됩니다.
➕ 2-1. 문서화 가치가 높은 문제
운영 장애
배포 후 오류
DB migration 문제
데이터 정합성 문제
외부 API 장애
알림톡 발송 실패
Webhook 중복/검증 문제
권한/인증 오류
대량 Export 실패
관리자 핵심 UX 오류
보안 관련 문제➕ 2-2. 간단 메모로 충분한 문제
단순 문구 오타
작은 CSS 간격 수정
일회성 이미지 교체
원인이 명확한 단순 validation 오류➕ 2-3. 판단 기준
30분 이상 원인 분석이 필요했는가?
운영에 실제 영향을 줬는가?
같은 문제가 다시 생길 수 있는가?
다른 기능에도 영향을 줄 수 있는가?
해결 과정에서 배울 점이 있었는가?- “다시 만나면 또 시간 쓸 것 같은 문제”는 문서화 가치가 높습니다.
✅ 3. 트러블슈팅 문서 기본 구조
# Troubleshooting: 상담 상태 변경 후 목록이 갱신되지 않는 문제
## 1. 문제 상황
- 관리자 상담 상세에서 상태를 변경했지만 목록 화면에는 이전 상태가 유지됨
## 2. 발생 조건
- 관리자 상담 상세 → 상태 변경
- 목록으로 돌아왔을 때 재현
- TanStack Query cache 사용 중
## 3. 영향 범위
- 상담 처리 상태 오인 가능
- 관리자 중복 작업 가능
- 운영자가 새로고침해야 정상 상태 확인 가능
## 4. 원인
- 상태 변경 mutation 성공 후 consult list query invalidate가 실행되지 않음
- detail query만 invalidate됨
## 5. 해결 방법
- mutation 성공 후 consult list와 consult detail query를 모두 invalidate
- queryKey 기준 통일
## 6. 검증
- 상태 변경 후 상세 화면 갱신 확인
- 목록으로 이동 후 상태 반영 확인
- 상태 필터별 목록 재조회 확인
- 다른 상담 row 영향 없음 확인
## 7. 재발 방지
- mutation별 invalidate 대상 문서화
- queryKey factory 도입 검토
- 상태 변경 E2E 테스트 추가
## 8. 관련 파일
- update-consult-status.mutation.ts
- consult-query-key.ts
- consult-list.page.tsx
## 9. 관련 커밋
- fix(admin): 상담 상태 변경 후 목록 캐시 갱신
## 10. 배운 점
- 서버 상태 변경 후 화면 일관성을 위해 관련 query cache를 함께 갱신해야 함➕ 3-1. 핵심 섹션
문제 상황
발생 조건
영향 범위
원인
해결 방법
검증
재발 방지- 이 7개만 있어도 실무에서 충분히 쓸 수 있습니다.
- 파일/커밋/로그는 자동화로 추가하면 좋습니다.
✅ 4. 문제 상황은 증상 중심으로 작성하기
- 트러블슈팅 문서는 처음부터 원인을 단정하면 안 됩니다.
- 먼저 사용자가 실제로 본 증상을 기록해야 합니다.
➕ 4-1. 좋은 문제 상황
관리자 신청 모달에서 드롭다운을 열면 옵션 영역이 모달 하단에 가려져 마지막 항목을 선택할 수 없음➕ 4-2. 나쁜 문제 상황
z-index 문제 발생문제:
실제 증상을 알 수 없음
원인을 미리 단정함
다른 원인이었을 가능성을 놓침➕ 4-3. 기준
누가:
고객/관리자
어디에서:
페이지/기능
무엇을 했을 때:
행동
무슨 일이 발생했는가:
증상- 증상과 원인을 분리해야 나중에 같은 증상이 다른 원인으로 발생했을 때도 도움이 됩니다.
✅ 5. 발생 조건 정리
- 같은 오류라도 특정 브라우저, 데이터, 관리자 권한, 상태값에서만 발생할 수 있습니다.
- 재현 조건을 남기면 다음 분석이 훨씬 빨라집니다.
➕ 5-1. 발생 조건 예시
환경:
운영 / 개발
사용자:
관리자 STAFF 권한
브라우저:
Chrome / Safari
화면:
상담 상세
데이터 조건:
현재 상태 = PENDING
행동:
상태를 CALLING으로 변경
결과:
409 Conflict 발생➕ 5-2. 재현 절차
1. 관리자 로그인
2. PENDING 상태 상담 상세 진입
3. 상태를 CALLING으로 변경
4. 저장 버튼 클릭
5. 409 에러 발생 확인➕ 5-3. 기준
누구나 같은 절차로 재현할 수 있어야 함
환경/브라우저/권한 조건 기록
특정 데이터 조건이 있으면 명시- 재현이 가능해야 문제를 제대로 고칠 수 있습니다.
✅ 6. 영향 범위 정리
- 기술적으로 작은 버그라도 운영 영향은 클 수 있습니다.
- 반대로 코드 에러가 커 보여도 실제 영향은 작을 수 있습니다.
➕ 6-1. 영향 범위 분류
고객 영향
관리자 영향
데이터 영향
매출 영향
보안 영향
외부 API 영향
배포 영향➕ 6-2. 예시
고객 영향:
없음
관리자 영향:
상담 상태를 정상적으로 변경할 수 없음
데이터 영향:
상태 update는 실패하므로 데이터 오염 없음
운영 영향:
관리자 상담 처리 중단 가능➕ 6-3. Impact Level
P0:
서비스 전체 중단, 개인정보/데이터 손실, 치명적 장애
P1:
핵심 기능 장애, 상담/주문 처리 불가
P2:
일부 기능 오류, 우회 가능
P3:
경미한 UI/편의 문제- 장애 회고에서는 영향 범위를 반드시 남겨야 합니다.
- 나중에 우선순위를 정하는 근거가 됩니다.
✅ 7. 원인 분석은 Root Cause와 Trigger를 구분하기
- 문제를 분석할 때 “직접적인 발생 계기”와 “근본 원인”을 구분하는 것이 좋습니다.
➕ 7-1. Trigger
상태 변경 API에서 새로운 PermissionGuard를 적용한 직후 오류 발생➕ 7-2. Root Cause
기존 JWT payload에는 permissions 필드가 없었지만
PermissionGuard가 항상 permissions 배열이 존재한다고 가정함➕ 7-3. 구분
Trigger:
문제가 드러난 계기
Root Cause:
문제가 발생하게 만든 구조적 원인- 단순히 “배포해서 장애가 났다”는 원인이 아닙니다.
- 왜 그 배포가 장애로 이어졌는지까지 봐야 재발 방지가 가능합니다.
✅ 8. 5 Whys를 이용한 원인 분석
- 복잡한 장애는 “왜?”를 반복하면 근본 원인을 찾는 데 도움이 됩니다.
➕ 8-1. 예시
문제:
상담 상태 변경이 500 오류 발생
왜?
→ Audit Log insert가 실패함
왜?
→ beforeValue에 Date 객체가 예상 형식과 다르게 들어감
왜?
→ Audit Log Factory 없이 Use Case에서 객체를 직접 생성함
왜?
→ Audit Log payload 표준이 정의되어 있지 않음
근본 원인:
Audit Log 입력 형식과 sanitize 기준이 공통화되어 있지 않음➕ 8-2. 재발 방지
AuditLogFactory 도입
입력 schema 검증
Integration Test 추가- 모든 작은 버그에 5 Whys를 쓸 필요는 없습니다.
- 반복 가능성이나 장애 영향이 큰 문제에 유용합니다.
✅ 9. 해결 방법 기록 기준
- “고쳤다”가 아니라 어떤 방식으로 수정했는지 남겨야 합니다.
- 나중에 비슷한 문제가 발생했을 때 재사용할 수 있어야 합니다.
➕ 9-1. 좋은 해결 기록
기존:
Controller에서 상태 update와 history insert를 순차 실행
변경:
UpdateConsultStatusUseCase에서 transaction을 열고
ConsultRepository와 AuditLogRepository에 동일 tx 전달
결과:
상태 변경/이력/Audit Log 중 하나가 실패하면 전체 rollback➕ 9-2. 나쁜 해결 기록
코드 수정해서 해결➕ 9-3. 기록할 것
기존 구조
수정한 구조
왜 이 방법을 선택했는가?
다른 대안은 왜 쓰지 않았는가?
영향 파일은 무엇인가?- 해결 방법은 미래의 자신에게 설명한다고 생각하면 됩니다.
✅ 10. 검증 기록
- 수정 후 “에러 안 난다”만 확인하면 부족합니다.
- 정상 케이스, 실패 케이스, 영향 범위를 함께 봐야 합니다.
➕ 10-1. 검증 항목 예시
정상:
NEW → CALLING 변경 성공
비정상:
CANCELED → CONVERTED 차단
동시성:
다른 관리자가 먼저 수정하면 409
이력:
상태 변경 history 생성
Audit:
CONSULT_STATUS_UPDATE 로그 생성
프론트:
목록과 상세 상태 동기화➕ 10-2. 검증 상태
NOT_TESTED
MANUAL_TESTED
AUTOMATED_TESTED
DEPLOYED_VERIFIED➕ 10-3. 주의
로컬에서만 확인:
운영 검증 완료라고 쓰지 않기
Unit Test만 성공:
E2E 검증 완료라고 쓰지 않기
배포만 완료:
문제 해결 완료라고 단정하지 않기- 검증 수준도 문서에 남겨야 정확한 기록이 됩니다.
✅ 11. 재발 방지 항목
- 좋은 트러블슈팅 문서는 수정 방법보다 재발 방지가 중요합니다.
➕ 11-1. 재발 방지 후보
Unit Test 추가
Integration Test 추가
E2E Test 추가
Validation 추가
DB constraint 추가
Monitoring 추가
Alert 추가
Runbook 작성
공통 컴포넌트화
Lint/CI 규칙 추가
권한/Policy 공통화➕ 11-2. 예시
문제:
상태 변경 이력 누락
재발 방지:
- 상태 변경 Use Case Integration Test 추가
- 상태 update/history/audit transaction 강제
- 현재 상태와 마지막 history 정합성 점검 쿼리 추가➕ 11-3. TODO로 남기기
[ ] 상태 변경 Integration Test 추가
[ ] Audit Log Factory 적용
[ ] 관련 Runbook 링크 추가- 재발 방지 TODO가 실제 작업으로 이어져야 문서 가치가 있습니다.
✅ 12. 트러블슈팅 문서 자동 생성 흐름
에러/운영 문제 발생
↓
사용자가 짧은 메모 작성
↓
Git 변경사항 수집
↓
관련 commit/diff 수집
↓
관련 로그/에러 코드 입력
↓
AI 초안 생성
↓
사용자 검토
↓
Markdown 저장
↓
Notion 업로드➕ 12-1. 자동으로 가져올 수 있는 정보
현재 브랜치
최근 commit
변경 파일
git diff --stat
수정 시간
관련 test 결과
관련 issue/ticket 번호➕ 12-2. 수동 입력이 필요한 정보
실제 증상
운영 영향
재현 절차
근본 원인
왜 해당 해결책을 선택했는지
배포 후 실제 결과- Git만 보고 근본 원인을 완벽히 추론하게 하면 안 됩니다.
- AI는 초안을 만들고 사람이 사실을 보완하는 구조가 좋습니다.
✅ 13. CLI 명령어 설계
llm-report troubleshoot
llm-report troubleshoot --project togethermall
llm-report troubleshoot --since HEAD~3
llm-report troubleshoot --commit abc123
llm-report troubleshoot --upload-notion➕ 13-1. 인터랙티브 입력
문제 제목:
문제 상황:
영향 범위:
재현 여부:
관련 에러 코드:
원인:
해결 방법:
검증 결과:
재발 방지:➕ 13-2. 결과 경로
~/shn/daily-report/
togethermall/
troubleshooting/
2026-09/
2026-09-07_consult-status-cache.md➕ 13-3. 파일명 기준
YYYY-MM-DD_<short-slug>.md- 트러블슈팅은 날짜뿐 아니라 문제 이름이 파일명에 있는 것이 좋습니다.
- 나중에 grep이나 파일 검색으로 찾기 쉽습니다.
✅ 14. 트러블슈팅 문서 Frontmatter
---
date: 2026-09-07
project: togethermall
type: troubleshooting
severity: P1
status: resolved
domain:
- consult
- admin
tags:
- bugfix
- transaction
- audit-log
relatedCommits:
- abc123
verification: DEPLOYED_VERIFIED
---➕ 14-1. 추천 필드
date
project
severity
status
domain
tags
relatedCommits
verification
incidentId
notionPageId➕ 14-2. Status 후보
INVESTIGATING
IDENTIFIED
FIXED
TESTED
DEPLOYED
RESOLVED
MONITORING- Frontmatter를 구조화하면 월간 리포트에서 장애/버그만 따로 집계하기 쉽습니다.
✅ 15. 장애 Incident와 일반 Troubleshooting 구분
- 모든 트러블슈팅이 장애는 아닙니다.
- 실제 사용자/운영에 영향을 준 문제는 Incident로 별도 관리할 수 있습니다.
➕ 15-1. Troubleshooting
개발 중 발견된 문제
운영 영향 없는 버그
구조적 문제 분석
성능 저하 원인 분석➕ 15-2. Incident
운영 서비스 장애
고객 신청 불가
관리자 핵심 기능 중단
데이터 오류
개인정보/보안 문제
대량 알림 실패➕ 15-3. 기준
Troubleshooting:
기술 해결 기록
Incident:
영향 + 타임라인 + 복구 + 재발 방지까지 포함- Incident는 좀 더 엄격한 형식이 필요합니다.
✅ 16. Incident 문서 구조
# Incident: 상담 신청 API 장애
## 1. 요약
- 상담 신청 API에서 500 오류가 발생해 일정 시간 신규 상담 접수가 불가능했습니다.
## 2. 영향
- 고객 상담 신청 실패
- 영향 시간: 10:20 ~ 10:42
- 관리자 기존 상담 조회에는 영향 없음
## 3. 타임라인
- 10:20 최초 오류 발생
- 10:24 관리자 문의로 인지
- 10:27 로그 확인 시작
- 10:32 Prisma migration 오류 확인
- 10:36 수정 배포
- 10:42 정상화 확인
## 4. 근본 원인
- 신규 필드를 NOT NULL로 추가했지만 기존 데이터 backfill 없이 migration 적용
## 5. 복구
- 필드를 nullable로 수정
- migration 재적용
- 상담 신청 Smoke Test 진행
## 6. 재발 방지
- destructive migration 체크리스트 추가
- staging migration 검증 의무화
- 배포 전 상담 신청 E2E Test 추가
## 7. 관련 자료
- requestId:
- commit:
- migration:
- deploy:- Incident 문서는 기술적으로 무엇이 틀렸는지뿐 아니라 “얼마나 영향을 줬는가”를 기록합니다.
✅ 17. 장애 타임라인 자동화
- 장애가 길어질수록 시간 순서가 중요합니다.
- 로그와 Git 기록을 이용해 일부 타임라인을 자동화할 수 있습니다.
➕ 17-1. 수집 후보
에러 로그 최초 발생 시각
배포 시각
commit 시각
Worker FAILED 증가 시각
API 복구 시각
Smoke Test 완료 시각➕ 17-2. 자동 생성 예시
09:13 배포 완료
09:15 500 error 최초 감지
09:18 CONSULT_CREATE_FAILED 증가
09:24 hotfix commit 생성
09:29 재배포
09:31 health check 정상
09:34 상담 신청 Smoke Test 정상➕ 17-3. 주의
자동 수집 시각은 사실 확인 필요
로그 시각 timezone 통일
추정 시각을 실제 사건처럼 쓰지 않기- 자동화된 타임라인은 초안으로 쓰고 실제 사실을 검토해야 합니다.
✅ 18. Postmortem이란 무엇인가?
- Postmortem은 장애가 끝난 뒤 “왜 발생했고, 다음에는 어떻게 막을 것인가”를 정리하는 회고입니다.
- 사람을 탓하는 문서가 아니라 시스템과 프로세스를 개선하기 위한 문서입니다.
➕ 18-1. Postmortem에서 볼 것
왜 발견이 늦었는가?
왜 테스트가 못 잡았는가?
왜 배포 단계에서 막히지 않았는가?
왜 장애 영향이 커졌는가?
무엇을 자동화하면 다음에 빨리 막을 수 있는가?➕ 18-2. 나쁜 회고
실수로 잘못 배포했다.
다음부터 조심한다.➕ 18-3. 좋은 회고
migration에 기존 데이터 backfill이 필요한 변경이었지만,
배포 체크리스트에 nullable/default 검증 항목이 없어 사전에 발견하지 못했다.
재발 방지를 위해:
- migration checklist에 backfill 검증 추가
- staging migration 테스트 추가
- 상담 신청 E2E Test를 CI 필수 단계로 추가- “조심한다”는 재발 방지가 아닙니다.
- 구조나 자동화가 바뀌어야 합니다.
✅ 19. 장애에서 성과를 뽑을 때 주의
- 장애 자체를 성과처럼 포장하면 안 됩니다.
- 하지만 장애를 해결하고 재발 방지 체계를 만든 경험은 충분히 실무 성과가 될 수 있습니다.
➕ 19-1. 나쁜 표현
대규모 장애를 해결해 운영 역량을 증명했습니다.➕ 19-2. 좋은 표현
운영 중 발생한 DB migration 오류를 분석해 복구하고, 이후 staging migration 검증과 배포 체크리스트를 추가해 동일 유형의 장애를 사전에 확인할 수 있는 기준을 마련했습니다.➕ 19-3. 핵심
장애를 자랑하지 않기
문제 해결 과정 강조
재발 방지 개선 강조
운영 책임감과 학습을 보여주기- 포트폴리오에는 “문제를 숨기지 않고 시스템을 개선한 경험”으로 쓰는 것이 좋습니다.
✅ 20. 기존 일일/주간/월간 리포트와 연결
- 트러블슈팅 문서는 별도 파일로 남기되, 일일/주간/월간 리포트와 연결해야 합니다.
Troubleshooting
↓
Daily Report:
오늘 해결한 이슈로 링크
Weekly Report:
해결한 주요 이슈로 요약
Monthly Report:
운영 안정성 개선 성과로 변환➕ 20-1. 일일 보고서
## 해결한 이슈
- 상담 상태 변경 후 목록 캐시 미갱신 문제 해결
- 자세한 내용: troubleshooting/2026-09-07_consult-cache.md➕ 20-2. 주간 보고서
이번 주 주요 운영 이슈:
- 상담 상태 변경 후 목록 동기화 문제 해결
- NotificationJob retry 오류 해결➕ 20-3. 월간 성과
운영 안정성:
- 상태 변경 캐시 동기화 문제와 NotificationJob 재시도 오류를 해결하고 관련 테스트/재발 방지 기준을 추가했습니다.- 이렇게 연결하면 단일 버그가 월간 성과로 과장되지 않고, 여러 개선 흐름 안에서 자연스럽게 정리됩니다.
✅ 21. AI에게 트러블슈팅 초안을 맡길 때 프롬프트
다음 문제 해결 기록을 바탕으로 트러블슈팅 문서 초안을 작성해줘.
조건:
1. 한국어로 작성
2. 실제 제공된 사실만 사용
3. 원인을 확정할 근거가 부족하면 “추정 원인”으로 표시
4. 문제 상황과 원인을 분리
5. 발생 조건과 재현 절차를 정리
6. 고객/관리자/데이터/운영 영향 범위를 구분
7. Trigger와 Root Cause를 가능하면 구분
8. 해결 방법과 선택 이유를 작성
9. 검증한 항목과 아직 검증하지 않은 항목을 구분
10. 재발 방지 TODO를 작성
11. 관련 커밋과 변경 파일을 정리
12. Secret, 전화번호 원본, 고객 개인정보, DB 접속정보는 포함하지 말 것
입력:
- 문제 제목:
- 문제 상황:
- 발생 환경:
- 재현 절차:
- 에러 코드:
- 관련 로그:
- 관련 커밋:
- 변경 파일:
- 원인 메모:
- 해결 방법:
- 검증 결과:➕ 21-1. 중요한 조건
원인을 임의로 만들어내지 말 것
실제 검증하지 않은 내용을 검증 완료로 쓰지 말 것
배포 여부를 추측하지 말 것
운영 영향을 과장하지 말 것- 트러블슈팅 자동화에서는 정확성이 요약 품질보다 더 중요합니다.
✅ 22. 로그 입력 시 보안 기준
- 트러블슈팅 자동화에서 가장 위험한 입력은 로그입니다.
- 에러 로그에는 개인정보와 Secret이 들어 있을 수 있습니다.
➕ 22-1. 자동 제거 대상
Authorization header
Cookie
Set-Cookie
JWT
accessToken
refreshToken
DATABASE_URL
AWS Access Key
API Key
Webhook Secret
전화번호
이메일
고객 이름
주소➕ 22-2. 좋은 입력
requestId=req_123
errorCode=CONSULT_STATUS_CONFLICT
consultId=532
statusCode=409
durationMs=145➕ 22-3. 피해야 할 입력
phone=01012345678
Authorization=Bearer eyJ...
DATABASE_URL=postgresql://...
customerMemo=...- AI에게 로그를 전달하기 전에 sanitize하는 구조가 필요합니다.
✅ 23. Troubleshooting Sanitizer
const REDACT_PATTERNS = [
/Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
/postgres(?:ql)?:\/\/[^\s]+/gi,
/\b01[016789]-?\d{3,4}-?\d{4}\b/g,
];
export function sanitizeTroubleshootingInput(input: string) {
let result = input;
for (const pattern of REDACT_PATTERNS) {
result = result.replace(pattern, '[REDACTED]');
}
return result;
}➕ 23-1. 추가 기준
.env 파일 자체 제외
로그 파일 전체 전달 지양
필요한 줄만 추출
secret key 이름 감지
response body 전체 전달 지양- 정규식 하나로 완벽한 보안을 만들 수는 없습니다.
- 자동 필터 + 수동 검토를 같이 써야 합니다.
✅ 24. 트러블슈팅 검색 체계
- 문서를 쌓는 것보다 나중에 찾을 수 있는 것이 중요합니다.
- 제목, 태그, 에러 코드, 도메인 기준으로 검색할 수 있어야 합니다.
➕ 24-1. 제목 규칙
Troubleshooting: 상담 상태 변경 후 목록 캐시 미갱신
Troubleshooting: Prisma migration 이후 상담 신청 500 오류
Troubleshooting: 알림톡 Worker 중복 발송➕ 24-2. 검색 태그
domain:
consult
product
export
notification
webhook
database
auth
cause:
transaction
cache
migration
permission
timeout
duplicate
race-condition➕ 24-3. 에러 코드
CONSULT_STATUS_CONFLICT
P2002
NOTIFICATION_PROVIDER_TIMEOUT
WEBHOOK_SIGNATURE_INVALID- 나중에는 “P2002 관련 과거 이슈”, “notification timeout 문제”처럼 검색할 수 있어야 합니다.
✅ 25. AI/Codex에게 트러블슈팅 자동화를 맡길 때 규칙
➕ 25-1. Codex 요청 예시
기존 llm-report CLI에 트러블슈팅 문서 자동 생성 기능을 추가해줘.
조건:
1. llm-report troubleshoot 명령어를 추가해줘
2. --project, --commit, --since, --upload-notion 옵션을 지원해줘
3. 사용자에게 문제 제목, 문제 상황, 영향 범위, 재현 절차, 원인, 해결 방법, 검증 결과, 재발 방지를 입력받게 해줘
4. Git에서 관련 commit과 변경 파일을 자동 수집해줘
5. 문서는 문제 상황, 발생 조건, 영향 범위, 원인, 해결 방법, 검증, 재발 방지, 관련 파일/커밋, 배운 점 구조로 생성해줘
6. severity는 P0/P1/P2/P3 중 선택할 수 있게 해줘
7. status는 INVESTIGATING, FIXED, TESTED, DEPLOYED, RESOLVED 중 선택할 수 있게 해줘
8. verification 상태를 별도로 저장해줘
9. 결과는 ~/shn/daily-report/<project>/troubleshooting/<YYYY-MM>/에 Markdown으로 저장해줘
10. Secret, DATABASE_URL, Authorization header, JWT, 전화번호, 고객 개인정보는 생성 전에 sanitize 해줘
11. AI가 원인을 확정할 근거가 없으면 추정 원인으로 표시하게 해줘
12. LLM 또는 Notion 업로드 실패 시에도 로컬 Markdown은 남게 해줘
13. 같은 문서를 주간/월간 리포트에서 참조할 수 있도록 frontmatter를 구조화해줘
14. 테스트 방법과 QA 체크리스트를 문서화해줘➕ 25-2. 리뷰 기준
문제와 원인을 분리하는가?
원인을 AI가 임의로 확정하지 않는가?
영향 범위/severity가 있는가?
검증 상태를 구분하는가?
관련 commit/file을 자동 수집하는가?
민감정보 sanitize가 먼저 실행되는가?
Notion 실패 시 로컬 파일이 남는가?
주간/월간 리포트와 연결 가능한가?- 이 기능은 기존
local-llm-work-report를 한 단계 더 실무적인 도구로 만드는 확장입니다.
✅ 26. 실무 체크리스트
➕ 26-1. 트러블슈팅 작성 체크리스트
- 실제 증상이 명확한가?
- 발생 조건이 기록되어 있는가?
- 재현 절차가 있는가?
- 영향 범위가 정리되어 있는가?
- 원인과 추정 원인이 구분되어 있는가?
- Root Cause까지 확인했는가?
- 해결 방법이 구체적인가?
- 재발 방지 항목이 있는가?
➕ 26-2. 검증 체크리스트
- 정상 케이스를 확인했는가?
- 실패 케이스를 확인했는가?
- 다른 기능 영향 여부를 확인했는가?
- DB 정합성을 확인했는가?
- 권한/보안 영향이 없는가?
- 자동 테스트가 추가됐는가?
- 배포 후 Smoke Test를 했는가?
- 운영 로그를 확인했는가?
➕ 26-3. Incident 체크리스트
- 장애 시작 시각이 기록되어 있는가?
- 복구 시각이 기록되어 있는가?
- 고객/관리자 영향 범위가 있는가?
- 타임라인이 있는가?
- 근본 원인이 확인됐는가?
- 임시 조치와 근본 해결이 구분되는가?
- 재발 방지 작업이 TODO로 남아 있는가?
- Postmortem이 작성되어 있는가?
➕ 26-4. 보안 체크리스트
- 전화번호 원본이 제거되어 있는가?
- Authorization header가 제거되어 있는가?
- JWT/token이 제거되어 있는가?
- DATABASE_URL이 제거되어 있는가?
- API Key/Secret이 제거되어 있는가?
- 고객 메모 원문이 포함되지 않는가?
- 로그 전체가 아닌 필요한 부분만 입력하는가?
- Notion 업로드 전 검토하는가?
✅ 27. AI에게 트러블슈팅/장애 회고 체계를 물어볼 때 좋은 질문법
Node.js CLI와 로컬 LLM을 활용해서 개발/운영 중 발생한 문제를 트러블슈팅 문서와 Incident Postmortem으로 자동 정리하는 시스템을 만들려고 해.
상황:
1. 온라인 휴대폰 판매몰을 1인 개발자로 운영하고 있음
2. NestJS/React/Prisma/PostgreSQL/AWS 기반이며 상담, 관리자, 상품, Export, 알림톡, Webhook 기능이 있음
3. 이미 일일/주간/월간 작업 보고서를 Markdown과 Notion에 정리하는 구조가 있음
4. 운영 장애나 해결이 오래 걸린 버그는 별도 Troubleshooting Markdown으로 남기고 싶음
5. 문제 상황, 발생 조건, 영향 범위, 원인, 해결 방법, 검증, 재발 방지 구조로 작성하고 싶음
6. 실제 운영에 영향을 준 장애는 Incident로 분리해 타임라인과 Postmortem까지 기록하고 싶음
7. Git commit, 변경 파일, 에러 코드, requestId는 자동 수집하고 싶음
8. 원인은 사람이 입력한 내용과 로그를 기반으로 하고, AI가 근거 없이 원인을 확정하면 안 됨
9. Secret, Authorization header, DATABASE_URL, JWT, 전화번호, 고객 개인정보는 AI/Notion에 전달되면 안 됨
10. 트러블슈팅 문서는 주간/월간 리포트와 포트폴리오 성과 후보에도 연결하고 싶음
요청:
- Troubleshooting 문서 템플릿
- Incident/Postmortem 템플릿
- severity/status/verification 상태값
- Git/로그 자동 수집 구조
- Root Cause와 Trigger 구분 기준
- 5 Whys 적용 기준
- 재발 방지 TODO 구조
- sanitize 기준
- CLI 명령어 설계
- Notion 필드 구조
- 주간/월간 리포트 연결 방식
- AI 프롬프트 예시
- 테스트/QA 체크리스트
를 실무 기준으로 정리해줘.➕ 27-1. AI 답변 검증 기준
문제 상황과 원인을 구분하는가?
AI가 원인을 근거 없이 만들어내지 않게 하는가?
severity와 영향 범위를 다루는가?
Incident와 일반 Troubleshooting을 구분하는가?
재발 방지를 “다음엔 조심” 수준으로 끝내지 않는가?
테스트/모니터링/체크리스트 개선으로 연결하는가?
민감정보 sanitize를 강하게 다루는가?
기존 일일/주간/월간 자동화와 연결하는가?📌 요약
- 트러블슈팅 문서는 운영 중 발생한 문제의 증상, 원인, 해결 방법, 검증, 재발 방지를 기록해 같은 문제를 반복해서 분석하는 시간을 줄이는 문서입니다.
- 모든 작은 버그를 문서화할 필요는 없고, 운영 영향이 크거나 분석 시간이 오래 걸렸거나 재발 가능성이 높은 문제를 우선 기록하는 것이 좋습니다.
- 문제 상황은 “z-index 문제”처럼 원인을 미리 단정하지 말고, 실제 사용자가 본 증상 중심으로 작성해야 합니다.
- 발생 조건과 재현 절차를 기록하면 나중에 다른 개발자나 AI/Codex도 같은 상황을 재현하고 분석하기 쉬워집니다.
- 영향 범위는 고객, 관리자, 데이터, 보안, 매출, 외부 API 기준으로 정리하고 P0~P3 severity를 두면 우선순위 관리가 쉬워집니다.
- 원인 분석에서는 문제를 드러낸 Trigger와 실제 구조적 Root Cause를 구분하는 것이 좋으며, 복잡한 장애에는 5 Whys를 활용할 수 있습니다.
- 해결 방법은 단순히 “수정 완료”가 아니라 기존 구조, 변경 구조, 선택 이유, 영향 파일을 기록해야 재사용 가치가 생깁니다.
- 검증은 로컬 확인, 자동 테스트, 배포 확인을 구분해야 하며, 실제 검증하지 않은 내용을 완료로 기록하면 안 됩니다.
- 실제 운영 서비스에 영향을 준 문제는 일반 Troubleshooting과 분리해 Incident로 관리하고, 장애 타임라인, 영향 범위, 복구 과정, Postmortem을 함께 남기는 것이 좋습니다.
- Postmortem의 목적은 사람을 탓하는 것이 아니라 테스트, 배포 체크리스트, 모니터링, validation, DB constraint 같은 시스템 개선으로 재발 가능성을 낮추는 것입니다.
- 장애 자체를 성과처럼 포장하면 안 되지만, 장애를 해결하고 재발 방지 체계를 추가한 경험은 포트폴리오와 경력기술서에서 실무 운영 역량으로 활용할 수 있습니다.
- 트러블슈팅 자동화에서는 Git commit과 변경 파일은 자동 수집할 수 있지만, 실제 증상, 영향, Root Cause, 검증 결과는 사람이 확인해야 정확합니다.
- 로그에는 Authorization, JWT, DATABASE_URL, API Key, 전화번호, 고객 개인정보가 포함될 수 있으므로 AI나 Notion에 전달하기 전에 반드시 sanitize해야 합니다.
- 기존 일일/주간/월간 리포트와 Troubleshooting/Incident 문서를 연결하면 단순 작업 기록이 아니라 개발 성과, 운영 경험, 재발 방지 지식이 누적되는 체계를 만들 수 있습니다.
