기계가 판정하는 실행 결과 | 헤드리스와 팀 운영

헤드리스 잡의 진짜 위험은 실패가 아니라 실패인지 알 수 없는 성공입니다. 사람이 읽는 텍스트만 stdout에 찍히고 종료 코드가 늘 0이면 어떤 날의 결과가 쓸 만했는지 사후에 구분할 수 없습니다. --output-format json은 .result와 함께 session_id, total_cost_usd를 주고, --json-schema를 얹으면 검증된 결과가 structured_output에 담깁니다. 권한도 기본값에 맡기면 안 됩니다. v2.1.200부터 기본 permission mode가 Manual로 바뀐 것처럼 기본값은 릴리스마다 움직이므로, CI에서는 --permission-mode를 항상 명시해 기준선을 고정합니다.

CI가 읽어야 할 신호	어디서 나오나	없으면 벌어지는 일
종료 코드	모든 헤드리스 호출	실패는 알아도 원인은 모름
`total_cost_usd`	`--output-format json` 응답	호출당 지출을 사후에도 못 셈
`structured_output`	`--json-schema` 병행 시	비구조화 폴백을 성공으로 오인
`plugin_errors`	`stream-json`의 init 이벤트	플러그인 미로드가 조용히 통과
`system/api_retry`	재시도 직전 스트림 이벤트	지연 원인을 타임아웃으로 오판

스트리밍 이벤트는 `--verbose --include-partial-messages`를 함께 줘야 나옵니다.

출력 형식 고정--output-format json으로 바꿔 .result·session_id·total_cost_usd를 수집합니다.
결과 구조 고정--json-schema로 기대 구조를 선언하고 structured_output을 확인 대상에 넣습니다.
권한 기준선 명시잠긴 실행은 dontAsk, 편집 중심 작업은 acceptEdits로 --permission-mode를 못박습니다.
실행 계보 묶기--session-id에 유효한 UUID를 주어 CI run id·PR id와 세션을 연결합니다.