외부에 공개되어 있는 AI 에이전트 정의(이하, 에이전트 정의)를 자신의 환경으로 가져올 때, 단순히 "작동했다"로 끝내지 않고, 실행 전 리뷰(Pre-execution Review)·동작 확인·출처 관리·제3자 리뷰까지를 운용 프로세스로 돌리는 방법을 기술한다.

대상 독자는 이미 Claude Code/Codex 등으로 에이전트 정의를 자체 제작 및 운용하고 있으며, 외부 컬렉션과의 통합, Git 운용, Reviewer 체제 설계로 깊이 있게 들어가고 싶은 실무자이다.

예시로는 agency-agents의 공식 리포지토리(MIT License)를 지속적으로 참조한다.

후보 선정의 기점

외부의 에이전트 정의 모음집을 발견했을 때, 가장 먼저 떠오르기 쉬운 질문은 "이 컬렉션에서 무엇을 가져올 것인가"이다. 이 질문은 지금 내 손안의 환경에 무엇이 부족한가가 아니라, 외부 목록에 무엇이 나열되어 있는가를 기점으로 삼고 있다. 소개글의 매력에 이끌려 용도가 비슷한 역할까지 함께 늘려버리는 이유는 여기에 있다. 기점을 "현재 운용에 무엇이 부족한가"로 전환하면, 후보를 읽는 목적이 정해지고, 다음 전체 리뷰(Full Review)에서 무엇을 확인해야 할지도 좁혀진다.

외부의 선택지가 풍부하다는 것과 그것을 실행 환경에 모두 상주시키는 것은 별개의 문제이다. 사용할 수 있는 지식의 폭은 저장된 파일의 양만으로 결정되지 않는다. 필요할 때 후보로 돌아갈 수 있다는 것, 선택한 이유와 적용 범위를 설명할 수 있다는 점이 더 중요하다.

부족함은 "코드 리뷰가 필요하다"와 같은 넓은 단어로는 기능하지 않는다. 입력, 기대하는 출력, 금지하고 싶은 행동까지 포함하여 한 문장으로 만든다. 예를 들어, 미지의 코드베이스를 변경하지 않고 조사하며, 확인한 사실과 추측을 나누어 반환하는 역할이 없다,는 정도의 입도(Granularity)까지 좁힌다. 여기까지 구체화해야 비로소 기존의 조사역이나 리뷰역으로 대체할 수 없는지를 비교할 수 있다. 한 문장으로 정의할 수 없는 부족함은 도입을 보류할 대상이 된다. 보류는 외부 자산을 부정하는 판단이 아니라, README를 참조처로 남겨두고 필요성이 구체화된 시점에 다시 읽으면 된다.

부족함을 한 문장으로 쓸 때의 형식은, 직함이 아니라 업무의 경계(Boundary)로 한다. 입력(대상 종류와 전제, 기밀 정보를 포함할 수 있는지), 판단(확인하는 관점과 사실과 추측을 어떻게 나눌 것인지), 성과물(보고만 하는지, 수정안인지, 실제 파일 변경까지 포함하는지), 금지 행동(권한을 확장하지 않기 위한 명시)의 4점을 하나의 흐름으로 작성한다. 이 4점이 갖춰져야 비로소 후보의 비교는 "왠지 좋아 보인다"에서 "이 경계를 충족하는가"로 바뀐다. 다음 전체 리뷰는 이 경계를 충족하는지 확인하는 작업이 된다.

실행 환경에 두기 전의 전체 리뷰

소개글이나 README의 요약만으로 에이전트 정의를 채택하지 않는다. 후보 파일의 전문을 읽고 다음을 확인한다.

• 상정하는 입력의 종류와 전제(리포지토리를 읽는지, 공개 문서를 읽는지, 대화를 받는지)
• 출력 형식(보고만 하는지, 수정안인지, 실제 파일 변경인지)
• 참조하는 외부 파일·실행 명령어·이용 도구 목록
• 네트워크 액세스·파일 쓰기 전제
• 명시되어 있는 금지 사항

