문제: AI 코딩이 왜 맨날 같은 데서 박살나는가

Cursor, Windsurf, Claude Code로 프로젝트 돌리는 사람이라면 한 번쯤 겪었을 겁니다. AI가 코드 한 덩어리를 뱉어내고, 복붙해서 돌려보면 — 빌드 터지고, 테스트 빨갛게 뜨고, 의존성은 엉뚱한 데 깔리고. 문제는 AI 머리가 나빠서가 아니라, 우리 프로젝트의 「암묵의 규칙」을 모르기 때문입니다.

AGENTS.md는 프로젝트 루트에 두는 Markdown 파일 한 장입니다. AI 전용으로 쓰고, 빌드 방법, 테스트 방법, 코딩 컨벤션을 알려줍니다. README.md는 사람용이라 프로젝트 소개, 기여 가이드, 브랜드 스토리까지 잔뜩 들어있죠. AI가 그걸 읽으면 신입사원 입사 첫날에 회사 홍보 브로셔 한 권 받아들고 바로 코딩 시키는 격입니다. 회사가 뭘 하는지는 알지만, 빌드 명령어, 테스트 실행법, ESLint 룰 같은 건 모릅니다. 매번 채팅창에서 「pnpm 써, npm 말고」「테스트는 packages/web 아래에 있어」「lint 잊지 마」 주문을 외치게 됩니다. 백 번을 외쳐도 프로젝트는 여전히 엉망입니다.

외주 수주 현장에서 손해는 더 직격탄입니다. Next.js + Prisma 외주를 받아서 Cursor로 속도를 높이려는데, AI는 npm install로 의존성을 깔아버려서 pnpm workspace 설정이 다 날아가고, DB schema 경로를 몰라서 migration 파일을 뱉어내면 바로 에러. 클라이언트는 납품催促, 나는 AI가 짠 코드 디버깅에 3시간 — 번 돈이 너무 억울합니다.

AI가 프로젝트 규칙을 모를 때 전형적으로 박살나는 3가지: ① 패키지 매니저 착각 (프로젝트는 pnpm인데 AI는 기본값으로 npm install → 의존성 엉뚱한 위치, workspace 설정 무효화) ② 테스트 진입점 못 찾음 (테스트가 packages/web 아래에 있는데 AI는 루트에서 pnpm test 돌림 → 「테스트 파일 없음」 에러) ③ 코드 스타일 불일치 (ESLint + Prettier 쓰는 프로젝트인데 AI가 뱉는 코드는 들여쓰기, 따옴표 전부 다름 → CI에서 바로 빨강).

기회: AGENTS.md가 「사람 문서」와 「기계 문서」를 깔끔하게 가른다

GitHub 오픈소스 프로젝트 AGENTS.md (저장소 github.com/agentsmd/agents.md, 2026-08-25 기준 약 2.4만 stars)가 바로 이 문제를 풉니다. 핵심思路는 극도로 단순합니다. 프로젝트 루트에 Markdown 파일 하나 두고, AI에게 빌드·테스트·코드 스타일 알려주기.

이건 README 대체가 아니라 보완입니다. README는 사람 기여자용, AGENTS.md는 AI 에이전트용. 역할이 명확해서 서로 간섭 안 합니다.

원문에 따르면 AGENTS.md는 수만 개 오픈소스에 도입됐고 (정확한 수치 미확인), VS Code·Cursor·Windsurf·Aider·GitHub Copilot 등 주요 AI 코딩 도구를 커버합니다 (검증 완료). 커뮤니티 피드백으로는 OpenAI Codex, Google Jules 등도 지원한다고 하지만 (⚠️ 미검증). 지금 안 배우면 AI가 사투리로 말 걸어오는 걸 계속 들어야 합니다.

경로 1: 최소 가용 AGENTS.md 직접 쓰기

비용 거의 0입니다. 파일 하나 만들고, 세 단락이면 충분합니다.

사전 지식: 아래 예시는 pnpm (npm보다 디스크 절약, monorepo workspace 지원) 기준이고, turbo는 monorepo 작업 오케스트레이션 도구, --filter 옵션은 특정 서브 패키지만 지정해서 전체 저장소 영향을 막습니다.

첫 번째 단락 「Dev environment tips」: 패키지 매니저, 서브 패키지 이동, 새 모듈 생성 방법을 AI에게 알려줍니다. 공식 예시 기준:

• pnpm dlx turbo run where <project_name> — ls로 헤매지 말고 지정 서브 패키지 디렉터리로 바로 점프
• pnpm install --filter <project_name> — monorepo 전체 건드리지 않고 특정 서브 패키지 의존성만 설치
• pnpm create vite@latest <project_name> -- --template react-ts — TypeScript 검사 붙은 React + Vite 서브 패키지 새로 생성

이런 명령어는 AI가 혼자 추측 못 합니다. 적어두면 그대로 따라 합니다.

두 번째 단락 「Testing instructions」: 테스트 실행법, CI 계획 위치, 커밋 전 필수 검사. 공식 예시:

• pnpm turbo run test --filter <project_name> — 지정 서브 패키지 전체 검사 실행
• pnpm vitest run -t "<test name>" — 이름 매칭되는 단일 테스트만 실행
• 「Fix any test or type errors until the whole suite is green」 — 전부 초록불 뜰 때까지 멈추지 마
• 「Add or update tests for the code you change, even if nobody asked」 — 이 마지막 줄이 핵심입니다. 안 적으면 AI가 슬쩍 테스트 안 씁니다

