AI 에이전트 스킬을 수정했는데 왜 팀마다 다르게 움직일까? 실행기별 계약 테스트로 배포하는 법

읽는 시간 약 9분

먼저 답하면: 공용 AI 에이전트 지침을 고쳤다는 사실만으로 배포를 승인하면 안 됩니다. 같은 대표 업무를 각 실행기에서 다시 돌려, 필수 행동·금지 행동·산출물 형식·증거 기록이 공통 계약을 만족하는지 확인한 뒤에만 승격해야 합니다. 하나라도 어긋나면 지침 파일만이 아니라 해당 실행기의 연결 설정까지 이전 버전으로 함께 되돌리는 편이 안전합니다.

Claude, Codex, GitHub Copilot처럼 여러 실행기에 같은 업무 규칙을 배포하는 팀이라면 이런 장면을 한 번쯤 만납니다. 한쪽에서는 근거를 빠짐없이 남기는데, 다른 쪽에서는 허용되지 않은 도구를 먼저 쓰거나 결과 형식이 달라집니다. 이 글은 그 차이를 없애겠다고 약속하는 글이 아닙니다. 대신 변경을 어디에서 멈추고, 무엇을 보고 승인하거나 되돌릴지를 정하는 실무 틀을 제안합니다.

핵심 요약

공용 지침은 파일 하나가 아니라 업무 계약과 실행기별 연결 설정의 조합으로 보셔야 합니다.
정상 완료만 시험하지 말고 근거 누락, 금지 도구 호출, 승인 없는 외부 변경, 형식 오류를 함께 확인해야 합니다.
승격 조건은 임의의 성공 비율보다 필수 항목 통과·금지 동작 0건·재현 가능한 기록처럼 명확하게 두는 편이 좋습니다.
실패하면 이전 버전의 manifest와 실행기별 adapter를 함께 복귀시키고, 실패 기록은 다음 회귀 시험에 추가합니다.

공통 업무 계약에서 세 실행기별 어댑터로 연결되는 AI 에이전트 지침 배포 구조 — 공통 계약은 고정하고, 실행기에 따라 달라지는 연결부를 분리해 보세요.

같은 규칙인데 결과가 다른 이유

재사용 가능한 지침 자산은 이미 여러 제품에서 중요한 운영 단위가 되었습니다. Anthropic은 Skills를 지침·스크립트·리소스를 묶어 재사용하는 단위로 소개하며, OpenAI도 SKILL.md를 포함한 버전 관리 bundle을 문서화합니다. GitHub Copilot의 custom agent 역시 저장소·조직·엔터프라이즈 범위에서 도구와 행동 지침을 별도로 가진 실행 표면입니다.

하지만 이 사실이 파일 형식이나 결과가 서로 자동으로 같다는 뜻은 아닙니다. 실행기마다 읽는 설정 위치, 연결 가능한 도구, 승인 흐름, 출력 방식이 다를 수 있습니다. 그래서 “지침 버전 1.4를 배포했다”보다 “각 실행기가 1.4 계약을 대표 업무에서 만족했다”가 더 중요한 기록이 됩니다.

먼저 분리할 것: 공통 업무 계약과 실행기별 adapter

공통 업무 계약은 “무엇을 해야 하는가”를 적는 곳입니다. 실행기별 adapter는 “각 환경에서 그 계약을 어디에 연결하는가”만 담당합니다. 이 둘을 한 파일에 섞어 두면, 한 실행기 편의를 위한 수정이 다른 실행기의 행동까지 바꿨는지 알기 어려워집니다.

구분	공통으로 고정할 항목	실행기별로 달라질 항목	검증 증거
목표	고객 문의를 분류하고 허용된 지식베이스를 인용해 초안을 만듭니다.	지침 또는 agent profile을 연결하는 위치	완료 산출물과 task ID
도구 경계	허용된 지식베이스만 조회하고 외부 변경은 승인 요청으로 멈춥니다.	도구 이름, 권한 설정, MCP 연결	도구 호출 기록과 승인 요청
필수 증거	근거 링크와 분류 근거를 결과에 남깁니다.	trace 또는 실행 로그를 보관하는 방식	결과의 근거 필드와 trace URL
산출물	분류, 초안, 인용, 승인 필요 여부를 정해진 형식으로 냅니다.	출력 템플릿과 schema 검사 위치	형식 검사 결과

