devto 2026-08-01 원문 보기 ↗
You found a public collection of AI agent definitions — maybe for Claude Code, maybe for Codex — and one looks like the role you're missing. The fast path: copy the file into your agents directory and try it. That path skips every step that would tell you what the file does before it runs with your permissions.
TL;DR: Treat every external AI agent definition as untrusted input until you've read the whole file, not the README. Check what it claims to read, write, and execute against what your host actually grants it (for Claude Code, settings.json permissions, not the definition's own text). Adapt with the smallest diff possible, log every non-cosmetic change as a deliberate local decision, and run a short verification pass — structure, references, a permission-scoped trial, refusal behavior, routing — before the file goes near your real agents directory. If you can, hand the adoption decision to someone who didn't pick the candidate, with one job: try to prove it shouldn't be adopted.
"What should I pull from this collection" starts from what's listed on the other side, not from what your environment is missing. A large catalog of candidates and a large set of roles you actually run are different things — usefulness tracks with finding the right one, not how many files you saved.
"We need code review" isn't a gap statement; it's too wide to check anything against. Compress it to one sentence: input, expected output, what's explicitly forbidden — nothing today reads an unfamiliar codebase without modifying it and reports confirmed facts separately from inference, for example. Can't compress it that far? Hold off adopting anything for it; that's a sign the gap isn't concrete yet, not a verdict on the collection.
A README description and a full definition are different documents. Before adopting, read the candidate file in full and confirm:
A real file from a public, MIT-licensed collection called agency-agents shows exactly why this matters: its frontmatter carries fields like color, emoji, and vibe that mean nothing to Claude Code/Codex's own subagent loader, which reads name, description, and a few fields like tools. You only catch a gap like that by opening the file yourself.
Referenced paths and commands can be valid upstream and absent in your environment — don't resolve a broken reference by guessing the author's intent; list what has to change before it runs. Don't drop a candidate straight into a directory your tools watch automatically (for Claude Code, ~/.claude/agents/); stage it read-only first. Permissions depend on host configuration (settings.json) as much as the file's own claims — check both.
Resist rewriting on day one. Apply only what's required to run, and keep the original and your local version comparable. Split every change in two.
Format adjustments: name, frontmatter fields, file location, invocation conditions — mechanical, required to run.
Meaning changes: removing a prohibition, widening what the role can touch, changing its output type, swapping a referenced mechanism. These are local design decisions, not adjustments — they need an owner and a stated reason.
Strip the origin at copy time and you lose the ability to confirm what you were licensed to use (checkable against the LICENSE file) and to pull a future update cleanly. A minimal diff stays legible enough to explain later, small enough to know what to remove if the candidate stops earning its place.
Parsing the file isn't being ready to run it:
The fifth isn't about picking a winner — it's finding ambiguous routing before a user has to guess. If the boundary is unclear, fix the name or trigger conditions, or don't keep both.
agency-agents ships its own reference check — a script cross-checking its division list against directories on disk and CI path filters, failing the build on any disagreement:
./scripts/check-divisions.sh
PASSED: 17 divisions consistent across divisions.json, directories, scripts, and CI.
Pick whatever's supposed to be the source of truth, and write a check that fails loudly the moment anything disagrees, instead of finding out at runtime. Record what you tested, not just pass/fail — input, observed output, which permissions went unexercised. An unexercised permission isn't a verified one; mark it untested.
Decide who reviews the next update at adoption time, not after it lands. Automatic tracking needs a pre-change review step and a rollback path; pinning a version needs a way to learn about security fixes without it.
When an update arrives, read three things separately before applying anything:
Don't renew out of inertia — confirm the original reason still holds. Removal isn't failure: if an existing role covers the same ground now, terms changed, or nobody owns it, stop referencing it and confirm nothing breaks. Check what still calls it before deleting — a dangling reference is worse than a file left in place. Deferring these decisions converts a reviewed import into an unowned asset with no traceable origin.
If the questions change every time, only the impression survives to the final decision. Answer the same fields for every candidate; prose is fine if every field is addressed.
Worth less as a one-time filter than as a record: "why did we bring this in" gets a written answer later, not "it seemed useful at the time."
Whoever sourced the candidate is already inclined to see it favorably. Someone uninvolved in sourcing it should read the sheet and the file and try to disprove the adoption:
While any of these four stays an open Blocker, the candidate doesn't move to its permanent location. The Reviewer's job isn't polishing a version to paper over the gap — an unsupported claim gets deleted or marked open. Whoever finalizes the adopted version (the Compiler) works only from what's already confirmed.
Once adopted, it's easy to lose track of which copy is authoritative for what:
When upstream changes, read why before applying the diff, and check whether it touches what you actually rely on — not updating can be legitimate, not negligence. If you improve your local copy, don't describe that as upstream's behavior; that makes a future bug harder to attribute. If upstream disappears or its terms change, you'll want the version and scope you adopted under preserved — not instead of checking terms while available, but as the fallback once they aren't.
Importing an external AI agent definition without an accident scales down to seven steps:
None of these steps is expensive alone. What they replace is one silent step — "it looked fine, so I copied it in" — expensive exactly when it turns out to have been wrong.
Not Claude Code/Codex-specific — it applies anywhere an external, executable role definition gets adopted into an environment with real permissions.
Treat it as a required adaptation. List every file, command, and tool referenced, and confirm each before adoption — a missing reference silently worked around at runtime is exactly what the full-file review catches.
You can review and verify solo. Falsification is harder alone — checking your own decision with intent to disprove it, after you're already attached to the candidate. At minimum, revisit the decision sheet after a delay and read it looking for what would make you say no.
That's what the provenance record is for: version pulled, license at the time, source. It won't recreate a deleted repository, but it shows what you were licensed to use at adoption time.
Sho Naka (nomurasan). This is an English-language adaptation of a Japanese-language original covering the same review workflow.