Claude Code나 Codex의 설정을 팀 단위로 맞추는 「Microsoft APM」 입문 ─ npm과의 대비를 통해 이해하기

서론

Claude Code나 Codex와 같은 AI 에이전트 (AI agent)를 계속 사용하다 보면, instructions, skills, MCP 등의 설정이 조금씩 늘어납니다.

혼자서 사용할 때는 로컬에 파일을 두거나 필요한 것을 복사하는 것만으로도 문제가 되지 않습니다. 하지만 여러 명의 AI 에이전트를 팀 단위로 사용하기 시작하면 다음과 같은 차이가 발생합니다.

• 사람마다 설정된 내용이 다름
• 업데이트를 해도 다른 멤버에게 반영되지 않음
• 새로 참여한 사람이 동일한 환경을 구축할 수 없음
• Claude Code와 Codex에서 동일한 설정을 이중으로 관리함

이러한 설정도 라이브러리와 마찬가지로 "무엇을 사용할지", "어떤 버전을 사용할지"를 프로젝트 측에서 관리하고 싶어집니다.

Microsoft의 APM은 이 문제를 해결하기 위한 도구입니다. 공식 README에서는 다음과 같이 설명하고 있습니다.

“Think package.json, requirements.txt, or Cargo.toml — but for AI agent configuration.”

감각적으로는 AI 에이전트용 npm이라고 할 수 있습니다.

package.json이 라이브러리의 의존 관계 (dependency)를 선언하는 것처럼, APM에서는 instructions, skills, MCP 등을 apm.yml에 정의하며, apm install을 통해 동일한 환경을 재현할 수 있습니다.

이 기사에서는 실제로 APM을 다루면서 다음 세 가지 사항을 확인합니다.

• APM을 프로젝트에 도입하는 방법
• apm.yml에 무엇을 정의할 수 있는지
• Codex / Claude Code용으로 어떻게 전개되는지

npm과의 대응을 통해 전체상 파악하기

APM의 개념은 npm과 나란히 놓고 보면 이해하기 쉽습니다.

완전히 npm과 동일하지는 않지만, 의존성을 선언하고 해결 결과를 lockfile에 고정하는 방식은 매우 유사합니다.

apm.yml에는 "무엇을 사용할지"를 작성합니다. apm install을 실행하면 실제로 해결된 commit이나 hash가 apm.lock.yaml에 기록됩니다. 팀에서 사용한다면 apm.yml과 apm.lock.yaml을 모두 커밋(commit)하는 운용 방식이 됩니다.

취득처는 GitHub와 같은 Git 호스트나 marketplace입니다. 리포지토리 (repository) 전체뿐만 아니라 특정 skill이나 agent 파일만 지정할 수도 있습니다. 태그(tag)나 SHA를 붙이면 참조 대상도 고정할 수 있습니다.

npm과 조금 다른 점은 apm compile입니다.

skills, agents, MCP 설정 등은 apm install 시점에 각 에이전트용 디렉토리로 배치됩니다. 반면, apm compile이 다루는 것은 instructions입니다. 동일한 instructions로부터 Claude Code용 CLAUDE.md나 Codex용 AGENTS.md를 생성합니다.

즉, install은 의존성의 취득과 배치를, compile은 instructions의 변환을 담당합니다.

프로젝트에 도입하기

여기서는 Next.js 프로젝트를 예로 듭니다. 사용한 APM은 v0.26.0입니다.

APM 본체 설치

macOS라면 Homebrew가 간편합니다.

brew install microsoft/apm/apm

공식 인스톨러를 사용하는 경우에는 다음을 실행해 주세요.

curl -sSL https://aka.ms/apm-unix | sh

초기화하기

기존 프로젝트의 바로 아래 디렉토리에서 실행합니다.

apm init -y --target claude,codex

apm init my-app과 같이 이름을 전달하면 서브 디렉토리가 생성되므로, 기존 프로젝트에 넣을 경우에는 이름을 전달하지 않습니다.

생성된 apm.yml은 다음과 같습니다.

name: demo
version: 1.0.0
targets:
...

의존성 추가하기

샘플 패키지를 넣어 보겠습니다.

