에이전트 설정에 「package.json」이 등장했다 ― Microsoft APM(Agent Package Manager)의 미래성과

서론

계기는 사내의 다른 프로젝트에서 APM(Agent Package Manager)을 사용하고 있는 사례를 본 것이었다. 편리해 보인다는 인상은 받았지만, 구체적인 이미지는 떠오르지 않았다. 그래서 실제로 조사하고 만져보니, 평소 안고 있던 두 가지 고민이 해결되었다.

하나는 여러 프로덕트에서 Claude Code를 사용하게 되면서, 프로덕트마다 동일한 Skill이나 MCP 설정을 복사해서 배포하는 작업. 또 하나는 Devcontainer 환경에서 로컬의 Claude 설정을 마운트하면 충돌이 발생한다는, 사소하지만 까다로운 문제였다.

이 기사는 도입 절차 그 자체보다는, "왜 지금 APM에 주목해야 하는가"를 미래성·확장성·거버넌스(Governance)의 관점에서 기술 선정의 판단 자료로 정리하는 것을 목표로 한다. 요점에서는 실제로 사용하며 느낀 사용감을 논거로 녹여낼 것이다.

참고로 본 기사는 2026년 6월 시점(APM v0.21.0)의 정보를 바탕으로 하고 있다. APM은 활발하게 개발이 진행되고 있으므로, 최신 사양은 공식 문서를 확인해 주길 바란다.

APM이란 무엇인가

APM은 Microsoft가 OSS(MIT 라이선스)로 공개하고 있는, **AI 에이전트 설정을 위한 의존성 관리자(Dependency Manager)**다. 입지를 한마디로 말하자면, package.json이나 requirements.txt, Cargo.toml의 에이전트 버전이라 할 수 있다.

AI 코딩 에이전트는 유용하게 작동하기 위해 대량의 컨텍스트(Context)를 필요로 한다. 코딩 규약, 프롬프트(Prompt), Skill, 플러그인(Plugin), MCP 서버……. 하지만 현재로서는 이 모든 것을 거의 모든 프로젝트에서 개발자가 수동으로 셋업하고 있다. 저장 위치도 형식도 툴마다 제각각이라, 포터블(Portable)하지도 재현 가능하지도 않다. 즉, 이것들을 관리할 "매니페스트(Manifest)"가 존재하지 않았다.

APM은 이 부분을 채워준다. 프로젝트에 필요한 에이전트 의존성을 apm.yml에 한 번 선언해 두면, 리포지토리를 클론(Clone)한 개발자가 apm install을 실행하는 것만으로 몇 초 만에 동일한 에이전트 환경이 재현된다.

# apm.yml — 리포지토리에 동봉하는, package.json과 같은 것
name: my-project
version: 1.0.0
...

git clone <repo> && cd <repo> && apm install
# 이것만으로 충분. 검출된 모든 하네스(Harness)가 구성됨

여기서 중요한 점은, 생성 대상이 단일 툴에 국한되지 않는다는 점이다. 동일한 apm.yml로부터 GitHub Copilot, Claude Code, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro와 같은 여러 에이전트(하네스)를 향해 설정이 전개된다. 에이전트마다 설정을 따로 작성할 필요가 없다.

APM의 설계 사상은 "Portable by manifest(매니페스트로 이식 가능) / Secure by default(기본적으로 안전) / Governed by policy(정책으로 통제)"라는 세 가지 약속으로 집약되어 있다. 후술할 미래성·확장성도 모두 이 세 기둥에서 파생된다.

미래성이라는 관점

새로운 툴을 채택할지 판단할 때 가장 신경 쓰이는 것은 "이 추상화(Abstraction)가 오래 지속될 것인가"이다. APM에 관해서는 몇 가지 이유로 미래성이 높다고 느끼고 있다.

"익숙한 추상화"를 에이전트 영역으로 가져오고 있다

패키지 매니저(Package Manager)라는 개념 자체는 npm, pip, Cargo, Maven 등 이미 수십 년간 검증되어 온 익숙한 추상화다. 매니페스트와 락 파일(Lock file)로 의존성을 선언하고 재현성을 담보한다는 형태는 소프트웨어 개발에서 반복적으로 승리해 온 패턴이다.

AI 에이전트의 설정 관리는 지금 바로 "모두가 수동으로 설정하고 있는" 단계에 있다. 이는 라이브러리를 수동으로 복사하던 시대와 구조적으로 동일하다. 역사적으로 이러한 종류의 수작업은 반드시 패키지 매니저로 대체되어 왔다. APM이 그 역할을 담당할 가능성이 높다는 것이 기본적인 견해다.

