에이전트 오류를 사건 리뷰로 정리하는 템플릿

에이전트 오류는 단순히 실패 로그로 끝내면 다음에 같은 문제가 반복됩니다. 사건 리뷰는 누가 잘못했는지 찾는 문서가 아니라, 어떤 조건에서 문제가 발생했고 어떤 안전장치를 추가해야 하는지 정리하는 문서입니다.

템플릿의 첫 부분은 관찰된 사실입니다. 발생 시각, 사용한 모델 또는 도구, 입력 요약, 실제 출력, 기대 출력, 영향을 받은 페이지나 사용자 범위를 적습니다. 확인되지 않은 원인은 이 단계에 쓰지 않고, 로그에서 보이는 사실만 남깁니다.

두 번째 부분은 원인 후보입니다. 프롬프트 조건 부족, 도구 권한 오류, API timeout, UI selector 변경, 데이터 부족, 검증 누락처럼 가능한 원인을 나눕니다. 각 원인 옆에는 확인 방법을 적어 추측과 검증을 분리합니다.

세 번째 부분은 즉시 조치입니다. 문제가 되는 글을 숨겼는지, 토큰을 회수했는지, 자동 게시를 멈췄는지, 사용자에게 안내했는지 기록합니다. 즉시 조치는 원인을 완전히 해결하지 못해도 피해를 줄이는 데 집중합니다.

네 번째 부분은 재발 방지입니다. 입력 검증 추가, 공개 전 길이 검사, 중복 검사, noindex 기본값, timeout 재시도, 운영자 승인 단계를 추가할 수 있습니다. 재발 방지는 한 번에 크게 고치기보다 작은 기준을 여러 곳에 배치하는 편이 안정적입니다.

마지막으로 공개 버전을 따로 만듭니다. 내부 사건 리뷰에는 경로와 로그가 필요하지만, 공개 문서에는 개인정보와 토큰을 제거하고 배운 점만 남깁니다. 이렇게 하면 실패가 사이트 품질을 해치는 기록이 아니라 독자가 배울 수 있는 운영 지식이 됩니다.

사건 리뷰에는 시간 순서가 필요합니다. 언제 문제가 시작됐고, 언제 발견됐고, 어떤 조치를 먼저 했는지 적으면 대응의 빈틈이 보입니다. 시간 순서가 없으면 실제 원인보다 눈에 띄는 증상만 고치게 됩니다.

리뷰의 결론은 반드시 소유자를 가져야 합니다. 재발 방지 항목마다 담당자, 완료 조건, 확인 날짜를 적습니다. 담당자가 없으면 문서는 좋아 보여도 실행되지 않습니다. 자동화 운영에서는 작은 미완료 항목이 다음 장애의 원인이 되기 쉽습니다.

공개 사건 리뷰는 브랜드 방어용 문서가 아니라 학습 자료입니다. 어떤 판단이 틀렸는지, 어떤 검사가 부족했는지, 어떤 기준을 새로 만들었는지를 솔직하게 적습니다. 이 방식은 개발자 독자에게 실제 가치가 있고 사이트의 전문성을 보여줍니다.

템플릿은 짧아도 반복 가능해야 합니다. 사건 제목, 영향, 원인 후보, 즉시 조치, 재발 방지, 확인 결과 여섯 항목만 있어도 대부분의 오류를 정리할 수 있습니다. 중요한 것은 모든 사건을 같은 형식으로 남겨 나중에 비교할 수 있게 하는 것입니다.

에이전트 오류는 사람의 실수와 다르게 대량 반복될 수 있습니다. 그래서 한 번의 잘못된 답변보다 같은 조건에서 반복될 가능성을 더 크게 봐야 합니다. 사건 리뷰는 그 반복 가능성을 낮추는 안전장치를 설계하는 문서입니다.