apm install microsoft/apm-sample-package

제 환경에서는 다음과 같은 출력이 나왔습니다.

[+] microsoft/apm-sample-package #main @fb285168
|-- 2 agents integrated -> .claude/agents/, .codex/agents/
|-- 1 skill(s) integrated -> .agents/skills/, .claude/skills/
...

실행 결과를 보면 APM이 무엇을 하고 있는지 알 수 있습니다.

• 샘플 패키지가 의존하는 skill(기술)도 가져옴
• 패키지 본체를 apm_modules/에 배치
• agents(에이전트)나 skills(기술)를 .claude/, .codex/, .agents/로 배치
• apm.lock.yaml에 commit(커밋)이나 hash(해시)를 기록
• 고정되지 않은 의존성에는 경고를 표시

apm install microsoft/apm-sample-package#v1.0.0

우선은 고정하지 않은 상태로 테스트해 보고, 팀에서 공유하는 단계에서 태그(tag)나 SHA를 지정하는 것이 좋아 보입니다.

무엇을 커밋할 것인가

저는 다음과 같은 방침을 세웠습니다.

• apm.yml과 apm.lock.yaml은 커밋한다.
• apm_modules/는 커밋하지 않는다.
• .claude/나 .codex/의 생성물은 팀 방침에 따라 결정한다.

apm_modules/는 자동으로 .gitignore에 추가됩니다.

생성물에 대해서는, APM을 설치하지 않은 환경에서도 사용할 수 있게 하고 싶다거나, 리뷰에서 차이점(diff)을 확인하고 싶다는 등의 이유가 있기 때문에, 저는 커밋하는 쪽을 선택했습니다.

CI나 셋업 시에 반드시 생성한다면, 생성물을 커밋하지 않는 선택을 할 수도 있습니다.

(이 부분은 개인이나 팀이 운용 및 관리하기 쉬운 형태를 선택하면 됩니다.)

apm.yml에 무엇을 쓸 수 있는가

의존성은 크게 두 가지로 나뉩니다.

• APM 의존성: dependencies.apm
• MCP 서버: dependencies.mcp

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

dependencies.apm에는 다음과 같은 단위로 의존성을 지정할 수 있습니다.

• instructions(지침), skills(기술), agents(에이전트) 등을 모은 풀 패키지
• 특정 용도를 모은 plugin(플러그인)
• *.agent.md와 같은 단일 파일
• 리포지토리 내의 특정 skill(기술)

GitHub 상의 의존성은 owner/repo의 생략 형식으로 쓸 수 있습니다. 리포지토리 전체뿐만 아니라 디렉토리나 단일 파일 지정도 가능합니다.

dependencies:
  apm:
    - owner/repo
...

GitLab 등 다른 Git 호스트에서는 호스트 이름을 포함합니다.

dependencies:
  apm:
    - gitlab.com/owner/repo#v2.0

버전을 고정하기

의존성 끝에 태그나 SHA를 붙이면 참조 대상을 고정할 수 있습니다.

dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0

해결 결과는 apm.lock.yaml에 기록됩니다.

- repo_url: microsoft/apm-sample-package
  resolved_commit: fb2851683be0e0e7711421d518bd8dba23b0b1f6
  version: 1.0.0
...

개인적으로 테스트하는 단계에서는 고정하지 않아도 괜찮지만, 팀 단위로 확장하는 단계에서는 고정하여 lockfile을 커밋하는 것이 좋습니다.

CLI에서 추가하기

apm.yml을 직접 편집하지 않아도, CLI를 통해 의존성 (dependency)을 추가할 수 있습니다.

apm install microsoft/apm-sample-package#v1.0.0
apm install vercel-labs/agent-skills --skill deploy-to-vercel
apm install --mcp io.github.github/github-mcp-server --transport http

CLI에서 추가한 내용은 apm.yml에 반영됩니다.

MCP의 transport: http는 URL 스킴 (scheme)이 아니라, MCP의 트랜스포트 (transport) 이름입니다. URL이 https://라면 통신 자체는 HTTPS로 수행됩니다.

Codex / Claude Code용으로 전개하기

