팀에서 AI 에이전트 설정을 통일하는 메커니즘 APM

서론

AI에게 코드를 작성하게 할 때, 출력을 안정시키기 위해서는 「규칙 지시서(Skill)」가 필수적입니다.

하지만, **「그 규칙을 어떻게 팀원 전체와 공유할 것인가」**는 큰 과제입니다. 개인의 .cursorrules에 수동으로 복사하여 붙여넣는 운영 방식으로는 반드시 환경 차이(A님에게만 잘 작동하는 등)가 발생합니다.

이 「AI 환경의 개인화(属人化)」를 해결하는 것이 Microsoft의 APM(Agent Package Manager) 입니다.

APM은 한마디로 **「AI 에이전트를 위한 npm」**입니다.

프로젝트의 AI 규칙을 코드화(apm.yml)하고, Git을 통해 팀원 전체에게 한 번에 공유 및 배포하는 방법을 튜토리얼 형식으로 소개합니다.

APM이 해결하는 워크플로우 전체도

APM을 도입하면 규칙의 「작성·검증」부터 「패키지화」, 그리고 타 팀으로의 「자동 배포」까지 일관되게 연결됩니다. 본 기사에서는 다음의 전체상을 순서대로 체험해 보겠습니다.

튜토리얼: APM으로 AI 에이전트 환경을 구축하기

실제로 Vite로 React 프로젝트를 생성하고, APM을 사용하여 AI 환경을 구축 및 공유하기까지의 흐름을 단계별(Step-by-step)로 체험해 봅시다.

Step 1: Vite로 React 프로젝트 생성하기

먼저, 베이스가 되는 React 프로젝트를 생성합니다. 다음 명령어를 실행해 주세요.

# Vite로 React(TypeScript) 프로젝트 생성
npm create vite@latest react-apm-skills-demo -- --template react-ts
cd react-apm-skills-demo
...

이것으로 개선 대상이 될 표준적인 React 앱이 준비되었습니다.

Step 2: APM 초기화 및 Skill 설치

프로젝트 루트에서 APM을 초기화하고, 외부의 우수한 규칙(Skill)을 설치합니다.

apm init -y
apm install imohuke/skills/skills/vercel-react-best-practices
apm install anthropics/skills/skills/frontend-design
...

실행 후, 프로젝트 루트에 다음과 같은 apm.yml (package.json에 해당)이 자동으로 생성됩니다. 이것만으로 AI가 Skill을 읽어들일 준비가 완료됩니다.

name: react-apm-skills-demo
version: 1.0.0
dependencies:
...

Step 3: 의존 도구의 셋업 자동화하기

AI가 사용하는 CLI 도구 자체의 설치 명령어 또한 팀에서 공유합니다. apm.yml에 scripts를 추가합니다.

# ... (생략) ...
scripts:
  setup: npm install -g @playwright/cli@latest

이를 정의해 두면, apm run setup이라는 명령어로 언제든지 도구를 설치할 수 있게 됩니다. 실제로 실행해 봅시다.

> apm run setup
[>] Running script: setup
> npm install -g @playwright/cli@latest
...

이로써 「명령어 한 번으로 셋업이 끝나는」 상태를 만들 수 있었습니다.

Step 4: 자체 규칙 생성 및 컴파일 (로컬 개발)

자사 고유의 로컬 규칙을 생성하고 AI가 인식하게 하는 절차입니다.

1. 규칙 생성

먼저, .apm/instructions/ 디렉토리에 Markdown 파일을 생성합니다.

---
name: my-react-rules
description: Custom react rules
...

2. 컴파일 실행

작성한 규칙을 AI가 읽을 수 있는 형식으로 컴파일합니다.

> apm compile
[*] Starting context compilation...
[i] Targets: gemini (source: apm.yml)
...

컴파일이 성공하면 프로젝트 루트에 각종 에디터용 파일이 자동으로 생성됩니다.

my-project/
+-- apm.yml
+-- .apm/
...

※ apm.yml의 targets 지정에 맞춰 파일이 생성됩니다. 모든 에디터용으로 생성하고 싶다면 apm compile --all을 사용합니다.

실제로 생성된 AGENTS.md의 내용을 살펴보면, 여기저기 흩어져 있던 규칙들이 AI가 읽기 쉬운 하나의 파일로 통합되어 있음을 알 수 있습니다.

# AGENTS.md
<!-- Generated by APM CLI from distributed .apm/ primitives -->
## Global Instructions
...

개발 중에는 Hot Reload ( --watch) 사용하기

규칙을 조정하는 동안 매번 명령어를 실행할 필요가 없습니다.

> apm compile --watch
[>] Watching for changes in: .apm/, apm.yml
[i] Press Ctrl+C to stop watching...
...

이것을 백그라운드에서 실행해 두면, Markdown 파일을 편집하고 저장할 때마다 AGENTS.md가 즉시 재구축됩니다.

Step 5: 다른 팀과의 공유 및 배포 (패키징)

완성된 사내 규칙을 다른 팀에 배포하여 사용하게 하려면 패키징(packaging) 작업을 수행합니다. 여기서 사용하는 것이 apm pack 명령어입니다.

apm pack이란 어떤 명령어인가요?

로컬의 .apm/ 디렉터리 아래에서 개발한 규칙들을, 다른 팀이 그대로 apm install할 수 있는 '배포용 아티팩트(패키지)'로 빌드하고 수집하는 명령어입니다.

규칙 개발이 어느 정도 마무리되어,

> apm compile
[*] Starting context compilation...
[i] Compiling for AGENTS.md + GEMINI.md
...

최종적인 프로젝트 트리

컴파일이 완료되면, 사용자의 AI 에디터 환경(Cursor, Copilot, Gemini 등)에 맞춰 설치된 규칙이 적절한 형식으로 자동 배포됩니다.

other-team-project/
+-- .agents/
+-- skills/ # 설치된 외부 패키지 그룹
...

이와 같이, "규칙을 만드는 측(팀 A)은 한 곳에 작성하여 pack하기만 하면 되고, 사용하는 측(팀 B)은 install하여 compile하기만 하면 됩니다."

apm audit

안전한 운용을 위한 명령어 (서드파티(Third-party) Skill을 프로젝트에 도입할 때, "악의적인 기술의 혼입"을 방지해야 합니다. APM에는 이를 검사하는 apm audit 명령어가 갖춰져 있습니다.)

# 숨겨진 문자나 악의적인 프롬프트 인젝션 (Prompt Injection)을 스캔
apm audit --ci

실행 결과는 다음과 같습니다. 프로젝트의 안전성이 항목별로 체크되고 있음을 알 수 있습니다.

> apm audit --ci
[!] No org policy found at org:tamutamu/.github; enforcement skipped
[>] Replaying install (cache-only)...
...

CI/CD에 통합함으로써 설정 미비나 악의적인 프롬프트의 혼입을 차단하고, 안전한 운용이 가능해집니다.