AI 에이전트 간의 협업

최근 에이전트 간의 협업에 대해서 많은 고민을 했다. 나는 Claude Code를 주로 사용하기 때문에 이런 고민을 할 일이 없었는데, 동료 개발자를 통해 카카오톡 선물하기로 ChatGPT Pro를 한 달 동안 10% 가격에 사용할 수 있는 프로모션을 알게 됐고, 경험 삼아 써보게 된 게 발단이었다.

에이전트 간 MD 파일 지원 방식의 문제점

기존에 내 개발 환경은 모두 Claude Code를 기준으로 설정되어 있었다. 문서 자동화나 글로벌한 코딩 스타일 규칙, git 커밋 규칙, 디렉토리별 참조 규칙 등. 그런데 새로 설정한 Codex는 이런 맥락을 전혀 모르고 있으니 처음부터 다시 설정해야 한다는 게 막막했다. 게다가 Claude Code처럼 루트(/) 경로까지 재귀적으로 CLAUDE.md를 참조하면서 맥락을 파악하는 방식은 Codex에선 아예 지원하지 않는 기능이었다. 설정 방식 자체가 에이전트마다 달라지니, 이를 계기로 서로 다른 AI 에이전트들이 공통 규격을 따르면 좋겠다는 생각을 하게 됐다.

MCP(Model Context Protocol)

MCP는 AI 애플리케이션을 외부 시스템에 연결하기 위한 오픈 소스 표준이다. 예를 들어 엑셀 파일을 다루거나 DB를 조회하는 기능을 tool로 만들어두면, 에이전트가 맥락을 파악해서 상황에 맞게 골라 쓰는 구조다. 한번 만들어두면 MCP를 지원하는 어떤 에이전트에서도 재사용할 수 있다는 게 핵심이다. 더 자세한 내용은 공식 사이트에서 확인할 수 있다.

가장 먼저 떠오른 건 이 MCP였다. 대부분의 에이전트가 MCP를 지원한다는 걸 확인하고 나니, MCP 서버를 하나 만들어서 프로젝트의 공통 설정이나 도메인 지식을 등록·변경·기여할 수 있게 해두면, 팀원들이 각자 사용하는 에이전트에 그 MCP를 연결해서 쓰면 되지 않을까 하는 생각이 들었다.

하지만 결론적으로 MCP를 쓰는 건 좀 과하다고 판단했다. 요구사항이나 도메인 지식베이스를 공유하는 게 목적인데, 거기에 MCP 서버까지 직접 설계하고 구현하는 건 문제에 비해 너무 무거운 해결책이었다. 라이브러리를 몇 번 직접 만들어본 경험상, 구현 당시의 의도와 달리 이미 누군가 더 잘 만들어서 유지보수하고 있는 게 있거나, 얼마 지나지 않아 사용하지 않게 되는 경우가 많았다. 이번에도 같은 전철을 밟을 것 같다는 느낌이 강하게 들었다.

그래서 MCP를 어떻게 만들지 설계하다가 방향을 틀어, 에이전트 협업이라는 키워드로 정보를 검색하기 시작했다.

에이전트들의 표준 md 파일

내가 원하는 협업 환경에 대해 해결해야 할 문제점들을 보면 다음과 같다.

1. 에이전트마다 설정 파일이 다르다 — Claude Code는 CLAUDE.md, Codex는 AGENTS.md, Gemini CLI는 GEMINI.md를 읽는다. 같은 프로젝트에서 같은 규칙을 공유하고 싶은데, 파일부터 달라지는 거다.
2. 프로젝트 공통 지식을 모든 에이전트가 참조하게 해야 한다 — 코딩 스타일, 디렉토리 구조, 도메인 규칙 같은 건 에이전트가 뭐든 동일하게 알아야 한다.
3. 개인 설정과 팀 공유 설정을 분리해야 한다 — 내 에이전트만의 워크플로우 규칙(예: 자동 커밋 여부)과 팀 전체가 따라야 할 규칙은 다르다.
4. 분산 레포지토리에서도 지식을 공유할 수 있어야 한다 — 모놀리식 레포지토리뿐만 아니라 한 도메인(프로젝트)을 완료하기 위해 분산된 레포지토리(예: frontend, backend, mobile 등)에서 팀원들이 쉽게 지식베이스나 가이드라인 준수 사항들을 확인하고 지속적으로 개선할 수 있어야 한다.

