마지막 수정
개인 프로젝트에 AGENTS.md를 두는 이유
AI 코딩 도구와 함께 개인 프로젝트를 운영할 때 AGENTS.md 같은 규칙 파일이 왜 필요한지 Daejin Lab 사례로 기록했습니다.
AGENTS.md 같은 파일은 팀 프로젝트에서나 필요할 것처럼 보였습니다. 개인 프로젝트에 규칙 문서를 두는 건 조금 과한 일처럼 느껴질 수도 있습니다.
그런데 AI 도구와 같이 작업하다 보니 생각이 바뀌었습니다. 제가 매번 같은 설명을 반복하지 않으려면, 프로젝트 안에 기준을 적어두는 편이 훨씬 낫습니다.
AGENTS.md가 하는 일
AGENTS.md는 AI 에이전트에게 주는 프로젝트 운영 설명서에 가깝습니다.
넣을 수 있는 내용은 다음과 같습니다.
프로젝트 목적
주요 폴더 구조
금지 사항
빌드/테스트 명령어
배포 방식
코딩 스타일
보안 원칙
작업 완료 기준AI가 프로젝트를 열 때 이 파일을 먼저 읽으면, 매번 같은 설명을 하지 않아도 됩니다.
Daejin Lab에서 필요한 규칙
이 블로그에는 특히 아래 규칙이 중요했습니다.
자동 발행 금지
초안은 검수 후 발행
환경 변수 파일, 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처럼 블로그 운영과 자동화를 함께 다루는 프로젝트에서는 반복 비용과 실수를 줄이는 기본 장치가 됩니다.
이번 오토파일럿에서 바로 적용한 규칙
이번 Daejin Lab 글 보강에서도 AGENTS.md 같은 규칙 파일의 필요성이 다시 드러났습니다. 사용자가 “오토파일럿”으로 맡겨도 모든 일을 자동으로 진행하는 것이 아니라, 미리 정한 승인 경계를 지키는 것이 핵심이었습니다. 실제로 글 보강, 빌드, 감사, 로컬 커밋은 진행할 수 있지만, git push와 외부 콘솔 조작은 별도 승인 전까지 멈추는 식입니다.
지금 프로젝트에서 효과가 있었던 규칙은 아래입니다.
기존 글 보강은 가능하다.
신규 글을 한꺼번에 발행하지 않는다.
기술 SEO 파일은 문제가 확인될 때만 바꾼다.
변경 후 npm run build와 감사 스크립트를 실행한다.
push, Search Console, AdSense, 결제, 계정 접근은 승인 게이트로 둔다.이 기준 덕분에 작은 자동화가 일을 더 늘리는 순간에서 말한 문제를 줄일 수 있었습니다. AGENTS.md는 형식적인 문서가 아니라, 에이전트에게 맡길 일과 직접 볼 일을 실제 작업 중에 지키게 만드는 안전장치였습니다.
개인 프로젝트에도 규칙이 필요했다
개인 프로젝트라고 해서 기준이 필요 없는 건 아니었습니다. 오히려 혼자 할수록 나중에 왜 그렇게 했는지 잊기 쉽습니다.
AGENTS.md는 AI에게만 주는 지시문이 아니라, 미래의 제가 다시 보는 운영 메모에 가깝습니다. Daejin Lab도 앞으로 규칙이 늘어나면 코드보다 먼저 이 기준을 정리하려고 합니다.
혼자 하는 프로젝트에도 설명서가 필요했다
처음에는 개인 프로젝트에 AGENTS.md까지 두는 게 과해 보였습니다. 그런데 AI 도구를 여러 번 쓰다 보니 매번 같은 설명을 반복하고 있었습니다. 결국 이 파일은 팀원을 위한 문서가 아니라, 미래의 저와 AI 도구에게 같은 말을 덜 하기 위한 메모였습니다.
2026-05-31에 다시 본 AGENTS.md의 필요성
애드센스 대응처럼 여러 글을 반복해서 고치는 작업에서는 프로젝트 기준이 없으면 결과가 쉽게 흔들립니다. 어떤 글은 길게 고치고, 어떤 글은 출처를 빼먹고, 어떤 파일은 의도치 않게 push 대상에 들어갈 수 있습니다. 그래서 개인 프로젝트에도 AGENTS.md 같은 운영 메모가 필요했습니다.
이 카드는 AGENTS.md를 팀 규칙이 아니라 개인 프로젝트의 반복 설명 줄이기 장치로 본 것입니다.
Daejin Lab에서 지키려는 규칙은 복잡하지 않습니다. 공개 글에는 비밀값을 넣지 않는다, AI 초안은 사람이 검수한다, build와 publish check를 통과한다, git push는 발행이라는 점을 잊지 않는다. 이런 규칙을 매번 채팅으로 설명하면 빠뜨리기 쉽습니다. 프로젝트 안에 남겨두면 다음 작업도 같은 기준에서 시작합니다.
참고한 공식 문서
AGENTS.md는 에이전트가 프로젝트 맥락을 읽는 방식의 참고로 보고, Google과 GitHub 문서는 공개 콘텐츠와 비밀값 노출 위험을 확인하는 기준으로 봅니다.
확인하지 않은 것
이 글은 모든 프로젝트에 긴 AGENTS.md를 만들자는 뜻이 아닙니다. 작은 프로젝트라면 짧은 규칙 몇 줄이면 충분합니다. 길이보다 중요한 건, 반복해서 지킬 기준이 프로젝트 안에 남아 있는가입니다.
FAQ
개인 프로젝트에 규칙 문서가 과하지 않나요?
혼자만 작업한다면 과하게 느껴질 때가 있습니다. 하지만 AI 도구와 반복 작업을 하다 보면 같은 설명을 계속 하게 됩니다. 짧은 규칙 문서 하나가 그 반복을 꽤 줄여줍니다.
AGENTS.md에는 무엇을 먼저 적나요?
수정 범위, 금지 파일, 테스트 명령, 발행 승인선처럼 사고를 막는 기준을 먼저 적는 편이 좋습니다.
블로그 품질과 어떤 관련이 있나요?
일관된 검수 기준이 있어야 글마다 출처, 이미지, FAQ, 공개 경계가 빠지지 않습니다. 품질은 문장만이 아니라 운영 방식에서도 나옵니다.