외부 정의가 참조하는 경로·명령어는 제공처의 환경에서는 올바르더라도, 내 환경에는 존재하지 않을 수 있다. 존재하지 않는 참조를 편의에 따라 해석하여 보완하면, 의도치 않게 원래의 역할에서 벗어난 동작이 된다. 작동시키기 위해 무엇을 바꿔야 하는지를 적용 전에 열거한다.

처음부터 실행 환경에 바로 배치하지 않는다. 자동 실행되는 디렉토리(Claude Code라면 ~/.claude/agents/ 등)에 두면, 내용을 이해하기도 전에 후보로 인식될 가능성이 있다. 우선 읽기 전용의 임시 배치 장소에서 확인하고, 채택 판단이 끝난 후에 정식 배치로 진행한다.

권한은 정의 파일의 기술만으로 단정하지 않는다. 실제로 사용할 수 있는 셸(Shell)·브라우저·네트워크·파일 쓰기는 호스트 측의 설정(Claude Code라면 settings.json의 permissions 등)에도 의존한다. 외부 정의와 호스트 설정 양쪽을 확인하여, 필요 이상의 권한을 주지 않는다.

로컬 규약으로의 적응은 최소 차분으로 유지한다

채택하는 경우에도 처음부터 크게 다시 쓰지 않는다. 필요한 차분(Diff)만 적용하여, 외부 원문과 로컬 버전의 대응 관계를 추적할 수 있도록 한다.

적응은 두 종류로 나누어 기록한다.

형식 조정: 이름, frontmatter(정의 파일 도입부의 YAML 설정란), 배치 경로, 호출 조건 등 실행에 필요한 정합성을 맞추기 위한 변경.

의미 변경: 금지 사항을 삭제함, 권한을 확장함, 성과물의 종류를 바꿈, 참조처를 다른 메커니즘으로 교체함과 같은 변경. 이는 원래 정의의 조정이 아니라, 로컬 독자적인 설계 판단에 해당한다. 변경 이유와 책임자를 명시한다.

외부 원문을 그대로 유지할지, 차분(diff)만 남길지는 운영 방식에 맞춘다. 다만, 업데이트 시 무엇이 외부 유래이고 무엇이 로컬 변경인지 비교할 수 있어야 한다. 복사 후 출처를 지워버리면 업데이트 확인도 라이선스(License) 확인도 어려워진다.

최소 적응(Minimal Adaptation)을 권장하는 이유는 단순히 작업량을 줄일 수 있기 때문만이 아니다. 차분의 의미를 추적하기 쉽게 하고, 불필요해졌을 때 제거 범위를 판단하기 쉽게 하기 위함이다. 효과는 환경마다 검증한다.

동작 확인의 합격 조건

구문(Syntax)을 읽을 수 있는 것만으로는 운영에 투입했다고 말할 수 없다. 다음 순서로 확인한다.

• 구조 검사: YAML이나 프론트매터(frontmatter)의 필수 항목이 갖춰져 있는가
• 참조 정합성: 참조 파일이나 명령어가 실제로 존재하는가
• 권한을 제한한 시험: 기대하는 입력에 대해 기대하는 종류의 출력을 반환하는가
• 거부 조건 확인: 대상 외의 요청을 거부할 수 있는가, 실패 시 아무것도 다시 쓰지 않고 멈출 수 있는가
• 라우팅(Routing) 확인: 기존의 유사한 역할에 동일한 요청을 주었을 때, 어느 쪽이 호출되는지 확인한다

5번째 항목은 성능 경쟁이 목적이 아니다. 목적은 이용자가 선택할 수 없는 모호한 라우팅을 찾아내는 데 있다. 모호함이 남는다면 이름이나 발화(Trigger) 조건을 재검토하거나, 둘 중 하나를 채택하지 않는다.

동작 확인 결과는 합격/불합격뿐만 아니라 입력, 관측된 출력, 거부 조건, 남은 제약 사항을 기록한다. 확인되지 않은 권한이나 경로가 있다면 '미확인'으로 남긴다. 시험하지 않은 조건을 일반적인 기대만으로 합격 처리하지 않는다.

