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. 글 작성 원칙

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

Daejin Lab에 실제로 둘 규칙 초안

이번 블로그를 운영하면서 AGENTS.md에 넣어야 할 항목도 더 분명해졌습니다. 지금 기준으로는 긴 선언문보다, 에이전트가 바로 지킬 수 있는 짧은 운영 규칙이 필요합니다.

프로젝트: Astro 기반 정적 블로그
배포: Cloudflare Pages
검증: npm run build
검색 파일: sitemap/robots는 문제 없으면 계속 수정하지 않기
콘텐츠: 자동 발행 금지, 사람 검수 후 반영
보안: API 키, 토큰, 계정 정보 커밋 금지
승인 게이트: git push, 콘솔 조작, 결제는 사용자 확인 후 진행

이 정도만 있어도 다음 작업에서 같은 설명을 반복할 일이 줄어듭니다. 특히 Search Console처럼 외부 처리 지연이 있는 문제는 “계속 파일을 고치지 말 것” 같은 운영 규칙이 중요했습니다.

이번 블로그 작업에서 바로 효과가 있었던 부분

Daejin Lab 작업에서는 규칙 파일의 효과가 꽤 빨리 드러났습니다. 예를 들어 sitemap 문제가 남아 있을 때는 정상 확인 후 파일을 계속 고치지 않는다는 기준이 필요했고, OG 이미지나 콘텐츠 보강처럼 실제 파일이 바뀌는 작업은 빌드 검증 후 커밋으로 묶어야 했습니다.

또한 git push, 외부 콘솔 조작, 결제, 계정 접근은 승인 게이트로 남겨두는 편이 안전했습니다. 개인 프로젝트라도 검색 등록, 배포, 수익화 준비가 섞이면 실수의 비용이 커지기 때문입니다.

이 기준은 Daejin Lab 운영 원칙을 먼저 정했습니다와 초안을 만들어도 자동 발행하지 않는 이유에 연결됩니다. 실제 배포 확인 흐름은 Cloudflare Pages 배포 후 꼭 확인하는 체크리스트에서 따로 관리합니다.

지금 프로젝트에 남긴 기준

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

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