비슷한 고민을 하는 사람이 나만은 아니었다. 정보를 찾다가 agents.md라는 사이트를 발견했는데, Linux Foundation 산하의 Agentic AI Foundation이 관리하고 있고, 이미 60,000개 이상의 오픈소스 프로젝트에서 사용 중이라고 한다. README가 사람을 위한 문서라면, AGENTS.md는 AI 에이전트를 위한 전담 문서라는 컨셉이었다.

이걸 보고 바로 시도했다. Codex, Cursor, Windsurf 등 20개 이상의 플랫폼이 AGENTS.md를 자동으로 읽는다는 걸 확인했고, 여기에 프로젝트 공통 규칙을 모아두면 팀원들이 어떤 에이전트를 쓰든 같은 맥락을 공유할 수 있겠다고 생각했다.

문제는 Claude Code와 Gemini CLI였다. 이 둘은 AGENTS.md를 공식 지원하지 않는다. 그래서 CLAUDE.md에 "AGENTS.md를 참조하라"는 내용을 수동으로 추가하는 식으로 우회했다. 쉘 스크립트로 이 과정을 자동화해볼까도 생각했는데, 막상 해보니 AGENTS.md에 작성하는 내용은 초기 프로젝트 구성 이후로 크게 바뀌지 않았다. 스크립트를 만들고 유지하는 비용 대비 효과가 적어서, 지원하지 않는 에이전트에는 수동으로 참조를 추가하는 것으로 타협했다.

완벽하진 않지만, 최소한 한 곳에서 규칙을 관리하고 에이전트별 설정 파일에서 그걸 가리키게 하면 되니까 나름 괜찮은 구조라고 생각했다.

에이전트 스킬 (Agent Skills)

AGENTS.md로 공통 규칙을 정의하는 건 잘 됐다. 그 다음으로 활용하게 된 게 에이전트 스킬(Agent Skills)이라는 개념이다. 원래 Anthropic에서 만든 개념인데, 지금은 오픈소스로 공개되면서 대부분의 에이전트가 지원하게 됐다. .agents/skills/ 같은 디렉토리에 마크다운 파일을 모아두고, 에이전트가 필요할 때 on-demand로 로딩하는 구조다. 예를 들어 "NestJS 서비스 작성법", "PR 컨벤션", "Docker 배포 절차" 같은 기술 가이드라인을 스킬로 만들어두면, 에이전트가 관련 작업을 할 때 자동으로 참조한다.

여기서 실용적인 도구도 발견했다. Vercel에서 만든 skills라는 npm 패키지인데, npx skills add로 스킬을 설치하면 각 에이전트 설정에 맞는 방식으로 글로벌 또는 프로젝트 단위로 스킬을 세팅해준다. 에이전트마다 스킬 파일 위치나 참조 방식이 달라도 이 도구가 알아서 처리해줘서 훨씬 편했다.

나는 여기에 도메인 지식도 넣었다. HR 시스템의 엔티티 정의, 연차 계산 규칙, 결재 흐름 같은 비즈니스 로직을 knowledge-base라는 스킬로 관리했는데, 나름 잘 돌아갔다. AGENTS.md와 스킬로 프로젝트를 구성하고, 멀티 레포 구조에서도 npx skills add로 지식베이스 스킬을 각 레포에 설치하면 하나의 지식베이스를 여러 레포에서 공유할 수 있었다.

실제로 이런 구조로 운영 중이다.

• pokitwork — SvelteKit 기반 풀스택 프레임워크. 현재는 프론트와 백엔드를 모놀리식으로 관리
• knowledge-base — 지식베이스 스킬 레포. 프로젝트가 여러 레포로 분리될 경우 각 레포에서 npx skills add로 설치하면 하나의 지식베이스를 여러 곳에서 바라볼 수 있다