업데이트와 제거는 도입 시에 결정해 둔다

도입 완료 시에 다음 업데이트를 누가 확인할지 결정한다. 자동 업데이트를 받는다면 변경 전 리뷰와 롤백(Rollback) 방법이 필요하다. 버전을 고정한다면 취약점 수정이나 중요한 변경을 어떻게 알 수 있을지를 결정한다.

업데이트 시에는 외부 차분을 갑자기 적용하지 않는다. 다음 세 가지를 별도로 읽는다.

• 현재 사용 중인 역할
• 부족한 부분을 메우고 있던 곳
• 로컬 변경 사항

불필요해진 기능을 관성적으로 계속 업데이트하지 않도록, 채택 이유가 지금도 성립하는지 확인한다.

제거는 실패가 아니다. 기존 자산으로 대체할 수 있게 되었거나, 외부 조건이 변했거나, 이용 실적이 없거나, 책임자가 없는 경우에는 참조를 중단하고 영향을 확인한 뒤 제거한다. 삭제 전에 호출 측을 조사하여, 실체만 지우고 참조를 남기지 않도록 한다.

업데이트와 제거를 뒤로 미루면 외부 자산은 도입한 순간에만 관리되고, 그 이후에는 유래를 알 수 없는 로컬 자산이 된다. 도입 시에 출구(Exit)를 결정함으로써 채택 판단을 지속적인 관리로 바꾼다.

도입 판단 시트 템플릿

후보를 읽을 때마다 관점이 바뀌면 마지막에는 인상만 남게 된다. 다음 항목을 통해 후보마다 동일한 질문에 답한다. 표 형식일 필요는 없으며, 문장이라도 항목이 갖춰져 있다면 비교할 수 있다.

• 부족 사항과의 적합성: 후보의 어느 부분이 부족함을 메우고, 어느 부분이 대상 외인가
• 중복: 기존의 유사한 역할, 대체할 수 없는 이유, 병존시킬 경우의 선택 조건
• 유래와 조건: 취득처, 참조한 버전, LICENSE, 필요한 표시 의무, 외부 참조, 호스트 측의 권한. 확인할 수 없는 항목은 '미확인'이라고 명시하며, 미확인이 채택을 중단시키는 조건인지 아니면 시험만 허용하는 조건인지도 결정한다
• 적응 차분: 형식 변경과 의미 변경을 나누어 기록
• 시험 결과: 성공 사례뿐만 아니라 거부 사례와 실패 시의 부작용
• 채택 상태: 정식 채택/시험 지속/보류/보류(見送り)/제거 후보 중 하나. '확인됨'이라는 한 마디로는 무엇을 확인했고 무엇이 남았는지 나타낼 수 없다

Reviewer가 반증해야 할 4가지 점

도입 담당자만 채택 여부를 결정하면, 자신이 찾아낸 후보를 통과시키고 싶은 방향으로 평가가 치우친다. 가능하다면 도입 작업에 관여하지 않은 제3자(Reviewer)가 판단 시트와 실제 파일을 읽고, 근거의 누락을 반증하는 체제를 만든다.

Reviewer가 확인하는 4가지 점:

• 부족 사항의 실재성: 기존 자산의 검색 범위가 좁지는 않은가, 다른 이름의 대체 역할이 있지는 않은가, 단순한 취향을 부족함이라고 부르고 있지는 않은가
• 1차 자료로의 소급: README의 소개만으로 LICENSE나 권한을 추측하고 있지는 않은가, 변동하는 건수나 인기 지표를 품질의 증거로 삼고 있지는 않은가. 취득처로 돌아갈 수 없는 기록은 불합격으로 처리한다
• 적응에 따른 의미 변화: 금지 사항의 삭제, 권한의 추가, 결과물의 변경이 있다면 그것을 외부 자산의 기능으로서 설명하고 있지는 않은가. 로컬 변경은 로컬의 책임으로서 분리하여 다룬다
• 실패 시의 되돌아가는 길: 시험에서 변경한 것을 되돌릴 수 있는가, 참조를 중단할 수 있는가, 대장에서 영향 범위를 추적할 수 있는가