오픈 표준 위에 서 있다

APM은 독자적인 사양으로 가두는 것이 아니라 AGENTS.md, Agent Skills, MCP와 같이 업계에서 합의가 진행 중인 오픈 표준(Open Standard) 위에 구축되어 있다.

이는 미래성을 측정하는 데 있어 매우 중요한 요소다. 설령 APM 자체의 인기가 변동하더라도, 입출력이 표준 포맷(Standard Format)인 한 자산(Skill이나 instructions)은 다른 도구로 옮길 수 있다. 락인(Lock-in) 리스크가 구조적으로 작기 때문에 장기적인 투자가 용이하다.

멀티 하네스(Multi-harness)를 전제로 하고 있다

현시점에서 AI 코딩 에이전트(AI Coding Agent)의 패자는 확정되지 않았다. Claude Code, Copilot, Cursor, Codex…… 세력도는 유동적이다.

이러한 상황에서 '특정 에이전트 전용 설정 자산'을 쌓아 올리면, 해당 에이전트가 주류가 아니게 되었을 때 자산까지 통째로 다시 만들어야 하는 재작업(rework)이 발생하기 쉽다. APM은 처음부터 "어떤 하네스에서도 동일한 매니페스트(Manifest)로부터 전개한다"라는 전제에 서 있기 때문에, 에이전트 선정의 불확실성에 좌우되지 않는다. 조직으로서 여러 에이전트를 병용하거나 이행하는 미래를 내다볼수록 이 설계의 가치는 커진다.

Microsoft가 microsoft/apm을 공식적으로 내놓고 있다는 점, 릴리스가 활발하며 스타(Star) 수도 늘어나고 있다는 점 또한 에코시스템(Ecosystem)의 지속성을 판단하는 데 있어 긍정적인 요소다.

확장성이라는 관점

미래성이 "얼마나 오래 지속되는가"에 대한 이야기라면, 확장성은 "어디까지 넓힐 수 있는가"에 대한 이야기다. 이 부분은 실제로 사용해 보면서 실감이 컸던 부분이기도 하다.

하나의 매니페스트가 기점이 되는 구조

APM 확장성의 핵심은 apm.yml이라는 단일 기점에 모든 프리미티브(Primitives: instructions, Skill, prompt, agent, hook, plugin, MCP 서버)를 집약할 수 있다는 점에 있다.

어디서든 설치 가능: GitHub뿐만 아니라 GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea 등 임의의 Git 호스트에서 가져올 수 있다. 사내 Git에 호스팅한 독자적인 패키지도 동일한 방식으로 배포할 수 있다.
이행적 의존성 (Transitive dependencies): 패키지가 다른 패키지에 의존할 수 있으며, APM이 의존성 트리(Dependency Tree) 전체를 해결한다. npm과 같은 감각으로 패키지를 조합하여 키워나갈 수 있다.
플러그인 저작 (Authoring): 의존성 관리가 포함된 플러그인을 구축하고, 표준 plugin.json으로 내보낼(Export) 수 있다. '소비하는 것'뿐만 아니라 '만들어서 배포하는' 측면에서도 활동할 수 있다.
마켓플레이스 (Marketplace): 큐레이션된 레지스트리(Registry)로부터 명령어 한 줄로 플러그인을 도입할 수 있다.

# 마켓플레이스를 추가하고, 거기서 설치
apm marketplace add github/awesome-copilot
apm install azure-cloud-development@awesome-copilot

사용감 ①: 각 프로덕트로의 전개가 용이함

여기서부터가 실제로 만져보며 좋다고 느낀 점이다.

서두에서 언급했듯이, 여러 프로덕트에서 동일한 Skill이나 MCP를 복사해서 붙여넣는(Copy-paste) 작업에 은근히 소모되고 있었다. APM을 사용하면 공통 설정군을 하나의 패키지(또는 사내 리포지토리의 apm.yml)로 묶어 두고, 각 프로덕트에서는 apm install로 가져오기만 하면 된다.