skills, agents, MCP 설정은 apm install을 통해 각 에이전트 (agent)용으로 배치됩니다.

instructions는 apm compile을 사용하여, Claude Code용 CLAUDE.md나 Codex용 AGENTS.md로 변환합니다.

의존 관계와 대상 타겟 (target)은 apm.yml로, 프로젝트 내에서 작성하는 instructions는 .apm/을 기점으로 관리합니다.

동일한 instruction을 Codex용과 Claude Code용으로 이중 관리할 필요가 없다는 점이 핵심입니다.

타겟 확인하기

apm targets

이번 예시에서는 apm.yml의 targets에 작성한 claude와 codex가 active 상태가 됩니다.

TARGET STATUS DEPLOY DIR
------------ ---------- ----------
claude active .claude/
...

compile 하기

apm compile # apm.yml의 targets를 생성
apm compile -t claude # Claude Code용만 생성
apm compile -t codex # Codex용만 생성
...

타겟은 다음 순서로 결정됩니다.

• CLI의 --target / --all
• apm.yml의 targets
• 디렉토리로부터의 자동 탐지

평소 운영 시에는 apm.yml에 targets를 명시하고, 인자 없이 apm compile을 사용하는 것이 이해하기 쉽습니다.

--all은 apm.yml에서 활성화한 것뿐만 아니라, APM의 표준 타겟 세트 전체를 대상으로 합니다. 보통은 필요한 타겟만 명시하는 것이 안전합니다.

예를 들어, 다음과 같은 instruction이 있다고 가정해 봅시다.

- App Router를 사용한다. pages 디렉토리는 새로 추가하지 않는다.
- 서버 컴포넌트 (Server Component)를 기본으로 한다.

compile 후에는 Claude Code용으로는 CLAUDE.md, Codex용으로는 AGENTS.md로 출력됩니다.

형식은 다르지만, 근간이 되는 방침은 한 곳에서 관리할 수 있습니다.

운영에 도입하기

생성된 CLAUDE.md나 AGENTS.md를 직접 편집하지 않고, 원본인 .apm/instructions/를 수정하여 다시 compile 합니다.

예를 들어, npm scripts에 등록해 두면 일관성 있게 다루기 쉬워집니다.

