당신은 Claude Code 또는 Codex를 위한 공개된 AI 에이전트 정의 컬렉션을 발견했고, 그중 하나가 당신에게 부족한 역할을 수행할 것처럼 보입니다. 가장 빠른 방법은 파일을 에이전트 디렉토리로 복사하여 바로 실행해 보는 것입니다. 하지만 이 방식은 해당 파일이 당신의 권한으로 실행되기 전에 무엇을 하는지 알려줄 수 있는 모든 단계를 건너뛰는 행위입니다.

빠른 답변

요약 (TL;DR): README 파일이 아닌 파일 전체를 읽기 전까지는 모든 외부 AI 에이전트 정의를 신뢰할 수 없는 입력값(untrusted input)으로 취급하십시오. 해당 정의가 무엇을 읽고, 쓰고, 실행한다고 주장하는지, 그리고 호스트가 실제로 부여한 권한(Claude Code의 경우 정의 자체의 텍스트가 아닌 settings.json 권한)과 대조하여 확인하십시오. 가능한 최소한의 차이(diff)로 수정하고, 미관상 목적이 아닌 모든 변경 사항은 의도적인 로컬 결정으로서 로그를 남기십시오. 그리고 파일이 실제 에이전트 디렉토리에 접근하기 전에 구조, 참조, 권한 범위 내 테스트, 거부 동작, 라우팅(routing)에 대한 짧은 검증 단계를 거치십시오. 가능하다면, 채택 결정을 해당 후보를 직접 고르지 않은 사람에게 맡기십시오. 그 사람의 임무는 단 하나입니다: 해당 정의가 왜 채택되어서는 안 되는지 증명하는 것입니다.

후보를 선택할 때 시작해야 할 곳

"이 컬렉션에서 무엇을 가져와야 할까"라는 질문은 당신의 환경에 무엇이 부족한가가 아니라, 상대방 측에 무엇이 나열되어 있는가에서 시작됩니다. 방대한 후보 카탈로그와 당신이 실제로 실행하는 방대한 역할 세트는 서로 다른 것입니다. 유용성은 얼마나 많은 파일을 저장했느냐가 아니라, 적절한 것을 찾아내느냐에 달려 있습니다.

"코드 리뷰가 필요하다"라는 말은 공백을 나타내는 진술이 아닙니다. 무엇과 대조해야 할지 알 수 없을 정도로 너무 광범위합니다. 이를 한 문장으로 압축하십시오. 예를 들어, 입력, 예상 출력, 명시적으로 금지된 사항 — "현재 그 어떤 것도 코드베이스를 수정하지 않고 낯선 코드를 읽은 뒤, 추론(inference)과 확인된 사실을 분리하여 보고하지 않는다" — 와 같이 말입니다. 이 정도로 압축할 수 없다면, 아무것도 채택하지 말고 기다리십시오. 그것은 컬렉션에 대한 판결이 아니라, 아직 공백이 구체적이지 않다는 신호입니다.

환경에 적용하기 전에 파일 전체를 읽으십시오

README 설명과 전체 정의(full definition)는 서로 다른 문서입니다. 채택하기 전에 후보 파일을 전체적으로 읽고 다음 사항을 확인하십시오:

• 어떤 종류의 입력(리포지토리, 공개 문서, 개방형 대화 등)을 기대하는지
• 무엇을 생성해야 하는지 (보고서, 제안된 diff, 또는 직접적인 파일 수정)
• 참조하는 모든 외부 파일, 명령(command), 그리고 도구(tool)
• 네트워크 액세스 및 파일 쓰기 권한(file-write permissions)에 대해 무엇을 가정하는지
• 명시적으로 규정된 금지 사항이 있는지

agency-agents라고 불리는 MIT 라이선스 기반의 공개 컬렉션에 포함된 실제 파일을 보면 이것이 왜 중요한지 정확히 알 수 있습니다. 해당 파일의 프론트매터(frontmatter)에는 color, emoji, vibe와 같은 필드가 포함되어 있지만, 이는 name, description, 그리고 tools와 같은 몇 가지 필드만을 읽는 Claude Code/Codex의 자체 서브에이전트 로더(subagent loader)에게는 아무런 의미가 없습니다. 이러한 격차는 파일을 직접 열어보아야만 발견할 수 있습니다.

