사람과 사람끼리의 협업에서도 보다 체계적이고 전문화된 프로세스를 위해 다양한 SaaS 도구들이 고안되었죠. 이제 사람은 AI와도 협업합니다. 그런데 AI와의 협업은 여전히 대화로만 이루어지고 있죠. AI와 사람, 그리고 AI 에이전트들끼리의 협업툴은 없을까요? 그래서 만들었습니다.

저는 현재 Claude Code를 활용해 영상 관제 시스템(VMS)을 개발하고 있습니다. 백엔드와 프론트엔드를 포함하는 모노레포 프로젝트이며, 기획부터 설계, 개발까지 전 과정을 AI 드리븐으로 진행하고 있습니다. 이 글에서는 이 과정에서 만들어진 AI 에이전트 팀과 이들의 협업 도구인 AI Hub의 개발 과정을 소개합니다.

TL;DR

• LLM의 Context Window 한계를 극복하기 위해 7명의 전문화된 AI 에이전트 팀을 구성했습니다.
• 에이전트 간 협업을 위해 파일 기반 이슈 관리 시스템과 구조화된 JSON 기획 문서 체계를 설계했습니다.
• 이 모든 산출물을 사람이 검토할 수 있도록 시각화하는 사내 도구 AI Hub를 만들었습니다.
• 코드를 직접 작성하지 않고도 프로덕트를 만들 수 있었으며, 개발자의 역할이 '만드는 사람'에서 '설계하고 검수하는 사람'으로 변화하고 있음을 체감했습니다.

AI Hub 대시보드. 구조화된 데이터 4건, 문서 7건, 활성 이슈 12건, 에이전트 7명의 현황을 보여줍니다.

AI도 팀이 필요하다

처음에는 Claude Code 하나로 충분할 줄 알았습니다. "이런 기능 만들어줘"라고 지시하면 끝날 줄 알았는데, 프로젝트의 규모가 커지면서 금방 한계를 느꼈습니다.

LLM에는 Context Window라는 물리적 제약이 있습니다. 아무리 긴 컨텍스트를 지원하는 모델이라 하더라도, 하나의 세션에 기획 문서, 아키텍처 설계, 백엔드 스펙, 프론트엔드 컴포넌트 구조까지 전부 넣으면 맥락이 희석되죠. 주의를 기울여야 할 정보가 너무 많아지면 산출물의 품질이 떨어지는 건 자연스러운 현상입니다. 기획과 개발이 뒤섞이면서 일관성이 무너지는 것도 같은 맥락이었고요.

사람의 조직에서도 한 사람이 모든 역할을 겸하면 퀄리티가 떨어집니다. AI도 마찬가지였습니다. 각 에이전트가 자신의 전문 영역에 해당하는 컨텍스트만 집중적으로 다루도록 역할을 분리하면, Context Window를 보다 효율적으로 사용할 수 있고, 결과적으로 산출물의 품질도 높아질 것이라 판단했습니다.

그래서 사람의 개발 조직처럼 역할을 나눠보기로 했습니다. Claude Code에는 Agent Teams라는 기능이 있습니다. 여러 에이전트를 정의하고 각자의 역할을 부여할 수 있는 기능인데요. 이를 활용하여 7개의 에이전트로 팀을 구성했습니다.

AI Hub의 에이전트 페이지. PM의 정체성, 성격, 도구 등이 정의되어 있습니다.

에이전트	역할	비고
PM	업무 분배, 교정, 팀 운영	유일하게 에이전트 규칙 문서를 직접 수정하는 '자기 파괴 성향' 보유
Planner	PRD, 기능 명세, 역할 정의, 유저 플로우	모든 산출물을 JSON으로 작성 (이유는 후술)
Architect	시스템 아키텍처, 배포 전략, 기술 리서치	기획과 개발 사이의 기술적 교량
Backend	API, DB 스키마, 인증/인가	NestJS + Drizzle ORM 기반
Frontend	UI/UX 구현	Next.js 기반, 백엔드 스펙 문서 참조
Hub Developer	AI Hub 자체 개발/유지보수	다른 에이전트의 산출물을 시각화
CLI & Infra	CLI 도구, Docker, 배포	자율적 테스트 사이클을 수행하는 유일한 에이전트

병렬 실행은 생각보다 안 먹혔다

처음에는 Agent Teams의 병렬 실행 기능을 적극 활용하려 했습니다. 에이전트 여러 명을 동시에 돌리면 빠를 것이라는 기대였는데요.

하지만 기획 → 설계 → 개발이라는 업무 자체가 순차적이었습니다. PRD가 나와야 기능 명세를 쓸 수 있고, 기능 명세가 있어야 유저 플로우를 정의할 수 있습니다. 무리하게 병렬로 돌리니 각자 다른 맥락에서 작업하면서 산출물이 엉뚱하게 나왔습니다. Agent Teams는 토큰 소모량도 상당했고요.