세 번째 단락 「PR instructions」: 커밋 제목 형식, lint·test 강제 실행. 공식 예시는 Title format: [<project_name>] <Title>, 그리고 「Always run pnpm lint and pnpm test before committing」.

세 단락 합쳐서 50줄도 안 되지만, AI 코드 1차 통과율이 눈에 띄게 올라갑니다 (커뮤니티 피드백, 수치 미확인).

경로 2: 대형 monorepo에서 중첩 사용

기업급 프로젝트, 즉 monorepo 구조 (여러 관련 프로젝트를 같은 Git 저장소에서 관리, 예: 프론트·백엔드·공유 코드 각각 서브 디렉터리) 외주를 받았다면, AGENTS.md 하나로는 부족합니다. AGENTS.md는 중첩을 지원합니다. 각 서브 디렉터리에 전용 AGENTS.md를 두면, AI가 자동으로 「가장 가까운 것」을 읽습니다.

실전 운영: 루트 AGENTS.md에는 전역 규칙 (패키지 매니저, CI 흐름, 보안 주의사항) 적고, packages/web/, packages/api/, packages/shared/ 각각에 그 서브 패키지만의 빌드 명령, 테스트 진입점, 특수 의존성을 적습니다. 예컨대 프론트 패키지는 「컴포넌트 라이브러리는 shadcn, 스타일은 Tailwind, 아이콘은 lucide-react」, 백엔드 패키지는 「DB migration은 Prisma, API 라우트는 src/routes 아래, 인증은 JWT」.

AI가 서브 디렉터리에서 작업할 때 가장 가까운 AGENTS.md를 자동 로드하고, 루트보다 우선순위가 높습니다. 같은 프로젝트에서 프론트엔드 AI 도우미와 백엔드 AI 도우미가 완전히 다른 지시를 받는다는 뜻이죠. 서로 헷갈리지 않습니다.

경로 3: 외주 수주의 차별화 무기로 만들기

지금 AI 외주 시장은 이미 핏빛 경쟁입니다. 다들 Cursor는 쓰는데, 납품 품질은 천차만별입니다.投标서에 「본 프로젝트는 AGENTS.md 표준 문서를 구성해 AI 보조 개발이 프로젝트 규칙을 따르도록 했습니다」 한 줄 넣으면, 「저는 AI로 코딩합니다」만 외치는 동료보다 낙찰률이 눈에 띄게 올라갑니다.

실전 플레이: 수주 후 30분 투자해 클라이언트 프로젝트 구조를 파악하고, 맞춤 AGENTS.md를 작성합니다. 이 문서 자체가 납품물의 일부입니다. 클라이언트가 나중에 직접 AI로 유지보수할 때도 훨씬 수월해집니다.

AGENTS.md 설정 서비스를 단독 가격표로 파세요 (현지 시장 기준 조정 필요): 베이직 ₩70,000 (단일 파일 구성 + README 설명서 1부), 엔터프라이즈 ₩420,000 (monorepo 중첩 + 보안 규범 + 팀 교육). 납품물: ① 맞춤 AGENTS.md 파일 ② 30일 카카오톡 Q&A ③ 10분 화면 녹화 교육. 적합 대상: Cursor/Windsurf 멤버십은 이미 쓰는데 효과를 못 보는 팀. 부적합: 아직 순수 인력 개발만 하고 AI 도구를 안 들인 클라이언트.

사례: AGENTS.md의 호환성 해자

AGENTS.md는 MIT 라이선스 (소스 확인), 커뮤니티 유지 (거버넌스 구조 미확인), 공식 사이트는 agents.md입니다.

호환성이 최대 해자입니다. 검증 완료 — VS Code, Cursor, Windsurf, Aider, GitHub Copilot 모두 AGENTS.md 읽기 지원. 커뮤니티 피드백으로는 OpenAI Codex, Claude Code, Gemini CLI, Google Jules 등도 지원 (⚠️ 미검증). 파일 하나 쓰면 주요 AI 도구 전부 돌아간다는 뜻입니다. 도구별로 따로 설정 안 해도 됩니다.

다른方案과 비교: Cursor의 .cursorrules는 Cursor 전용, Windsurf로 바꾸면 무효. Claude Code의 CLAUDE.md는 Claude만. GitHub Copilot 지시 시스템은 또 다른 세트. AGENTS.md의 「한 번 작성, 어디서나 실행」 특성이 단기간에 폭넓게 채택된 근본 이유입니다.

도구 이전 비용 0원. 오늘 Cursor 쓰다가 내일 Windsurf로 갈아타도 AGENTS.md 그대로 재사용, 규칙 다시 쓸 필요 없습니다.

행동 호출: 오늘 밤 프로젝트에 기계 매뉴얼 한 장 박아라

5분 액션 체크리스트: ① 프로젝트 루트 열기 ② AGENTS.md 새로 만들기 ③ 공식 템플릿 복사 (github.com/agentsmd/agents.md) ④ 세 가지 명령어 채우기 (빌드, 테스트, lint) ⑤ 다음에 AI 코딩 시키면서 효과 관찰.

monorepo 쓴다면 오늘 밤 20분만 더 투자해 서브 패키지마다 중첩 설정 추가하세요. 내일 출근하면 AI가 뱉는 코드에 더 이상 주문 외치지 않아도 됩니다.

AGENTS.md는 지금 시점 ROI 최고 AI 코딩 설정입니다. 30분 투자로 매달 수 시간 디버깅 시간을 바꿉니다.