예를 들어 한 실행기에서만 외부 티켓 생성 도구가 연결돼 있다면, adapter에는 그 도구가 승인 전에는 호출되지 않아야 한다는 연결 규칙을 둡니다. 공통 계약에는 “승인 없는 외부 변경 금지”라는 행동 원칙을 둡니다. 이렇게 나누면 보안·권한 검토는 adapter에서, 결과 품질 검토는 공통 계약에서 동시에 할 수 있습니다.

도구 호출의 승인 경계를 설계할 때는 AI 에이전트의 도구 호출을 코드로 묶어도 될까? 병렬 처리와 승인 경계를 나누는 결정표도 함께 참고해 보세요. 설치 단계의 출처와 권한 검토는 AI 에이전트 스킬을 설치하기 전: 출처·훅·권한을 거르는 7단계 수용 게이트에서 별도로 다룹니다.

변경 전후에 돌릴 golden task 5종

대표 업무는 실제 팀의 위험을 압축해 보여주는 작은 재현 시나리오입니다. OpenAI의 평가 가이드는 지침 준수, 도구 선택, 도구 인자 정확도를 평가 대상으로 두고 변경마다 지속 평가를 실행하라고 권합니다. 아래 다섯 가지는 특정 제품 기능이 아니라, 공용 업무 규칙을 바꿀 때 확인할 수 있는 최소한의 시험 세트입니다.

AI 에이전트 지침 변경을 검증하는 다섯 가지 golden task 카드 — 정상 경로 하나만 통과해도 배포를 승인하기에는 부족합니다.

테스트	통과 조건	차단 실패	남길 기록
정상 완료	분류·초안·허용된 근거가 모두 있습니다.	필수 산출물 필드 누락	task ID, 결과, 근거 링크
근거 누락	근거가 없으면 완료 대신 보완 요청으로 전환합니다.	근거 없이 단정한 초안	누락 감지 결과
금지 도구	허용 목록 밖 도구를 호출하지 않습니다.	차단 없이 외부 도구 호출	도구 호출 목록
외부 변경	티켓 생성·전송 같은 변경 전 승인 요청으로 멈춥니다.	승인 없이 실제 변경 수행	승인 요청과 응답
형식 오류	정해진 schema에 맞지 않으면 실패로 처리합니다.	보기 좋은 문장으로 오류를 숨김	schema 검사 결과

구체적인 실패 조건을 미리 적어 두는 것이 핵심입니다. 예를 들어 결과에 인용 필드가 없거나, 허용되지 않은 도구 호출이 보이거나, 승인 없이 외부 시스템을 바꾸려 했다면 다른 항목이 좋아도 승격을 멈춥니다. 성공률 하나로 묶으면 이러한 위험이 평균값에 가려질 수 있습니다.

각 task의 기록에는 실행기 이름, 지침 버전, adapter 버전, task ID, 통과·실패, 검토자, trace 위치를 남기세요. 어떤 기록을 남겨야 하는지 더 넓은 관점은 AI 에이전트는 성공률만 보면 안 되는 이유: 추적과 평가의 최소 단위에서 확인할 수 있습니다.

승격을 막아야 하는 실패와 rollback 절차

승격 판정은 복잡할 필요가 없습니다. 다만 누구나 같은 결론을 낼 수 있도록 필수 조건을 고정해야 합니다. 아래 네 항목을 모두 만족할 때만 다음 환경으로 올리는 규칙부터 시작해 보세요.

모든 필수 golden task가 통과했습니다.
허용되지 않은 도구 호출과 승인 없는 외부 변경이 0건입니다.
산출물 형식 검사를 통과했고, 필수 근거가 남아 있습니다.
각 실행기의 결과를 다시 확인할 수 있는 기록이 있습니다.

AI 에이전트 지침 변경의 승격 차단과 롤백 흐름도 — 차단은 실패가 아니라, 더 큰 운영 문제를 앞에서 발견하는 장치입니다.

한 항목이라도 실패했다면 지침 파일만 되돌리지 마세요. 이전 release manifest가 가리키는 지침 버전과 각 실행기의 adapter 버전을 함께 복귀시킨 뒤, 같은 task를 다시 돌려 복귀가 실제로 됐는지 확인합니다. 특히 권한 관련 변경은 기존 조직 정책, 비밀값 처리 방식, sandbox 경계와 맞는지 별도 검토가 필요합니다.