참조된 경로와 명령은 상위(upstream) 환경에서는 유효하지만 사용자의 환경에는 없을 수 있습니다. 작성자의 의도를 추측하여 깨진 참조를 해결하려 하지 마십시오. 실행하기 전에 무엇을 변경해야 하는지 목록을 작성하십시오. 후보 파일을 도구가 자동으로 감시하는 디렉토리(Claude Code의 경우 ~/.claude/agents/)에 바로 넣지 마십시오. 먼저 읽기 전용(read-only)으로 스테이징(stage)하십시오. 권한은 파일 자체의 주장만큼이나 호스트 설정(settings.json)에 따라 달라지므로, 두 가지를 모두 확인하십시오.

가능한 가장 작은 diff로 적응시키십시오

첫날부터 다시 쓰는 것을 지양하십시오. 실행에 필요한 것만 적용하고, 원본과 로컬 버전을 비교 가능한 상태로 유지하십시오. 모든 변경 사항을 두 가지로 나누십시오.

형식 조정 (Format adjustments): 이름, 프론트매터(frontmatter) 필드, 파일 위치, 호출 조건 — 실행을 위해 필요한 기계적인 작업입니다.

의미 변경 (Meaning changes): 금지 사항 제거, 역할이 다룰 수 있는 범위 확장, 출력 유형 변경, 참조된 메커니즘 교체. 이것들은 단순한 조정이 아니라 로컬 설계 결정(local design decisions)입니다. 따라서 담당자와 명시된 이유가 필요합니다.

복사 시점에 출처(origin)를 제거하면, 무엇에 대해 라이선스를 부여받았는지 확인(LICENSE 파일과 대조 가능 여부)할 수 있는 능력과 향후 업데이트를 깔끔하게 가져올 수 있는 능력을 모두 잃게 됩니다. 최소한의 차이(diff)는 나중에 설명할 수 있을 만큼 충분히 읽기 쉬워야 하며, 해당 후보가 자격을 유지하지 못할 경우 무엇을 제거해야 할지 알 수 있을 만큼 작아야 합니다.

통과 기준으로서의 검증 항목

파일을 파싱(parsing)하는 것이 실행 준비가 되었다는 뜻은 아닙니다.

1. 구조적 확인 (Structural check) — 필수적인 YAML 프론트매터(frontmatter) 필드가 존재하며 형식이 올바른가?
2. 참조 확인 (Reference check) — 참조된 파일, 경로, 명령어가 실제로 여기에 존재하는가?
3. 범위 제한 테스트 (Scoped trial) — 권한을 좁혔을 때, 현실적인 입력에 대해 예상된 출력을 생성하는가?
4. 거부 확인 (Refusal check) — 범위를 벗어난 요청을 거부하며, 실패 시 깔끔하게 중단되는가?
5. 라우팅 확인 (Routing check) — 동일한 요청을 해당 에이전트와 유사한 기존 역할(role)에 보냈을 때, 어느 쪽이 응답하는가?

다섯 번째 항목은 승자를 뽑기 위한 것이 아니라, 사용자가 추측해야 하기 전에 모호한 라우팅을 찾아내기 위한 것입니다. 경계가 불분명하다면 이름이나 트리거 조건(trigger conditions)을 수정하거나, 둘 다 유지하지 마십시오.

agency-agents는 자체적인 참조 확인(reference check) 기능을 제공합니다. 이는 디스크 상의 디렉토리 및 CI 경로 필터와 분할 목록(division list)을 교차 검증하는 스크립트로, 불일치가 발생하면 빌드를 실패 처리합니다:

./scripts/check-divisions.sh

PASSED: 17 divisions consistent across divisions.json, directories, scripts, and CI.

신뢰할 수 있는 단일 원천(source of truth)이 되어야 하는 것을 선택하고, 런타임(runtime)에 알게 되는 대신 불일치가 발생하는 즉시 명확하게 실패를 알리는 확인 절차를 작성하십시오. 단순히 통과/실패 여부만 기록하지 말고, 입력값, 관찰된 출력, 사용되지 않은 권한이 무엇인지 기록하십시오. 사용되지 않은 권한은 검증된 권한이 아닙니다. 테스트되지 않은 것으로 표시하십시오.

채택하기 전에 업데이트 및 제거 방식을 결정하십시오

다음 업데이트를 누가 검토할지는 업데이트가 도달한 후가 아니라, 채택하는 시점에 결정해야 합니다. 자동 추적(Automatic tracking)에는 변경 전 검토 단계와 롤백(rollback) 경로가 필요하며, 버전을 고정(pinning)하는 경우에는 이를 통하지 않고도 보안 패치에 대해 알 수 있는 방법이 필요합니다.

업데이트가 도착하면, 무엇인가를 적용하기 전에 다음 세 가지를 별도로 읽어보십시오.

