코딩 에이전트에게 우리 팀 규칙, 어떻게 알려줄까?
AGENTS.md 같은 규칙 파일 하나로 코딩 에이전트의 반복 실수를 줄이는 방법.
AI 코딩 에이전트를 처음 붙이면 며칠은 마법 같습니다.
말로 설명한 화면이 나오고, 버그도 알아서 잡습니다.
그런데 3주쯤 지나면 묘한 일이 반복됩니다.
어제는 잘 지키던 폴더 구조를 오늘은 무시하고, 이미 있는 포맷 함수를 또 만들고, 쓰지 말라고 했던 라이브러리를 조용히 설치합니다.
결국 사람이 매번 같은 잔소리를 채팅창에 다시 적게 됩니다.
이 문제를 해결하는 방법은 더 좋은 모델을 기다리는 게 아니라, 규칙을 대화가 아니라 저장소에 두는 것입니다.
요즘 코딩 에이전트들이 프로젝트 루트의 규칙 파일(AGENTS.md, CLAUDE.md, Cursor의 rules 등)을 먼저 읽도록 설계된 이유가 여기에 있습니다.
왜 에이전트는 같은 실수를 반복할까?
세션이 끝나면 맥락이 대부분 사라지기 때문입니다.
사람 신입은 첫 주에 배운 걸 두 달 뒤에도 기억하지만, 에이전트는 새 대화마다 다시 첫 출근입니다.
그래서 어제의 지시는 오늘 존재하지 않는 정보로 취급됩니다.
또 하나, 에이전트는 코드베이스 전체를 다 보지 않습니다.
필요한 파일 몇 개를 골라 읽고 판단합니다.
우리 프로젝트에 이미 lib/format.ts가 있다는 사실을 발견하지 못하면, 가장 합리적인 선택으로 새 함수를 만듭니다.
즉 이건 모델의 게으름이 아니라 정보 부족 문제이고, 정보는 파일로 줄 수 있습니다.
규칙 파일에는 무엇을 적어야 할까?
취향이 아니라 모르면 사고가 나는 것부터 적습니다.
코딩 컨벤션 백과사전보다, 이 프로젝트에서만 통하는 사실 20줄이 훨씬 효과적입니다.
다음 여섯 가지면 대부분의 반복 실수가 줄어듭니다.
- 실행·검증 명령: 개발 서버 실행, 테스트, 타입체크, 빌드 명령을 정확한 문자열로. 예: 패키지 매니저는 pnpm만 사용
- 구조와 배치 규칙: 새 페이지는 어디에, 공용 컴포넌트는 어디에, API 호출 코드는 어디에 두는지
- 이미 있는 것: 날짜·가격 포맷, 인증 체크, 토스트 알림은 새로 만들지 말고 어느 파일을 쓰라고 경로까지 명시
- 손대면 안 되는 것: DB 마이그레이션 직접 실행 금지, 결제·정산 로직은 수정 제안만 하고 사람 승인 대기, .env 값은 출력·커밋 금지
- 서비스 고유 상식: 예를 들어 "가격 계산은 lib/pricing.ts 한 곳에서만", "모든 금액은 원 단위 정수로 저장"
- 완료의 정의: 타입체크와 테스트가 통과해야 끝, 커밋 메시지는 지정한 형식으로
파일은 어디에 두나요?
프로젝트 루트에 규칙 파일 하나를 두는 것이 기본입니다.
도구마다 읽는 파일 이름이 조금씩 다르니(예: Claude Code는 CLAUDE.md, Cursor는 rules 디렉터리) 사용 중인 도구 문서를 한 번 확인하고, 내용은 한 파일에 모아두고 나머지는 그 파일을 가리키게 하면 관리가 쉽습니다.
프론트엔드·백엔드 폴더가 크게 나뉘어 있다면 각 폴더에 짧은 하위 규칙 파일을 두는 것도 좋습니다.
규칙을 적어도 안 지켜지는 이유는?
대개 파일이 너무 길고, 표현이 추상적이고, 코드보다 낡았기 때문입니다.
"클린 코드를 지향한다" 같은 문장은 행동을 바꾸지 못합니다.
다음 순서로 운영하면 규칙이 살아 있게 됩니다.
- 한 화면에 들어오는 분량으로 시작합니다.
길어지면 읽히지 않고 우선순위가 흐려집니다. - 형용사 대신 명령문과 경로로 씁니다.
"에러 처리를 잘한다" 대신 "API 실패는 lib/api.ts의 handleError로 처리". - 에이전트가 규칙을 어긴 순간, 채팅으로 고치고 같은 날 한 줄을 추가합니다.
이 회고 습관이 규칙 파일의 품질을 만듭니다. - 진짜 중요한 것은 문서가 아니라 자동화로 막습니다.
린트, 타입체크, 테스트, CI를 걸어두면 에이전트가 스스로 실패를 보고 고칩니다. - 분기마다 안 쓰는 줄을 지웁니다.
삭제하지 않은 규칙 파일은 결국 아무도 신뢰하지 않습니다.
규칙 파일은 문서가 아니라 사람과 에이전트 사이의 인터페이스입니다.
팀이 한 명이어도 효과는 큽니다.
세느루로 만든 프로젝트의 소스를 내려받아 이어서 작업할 때도, 첫 커밋에 규칙 파일 한 장을 넣어두면 그다음 100번의 요청이 훨씬 조용해집니다.