9장. 출력 형식을 계약한다

사람이 읽는 문서도 구조가 필요하다. “알아서 보기 좋게”라고 하면 매번 제목과 항목이 달라져 비교와 자동 처리가 어렵다. 결정 브리프라면 결론, 근거, 위험, 반대 조건, 다음 행동을 고정한다.

# 결정

## 권고
- 시작 / 조건부 시작 / 연기

## 근거
- 주장 [source_id]

## 위험과 완화
- 위험 / 영향 / 완화 / owner

## 반대 조건
- 어떤 사실이 바뀌면 결정을 뒤집는가

## 승인 요청
- 행동 / 승인자 / 기한 / 롤백

기계가 읽는 결과에는 JSON Schema 같은 검사를 쓸 수 있다. 그러나 형식 검증과 의미 검증을 구분한다. source_id 필드가 있다고 실제 근거가 맞는 것은 아니다. 날짜 문자열이 형식에 맞아도 미래 날짜일 수 있다.

{
  "recommendation": "conditional_launch",
  "claims": [
    {"text": "...", "source_ids": ["SRC-01"], "confidence": "supported"}
  ],
  "approval": {"required": true, "action": "invite_beta_users"}
}

출력 형식을 너무 세밀하게 고정하면 모델이 중요한 예외를 넣을 자리가 사라진다. unknowns, conflicts, notes 같은 안전한 탈출구를 둔다. 추가 필드를 허용하지 않는 기계 계약에서는 별도 warnings 배열을 필수로 만든다.

표는 비교에 좋지만 모바일과 접근성에서 불편할 수 있다. 열이 여섯 개를 넘으면 카드나 목록으로 바꾼다. 코드는 언어와 파일명을 표시하고 실행 위치를 설명한다.

구조화 출력의 실패를 처리한다

JSON 파싱 실패를 모델 호출 재시도로만 해결하면 비용이 늘고 같은 오류가 반복된다. 먼저 응답이 잘렸는지, schema가 모순인지, 출력 상한이 충분한지 확인한다. 유효성 검사 오류를 안전한 필드 수준 메시지로 모델에 돌려 주되 원본 비밀정보를 포함하지 않는다.

1차: JSON parse
2차: schema validation
3차: source_id 존재 확인
4차: 의미 rubric
5차: 사람 승인

파싱이 성공해도 recommendation 값이 허용 enum인지 확인한다. 알려지지 않은 값은 기본 행동으로 매핑하지 말고 실패로 처리한다. 특히 approve로 default하는 코드는 위험하다. 알 수 없을 때의 기본 상태는 blocked 또는 awaiting_review다.