• 현재 사용 중인 역할 (role)
• 해당 역할이 채워지도록 채택된 간극 (gap)
• 그 위에 레이어링된 로컬 변경 사항 (local changes)

관성 때문에 갱신하지 마십시오. 원래의 이유가 여전히 유효한지 확인하십시오. 제거하는 것은 실패가 아닙니다. 만약 기존의 역할이 현재 동일한 영역을 커버하거나, 조건이 변경되었거나, 혹은 아무도 해당 역할을 소유하고 있지 않다면, 참조를 중단하고 아무것도 깨지지 않는지 확인하십시오. 삭제하기 전에 여전히 그것을 호출하는 것이 있는지 확인하십시오. 공중에 떠 있는 참조 (dangling reference)는 파일을 그대로 두는 것보다 더 나쁩니다. 이러한 결정을 미루는 것은 검토된 임포트 (import)를 추적 가능한 기원이 없는 소유되지 않은 자산으로 변질시킵니다.

채택 결정 시트 템플릿

질문이 매번 바뀐다면, 최종 결정에는 인상 (impression)만이 남게 됩니다. 모든 후보에 대해 동일한 필드에 답하십시오. 모든 필드가 다뤄진다면 산문 형태여도 괜찮습니다.

1. 간극과의 적합성 (Fit with the gap) — 어느 부분이 간극을 채우며, 어느 부분이 범위 외 (out of scope)인가?

2. 중복 (Overlap) — 가장 유사한 기존 역할은 무엇인가? 왜 기존 역할이 이를 이미 커버하지 못하는가? 두 가지를 모두 실행하기 위한 조건은 무엇인가?

3. 출처 및 조건 (Provenance and terms) — 출처, 정확한 버전 (Git commit 또는 tag), LICENSE 파일 자체, 속성 표기 (attribution) 요구 사항, 필요한 호스트 측 권한. 확인되지 않은 항목을 표시하고, 이것이 채택을 차단하는지 아니면 단순히 주의가 필요한 사용 (unattended use)에 해당하는지 결정하십시오.

4. 적응 차이 (Adaptation diff) — 형식 조정과 의미 변화를 분리하여 작성하십시오.

5. 테스트 결과 (Trial results) — 성공 사례, 거부 사례, 실패한 테스트가 남긴 부작용.

6. 채택 상태 (Adoption state) — 채택됨 (adopted), 테스트 중 (on trial), 보류 (on hold), 거절됨 (declined), 또는 제거 대상으로 표시됨 (marked for removal).

7. 실제로 격차(gap)가 존재하는가? 기존의 유사한 대안을 찾는 과정이 충분히 광범위했는가?

8. 문서 기록(paper trail)이 유효한가? 라이선스가 README에서 추론되었는가, 아니면 소스(source)에서 확인되었는가? 추적 가능한 출처가 없는 것은 주의 사항(caveat)이 아니라 실패 조건(fail condition)이다.

9. 적응(adaptation) 과정에서 실제로 무엇이 바뀌었는가? 제거된 금지 사항이나 추가된 허용 사항은 원래 정의의 동작으로 설명해서는 안 되며, 로컬 결정(local decision)으로 라벨링되어야 한다.

10. 되돌릴 방법이 있는가? 시험(trial) 중의 변경 사항을 되돌릴 수 있는가? 참조를 깔끔하게 제거할 수 있는가? 시트(sheet)만으로 영향 범위(blast radius)를 추적할 수 있는가?

이 네 가지 중 어느 하나라도 해결되지 않은 차단 요소(Blocker)로 남아 있다면, 해당 후보는 영구적인 위치로 이동할 수 없습니다. 검토자(Reviewer)의 역할은 격차를 덮기 위해 버전을 다듬는 것이 아닙니다. 근거 없는 주장은 삭제되거나 미결(open) 상태로 표시됩니다. 채택된 버전을 최종 확정하는 사람(Compiler)은 이미 확인된 내용만을 바탕으로 작업합니다.

두 가지 진실의 원천: 업스트림(upstream)과 로컬 복사본

한번 채택되면, 어떤 복사본이 무엇에 대해 권위(authoritative)를 갖는지 놓치기 쉽습니다:

• 업스트림 원본 (the upstream original) — 유지 관리자(maintainer)가 게시하는 설계 및 업데이트 이력에 대해 권위를 가짐
• 사용자의 로컬 버전 (your local version) — 사용자가 실제로 승인한 권한, 금지 사항, 배치 및 호출 조건에 대해 권위를 가짐

