13개 주요 오픈소스 레포지토리를 직접 점검한 결과가 꽤 충격적이다. Django, Angular, Vue, Svelte, Remix—이름만 들어도 알 만한 프로젝트들이 AGENTS.md, .cursorrules, CLAUDE.md 같은 AI 에이전트 설정 파일을 단 하나도 갖고 있지 않다. 수백 명의 컨트리뷰터가 활발하게 기여하는 프로젝트들인데도. 이 관찰이 불편한 이유는 단순하다. 당신의 프로젝트도 거의 확실히 마찬가지일 테니까.
설정이 있는 4개 프로젝트도 사정이 낫다고 보기 어렵다. Grafana의 CLAUDE.md는 단 한 줄—@AGENTS.md 참조뿐이다. Prisma의 AGENTS.md는 166줄이지만 도입부에 이런 경고를 달고 있다. "당신의 학습 데이터에는 Prisma 7에 맞지 않는 낡은 정보가 많다. 이 코드베이스를 처음 보는 프로젝트처럼 분석하라." Prisma 메인테이너 스스로 AI 학습 데이터를 신뢰하지 않는다는 고백이다. Supabase는 Claude·Copilot·Cursor 세 툴 각각에 설정 파일을 따로 만들었는데, 세 파일 사이에 겹치는 내용이 하나도 없다. 관리 비용이 세 배로 늘어나는 구조다.
이 데이터가 가리키는 핵심 문제는 AI 에이전트는 프로젝트 컨텍스트 없이 일한다는 것이다. CI가 어떤 품질 게이트를 돌리는지, 디렉터리 구조가 어떻게 짜여 있는지, 어떤 패턴을 피해야 하는지—이런 정보 없이 에이전트가 생성하는 코드는 결국 낡은 학습 데이터 위에서 작동한다. 로컬에서는 돌아가도 CI에서 터지는 코드가 여기서 나온다. '어떤 도구를 쓸까'보다 '에이전트에게 무엇을 알려줄까'가 먼저인 이유다.
도구 선택 논의에도 비슷한 맹점이 있다. Cursor의 사용량 기반 과금 전환 이후 대안 탐색이 급증했고, Windsurf·Cline·Claude Code·Aider 등 각 툴의 스펙 비교가 쏟아졌다. 그러나 어떤 도구로 갈아타든, 프로젝트에 에이전트 컨텍스트가 없으면 결과는 똑같다. Cursor에서 Windsurf로 IDE를 바꾸는 데 30분이 걸린다면, AGENTS.md 하나 제대로 작성하는 데는 그것보다 짧은 시간이 든다. 그런데 후자가 실질적인 코드 품질 차이를 만든다.
조직 단위로 확대하면 문제는 더 구조적이다. '주말 개인 프로젝트는 AI로 하루 만에 끝내는데, 엔터프라이즈 R&D는 왜 이렇게 느린가'라는 질문—많은 개발자들이 공감할 이 역설에는 이름이 있다. Synchronization Tax. AI가 코드 작성 속도를 5배 올려줘도, 팀 간 핸드오프와 커뮤니케이션 병목이 그대로라면 생산성 향상은 제로에 수렴한다. 개인 프로젝트가 빠른 건 AI 덕분이기도 하지만, 조율 비용이 없기 때문이기도 하다. 문제는 도구가 아니라 에이전트가 작동할 수 있는 환경 설계에 있다.
이 구조 문제를 풀기 위해 제안되는 모델이 흥미롭다. '2인 에픽 모델'—PM 1명과 Full-Spectrum Engineer 1명이 짝을 이뤄 기획부터 프로덕션까지 end-to-end로 처리하는 방식이다. 여기서 엔지니어가 프론트엔드·백엔드 경계를 넘나들 수 있는 전제 조건이 바로 AI-Ready 레포지토리다. .ai-rules.md, ARCHITECTURE.md 같은 컨텍스트 파일이 표준화돼 있어야, 낯선 코드베이스에서도 에이전트가 안전한 가이드 역할을 할 수 있다. 도구보다 레포 세팅이 먼저인 이유가 조직 설계 레벨에서도 동일하게 적용된다.
실용적인 접근도 있다. crag라는 오픈소스 CLI 도구(npx @whitehatd/crag)는 프로젝트의 CI 워크플로우, 패키지 매니페스트, 설정 파일을 읽어서 단일 governance.md를 생성하고, 이를 Cursor·Claude·Copilot·Windsurf 등 12개 AI 툴의 네이티브 포맷으로 컴파일한다. LLM 없이, 네트워크 없이, 500ms 안에 실행된다. 직접 써볼 만한 도구지만, 더 중요한 건 이 도구가 드러내는 원칙—컨텍스트는 한 곳에서 관리하고 각 툴로 배포해야 한다는 것이다. Supabase처럼 툴마다 따로 파일을 만들면 곧 드리프트가 생긴다.
결국 이 모든 신호가 가리키는 방향은 하나다. AI 코딩 에이전트 도입의 첫 번째 과제는 어떤 툴을 쓸지 결정하는 것이 아니다. CI 게이트, 아키텍처, 금지 패턴, 코드 컨벤션—이 정보를 에이전트가 읽을 수 있는 형태로 레포지토리에 심어두는 것이 선행 조건이다. 팀이 확장되고 툴이 바뀌어도 이 컨텍스트 레이어가 살아있으면, AI는 비로소 낡은 학습 데이터가 아니라 지금 이 프로젝트의 문법으로 코드를 쓴다. 에이전트를 올바르게 세팅하는 것은 개발자 개인의 생산성 문제가 아니라, 팀 전체의 AI 전환 ROI를 결정하는 아키텍처 결정이다.