전체 논문 읽기 또는 댓글 달기: 영어판 | 프랑스어판

나는 고통스러울 정도로 단순한 사실을 인정하기 전까지, 아주 오랜 시간 동안 AI 워크플로우 (AI workflows)를 구축하는 데 시간을 보냈다. 그것은 바로 지침(instructions)으로 가득 찬 폴더가 자동으로 도구 (tool)가 되는 것은 아니라는 사실이다.

SKILL.md는 훌륭할 수 있다. AGENTS.md는 저장소 (repository)를 구할 수도 있다. 플러그인 매니페스트 (plugin manifest)는 깔끔한 아이디어를 패키징할 수 있다. 하지만 그 어느 것도 단독으로는 파일을 검증하거나, 라이브 상태 (live state)를 조사하거나, 서비스를 호출하거나, 잘못된 입력을 거부하거나, 혹은 어떤 동작이 실제로 일어났음을 증명할 수 없다.

이러한 구분이 중요한 이유는 에이전트 생태계 (agent ecosystems)가 그 어휘력보다 더 빠르게 확장되고 있기 때문이다. 우리는 기술 (skill), 플러그인 (plugin), 도구 (tool), 훅 (hook), 리소스 (resource), 그리고 _MCP 서버 (MCP server)_를 마치 서로 교체 가능한 것처럼 사용한다. 하지만 이들은 서로 다르다.

이 연구를 마친 후 나의 규칙은 명확하다:

기술 (skill)은 에이전트에게 특정 기능 (capability)을 사용하는 방법을 가르쳐야 한다. 진정한 플러그인 (plugin)은 해당 기능을 사용할 수 있게 만들어야 한다. 작업에 실행 (action)이 필요할 때, 플러그인에는 모터 (motor)가 필요하다.

내 플러그인이 문제를 드러낸 순간

이 글은 내 작업실 내부의 사례 연구 (case study)가 되었다.

나는 가짜가 아닌 하나의 메모리 플러그인 (memory plugin)을 조사했다. 그것은 이미 실행 가능한 도구 (executable tools), 서버 인터페이스 (server surface), 테스트, 그리고 유용한 경로 (routes)를 갖추고 있었다. 그럼에도 불구하고, 그것의 활성화 지침 (activation instructions)은 Codex가 메모리가 정말로 필요한지 확인하기도 전에 대규모 에이전트 작업 (agent job)을 선택하고 배정하도록 유도했다.

구문론적으로(syntactically) 깨진 것은 아무것도 없었다. 아키텍처 (architecture)가 단순히 활성화 (activation) 단계에 너무 많은 일을 요구하고 있었을 뿐이다.

플러그인을 활성화하는 것은 기능을 사용할 수 있게 만들어야 한다. 그것이 배정 명령 (dispatch order)처럼 동작해서는 안 된다.

워크스페이스가 커지기 전까지는 그 차이가 작게 느껴질 수 있습니다. 하나의 기술 (Skill)이 열 개가 됩니다. 모든 수정 사항이 영구적인 규칙이 됩니다. 모든 성공적인 워크플로우 (Workflow)가 또 다른 마크다운 (Markdown) 파일이 됩니다. 곧 모델은 작업을 시작하기도 전에 작업 내용 대신 워크숍 라벨을 읽는 데 시간을 허비하게 됩니다.

나는 이것을 **컨텍스트 부채 (context debt)**라고 부릅니다.

이 부채는 망설임, 지시 사항 간의 충돌, 오래된 규칙, 광범위한 트리거, 그리고 반복적인 검색의 형태로 나타납니다. 모델이 반드시 약해진 것은 아닙니다. 모델이 문제에 도달하기도 전에 우리가 모델의 유용한 주의력 (Attention)을 소진해 버렸을 수 있습니다.

지시 (Instruction)는 계측 (Instrumentation)이 아니다

지시는 언어입니다. 계측은 현실과의 접점입니다.

• 지시는 "원고를 검증하라"고 말합니다.
• 모터 (Motor)는 검증기를 실행하고 증거를 반환합니다.
• 지시는 "이 스키마 (Schema)를 준수하라"고 말합니다.
• 모터는 잘못된 형식의 입력을 거부합니다.
• 지시는 "비밀 정보를 절대 노출하지 마라"고 말합니다.
• 권한 부여 계층 (Authorization layer)은 비밀 정보가 모델이 볼 수 있는 컨텍스트 (Context)에 들어오는 것을 방지합니다.
• 지시는 워크플로우 (Workflow)를 설명합니다.
• 계측은 어떤 단계가 수행되었는지 증명합니다.