업스트림이 변경되면, 차이점(diff)을 적용하기 전에 그 이유를 읽고, 사용자가 실제로 의존하는 부분에 영향을 미치는지 확인하십시오. 업데이트를 하지 않는 것이 정당할 수도 있으며, 이는 태만(negligence)이 아닐 수 있습니다. 로컬 복사본을 개선했다면 이를 업스트림의 동작으로 설명하지 마십시오. 그렇게 하면 향후 버그의 원인을 파악하기가 더 어려워집니다. 업스트림이 사라지거나 약관이 변경될 경우, 사용자는 자신이 채택한 버전과 범위를 보존하고 싶어 할 것입니다. 이는 약관이 유효할 때 확인하지 않는 대신, 더 이상 확인이 불가능할 때를 대비한 대비책(fallback)으로서의 의미를 갖습니다.

요약 체크리스트

실수 없이 외부 AI 에이전트 정의를 가져오는 과정은 다음의 7단계로 요약됩니다:

1. 먼저 후보 파일 전체를 읽으십시오. 주장된 권한(permissions)이 귀하의 호스트 설정(host configuration)과 일치하는지 확인하십시오.
2. 가장 작은 차이(diff)로 적응시키되, 형식 조정 사항과 의미 변화를 별도로 기록하십시오.
3. 채택하기 전에 구조, 참조(references), 범위 제한 테스트(scoped trial), 거부 동작(refusal behavior), 그리고 라우팅(routing)을 검증하십시오.
4. 채택 시점에 다음 업데이트의 소유자가 누구인지, 그리고 언제 해당 역할을 제거할 것인지 결정하십시오.
5. 모든 후보에 대해 동일한 필드를 사용하여 결정 시트(decision sheet)를 작성하십시오.
6. 후보를 소싱하지 않은 다른 사람이 채택 과정이 잘못되었음을 증명(falsify)하도록 시도하십시오.
7. 업스트림(upstream)과 로컬 버전을 출처(provenance)를 통해 연결된 두 개의 신뢰할 수 있는 소스(sources of truth)로 유지하십시오.

이 단계들 중 어느 것도 단독으로는 비용이 많이 들지 않습니다. 이 단계들이 대체하는 것은 바로 "괜찮아 보여서 그냥 복사해 넣었다"라는 하나의 조용한 단계이며, 이 단계는 그것이 잘못되었다는 것이 밝혀지는 바로 그 순간에 매우 큰 비용을 치르게 합니다.

FAQ

이 체크리스트는 모든 AI 에이전트 프레임워크에 적용되나요, 아니면 Claude Code에만 적용되나요?

Claude Code/Codex에 국한되지 않습니다. 외부의 실행 가능한 역할 정의(executable role definition)가 실제 권한을 가진 환경으로 채택되는 곳이라면 어디든 적용됩니다.

만약 정의에 제가 설치하지 않은 도구나 명령어가 참조되어 있다면 어떻게 하나요?

필수적인 적응(adaptation) 사항으로 취급하십시오. 참조된 모든 파일, 명령어, 도구를 나열하고 채택 전에 각각을 확인하십시오. 런타임(runtime) 중에 누락된 참조가 조용히 우회되어 작동하는 상황을 잡아내는 것이 바로 전체 파일 검토(full-file review)의 목적입니다.

별도의 검토자(Reviewer) 없이 혼자서 이 체크리스트를 실행할 수 있나요?

혼자서 검토하고 검증할 수 있습니다. 하지만 혼자서는 허위 증명(falsification)이 더 어렵습니다. 이미 후보에 애착을 가진 상태에서, 자신의 결정을 반증하려는 의도를 가지고 스스로를 검증하는 것은 쉽지 않기 때문입니다. 최소한, 일정 시간이 지난 후 결정 시트를 다시 검토하며, 어떤 점이 귀하로 하여금 "아니오"라고 말하게 만들지 찾아보며 읽으십시오.

나중에 업스트림 저장소가 삭제되거나 라이선스가 변경되면 어떻게 되나요?

그것이 바로 출처(provenance) 기록이 필요한 이유입니다: 가져온 버전, 당시의 라이선스, 소스. 이것이 삭제된 저장소를 재생성해주지는 않지만, 채택 시점에 귀하가 사용 허가를 받았던 내용이 무엇인지는 보여줍니다.

References

• GitHub의 agency-agents — 이 글 전반에서 참조된 MIT 라이선스의 공개 컬렉션

Sho Naka (nomurasan). 이 글은 동일한 검토 워크플로우를 다루는 일본어 원문을 영어로 각색한 것입니다.