결국 사람인 제가 직접 에이전트를 하나씩 소환하는 방식이 더 나았습니다. 그런데 그러다 보니 에이전트별로 전달해야 할 컨텍스트가 흩어지고, 누가 무엇을 하고 있는지 추적하기가 점점 어려워졌습니다.

파일 기반 메모리에서 시작되다

이 문제를 처음 체감한 건 AI 기획팀을 운영할 때였습니다. 기획팀은 Agent Teams 기반으로 구성했는데, 핵심 문제는 에이전트의 메모리가 세션이 끝나면 휘발된다는 것이었습니다. 어제 나눈 맥락을 오늘의 에이전트는 모릅니다.

코딩없이 Claude Code로 자율 AI 마케팅 팀을 만들어 1주일간 운영한 이야기라는 글에서 힌트를 얻었습니다. 이 글에서는 마크다운 파일로 에이전트의 직무, 스타일, 권한을 정의하고 파일 시스템으로 조직 지식을 축적하는 방식을 소개하고 있었는데요. 여기서 아이디어를 얻어 개별 에이전트마다 메모리 파일을 두고, 팀 리더가 관리하는 트래커 파일로 전체 진행 상황을 추적하는 구조를 만들었습니다.

이 방식은 잘 동작했지만, 트래커 파일이 점점 복잡해지고 에이전트 간 산출물이 늘어나면서 JSON 파일만으로는 전체 상황을 파악하기가 어려워졌습니다. 사람이 한눈에 볼 수 있는 도구가 필요했고, 그렇게 AI Hub가 시작되었습니다.

파일 기반 이슈 관리

AI Hub에서 가장 먼저 만든 것은 이슈 관리 기능입니다. 사람들끼리 Jira로 소통하듯, AI 에이전트들끼리 그리고 사람과의 소통을 위한 창구가 필요했습니다.

이슈 관리라고 하면 보통 클라우드 기반의 SaaS를 떠올리겠지만, 저는 프로젝트 파일 자체에 이슈를 만들어 관리하는 방식을 택했습니다. AI가 가장 잘 다루는 것은 파일이니까요. 별도 API를 호출하거나 데이터를 파싱할 필요 없이 JSON 파일을 직접 읽고 쓰면 됩니다. API 비용이 발생하지 않는 건 덤이고요.

issues/ 디렉토리. 각 이슈가 ISS-xxx.json 형태의 개별 파일로 관리됩니다.

지금까지 약 150개에 가까운 이슈가 생성되었습니다. 각 이슈에는 상태, 우선순위, 담당 에이전트뿐 아니라 관련 파일 경로(docs/develop/frontend-spec.md)와 관련 ID(F-012, US-003 같은 기능 명세·유저 스토리 ID)가 연결되어 있어서, 단순한 할일 목록이 아니라 기획 문서와 유기적으로 엮인 작업 단위로 동작합니다.

이슈 관리 화면. 왼쪽 이슈 목록, 오른쪽 상세 내용과 에이전트가 남긴 코멘트가 표시됩니다.

이 시스템을 운영하기 위해 모든 에이전트의 규칙 문서에 이슈 프로세스를 추가했습니다. 에이전트가 업무를 시작하거나 다른 에이전트에게 작업을 넘길 때 반드시 이슈를 생성하도록 한 것입니다. 사람이 이슈를 등록한 경우에는 할당된 업무 진행해줘 또는 /do-issues 커맨드를 통해 에이전트가 자신에게 할당된 이슈를 순차적으로 처리하도록 했습니다. 처리 과정에서 상태 변경과 코멘트도 남기도록 했고요.

이게 만약 클라우드 기반의 SaaS 도구였다면 이슈만 올려도 알아서 돌아가는 AI를 기대하겠지만, 순전히 로컬에서 동작하는 Claude Code 기반이기 때문에 약간의 수동 작업은 필요합니다. CronJob을 돌리는 방법도 있겠지만, 어느 정도 제어 가능한 상태를 유지하고 싶었습니다. 어차피 업무를 할당하면 처리는 순식간이기 때문에 큰 불편은 없습니다.

구조화된 기획서

에이전트 팀을 운영하면서 가장 어려웠던 부분은 기획 문서의 품질이었습니다.

처음에는 마크다운으로 요구사항 명세서와 서비스 기획서를 작성하게 했습니다. 결과가 나쁘지는 않았지만, 문서 두 장으로 프로젝트의 모든 맥락을 담기에는 한계가 있었습니다. 그러다 매니패스트 AI의 블로그에서 힌트를 얻었습니다. AI가 잘 읽을 수 있는 기획서는 자유도가 높은 마크다운보다 구조가 명확한 형태, 예를 들면 JSON 같은 구조화된 데이터라는 것이었습니다.