Blocker(차단 요소)가 남아 있는 동안에는 정식 배치로 진행할 수 없다. Reviewer(검토자)의 역할은 대신하여 안전한 문장을 창작하는 것이 아니다. 근거가 없는 주장은 삭제하거나 보류하고, 부족한 증거와 합격 조건을 반환한다. 수정은 검증된 재료만을 바탕으로 최종적인 반영 담당자(본문에서는 Compiler라고 부름)가 수행한다.

정본은 2개 — 외부 원문과 로컬 버전

가져온(Import) 후에 혼란스러워하기 쉬운 것이 외부 원문과 로컬 버전의 관계다. 어느 한쪽만을 정본(Source of Truth)이라 부르기 전에, 책임을 나눈다.

외부 원문: 제공처의 설계와 업데이트 이력의 정본 -
로컬 버전: 자신의 환경에서 허가한 권한, 금지 사항, 배치, 호출 조건의 정본

upstream(취득원의 계속 업데이트되는 리포지토리)의 업데이트가 오더라도 로컬 버전을 자동으로 교체하지 않는다. 먼저 외부 원문의 변경 이유를 읽고, 현재 채택하고 있는 역할과 관계가 있는지 확인한다. 관계가 없다면 업데이트하지 않기로 판단할 수도 있다. 관계가 있는 경우에는 로컬 차분(Diff)을 남긴 채로 가져올 수 있을지를 검토한다.

로컬 측만 개량한 경우에도 그 변경을 외부의 기능으로서 설명하지 않는다. 외부에서 빌려온 골격과 자신들이 추가한 제약이나 처리를 분리하여 기록한다. 그렇게 하면 결함이 외부 유래인지 로컬 변경 유래인지를 조사하기 쉬워진다.

외부 리포지토리가 삭제되거나 이용 조건이 바뀌는 경우에 대비하여, 채택 시점의 참조 정보와 허용되는 범위의 원문을 보유한다. 단, 원문을 저장했다는 이유로 업데이트 확인이나 라이선스 확인을 중단해서는 안 된다.

이 두 가지 정본을 잇는 것이 출전 대장(취득일·명칭·종별·취득원·참조한 버전·배치처·라이선스·채택 이유·로컬 변경·확인 결과·업데이트 및 철거 조건 등을 남기는 색인)이다. 외부의 어떤 버전을 기점으로 삼았는지, 로컬에서 무엇을 바꾸었는지, 현재 어떤 상태로 사용하고 있는지를 추적할 수 있도록 한다. 완전한 동기화를 목표로 하는 것이 아니라, 차분을 설명할 수 있는 상태를 유지한다.

요약

외부 AI 에이전트 정의 수용을 사고 없이 운영하기 위한 실무는 다음 순서로 쌓아 올린다.

• 실행 환경에 두기 전에 전체 리뷰를 수행하고, 권한을 호스트 설정과 대조한다
• 채택 시에는 형식 조정과 의미 변경을 분리하여 최소 차분으로 적용한다
• 거부 조건·라우팅 확인까지 포함하여 동작 확인을 한다
• 업데이트·철거 담당과 조건을 도입 시에 결정한다
• 판단 시트(Decision Sheet)로 후보별 근거를 통일한다
• 제3자 Reviewer에게 4가지 사항을 반증하도록 한다
• 외부 원문과 로컬 버전, 두 가지 정본을 출전 대장으로 잇는다

참고

• agency-agents(MIT License) — 본문에서 예시로 사용한 외부 에이전트 정의 모음
• A Review Checklist Before You Import External AI Agent Definitions(영어) — 이 절차를 agency-agents의 실제 파일에 적용한 기사. 정의 측의 frontmatter가 호스트의 로더(Loader)와 맞지 않는 실례와, 리포지토리에 동봉된 정합성 체크 스크립트의 실행 예시를 싣고 있다

Discussion