Spec Kit과 스펙 주도 개발 (SDD)

이 구조로 한동안 잘 쓰고 있었는데, 개발을 진행하다 보니 다른 문제가 생겼다. 에이전트들이 맥락을 잘 이해하고 변경된 요구사항도 지식베이스에 잘 반영해줬는데, AI에게 너무 의존하다 보니 오히려 내가 요구사항을 스스로 이해하는 능력이 떨어지는 느낌이 들었다. 최초 요구사항 분석 때 대충 정리해서 AI에게 넘기고, 이후엔 변경사항을 지식베이스에 반영하는 것만 반복하다 보니, 내가 만드는 프로젝트에 대한 이해도가 점점 희미해지는 거다. 개발자가 개입하는 영역이 줄어들수록 자신감도 같이 하락했다.

이 부분을 어떻게 개선할까 고민하다가, 예전에 선임 개발자가 언급했던 스펙 주도 개발(Spec-Driven Development, SDD)이 떠올랐다. 당시엔 내 상황에 맞지 않는다고 흘려들었는데, 지금 와서 보니 딱 필요한 방법론이었다. 에이전트와 팀원 사이에 개발자가 적당히 개입할 수 있는 구조, 그게 스펙이었다.

찾다 보니 GitHub이 만든 오픈소스 도구 Spec Kit이 나왔다. 간단히 말하면 코드보다 스펙을 먼저 작성하고, 그 스펙을 기반으로 AI가 구현하는 방식이다.

Spec Kit의 핵심은 .specify/ 폴더에 들어가는 마크다운 문서들이다.

.specify/
  memory/
    constitution.md       ← 프로젝트 원칙 (모든 에이전트 공유)
  specs/
    001-auth/
      spec.md             ← 무엇을 만들지 (요구사항)
      plan.md             ← 어떻게 만들지 (설계)
      data-model.md       ← 데이터 구조
      tasks.md            ← 할 일 목록

constitution.md는 프로젝트의 기술 스택, 코딩 원칙, 핵심 규칙을 담는 파일인데, Spec Kit이 지원하는 모든 에이전트(Claude Code, Codex, Gemini CLI, Cursor 등)가 이 파일을 참조하도록 자동 설정된다. 그리고 스펙 문서를 직접 작성하는 과정 자체가 개발자가 요구사항을 깊이 이해하는 과정이 되니, 내가 느끼던 문제도 자연스럽게 해결될 것 같았다.

현재는 기존에 진행 중인 프로젝트에 Spec Kit을 거꾸로 도입하면서 사용해보는 중이다. 멀티 레포는 공식 지원하지 않아서 심볼릭 링크로 .specify/를 knowledge-base 레포에 연결하는 방식으로 우회하고 있는데, 아직 충분히 검증하지는 못한 단계다.

그래서 역할을 이렇게 정리했다.

마무리

정리하면, 내가 시도한 흐름은 이렇다.

1. MCP 서버를 직접 만들자 → 과하다, 그만둠
2. AGENTS.md에 공통 규칙을 모으자 → 공통 규칙은 되지만, 방대한 도메인 지식과 멀티 레포에는 한계
3. 에이전트 스킬로 지식을 관리하자 → 기술 가이드와 도메인 지식 모두 나름 잘 됐지만, AI 의존도가 높아지면서 개발자 개입이 줄어드는 문제가 생김
4. Spec Kit의 constitution.md로 통일하자 → 현재 개선 중

아직 완벽한 답을 찾은 건 아니다. 에이전트마다 설정 파일이 다른 문제는 여전하고, 커뮤니티에서도 표준 통일을 요구하는 목소리가 크다. 하지만 적어도 "무엇을"과 "어떻게"를 분리하고, 에이전트별 진입점은 얇게 유지하면서 공통 소스를 한 곳에서 관리한다는 방향은 개선하다 보면 더 좋은 방법에 가까워지지 않을까 생각해본다.