매니패스트는 클라우드 기반의 AI 최적화 기획 시스템을 만들었는데요. 저는 거기서 아이디어를 차용하여 Claude Code에서 현실적으로 동작하는 로컬 도구로 만들었습니다. 저희는 이미 Claude Code와 에이전트 팀이라는 실행 환경이 있었기 때문에, 기획 문서를 보다 전문화시키는 방향에 집중했습니다.

PRD부터 유저 플로우까지

기획 산출물을 prd.json, features.json, roles.json, userflow.json 4개의 파일로 분리했습니다.

PRD 뷰. 사용자 스토리 10건, MVP 포함 14건, 비기능 요구사항 14건 등의 현황이 정리되어 있습니다.

PRD의 데이터 구조를 설계할 때는 기획자 에이전트에게 먼저 마크다운으로 최선의 PRD를 작성하도록 한 다음, 같은 내용을 JSON으로도 작성하게 했습니다. 둘을 비교하면서 필요한 것과 불필요한 것을 추려내는 과정을 여러 차례 반복하여 지금의 구조를 만들었습니다.

기능 명세서: 기능 간 관계를 담다

4개 파일 중에서 가장 공을 들인 것은 features.json입니다.

보통 사람 기획자가 작성하는 기능 명세서를 보면 화면 단위로 나열되어 있는 경우가 많습니다. 엑셀 시트(혹은 테이블)이라는 시각적, 물리적 한계 때문입니다. 뎁스는 최대 3단계 정도이고, 기능 간의 관계를 표현할 방법이 마땅치 않습니다. 애초에 사람이 모든 도메인과 기능 간의 관계를 동시에 인지하면서 작업하기란 어려운 일이니까요.

하지만 AI는 다릅니다. 굳이 화면 단위로 보기 좋게 정리하지 않더라도, 관계 구조가 복잡하게 얽히더라도 전달하고자 하는 맥락이 디테일한 편이 AI에게는 오히려 더 좋은 환경입니다. 때문에 기능 명세서의 각 기능에 세부 설명과 수용 기준은 물론이고, 기능 간 의존·관련 관계 형성과 유저 스토리 연결까지 가능하도록 유기적으로 설계했습니다.

기능 명세서 트리 뷰. 9개 요구사항 아래 61개 기능이 트리로 표시되고, 오른쪽에서 연결된 유저 스토리와 수용 기준을 확인할 수 있습니다.

이런 구조 덕분에 백엔드 에이전트가 API를 설계할 때 관련 기능들의 의존성을 파악하기 수월해졌고, 프론트엔드 에이전트가 화면을 구현할 때도 유저 스토리 맥락을 놓치지 않게 되었습니다.

AI Hub: 시각화 도구

구조화된 JSON은 AI에게 최적이지만, 사람이 검토하기에는 상당히 불편합니다. 61개 기능의 계층 구조와 관계를 JSON 원본으로 읽는 것은 현실적이지 않습니다.

AI Hub는 이러한 구조화된 데이터를 시각화하는 도구입니다. AI가 인지하는 데이터 구조를 사람도 보기 쉬운 형태로 보여주는 것, 그래서 AI와 사람 간의 협업을 원활하게 하는 것이 주요 목적이었습니다.

Next.js 16 기반으로, 모노레포의 apps/hub/ 경로에서 포트 3100으로 독립 실행됩니다. 이슈 관리, 기능 트리 시각화, PRD 뷰, 권한 매트릭스, 유저 플로우, 문서 뷰어 등을 제공합니다.

구조화된 데이터 외에도 일반적인 마크다운 문서도 다룰 수 있게 했습니다. docs/ 디렉토리 아래에 plans/, develop/, research/로 분류하고, AI가 문서를 작성하면 frontmatter에 작성자(어떤 에이전트인지), 유형, 참조 파일 등의 메타데이터가 자동으로 기록됩니다.

특히 아키텍처 문서에서는 Mermaid를 활용한 도식화를 적극 활용했습니다. AI가 텍스트로 다이어그램 코드를 작성하면 AI Hub에서 이를 렌더링하여 인터랙티브하게 확인할 수 있도록 했습니다. AI에게도 사람에게도 친절한 소통 방식입니다.

아키텍처 설계서의 시스템 구성도. Mermaid 코드를 AI Hub에서 바로 렌더링합니다.

소유권 규칙

에이전트가 많아지면서 같은 파일을 여러 에이전트가 동시에 수정하려는 상황이 발생했습니다. 사람 조직에서도 "이 문서 누가 관리하는 거야?"라는 질문이 나오듯, AI 팀에서도 같은 일이 벌어진 것입니다.

이 문제를 해결하기 위해 단일 소유권(Single Ownership) 원칙을 세웠습니다. 각 산출물에 소유 에이전트가 하나만 존재하고, 나머지는 참조만 합니다.