수평 전개(Horizontal expansion) 비용이 '복사 붙여넣기 + 수정'에서 '의존성을 한 줄 선언하기'로 바뀐다. 프로덕트 수가 늘어날수록 효과는 커진다. 게다가 앞서 언급했듯이 생성 대상이 멀티 하네스이므로, "프로덕트 A는 Claude Code, 프로덕트 B는 Cursor"와 같이 사용하는 도구가 다르더라도 설정의 출처를 일원화할 수 있다. 확장성이 '프로덕트 축'과 '에이전트 축'이라는 2차원으로 작용한다 —— 이것이 사용해 보며 가장 명확하게 실감할 수 있었던 점이었다.

구체적인 예시로, Claude Code의 플러그인을 가져오는 절차를 들겠다. github/awesome-copilot의 frontend-web-dev 플러그인을 Claude Code용으로 도입할 경우, apm.yml은 다음과 같이 작성할 수 있다.

name: my-project
version: 1.0.0
targets:
...

apm install

이것만으로 플러그인에 포함된 agent나 Skill이 Claude Code의 기본 경로로 전개된다.

.claude/agents/electron-angular-native.md
.claude/agents/expert-react-frontend-engineer.md
.claude/skills/playwright-explore-website/SKILL.md
...

직접(APM v0.21.0) 테스트해 본 범위에서는, apm install 한 번으로 여기까지 완료되며, apm.lock.yaml에 해결된 commit과 해시(hash)가 고정되었다(정합성 검사의 상세 내용은 후술할 거버넌스 절을 참조). apm install github/awesome-copilot/plugins/frontend-web-dev라는 단축 표기법도 있지만, 위의 git: 형식은 임의의 Git 호스트에 동일한 방식으로 작성할 수 있어 사내 리포지토리(repository)에도 응용하기 쉽다.

사용감 ②: Devcontainer 환경에서의 로컬 설정 분리

또 하나, 궁합이 좋다고 느낀 점은 Devcontainer와의 조합이다.

Claude Code를 Devcontainer 내에서 안전하게 구동하는 구성 자체는 권장되고 있지만, 로컬(호스트)의 Claude 설정을 컨테이너에 마운트(mount)하려고 하면 충돌이나 오염이 발생하기 쉽다. 전형적인 사례는 인증 정보 관련 문제다. 호스트의 인증 토큰을 재사용하기 위해 마운트하면, 인증 정보뿐만 아니라 설정이나 MCP · 플러그인(plugin) 상태까지 함께 유입되어 컨테이너의 독립성이 무너진다. 그렇다고 마운트하지 않으면, 컨테이너를 리빌드(rebuild)할 때마다 재로그인을 요구받게 된다. 호스트의 개인 설정과 컨테이너 내의 설정이 섞이면 재현성 관점에서도 문제가 남는다.

APM을 사용하면 이 문제에 대한 접근 방식이 달라진다. 로컬 고유의 설정을 APM의 매니페스트(manifest)에 봉인하고, 컨테이너 측에서는 apm install로 설정을 재구축한다는 형태로 만들 수 있다. 호스트 설정을 마운트하여 공유하는 것이 아니라, 선언으로부터 다시 조립하는 것이다.

결과적으로 Devcontainer 환경에서도 로컬 환경을 분리한 채로 필요한 에이전트 설정만을 재현할 수 있다. '설정을 가져오는' 것이 아니라 '매니페스트로부터 조립하는' 방식을 통해 독립성과 재현성을 양립한다. 확장성이라기보다 설계의 우수성에 관한 이야기지만, 이러한 운용에 무리 없이 올라탈 수 있다는 점은 도구로서의 완성도가 높음을 보여준다.

거버넌스(Governance): 조직 규모에서의 확장

확장성은 팀 내에 국한되지 않는다. APM에는 apm-policy.yml에 의한 정책 통제가 있어, 보안 팀이 "허용하는 소스 · 스코프 · 프리미티브(primitive)는 이것뿐이다"라고 선언하면 모든 apm install이 이를 강제한다. 정책은 enterprise → org → repo 방향으로 "조이는 방향으로만" 상속된다.

게다가 설치 시 숨겨진 유니코드(에이전트의 동작을 탈취할 수 있는 불가시 문자)를 스캔하고, 락 파일(apm.lock.yaml)로 정합성 해시를 고정하며, 전이적으로 들어오는 MCP 서버는 명시적인 동의가 없는 한 차단된다. apm audit을 사용하면 생성물과 작업 트리(working tree)의 차이(drift)를 검출하여 수동 편집이 섞여 들어가는 것을 방지할 수 있다.

