AI 코딩 도구를 자주 쓰면 같은 설명을 반복하게 됩니다.

API 키는 커밋하지 말 것
빌드 후 확인할 것
자동 발행하지 말 것
Cloudflare Pages는 dist를 배포할 것
글은 Markdown으로 작성할 것

처음 몇 번은 직접 말하면 되지만, 프로젝트가 길어지면 매번 설명하는 것 자체가 비용입니다. 그래서 개인 프로젝트에도 AGENTS.md 같은 규칙 파일을 두는 것이 좋습니다.

AGENTS.md가 하는 일

AGENTS.md는 AI 에이전트에게 주는 프로젝트 운영 설명서에 가깝습니다.

넣을 수 있는 내용은 다음과 같습니다.

프로젝트 목적
주요 폴더 구조
금지 사항
빌드/테스트 명령어
배포 방식
코딩 스타일
보안 원칙
작업 완료 기준

AI가 프로젝트를 열 때 이 파일을 먼저 읽으면, 매번 같은 설명을 하지 않아도 됩니다.

Daejin Lab에서 필요한 규칙

이 블로그에는 특히 아래 규칙이 중요했습니다.

자동 발행 금지
AI 초안은 검수 후 발행
.env, API 키, 토큰 커밋 금지
Cloudflare Pages 기준으로 빌드
npm run build 성공 후 커밋
Search Console 메타 태그와 API 토큰 구분

이런 규칙이 없으면 AI가 선의로 작업하다가 원치 않는 방향으로 갈 수 있습니다. 예를 들어 Workers 배포와 Pages 배포를 헷갈리거나, 실제 도메인이 확정되기 전 sitemap 주소를 잘못 잡을 수 있습니다.

비용 절감 효과

규칙 파일은 비용 절감에도 도움이 됩니다.

AI에게 매번 긴 배경을 설명하지 않고, “프로젝트 규칙을 읽고 진행해줘”라고 할 수 있기 때문입니다.

반복 설명 감소
실수 감소
작업 완료 기준 통일
새 에이전트 투입 시 온보딩 시간 감소

블로그를 5개까지 늘릴 계획이라면 이 효과가 더 커집니다. 1호 블로그에서 정한 규칙을 2호, 3호 블로그에 복제할 수 있기 때문입니다.

너무 복잡하게 쓰지 않는다

다만 AGENTS.md도 너무 길면 오히려 부담이 됩니다. 처음에는 아래 정도면 충분합니다.

1. 이 프로젝트가 무엇인지
2. 절대 하면 안 되는 일
3. 수정 후 확인할 명령어
4. 배포 방식
5. 글 작성 원칙

규칙은 완벽하게 쓰기보다, 작업하면서 발견한 실수를 조금씩 추가하는 방식이 좋습니다.

결론

개인 프로젝트라도 AI 도구를 함께 쓴다면 규칙 파일이 필요합니다.

AGENTS.md는 개발자를 위한 문서이면서 동시에 AI 에이전트의 작업 가드레일입니다. Daejin Lab처럼 블로그 운영과 자동화를 함께 다루는 프로젝트에서는 반복 비용과 실수를 줄이는 기본 장치가 됩니다.