작게 시작하는 release manifest 템플릿

처음부터 거대한 플랫폼을 만들 필요는 없습니다. 저장소에 아래 정보를 가진 manifest 한 장과 실행기별 adapter 목록을 두는 것부터 시작할 수 있습니다. 실제 필드명은 팀의 도구에 맞게 바꾸되, 무엇을 검증하고 되돌릴지 빠지지 않게 하는 것이 목적입니다.

version: 1.4.0
contract: customer-inquiry-draft
supported_runners:
  - runner: claude
    adapter_version: 1.4.0
  - runner: codex
    adapter_version: 1.4.0
allowed_tools:
  - approved-knowledge-base
required_artifacts:
  - classification
  - draft
  - citations
  - approval_required
blocking_rules:
  - no-unapproved-external-change
  - schema-must-pass
rollback_version: 1.3.2

이 파일은 특정 제품의 필수 포맷이 아니라, FLOWIT이 제안하는 운영 예시입니다. 핵심은 변경 요청마다 “어느 실행기에서, 어떤 대표 업무를, 어떤 증거로 확인했는가”를 같은 자리에서 읽을 수 있게 하는 것입니다. 산출물을 결정적으로 검사할 수 있도록 설계하는 방법은 AI 에이전트에게 계산을 맡기기 전: 추론과 결정적 함수의 경계를 정하는 5문항도 도움이 됩니다.

배포 전 점검표

업무 계약의 목표·허용 도구·필수 근거·금지 동작·산출물 형식을 한곳에 기록했나요?
각 실행기의 adapter가 어떤 설정 파일 또는 프로필을 바꾸는지 알 수 있나요?
정상 경로 외에 권한 요청, 금지 도구, 형식 오류를 시험했나요?
필수 task 통과, 금지 동작 0건, 형식 통과, 재현 기록을 승격 조건으로 뒀나요?
실패 시 이전 manifest와 adapter를 함께 되돌리고, 실패 trace를 다음 시험에 추가하나요?

공용 지침을 운영한다는 것은 문서를 잘 쓰는 일에서 끝나지 않습니다. 같은 업무 계약을 실제 실행기에서 확인하고, 위험한 변화는 앞에서 멈추며, 되돌아갈 길을 남겨 두는 일이 함께 필요합니다.

자주 묻는 질문

실행기가 하나뿐이어도 계약 테스트가 필요한가요?

필요합니다. 다만 처음에는 정상 완료, 승인 없는 외부 변경 시도, 산출물 형식 오류처럼 위험이 큰 세 가지부터 시작해도 됩니다. 실행기가 하나여도 지침·도구·권한 설정이 함께 바뀔 수 있기 때문입니다.

사람 검토는 어느 단계에 두는 것이 좋나요?

외부 변경, 민감한 권한 요청, 근거가 불충분한 결과처럼 자동 규칙만으로 판단하기 어려운 지점에 두는 편이 좋습니다. 사람 검토가 필요한 이유와 요청 내용을 결과에 분명히 남기세요.

모든 실행기의 결과 문장이 완전히 같아야 하나요?

그럴 필요는 없습니다. 문장 표현은 달라도 됩니다. 대신 필수 근거, 금지 동작, 승인 경계, 산출물 형식처럼 팀이 약속한 행동 조건이 충족되는지를 비교하세요.

실패한 기록은 언제 시험 세트에 넣어야 하나요?

원인을 확인해 재현 가능한 입력과 기대 결과를 정리한 직후 넣는 것이 좋습니다. 같은 유형의 변경이 다시 들어올 때, 과거의 운영 문제를 빠르게 발견할 수 있습니다.

참고 자료

Anthropic, Introducing Agent Skills — 재사용 가능한 skill 자산과 관리 범위를 설명합니다.
OpenAI API, Skills — SKILL.md를 포함한 versioned bundle의 개념을 설명합니다.
GitHub Docs, Creating custom agents for Copilot cloud agent — custom agent의 구성 범위와 설정 표면을 설명합니다.
OpenAI API, Evaluation best practices — 지침 준수와 도구 사용을 지속적으로 평가하는 일반 원칙을 설명합니다.