개인이나 소규모 팀의 편의성부터 조직 전체의 거버넌스까지, 동일한 매니페스트 메커니즘을 유지한 채 단계적으로 스케일(scale)할 수 있다 —— 이것이 APM 확장성의 도달점이라고 생각한다.

현 시점에서의 유의점

공정성을 기하기 위해 낙관적인 전망뿐만 아니라 주의해야 할 점도 언급해 두겠다.

첫 번째는 락인(lock-in)에 대한 우려가 완전히 사라지지 않는다는 점이다. 앞서 언급했듯이 APM 자체는 오픈 표준(open standard) 위에 서 있지만, 그 위에 올라가는 프리미티브의 사양은 에이전트마다 다르다. 특히 Claude Code의 플러그인이나 훅(hook) 메커니즘은 각 에이전트마다 별개이며, APM은 "각 타겟에 맞춰 plugin.json을 엑스포트(export)하는" 형태로 이 차이를 흡수하고 있을 뿐이다. Skill 또한 Agent Skills라는 오픈 표준을 따르고는 있지만, 각 에이전트에서의 로드 방식이나 동작에는 차이가 있다. 뒤집어 말하면, Claude(Anthropic) 고유의 방식에 강하게 의존하여 만들어진 패키지는 다른 하네스(harness)로 그대로 옮기기 어렵다. APM의 이식성은 어디까지나 배포 레이어의 이야기이며, 프리미티브 계층에서는 Claude로의 락인이 남을 수 있다는 점을 의식해 둘 필요가 있다.

다음으로, APM은 아직 버전 0.x 계열이며 사양(Specification)이 활발하게 변화하고 있다. 본 기사의 커맨드(Command)나 매니페스트(Manifest) 표기법도 향후 릴리스에서 변경될 가능성이 있다. 프로덕션의 크리티컬 패스(Critical Path)에 포함시키기 전에, 버전 고정과 락 파일(Lockfile)의 커밋은 필수라고 생각하는 것이 좋다.

나아가, 패키지 매니저(Package Manager)는 에코시스템(Ecosystem)의 두께가 가치를 결정한다. npm이 강력한 이유는 방대한 패키지가 있기 때문이며, APM 또한 마켓플레이스(Marketplace)나 공개 패키지의 충실도가 향후 보급을 좌우할 것이다. 현재는 아직 도입기 단계로, "사용하고 싶은 패키지가 갖춰져 있는가"는 영역에 따라 차이가 있다.

마지막으로, 에이전트 설정을 선언적으로 외부화하는 이상, "설정 내용(프롬프트나 Skill)의 품질"은 별개의 문제로 남는다. APM은 어디까지나 배포와 재현을 위한 기반이며, 좋은 인스트럭션(Instructions)을 작성할 책임은 여전히 이용자 측에 있다. agentrc와 같은 인스트럭션 생성 도구와 조합하는 것을 전제로 생각하고 싶다.

요약

APM을 한마디로 평하자면, "AI 에이전트 설정에 드디어 package.json이 등장했다"라고 할 수 있는 도구다.

미래성의 핵심은 패키지 매니저라는 성숙한 추상화(Abstraction)를 AGENTS.md, Agent Skills, MCP라는 오픈 표준(Open Standard) 위에 얹고, 멀티 하네스(Multi-harness)를 전제로 구축했다는 점이다. 락인(Lock-in)이 적고, 에이전트 선정의 불확실성도 헤지(Hedge)할 수 있다. 확장성의 핵심은 단일 apm.yml을 기점으로, 이행적 의존성(Transitive Dependency), 마켓플레이스, 플러그인 오서링(Plugin Authoring), 정책 통제까지 개인에서 조직 스케일까지 끊김 없이 확장할 수 있다는 점에 있다. 실제로 사용해 보았을 때도, 각 프로덕트로의 수평 전개가 단 한 줄의 의존성 선언으로 끝난다는 점과, Devcontainer 환경에서 로컬 설정을 마운트하지 않고도 재구축할 수 있다는 점에서 명확한 효용을 느낄 수 있었다.

아직 0.x 버전의 초기 단계 도구이지만, "머지않아 에이전트 설정 또한 패키지 매니저로 관리하는 시대가 올 것"이라는 방향성은 상당히 확신도가 높다고 생각한다. 우선은 공식 샘플 패키지를 apm install 해보는 것부터 시작해 보길 권한다.

curl -sSL https://aka.ms/apm-unix | sh
apm install microsoft/apm-sample-package