산출물	소유자	참조자
prd.json, features.json, roles.json, userflow.json	Planner	Backend, Frontend, Architect
architecture.md, deployment.md	Architect	Backend, Frontend
backend-spec.md	Backend	Frontend
frontend-spec.md	Frontend	—

그 외에도 에이전트들은 빌드나 서버 실행을 직접 하지 않고(CLI Developer만 예외), main으로의 강제 푸시는 금지, 에이전트 간 소통은 SendMessage 도구와 이슈 코멘트로 하도록 정했습니다.

아키텍처 검수를 소홀히 하면 전부 무너진다

이 과정에서 가장 뼈아프게 배운 것이 있습니다. 아키텍처 설계의 중요성입니다.

기획의 경우 대부분 사람의 인지 영역 안에서 커버됩니다. AI Hub를 통해 에이전트가 작성한 기획을 확인하고 수정을 지시하기도 수월했습니다. 하지만 아키텍처는 성격이 달랐습니다. 사람인 저도 한 번에 정할 수 없는 부분이 많았고, 아키텍처 문서의 결정 사항이 백엔드와 프론트엔드까지 전파되다 보니 작업 중에 아키텍처에 대한 아젠다가 계속 나왔습니다.

무엇보다 아키텍처를 세부적으로, 견고하게 작성하지 않거나 검토를 소홀히 할 경우, 백엔드/프론트엔드가 만들어내는 산출물의 문제가 걷잡을 수 없이 커졌습니다. 물론 AI가 일을 잘 하기 때문에 개별적으로 지시하면 해결은 됩니다. 하지만 큰 틀에서 기술적 아키텍처를 잘 정의하는 것이 높은 품질을 달성하기 위한 전제 조건이라는 결론을 내렸습니다.

사람 조직에서도 마찬가지이겠지만, AI 팀에서는 그 영향이 더 극적으로 드러납니다. AI는 주어진 컨텍스트에 매우 충실하게 동작하기 때문에, 아키텍처 문서가 부실하면 그 부실함이 그대로 코드에 반영됩니다. 반대로 아키텍처가 탄탄하면 놀라울 정도로 일관된 품질의 코드가 나옵니다.

개발자의 역할이 바뀌고 있다

이 프로젝트에서 인상 깊었던 점은 코드를 직접 작성하는 일이 거의 없었다는 것입니다.

에이전트 팀 구성도, AI Hub 개발도, 실제 VMS 프로덕트도 제가 코드를 건드리는 일은 없었습니다. 다양한 사례를 온라인에서 조사하여 AI에게 전달했고, AI Hub는 아이디어만 전달했을 뿐 모든 개발과 디테일은 AI가 진행했습니다. 저는 AI가 작성한 기획 문서와 아키텍처 설계 등 전략적인 위치에서의 검수만 진행했고, 실제 코드는 전혀 보지 않았습니다. (디자인 영역은 아직 Claude의 감각이 부족한 부분이 있어 직접 다루는 경우도 있었습니다.)

개발자의 위치가 만드는 사람에서, 아이디어를 구상하고 전략을 세우고 지시하는 사람으로 변모했습니다. 코드 리뷰를 없애는 방법이라는 글에서도 언급되듯, 이미 코드 리뷰에서 의도 리뷰로의 전환이 필요한 시점이 다가오고 있습니다. AI가 작성한 코드의 한 줄 한 줄을 검토하는 것보다, AI에게 전달한 의도가 제대로 반영되었는지를 확인하는 것이 더 중요해졌습니다.

앞으로

모델의 성능이 상향 평준화되는 시점이 다가오고 있습니다. 실제로 Codex(GPT-5.4 xhigh)를 테스트해봤을 때 Claude Code에서의 경험과 크게 다르지 않았습니다. pnpm 마이그레이션을 무리 없이 수행했고, 연계된 CI 설정도 알아서 수정했습니다. 이 정도 발전 속도라면 Gemini CLI도 비슷한 수준에 도달할 것으로 보입니다.

그 시점이 오면 모델의 성능 자체보다는 비용 최적화, 그리고 AI 팀을 어떻게 꾸리고 운영해야 높은 퀄리티의 프로덕트를 효율적으로 만들 수 있는지가 더 중요해질 겁니다.

AI Hub는 아직 완성형이 아닙니다. 하지만 AI와의 협업 방식에 대한 하나의 실험이자, 미래의 개발 워크플로우를 엿보는 프로토타입이라고 생각합니다.

---

이 모든 작업이 AI로 이루어졌습니다. AI Hub도 아이디어만 전달했을 뿐인데 개발과 디테일이 전부 AI 손에서 나왔습니다. 실로 놀라운 경험이었습니다. 개발의 패러다임이 바뀌고 있다는 걸 직접 체감했습니다.

부족한 글 읽어주셔서 감사합니다.