{
"scripts": {
"agents:install": "apm install",
...

skills, agents, MCP만 이용하는 경우에는 apm install로 배치까지 완료됩니다. apm compile이 필요한 시점은 instructions를 각 에이전트용 형식으로 반영할 때입니다.

CI에서는 apm install --frozen을 사용할 수 있습니다. apm.yml과 lockfile 사이에 차이가 있으면 실패하므로, npm ci와 유사한 방식으로 사용할 수 있습니다.

apm install --frozen
apm compile
apm audit --ci

audit 및 업데이트

에이전트 설정은 파일을 직접 편집하거나 의존성을 변경하면, APM이 관리하고 있는 상태와의 차이가 발생합니다.

그 차이를 확인하는 것이 apm audit입니다.

공식 README에는 다음과 같은 설명이 있습니다.

“Agent context is executable in effect — a prompt is a program for an LLM.”

APM은 프롬프트(prompt)나 지침(instructions)을 단순한 문장이 아니라, 에이전트의 동작에 영향을 미치는 요소로 취급합니다.

apm audit은 npm의 npm audit처럼 알려진 라이브러리 취약점을 조사하는 명령어가 아닙니다.

에이전트에게 전달하는 콘텐츠의 불가시 문자(invisible characters)나, APM이 관리하는 상태와 실제 배치물 사이의 어긋남(drift)을 감지하는 명령어입니다.

apm audit은 예를 들어 다음과 같은 상태를 감지합니다.

• APM이 생성·배치한 파일을 직접 편집한 경우
• .apm/의 변경 사항을 install 또는 compile로 반영하지 않은 경우
• 의존성을 삭제한 후에도 오래된 배치물이 남아 있는 경우
• 지침 파일에 불가시 문자가 포함된 경우

$ apm audit
[+] Replayed 3 package(s)
[+] No drift detected
...

--format sarif를 지원하므로 CI에 통합할 수도 있습니다.

업데이트는 다음 흐름으로 진행할 수 있습니다.

apm outdated
apm update && apm compile && apm audit

또한, apm lock export를 통해 사용 중인 에이전트 자산 목록을 SBOM(Software Bill of Materials)으로 출력할 수 있습니다.

실무에서 사용한다면

좋았던 점

가장 좋다고 느낀 점은 에이전트 설정/자산을 개인 환경이 아닌 프로젝트의 의존 관계(dependency)로 다룰 수 있다는 것입니다.

• 팀에서 동일한 설정을 재현할 수 있음
  apm.yml과 lockfile을 커밋해 두면, 각 멤버가 동일한 의존성을 도입할 수 있습니다.
• 온보딩 시의 수작업을 줄일 수 있음
  "이 파일을 복사하고, 이 MCP를 수동으로 추가한다"와 같은 절차를 줄일 수 있습니다.
• Codex와 Claude Code에서 지침(instructions)을 공통화할 수 있음
  한 곳에서 관리한 내용을 각각의 에이전트가 읽는 형식으로 생성할 수 있습니다.
• 의존성의 의존성까지 관리할 수 있음
  이행 의존성(transitive dependency)을 해결하고 lockfile에 고정할 수 있으므로, 단순한 파일 복사보다 재현성이 높습니다.

아쉬운 점

현시점에서는 갑자기 전사 표준으로 도입하기보다, 검증하면서 사용하는 것이 좋아 보입니다.

• 생태계가 아직 발전 단계임
  Git 리포지토리에서 직접 가져올 수는 있지만, npm만큼 "찾으면 대부분 나오는" 상태는 아닙니다.
• 생성 결과의 확인이 필요함
  대응하는 타겟이 많더라도, 각 에이전트에서 기대한 대로 작동할지는 별개의 문제입니다. 처음에는 생성물을 육안으로 확인하는 것이 좋습니다.
• 명령어나 동작이 변경될 가능성이 있음
  APM 본체의 버전을 고정하고, 변경 사항을 확인하며 업데이트하는 운영이 필요합니다.
• 도입 출처를 어디까지 허용할지 결정해야 함
  Git 리포지토리에서 직접 가져올 수 있기 때문에, 조직 차원에서는 apm-policy.yml을 통한 제한도 검토하는 것이 좋아 보입니다.

우선은 작게 시작하기

우선 하나의 리포지토리에 최소 구성으로 도입하여, install, compile, audit을 한 번 통과시켜 보는 것이 좋다고 생각합니다.

그 과정에서 다음을 확인합니다.

• 팀 내에서 동일한 설정을 재현할 수 있는가
• Codex / Claude Code에서 생성 결과가 기대한 대로 작동하는가
• 생성물을 커밋할 것인가, 매번 생성할 것인가
• CI에 audit을 넣을 가치가 있는가

효과가 있다면 대상 리포지토리를 늘리고, CI에서의 audit이나 apm-policy.yml을 통한 이용 출처 제한으로 범위를 넓혀간다.

이 순서로 현실적으로 작게 시작할 수 있겠다는 느낌을 받았습니다.

요약

APM을 사용해 보며 가장 가치를 느낀 점은, 개인 환경에 흩어지기 쉬운 에이전트 설정을 프로젝트의 의존 관계로 다룰 수 있다는 점이었습니다.

apm.yml에 사용할 자산을 선언하고, apm.lock.yaml로 해결 결과를 고정한다. 지침(instructions)은 apm compile을 통해 각 에이전트용으로 변환하며, apm audit으로 관리 상태에서 벗어나지 않았는지 확인한다.

그 사고방식은 평소 사용하고 있는 패키지 관리 (Package Management)와 상당히 유사합니다.

우선 하나의 프로젝트에서 apm install, apm compile, apm audit을 한 바퀴 돌려본다면, APM이 해결하고자 하는 과제가 무엇인지 이해하기 쉬울 것입니다.

출처

크로스텍 매니지먼트 (Crosstech Management) 사는 「교육 × AI」를 통해 차세대 학습을 창조하기 위해 탄생한 예술 대학 발 스타트업입니다.

관심이 있으신 분들은 언제든 편하게 문의해 주시면 감사하겠습니다!

Discussion