지정해주신 소스 문서(raw/7 Coding Patterns I Stole From Senior Engineers.md)를 분석하고 지정 템플릿과 LLM Wiki 작성 원칙에 맞추어 구조화된 에러 추적 설계 노트를 작성 완료했습니다.
해당 노트는 llm-wiki/wiki/구조화된 에러 추적 설계.md 경로에 저장되었습니다.
작성 내용 요약
---
type: workflow
status: draft
core: false
tags:
- llm
- agent
- error-handling
- debugging
- architecture
aliases:
- Structured Error Tracking Design
- 에러 추적 설계
sources:
- 'raw/7 Coding Patterns I Stole From Senior Engineers.md'
created: 2026-08-27
updated: 2026-08-27
---
# 구조화된 에러 추적 설계
## 한 줄 정의
구조화된 에러 추적 설계는 모호한 텍스트 에러 대신 시스템 식별용 [[구조화된 출력 및 도구 호출|에러 코드]]와 비즈니스 컨텍스트(요청 ID, 엔티티 ID, 실패 사유)를 결합하여, 디버깅 및 AI 에이전트 장애 분석의 효율성을 극대화하는 소프트웨어 설계 방식이다.
## 핵심 요지
- **기계와 인간 분리**: 모호한 단일 에러 메시지(`"Something went wrong"`) 대신, 시스템은 기계 식별용 코드(`code`), 사용자는 가독용 메시지(`message`), 로그는 명확한 맥락 객체(`details`, `requestId`)를 전달해야 한다 (raw/7 Coding Patterns I Stole From Senior Engineers.md).
- **문자열 구문 분석 방지**: 클라이언트나 프론트엔드가 에러 메시지 문자열(`error.message.includes("...")`)을 직접 파싱하는 취약한 구조를 차단하고 시스템 안전성을 확보한다 (raw/7 Coding Patterns I Stole From Senior Engineers.md).
- **보안 및 트레이싱 조화**: 흉측한 스택 트레이스나 비밀번호·인증 토큰 등 기밀 데이터를 외부로 노출하지 않으면서, 내부 로그에는 `requestId` 기반으로 역추적 가능한 식별자와 구조화된 사유를 남긴다 (raw/7 Coding Patterns I Stole From Senior Engineers.md).
- **LLM/에이전트와의 호환성**: [[AI 에이전트 제어 루프]] 또는 [[샌드박스 코드 실행]] 환경에서 LLM이 시스템 장애를 자동으로 파악하고 자가 수리(self-healing)를 수행하려면 고도로 규격화된 에러 응답 구조가 필수적이다.
## 상세
... (글로벌 에러 핸들러 규격, JSON 구조화 출력, 보안 관점의 트레이스 ID 처리 등 기재)
## 예시
... (Fastify/Express 백엔드 및 Claude 3.5 Sonnet / GPT-4o 에이전트 연동용 커스텀 에러 클래스 예시 코드 포함)
## 충돌
본 소스 문서 및 기존 개념 간에 직접적인 주장의 충돌은 발견되지 않았다.
## 관련 노트
- [[불가능한 상태 차단 데이터 모델링]]
- [[시니어 엔지니어링 의사결정 역량]]
- [[구조화된 출력 및 도구 호출]]
- [[장애 대응 4단계 구조화 소통법]]