4.0 KiB
4.0 KiB
title, source_type, status, related_branches, related_projects, tags, created, status_label
| title | source_type | status | related_branches | related_projects | tags | created | status_label | |
|---|---|---|---|---|---|---|---|---|
| error / {{short-error-slug}} | error-note | raw |
|
YYYY-MM-DD | open |
error: {{short-error-slug}}
Layer:
raw/errors/— 작업 중 마주친 단일 실패·트러블슈팅 기록. 해결되면 wiki/concepts(공통 패턴) 또는 wiki/projects(프로젝트 특화)로/ingest시 일부 추출 가능. 원본은 raw에 영구 보관.status_label:open|investigating|resolved|workaround|wontfix|needs-confirmation
Citation / honesty discipline (필수):
## 증상의 에러 메시지는 원문 그대로 (paraphrase 금지). stack trace 핵심 부분만 발췌해도 verbatim 유지.## 재현 절차는 타인이 그대로 재현할 수 있는지 기준으로 명령·파일 변경·기대값/실제값을 적는다. 빈 상태로 두지 말 것.## 조사 단계는 시간순으로 시도와 결과를 모두 기록한다 (막다른 길 포함). 사후에 "원인은 X였다" 만 적으면 재발 시 패턴 인식 불가능.## 근본 원인의 "직접 원인 / 근본 원인 / 트리거 조건" 셋을 분리. "직접 원인" 만 적으면 다음 비슷한 상황을 인지 못 함.## 회고의 "빨리 감지하는 신호" 는 다음에 같은 에러를 더 빨리 잡기 위한 키워드 (예: "메시지에Read-only file system이 나오면 sandbox 권한 의심"). 추상적인 교훈만 적지 않는다.
부모
이 에러가 어느 작업 묶음에 속하는지 명시. 최소 1개 필수. 작업 외 발생 시(예: 환경 셋업 중)
[[raw/project-notes/<project>]]로 연결.
[[raw/branch-notes/{{branch-name}}]]- (또는)
[[raw/project-notes/{{project-name}}]]
증상
무슨 일이 일어났는가. 에러 메시지 원문, stack trace 핵심 부분, 발생 화면/명령 등.
- 에러 메시지 (원문 그대로):
<verbatim message> - 발생 컨텍스트: <어떤 명령·요청·UI 동작에서 발생>
- 발생 시점: YYYY-MM-DD HH:MM
- 발생 환경: <local / dev / staging / prod / CI>
- 재현 가능 여부:
always|sometimes|once
재현 절차
"타인이 이걸 보고 재현할 수 있는가" 기준. 명령 한 줄 또는 step-by-step.
- <단계 1>
- <단계 2>
- <기대 결과> vs <실제 결과>
조사 단계
시도한 것 + 결과를 시간 순으로. 막다른 길도 기록 (다음에 같은 길로 안 가기 위함).
- YYYY-MM-DD HH:MM — <시도한 것> → <결과·관측>
- YYYY-MM-DD HH:MM — <시도한 것> → <결과·관측>
근본 원인
사실에 입각해 결론. 추측이라면
needs-confirmation으로 표시.
- 직접 원인:
- 근본 원인:
- 트리거 조건:
근거 (해결 근거가 된 자료, 최소 1개+ 권장)
공식 문서·기술 블로그·이슈 트래커 링크. raw에 보관한 원문 발췌가 있다면
[[raw/official-docs/...]]또는[[raw/company-tech-blogs/...]]로 연결.
[[raw/official-docs/<...>]]— <어떤 부분이 근거인지 한 줄>[[raw/company-tech-blogs/<...>]]— <어떤 부분이 근거인지 한 줄>- 외부 URL (raw에 안 넣은 즉석 참조): — <한 줄 메모>
해결
어떻게 막았는가. 코드/설정/명령 변경 사항을 구체적으로.
- 적용한 조치:
- 검증 방법: <테스트·로그·재현 명령으로 확인>
- 잔여 위험 / 후속 작업: <있다면>
회고
다음번에 같은 에러를 더 빨리 잡으려면 무엇을 기억할지.
- 빨리 감지하는 신호:
- 예방 체크리스트 항목 후보:
- wiki로 끌어올릴 가치가 있는 일반화된 교훈: <있다면 wiki/concepts 추출 후보로 메모>
관련
같은 작업 묶음 내 다른 raw 문서.
- 트리거된 daily note:
[[raw/daily-notes/YYYY-MM-DD]] - 관련 에러 (선행/후속/유사):
[[raw/errors/<...>]] - 관련 wiki 개념:
[[wiki/concepts/<...>]](이미 검증된 요약 있을 시)