에이전트에게 규칙을 주지 않으면, 에이전트가 규칙을 만든다
코딩 에이전트를 팀에 도입하고 나서 가장 먼저 마주치는 문제는 '에이전트가 엉뚱한 파일을 건드린다'는 것이다. 마이그레이션 파일을 함부로 수정하거나, 자동 생성된 타입 파일을 직접 편집하거나, CI 전용 배포 명령을 로컬에서 실행하는 식이다. 이건 에이전트의 문제가 아니다. 규칙을 주지 않았기 때문이다.
dev.to에 게재된 AGENTS.md 가이드는 이 문제를 정면으로 다룬다. OpenAI Codex를 시작으로 OpenCode, 그리고 점점 더 많은 코딩 에이전트가 레포 루트의 AGENTS.md 파일을 읽고 행동 기준으로 삼는다. Claude Code는 CLAUDE.md, Cursor는 .cursor/rules/*.mdc를 읽지만 구조는 거의 동일하게 이식된다. 결국 에이전트가 읽는 단일 규칙 파일을 잘 쓰는 것이 AI-First 워크플로우의 첫 번째 인프라다.
AGENTS.md, 선언이 아니라 명세로 써야 한다
이 파일이 나쁘게 작성되는 이유는 단순하다. 어떤 형식도 강제하지 않기 때문이다. 가이드가 제시하는 실효 구조는 네 섹션이다: 프로젝트 개요 → 명령어 → 코드 스타일 → 경계(Boundaries). 순서에 의미가 있다. 에이전트가 가장 먼저 필요로 하는 정보 순서다.
특히 내가 팀에 강조하는 건 두 가지다. 첫째, Reason: 한 줄의 위력. src/db/repo.ts의 래퍼를 쓰라는 규칙만 있으면 에이전트는 명시된 파일에서만 지킨다. 하지만 "테넌트 격리를 강제하기 위함—raw 쿼리로 크로스 테넌트 데이터 유출 사례가 있었음"이라는 이유를 붙이면, 그 규칙이 명시되지 않은 새 파일에서도 같은 판단을 내린다. 이유를 아는 에이전트는 유추한다.
둘째, Boundaries 섹션이 토큰 대비 가장 높은 ROI를 가진다. 에이전트 실수 중 가장 비용이 큰 것은 건드려선 안 될 파일을 건드리는 것이다. migrations/는 먼저 물어보고, vendor/와 *.gen.ts는 절대 건드리지 말라는 한 줄이 수십 분의 롤백 작업을 막는다. 또한 모노레포에서는 파일 하나로 모든 걸 커버하려 하지 말고, 패키지별 AGENTS.md를 두어 근접성 기반 해석을 활용하는 것이 맞다.
개발자가 자리를 옮겼다
역할 변화를 가장 솔직하게 설명한 글도 dev.to에서 나왔다. 저자는 경력 초기에 완벽한 요구사항 문서를 받아서 코드를 짜던 경험을 떠올린다. 모든 엔티티, 동작 방식, '왜'가 명세된 문서. 그 문서 덕분에 주니어 개발자도 혼란 없이 제품을 만들 수 있었다.
수년 후 그가 깨달은 것: 그 프로젝트의 진짜 천재성은 코드가 아니라 명세를 쓴 사람이었다. 그리고 지금 그는 그 명세를 쓰는 사람이 됐다. 다만 우리는 그것을 프롬프트라고 부른다.
역할 테이블이 간결하게 요약된다:
| 역할 | 과거 | 현재 |
|---|---|---|
| 명세 작성 | 클라이언트 | 개발자 (프롬프트) |
| 코드 작성 | 개발자 | AI |
| 테스트·피드백 | 클라이언트 | 개발자 |
같은 워크플로우, 같은 리듬. 자리만 바뀌었다. 저자의 표현대로 "AI가 나를 대체한 게 아니라, 스펙을 읽는 자리에서 스펙을 쓰는 자리로 승진시켰다."
반복 작업은 에이전트가 가져간다—자율 업그레이더가 증명한다
추상적인 역할 전환 논의를 구체적 사례로 anchoring해주는 프로젝트도 등장했다. loopgrade는 LangGraph와 Loop Engineering을 활용해 의존성을 하나씩 업그레이드하고, 업그레이드마다 테스트를 돌리고, 통과하면 커밋, 실패하면 롤백 후 다음으로 넘어가는 자율 에이전트다.
이 사례가 시사하는 바는 단순하다. 20개 의존성을 한꺼번에 올렸다가 어디서 깨졌는지 모르는 상황, 그래서 아예 업그레이드를 미루다 보안 패치가 쌓이는 상황—이런 관리 가능하지만 귀찮아서 방치되던 작업이 에이전트의 첫 번째 먹잇감이다. 개발자의 시간은 여기서 해방되고, 더 판단이 필요한 곳으로 이동한다.
팀 리빌딩 관점의 시사점: 이제 '무엇을 뽑을 것인가'가 달라진다
AI-First 팀을 리빌딩할 때 이 세 가지 흐름이 동시에 가리키는 것은 하나다. 명세 능력이 기술 역량의 핵심 축으로 올라왔다.
- AGENTS.md를 잘 쓰는 개발자는 에이전트를 통제한다. 못 쓰는 개발자는 에이전트가 만든 혼란을 수습한다.
- 프롬프트를 완벽한 명세처럼 작성하는 개발자는 AI 생산물의 품질을 올린다. 대충 던지는 개발자는 대충 나온 코드를 뒤집는다.
- 반복적 운영 작업을 에이전트에게 위임할 줄 아는 개발자는 판단이 필요한 일에 집중한다.
온보딩 기준도 바뀐다. 새 팀원에게 물어야 할 것은 "어떤 언어를 쓰나요?"가 아니라 "AI에게 요구사항을 어떻게 전달하나요?"다.
전망: '이유를 아는 개발자'가 살아남는다
AGENTS.md 가이드가 Reason: 한 줄을 강조하는 이유, 저자가 '왜'를 소유하라고 조언하는 이유는 같다. AI는 어떤 솔루션이든 생성할 수 있다. 하지만 어떤 문제가 풀 가치가 있는지, 왜 이 아키텍처 결정이 내려졌는지, 이 규칙이 존재하는 맥락은 무엇인지—그 판단은 아직 개발자의 몫이다.
코드를 빠르게 생성하는 것은 에이전트가 더 잘한다. 하지만 에이전트에게 올바른 문제를 올바른 맥락과 함께 전달하는 것은 여전히 사람이 해야 한다. AI-First 팀의 경쟁력은 결국 그 명세 능력의 밀도에서 갈린다.