# 기계가 판정하는 실행 결과

> 출력 형식, 퍼미션 모드, 세션 식별자로 게이트 만들기

- Canonical: https://learning.reopt.ai/courses/claude-code-team-operations/lessons/ccto-m2-concept
- Language: ko-KR
- HTML: https://learning.reopt.ai/courses/claude-code-team-operations/lessons/ccto-m2-concept

---

[헤드리스와 팀 운영](/courses/claude-code-team-operations) 2. 출력 계약과 권한 기준선 3 / 9

# 기계가 판정하는 실행 결과

출력 형식, 퍼미션 모드, 세션 식별자로 게이트 만들기
개념 학습 45 XP 9분

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

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

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

- 1 출력 형식 고정 --output-format json 으로 바꿔 .result · session_id · total_cost_usd 를 수집합니다.

- 2 결과 구조 고정 --json-schema 로 기대 구조를 선언하고 structured_output 을 확인 대상에 넣습니다.

- 3 권한 기준선 명시 잠긴 실행은 dontAsk , 편집 중심 작업은 acceptEdits 로 --permission-mode 를 못박습니다.

- 4 실행 계보 묶기 --session-id 에 유효한 UUID를 주어 CI run id·PR id와 세션을 연결합니다.

실무에 남길 기준

- acceptEdits 는 파일 쓰기와 mkdir · touch · mv · cp 까지만 자동 승인한다
- 권한 규칙에서 Bash(git diff ) 의 앞 공백 하나가 매칭 범위를 바꾼다
- 실패한 실행은 원본 result 와 stderr를 artifact로 남겨야 재현할 수 있다

[이전](/courses/claude-code-team-operations/lessons/ccto-m1-quiz) 이해했어요 · 계속

---

에이전트용 사이트 안내: https://learning.reopt.ai/llms.txt · 사이트맵: https://learning.reopt.ai/sitemap.xml · 문의: https://learning.reopt.ai/contact