AI 코딩 에이전트를 위한 README, AGENTS.md
AI
142
1
들어가며
AI를 사용할 때 가장 중요한 것은 프롬프트 한 줄이 아니라, 그 프롬프트가 놓이는 맥락이라고 생각합니다.
회원가입 페이지에 전화번호 입력란을 추가해줘.
이 요청만으로도 AI는 코드를 작성할 수 있습니다. 다만 어떤 검증 규칙을 적용해야 하는지, 기존 UI 컴포넌트를 써야 하는지, 어느 파일까지 수정해도 되는지 알지 못합니다. 결과적으로 동작은 하지만 프로젝트의 방식과 어긋난 코드를 만들 가능성이 있습니다.
회원가입 페이지에 전화번호 입력란을 추가해줘. 기존 폼 컴포넌트와 검증 방식을 사용하고, 한국 휴대폰
번호 형식을 검증해줘. 관련 없는 리팩터링은 하지 말고, 변경한 뒤에는 수정 이유와 영향 범위를
설명해줘.
두 요청의 목표는 같지만, 후자의 결과는 훨씬 예측하기 쉽습니다. AI가 무엇을 만들어야 하는지뿐 아니라, 어떤 방식으로 작업해야 하는지까지 전달받기 때문입니다.
하지만 매번 이런 맥락을 프롬프트에 덧붙이는 일은 생각보다 피로합니다. 프로젝트가 커질수록 “기존 방식을 따를 것”, “불필요한 변경을 하지 말 것”, “검증 방법을 함께 알려줄 것” 같은 규칙은 계속 반복됩니다.
이러한 반복을 줄이기 위해 AGENTS.md를 사용합니다. 이번 글에서는 AGENTS.md가 무엇인지 살펴보고, 제가 어떤 기준으로 작성하고 활용하고 있는지 이야기해 보려 합니다.
AGENTS.md란?
AGENTS.md는 AI 코딩 에이전트가 프로젝트를 이해하고 작업할 수 있도록, 프로젝트의 맥락과 규칙을 전달하는 Markdown 문서입니다.
README.md가 프로젝트를 처음 접한 사람에게 "이 프로젝트는 무엇이고 어떻게 사용하는가"를 설명한다면, AGENTS.md는 AI에게 "이 프로젝트는 어떤 방식으로 작업해야 하는가"를 설명합니다. 쉽게 말해 “에이전트(AI)를 위한 README”라고 볼 수 있습니다.
AGENTS.md에는 보통 다음과 같은 내용을 작성합니다.
- 프로젝트의 기술 스택과 디렉터리 구조
- 설치, 실행, 빌드, 테스트 명령어
- 코드 스타일과 컨벤션
- Git, 커밋, PR 규칙
- 수정하면 안 되는 영역이나 보안상 주의할 점
등장 배경
AI 코딩 에이전트가 늘어나면서, AI마다 프로젝트 규칙을 전달하는 방식도 달라졌습니다.
- Claude Code:
CLAUDE.md - Cursor:
.cursorrules또는.cursor/rules - GitHub Copilot:
.github/copilot-instructions.md - Gemini CLI:
GEMINI.md - Windsurf:
.windsurfrules
이름은 달라도 내용은 비슷하게 프로젝트 구조, 설치와 테스트 명령어, 코드 스타일, Git 규칙, 수정 시 주의할 점 등을 에이전트에게 전달하기 위한 문서입니다.
하지만 AI마다 다른 파일을 사용하다 보니, 프로젝트의 규칙이 여러 곳에 흩어지는 문제가 생겼습니다.
- 같은 규칙을 여러 번 관리해야 한다.
- 파일마다 내용이 달라져 최신 규칙을 알기 어려워진다.
- 팀원이 사용하는 도구에 따라 AI의 작업 결과가 달라질 수 있다.
- 새로운 도구를 도입할 때마다 규칙 파일을 새로 만들어야 한다.
AGENTS.md는 이런 파편화를 줄이기 위해 등장했습니다. 특정 도구만을 위한 설정 파일이 아니라, 여러 AI 코딩 에이전트가 공통으로 읽을 수 있는 하나의 문서를 만들자는 접근입니다.
AGENTS.md를 사용하면 프로젝트의 작업 규칙을 하나의 파일에 작성하고, 이를 지원하는 여러 AI에서 공통으로 활용할 수 있습니다. “어떤 AI 도구를 사용할 것인가”와 별개로, “프로젝트에서 AI가 어떤 방식으로 작업해야 하는가”를 하나의 문서로 관리할 수 있습니다.
AGENTS.md 공식문서에 따르면 현재 6만 개 이상의 오픈소스 프로젝트가 AGENTS.md를 사용하며 AI 코딩 에이전트를 위한 공통 규약으로 빠르게 자리 잡고 있습니다.
AI 활용 목표: 바이브 코딩이 아니라 사고를 보조하는 도구 🧠
AI 코딩 에이전트를 사용하는 목표는 단순히 “요청하면 동작하는 결과물을 빠르게 받는 것”이 아닙니다. 내가 이해하고 판단하는 개발 과정을 더 빠르고 넓게 만드는 데 있습니다.
AI가 작성한 코드를 그대로 받아들이기보다, 왜 이 방식이 적절한지, 어떤 파일에 영향을 주는지, 무엇으로 검증할 수 있는지를 함께 설명하도록 요청합니다. 특히 익숙하지 않은 기술을 다룰 때는 답안을 생성하는 도구가 아니라 다음과 같은 역할을 기대합니다.
- 코드베이스를 빠르게 탐색하는 파트너
- 여러 구현 방식과 트레이드오프를 정리하는 도구
- 테스트 케이스와 놓친 조건을 점검하는 리뷰어
- 낯선 코드와 개념을 설명해 주는 학습 보조자
이 방식에서 최종 판단은 여전히 사람의 몫입니다. AI가 제안한 변경 사항을 이해하고, 프로젝트에 적합한지 검토하며, 결과에 책임지는 주체도 개발자입니다.
좋은 AI 활용의 기준은 “얼마나 많은 코드를 빠르게 만들었는가”가 아니라, "AI 없이도 왜 이렇게 변경했는지 설명할 수 있는가"라고 생각합니다.
나의 AGENTS.md
AGENTS.md를 작성할 때 가장 먼저 세운 기준은 AI를 단순한 코드 생성기가 아닌, 보조자이자 학습 파트너로 활용하는 것입니다.
그래서 AGENTS.md에는 AI에게 정답을 지시하기보다, 함께 작업할 때 지켜야 할 기준을 담았습니다. 불확실한 부분은 숨기지 않고 질문할 것, 필요한 만큼만 변경할 것, 변경 이유와 검증 방법을 명확히 할 것. AI의 도움으로 더 빠르게 작업하되, 최종적인 이해와 판단은 개발자인 제가 놓치지 않기 위해서입니다.
~/.codex/AGENTS.md: 어디서나 유지할 개인 개발 원칙
전역
~/.codex/AGENTS.md에는 프로젝트와 무관하게 AI와 협업할 때 지키고 싶은 개인 개발 원칙을 담았습니다.이 원칙은 andrej-karpathy-skills에서 제안한 네 가지 가이드를 기반으로 작성했습니다. LLM이 잘못된 가정을 한 채 작업을 이어가거나, 불필요하게 복잡한 코드를 만들고, 요청 범위 밖의 코드까지 수정하는 문제를 줄이기 위한 기준입니다.
Think Before Coding: 코딩하기 전에 생각하기
첫 번째는 코딩하기 전에 생각하라는 규칙입니다. 요구사항이 명확하지 않은데도 스스로 해석해 구현을 시작하는 것을 막기 위해 설정하였습니다.
- 임의로 가정하지 않기
- 정보가 부족하면 구현보다 질문을 우선하기
- 해석이 여러 가지라면 선택지를 먼저 보여주기
해당 부분은 Karpathy가 말한 "AI는 혼란을 제대로 관리하지 못하고, 명확한 설명을 요구하지 않으며, 불일치를 드러내지 않고, 장단점을 제시하지 않고, 필요할 때 반박하지 않는다"라는 문제를 해소하기 위한 규칙입니다.
Simplicity First: 단순함 우선
두 번째는 단순함을 우선하라는 규칙입니다.
1// 불필요하게 복잡한 구현: 같은 배열의 합계
2const calculateTotal = (items: number[]) =>
3 items.reduce(
4 (state, item) => ({
5 ...state,
6 value: state.value + item,
7 }),
8 { value: 0 },
9 ).value;
10
11const total = calculateTotal(prices);1// 단순한 구현: 배열의 합계
2let total = 0;
3
4for (const price of prices) {
5 total += price;
6}단순한 반복문을 만들어 달라는 요청에도 불필요한 재사용이나 확장을 고려해 임의로 코드를 작성할 수 있습니다.
요청하지 않은 기능을 추가하거나, 한 번만 쓰일 코드를 과도하게 추상화하지 않습니다. “시니어 개발자가 보기에 지나치게 복잡한가?”를 기준으로 코드를 다시 살펴봅니다.
Surgical Changes: 최소 범위 변경
세 번째는 최소 범위만 변경합니다. AI에게 모든 것을 맡길 경우 작업 범위가 너무 광범위해지는 문제가 있습니다.
기존 코드를 수정할 때는 요청과 직접 관련된 부분만 건드립니다. 주변 코드나 주석, 포맷팅을 함께 개선한다는 이유로 수정하지 않고, 기존 스타일을 따릅니다. 다만 이번 변경으로 사용되지 않게 된 코드만 정리합니다.
수정한 코드 한 줄 한 줄이 사용자의 요청과 직접 맞닿아 있어야 합니다.
Goal-Driven Execution: 목표 기반으로 실행
Karpathy가 설명한 내용 중 핵심 내용은 다음과 같습니다.
"Don't tell it what to do, give it success criteria and watch it go"무엇을 해야 할지 지시하지 말고, 성공 기준을 제시하고 결과를 지켜보세요.
“버그를 수정한다”처럼 모호한 요청을 재현 가능한 테스트와 검증 기준으로 바꿉니다. 여러 단계가 필요한 작업이라면 간단한 계획과 각 단계의 확인 방법을 먼저 세웁니다. 작업 완료는 코드 작성 시점이 아니라, 정의한 성공 기준을 검증했을 때입니다.
이 네 가지 원칙은 AI의 작업 속도를 무조건 높이기 위한 규칙이 아닙니다. AI가 낸 결과를 제가 이해하고 검토할 수 있도록, 협업 과정의 기준을 세우기 위한 장치입니다.
./AGENTS.md: 이 프로젝트에서만 지켜야 할 계약
전역
~/.codex/AGENTS.md가 어떤 프로젝트에서나 적용할 개인 원칙이라면, 프로젝트 루트의 ./AGENTS.md는 이 저장소에서만 유효한 작업 규칙입니다.AI가 코드를 수정하려면 일반적인 개발 원칙만으로는 부족합니다. 사용 중인 기술과 디렉터리 구조, 의존성 관리 방식, 실행해도 되는 명령, 현재 작업의 범위까지 알아야 기존 동작을 해치지 않고 변경할 수 있습니다.
현재 AGENTS.md는 다음 내용이 작성되어 있습니다.
- 프로젝트 개요
프로젝트의 목적과 기술 스택을 설명합니다. AI가 현재 사용 중인 프레임워크와 버전을 고려해 작업할 수 있습니다. - 패키지 매니저
pnpm만 사용한다는 규칙과 lockfile 관리 원칙을 명시합니다. 의존성 변경 과정에서 도구가 섞이는 일을 방지합니다. - 터미널 명령
빌드나 린트처럼 시간과 리소스가 필요한 명령은 실행 전 승인을 받도록 합니다. 실행의 통제권을 개발자에게 남겨 둡니다. - 프로젝트 구조
주요 디렉터리와 역할을 설명합니다. AI가 새 파일을 만들거나 기존 코드를 수정할 때, 프로젝트의 구조를 우선 따르게 합니다. 현재 사용 중인 기술 스택, 파일 구조에 대해 나열하고 있습니다. - Git 규칙
커밋, 푸시, 기존 변경 사항 되돌리기처럼 저장소 이력에 영향을 주는 작업의 기준을 정합니다. - Issue 및 PR 규칙
GitHub에 외부 변경을 만들기 전 확인해야 할 사항을 정리합니다. 예를 들어 관련 없는 변경을 PR에 포함하지 않도록 합니다. - 브랜치 한정 작업 규칙
현재 브랜치에서 해결하려는 문제와 제외할 범위를 명확히 합니다. 이 경우 Next.js 16 업그레이드와 직접 관련된 최소 변경만 허용합니다. 브랜치 업데이트 시 변경될 수 있습니다.
이 문서는 한 번 작성하고 끝나는 규칙이 아닙니다. AI와 협업하며 반복적으로 예상하지 못한 답변이나 작업이 발생한다면, 그 원인을 기록하고 필요한 규칙을 AGENTS.md에 추가할 수 있습니다.
중요한 것은 처음부터 모든 상황을 통제하려는 것이 아니라, 실제 작업에서 발견한 문제를 바탕으로 협업 방식을 조금씩 개선하는 것을 목표로 두고 있습니다.
마치며
AGENTS.md는 프로젝트의 모든 정보를 담아두는 거대한 위키가 아닙니다. AI가 작업 과정에서 잘못된 가정을 하거나, 요청 범위를 벗어나거나, 의도하지 않은 작업을 수행할 가능성을 줄이기 위한 최소한의 협업 문서입니다.
목표는 Codex에게 더 많은 권한을 주는 데 있지 않습니다. AI가 제 작업 방식과 프로젝트의 맥락을 이해한 상태에서, 제가 결과를 이해하고 판단할 수 있도록 돕는 것입니다.
결국 AGENTS.md는 Codex를 단순히 더 자율적인 도구로 만들기보다, 더 신뢰할 수 있는 보조자이자 학습 파트너로 만들기 위한 기준이라고 생각합니다.