이것이 지시의 힘을 약화시키는 것은 아닙니다. 지시는 의도, 스타일, 제약 조건, 그리고 전문적인 표준을 전달합니다. 집중된 기술 (Skill)은 비용이 많이 드는 방황을 방지할 수 있습니다.

문제는 가이드 (Guide)가 도구 (Instrument)를 사칭할 때 시작됩니다.

시스템이 작업을 실행하고, 결과를 검사하며, 정직하게 실패를 알리고, 증거를 보여줄 수 없다면, 그 기술 (Skill)은 여전히 유용한 매뉴얼일 수는 있습니다. 하지만 그것은 모터 (Motor)가 아닙니다.

기술(Skill), 플러그인(Plugin), 도구(Tool), 훅(Hook): 계층의 이름을 정의하라

오늘날 내가 옹호할 수 있는 가장 깔끔한 아키텍처 (Architecture)는 다음과 같습니다.

기술 (Skill)은 가르친다

기술 (Skill)은 집중된 가이드입니다. 어떤 메서드 (Method)를 사용할지, 도구 (Tool)를 어떻게 작동시킬지, 어떤 리스크가 중요한지, 그리고 결과에 어떤 증거가 포함되어야 하는지를 설명합니다.

플러그인 (Plugin)은 패키징한다

플러그인 (Plugin)은 배포 단위입니다. 기술 (Skill), 실행 가능한 도구 (Tool), MCP 서버, 훅 (Hook), 앱 (App), 메타데이터 (Metadata), 그리고 에셋 (Asset)을 묶을 수 있습니다. 패키징을 했다고 해서 광고된 모든 기능이 실제로 존재한다는 것이 증명되지는 않습니다.

도구 (Tool)는 행동한다

도구 (Tool)는 행동한다

도구 (Tool)는 제한된 동작 (bounded operation)을 수행합니다. 도구는 입력 (inputs), 출력 (outputs), 실패 동작 (failure behavior), 그리고 증거 (evidence)를 가집니다. 이는 스크립트 (script), CLI, 검증기 (validator), API 어댑터 (API adapter), 브라우저 브리지 (browser bridge), 또는 서버 핸들러 (server handler)일 수 있습니다.

MCP는 노출한다 (exposes)

Model Context Protocol 도구 경계 (tool boundary)는 스키마 (schemas)를 통해 기능들을 발견 가능하고 호출 가능하게 만듭니다. MCP는 깨끗한 문을 만듭니다. 하지만 그 문이 무엇을 향해 열릴지는 여전히 엔지니어링 (engineering)이 결정합니다.

훅 (hook)은 타이밍을 강제한다

훅 (hook)은 라이프사이클 (lifecycle)의 특정 순간에 실행됩니다: 편집 전, 도구 호출 후, 커밋 전, 또는 검증 (validation) 도중입니다. 숨겨진 자동화는 여전히 권한 (authority)을 가지므로, 훅은 범위를 좁게 유지해야 합니다.

인증 가드 (auth guard)는 권한을 보호한다

만약 동작이 계정, API, 개인 파일, OAuth 세션, 또는 쓰기 작업 (write action)에 접근한다면, 가드 (guard)가 무엇이 허용되는지, 어떤 범위 (scope) 내에서 이루어지는지, 그리고 어떤 감사 추적 (audit trail)을 남길지를 결정해야 합니다.

다음의 짧은 요약은 기억할 가치가 있습니다:

기술 (skill)은 가르칩니다. 플러그인 (plugin)은 패키징합니다. 도구 (tool)는 행동합니다. MCP는 노출합니다. 훅 (hook)은 타이밍을 강제합니다. 가드 (guard)는 권한을 보호합니다.

모터 (motor)의 실제 모습

모터 (motor)는 인상적일 필요가 없습니다. 실재해야 합니다.

도구로 노출된 원고 검증기 (manuscript validator)를 상상해 보십시오. 그 계약 (contract)은 다음과 같이 작을 수 있습니다:

{
  "operation": "validate_manuscript",
  "input": {
...

중요한 것은 JSON이 아닙니다. 중요한 것은 해당 동작이 실행될 수 있고, 잘못된 입력이 거부될 수 있으며, 출력을 검사할 수 있고, 결과를 재현 (reproduce)할 수 있다는 점입니다.

모터 (motor)는 다음과 같을 수 있습니다:

• Python 검증기 (validator);
• 결정론적 변환 스크립트 (deterministic transformation script);
• 메타데이터를 추출하는 CLI;
• 렌더링된 상태를 검사하는 브라우저 도구 (browser tool);
• 하나의 좁은 동작을 노출하는 MCP 서버;
• 안전하지 않은 출력을 차단하는 훅 (hook);
• 자격 증명 (credentials)을 유출하지 않고 서비스를 호출하는 어댑터 (adapter).

테스트된 하나의 모터가 열 개의 프롬프트 래퍼 (prompt wrappers)보다 낫습니다.

MCP는 마법의 문이 아니다

MCP가 중요한 이유는 바로 모델의 추론 (reasoning)과 외부 기능 (external capability)을 분리하기 때문입니다. 하지만 스키마 (schema)가 보안 인증서인 것은 아니며, 서버 이름이 정확성의 증거도 아닙니다.

제대로 된 MCP 도구 (tool)는 여전히 다음 사항들을 필요로 합니다:

• 좁은 범위의 동작 (narrow operation);
• 검증된 입력값 (validated inputs);
• 구조화된 출력값 (structured outputs);
• 정직한 에러 메시지 (honest errors);
• 권한 경계 (authorization boundary);
• 관찰 가능한 로그 또는 아티팩트 (observable logs or artifacts);
• 명확한 소유권 및 생명주기 (clear ownership and lifecycle);
• 중대한 쓰기 작업에 대한 인간의 검토 (human review for consequential writes).

공식 MCP 명세 (specification)는 우리에게 프로토콜 경계 (protocol boundary)를 제공합니다. 하지만 그것이 그 경계 뒤에 숨겨진 엔지니어링 작업을 없애주지는 않습니다.

이것이 바로 _플러그인 (plugin)_이라는 단어가 검토의 끝이 되어서는 안 되는 이유입니다. 플러그인이 실제로 무엇을 노출하는지 물으십시오. 어떤 프로세스가 호출을 처리하는지 물으십시오. 무엇이 성공을 증명하는지 물으십시오. 네트워크가 실패하거나, 토큰이 만료되거나, 입력이 비어 있거나, 사용자가 권한을 거부할 때 어떤 일이 발생하는지 물으십시오.

비밀 정보 (Secrets)가 모델의 지식이 되어서는 안 된다

모델은 시스템이 권한을 사용하는 빈도보다 더 적게 권한을 요청해야 합니다.

작업에 API 키, OAuth 토큰, JWT, 쿠키 또는 개인 계정이 필요한 경우, 이상적인 흐름은 다음과 같습니다:

사용자 비밀 정보 (user secret) -> 프롬프트 (prompt) -> 모델 컨텍스트 (model context) -> 도구 호출 (tool call)

이것이 아니라 다음과 같아야 합니다:

모델 의도 (model intent)
  -> 기능 요청 (capability request)
  -> 권한 가드 (authorization guard)
...

모델은 _무엇을 요청할 수 있는지_를 알아야 합니다. 일반적으로 비밀 정보 그 자체를 알 필요는 없습니다.

MCP 서버 (MCP servers) 및 플러그인 인증 (plugin authentication)에 관한 OpenAI의 문서는 명시적인 도구 및 권한 경계를 지향합니다. 이러한 방향성은 초보자들에게 매우 중요한데, 안전하지 않은 패턴은 빠르게 습관이 되기 때문입니다. 만약 일반적인 튜토리얼이 토큰, 쿠키, 헤더, .env 값을 채팅창에 붙여넣는 것으로 시작한다면, 우리는 잘못된 추상화 (abstraction)를 가르치고 있는 것입니다.

범위 (scopes), 동의 (consent), 검토 (review), 그리고 제한된 권한 (bounded authority)을 가르치십시오. 가공되지 않은 비밀 정보는 그것을 보유하도록 설계된 시스템 안에 유지하십시오.

초보자의 함정과 숙련된 사용자의 함정

초보자들은 구조를 능력으로 오해할 수 있습니다. 플러그인 폴더는 공식적인 것처럼 보이고, 매니페스트 (manifest)는 설계된 것처럼 보이며, 상세한 기술 (skill)은 작동하는 것처럼 들립니다. 점검 질문은 단순하게 유지해야 합니다:

1. 이 기술 (skill)은 무엇을 가르치는가?
2. 어떤 실행 가능한 작업 (executable operation)을 호출하는가?
3. 그 작업은 어떤 입력을 받는가?
4. 성공을 증명하는 출력 (output)은 무엇인가?
5. 실패 시에는 어떤 일이 발생하는가?
6. 권한 (authority)이나 비밀 정보 (secrets)를 필요로 하는가?
7. 테스트는 어디에 있는가?

숙련된 사용자들은 정반대의 문제를 겪습니다. 우리는 모든 곳에 구조를 만들 정도로 충분히 알고 있습니다. 우리는 어조 (tone)를 위한 기술 (skill)을, 도메인 (domains)을 위한 에이전트 (agents)를, 습관 (habits)을 위한 훅 (hooks)을, 메모리 (memory)를 위한 폴더를, 그리고 워크플로 (workflows)를 위한 플러그인 (plugins)을 구축합니다. 각 계층은 국소적인 고통을 해결하지만, 이들이 모이면 전역적인 정체 (global congestion)를 유발할 수 있습니다.

숙련된 기술 (skill)은 때때로 삭제하는 것입니다.

오래된 가이드를 은퇴시키십시오. 중복되는 기술 (skill)을 병합하십시오. 트리거 (triggers)를 조이십시오. 긴 이론은 문서화 (documentation)로 옮기십시오. 활성화 (activation)와 실행 (execution)을 분리하십시오. 활성 지침은 짧게 유지하고 살아있는 도구 (living tools)에 부착하십시오.

하나의 작고 실제적인 도구를 만드십시오

제가 현재 사용하는 복구 경로는 다음과 같습니다:

1. 하나의 반복적인 작업을 선택하십시오. 플랫폼이 아닙니다. 마켓플레이스 (marketplace)도 아닙니다. 단 하나의 작업입니다.
2. 가장 작은 결정론적 모터 (deterministic motor)를 구축하십시오. 보편적으로 만들기 전에 유용하게 만드십시오.
3. 구조화된 출력 (structured output)을 반환하십시오. 에이전트 (agent)가 성공이 어떤 모습인지 추측할 필요가 없어야 합니다.
4. 긍정적 사례와 부정적 사례를 테스트하십시오. 빈 입력과 실패 경로도 중요합니다.
5. 작업을 정직하게 노출하십시오. CLI, 훅 (hook), API 어댑터 (adapter), 또는 MCP 서버 (MCP server)를 사용하십시오.
6. 권한 (authority)을 보호하십시오. 자격 증명 (credentials)과 권한 결정은 일반적인 모델 컨텍스트 (model context) 외부에 유지하십시오.
7. 모터가 작동한 후에 기술 (skill)을 작성하십시오. 에이전트 (agent)에게 실제 도구를 어떻게 그리고 언제 사용하는지 가르치십시오.
8. 재사용성이 증명되었을 때 플러그인 (plugin)을 패키징하십시오. 배포 (distribution)는 능력 (capability)이 확보된 후에 이루어집니다.

이러한 규율은 AI에 반하는 것이 아닙니다. 이것은 우리가 에이전트 (agent)의 힘을 관찰 가능하고, 검토 가능하며, 유지 관리 가능하게 만드는 방법입니다.

내가 유지하고 싶은 표준

진정한 플러그인 (plugin)은 거대할 필요가 없습니다. 진실을 말할 필요가 있을 뿐입니다.

그것은 자신이 무엇을 할 수 있는지, 무엇을 할 수 없는지, 어떤 권한 (authority)이 필요한지, 어떤 증거 (evidence)를 반환하는지, 그리고 어떻게 실패하는지를 말해야 합니다. 만약 모터 (motor)가 단순한 스캐폴드 (scaffold)라면, scaffold_only를 반환하십시오. 만약 작업이 수행되지 않았다면, 매끄러운 문장 (polished prose)이 마치 작업이 수행된 것처럼 암시하게 두지 마십시오.

기술 (Skills)은 중요합니다. 플러그인 (Plugins)은 중요합니다. MCP도 중요합니다. 하지만 이들 중 그 어떤 것도 그 역할이 모호해질 때 더 강력해지지는 않습니다.

모터를 구축하십시오. 잘못된 입력 (bad inputs)을 처리하십시오. 결과를 검사하십시오. 비밀 (secret)을 보호하십시오. 경계 (boundary)를 문서화하십시오. 중대한 결정에 대해서는 인간이 책임을 지도록 유지하십시오.

이것은 만능 에이전트 플러그인 (universal agent plugin)을 약속하는 것보다 덜 마법적입니다. 하지만 동시에 훨씬 더 강력합니다. 왜냐하면 실제로 작동하기 때문입니다.

당신이 실제로 검증할 수 있는 증거를 생성했던 가장 작은 플러그인 모터 (plugin motor)는 무엇입니까?

더 깊이 알아보기 위한 5가지 참고 자료

• Using skills to accelerate OSS maintenance — OpenAI Developers
• MCP authorization specification — Model Context Protocol
• WebMCP best practices — Chrome for Developers
• Secrets Management Cheat Sheet — OWASP
• RFC 9700: Best Current Practice for OAuth 2.0 Security — IETF