스타 10만 오픈소스는 AGENTS.md를 어떻게 설계했을까

1. 인기 오픈소스는 AI 작업 규칙을 어디에 둘까

GitHub 스타 10만 개를 넘긴 프로젝트를 포함한 세 오픈소스는 AGENTS.md를 어떻게 설계했을까? 루트 문서부터 코드 가까이에 둔 하위 문서, 실제 검증 명령까지 공개 자료를 따라가며 분석했다.

프로필 저장 버튼을 고쳐 달라고 했다고 해보겠다. AI는 금세 동작하는 코드를 만들었다. 그런데 자세히 보니 이미 있는 공용 버튼 대신 새 컴포넌트를 만들었고, 자동 생성된 API 클라이언트를 두고 직접 fetch를 호출했다. 테스트도 실행했지만 엉뚱한 폴더에서 돌렸다.

코드를 못 작성한 것은 아니다. 다만 이 저장소에서 무엇을 먼저 찾아야 하는지, 어느 계층에 코드를 두어야 하는지, 무엇을 통과해야 작업이 끝나는지 몰랐다. 이런 지식은 프로그래밍 언어 문법만으로는 알기 어렵다.

AGENTS.md는 그 빈칸을 채우는 현장 작업 안내서이다. 저장소 전체를 길게 설명하는 문서라기보다, AI가 현재 위치에서 어떤 규칙을 따라야 하는지 알려주는 표지판에 가깝다.

이 글에서는 성격이 다른 세 프로젝트의 공개 문서와 실제 코드·설정을 함께 살펴본다. 목표는 AGENTS.md를 많이 만드는 것이 아니다. 루트와 하위 문서를 어떻게 나누고, 그렇게 나눴을 때 어떤 이득이 생기는지 이해하는 것이다.

2. README만으로는 왜 부족할까

README는 보통 “이 프로젝트는 무엇이고 어떻게 실행하는가”를 설명한다. CONTRIBUTING.md는 이슈를 어떻게 등록하고 PR을 어떤 절차로 제출할지 안내한다. 둘 다 중요하지만, 코드를 수정하는 순간에 필요한 질문은 조금 다르다.

• 이 기능은 어느 패키지가 맡고 있을까?
• 새로 만들기 전에 찾아봐야 할 기존 코드는 무엇일까?
• 웹 코드가 데이터베이스를 직접 호출해도 될까?
• 이 변경을 확인하려면 정확히 어떤 명령을 실행해야 할까?

AGENTS.md는 이런 질문에 답한다. 쉽게 말해 README가 방문자를 위한 안내판이라면, AGENTS.md는 작업자가 보는 현장 수칙이다.

세 문서의 역할을 한 문장씩만 나누면 이렇다.

• README: 제품과 빠른 시작을 설명한다.
• CONTRIBUTING.md: 사람이 변경을 제안하고 제출하는 절차를 설명한다.
• AGENTS.md: AI가 코드를 찾고, 수정하고, 검증할 때 지킬 프로젝트 규칙을 설명한다.

AGENTS.md가 README보다 더 길어야 한다는 뜻은 아니다. 오히려 지금 작업에 필요한 규칙을 빨리 찾게 해주는 편이 좋다. 그래서 규모가 큰 프로젝트는 보통 한 파일에 모든 내용을 몰아넣지 않고 범위별로 나눕니다.

3. 프로젝트 안에서는 어떻게 설계할까

웹·API·공용 패키지를 한 저장소에서 관리하는 프로젝트라면 다음과 같은 모양을 생각해볼 수 있다.

AGENTS.mdapps/  web/    AGENTS.md  api/    AGENTS.mdpackages/  ui/    AGENTS.md

이 구조에서 루트 AGENTS.md는 전체 지도를 보여준다. apps/web/AGENTS.md는 웹 작업에만 필요한 규칙을, apps/api/AGENTS.md는 API 작업에만 필요한 규칙을 알려준다.

예를 들어 AI가 apps/web/profile/page.tsx를 고친다면 흐름은 다음과 같다.

1. 루트 문서에서 apps/web의 역할과 공통 금지 사항을 확인한다.
2. 수정할 파일 쪽으로 내려가 apps/web/AGENTS.md를 읽다.
3. 그곳에서 공용 UI를 찾는 순서, API 호출 방법, 웹 테스트 명령을 확인한다.
4. 작업을 마치면 문서에 적힌 명령으로 결과를 검증한다.

이때 “가장 가까운 AGENTS.md가 언제나 자동으로 우선한다”를 모든 도구의 공통 규격으로 생각하면 곤란하다. 분석한 프로젝트 중 하나는 가장 가까운 지침을 따르라고 루트 문서에 직접 적어두었다. 다른 도구와 저장소는 문서를 찾고 합치는 방식이 다를 수 있다. 따라서 적용 범위와 충돌 시 우선순위도 프로젝트가 명시해야 하는 규칙이다.

루트 문서에는 전체 지도를 둡니다

루트에는 저장소 어디에서나 필요한 내용을 둡니다.

• 주요 디렉터리가 맡은 역할
• 모든 영역에 공통인 금지 사항
• 설치, 포맷, 린트처럼 공통으로 쓰는 명령
• 하위 AGENTS.md를 찾는 방법
• 문서끼리 충돌할 때 무엇을 우선할지

이렇게 하면 AI가 첫 단계에서 “어디를 고쳐야 하는가”를 좁힐 수 있다. 루트 문서가 모든 프레임워크의 세부 규칙까지 품을 필요는 없다.

하위 문서에는 그 지역의 작업 규칙을 둡니다

하위 문서는 수정할 코드 가까이에 둡니다.

• 먼저 재사용할 컴포넌트와 유틸리티
• 각 계층이 어디까지 맡는지 정한 선
• 자동 생성 파일처럼 직접 고치면 안 되는 대상
• 그 영역에서만 쓰는 테스트 명령
• 예외를 허용할 조건과 사람에게 확인해야 할 상황

덕분에 웹 작업을 하는 AI가 백엔드 트랜잭션 규칙까지 한꺼번에 읽지 않아도 된다. 반대로 API 작업에는 UI 스타일 규칙이 끼어들지 않다. 필요한 문맥만 가까이 두는 셈이다.

4. 실제 프로젝트는 무엇을 적어두었을까

세 프로젝트는 크기와 구조가 달랐지만 공통점이 있었다. 디렉터리 이름만 알려주지 않고, AI가 다음에 취할 행동까지 적어두었다는 점이다.

새로 만들기 전에 찾을 곳을 알려준다

특정 오픈소스 A는 프론트엔드 가까이에 별도 AGENTS.md를 둡니다. 아래에서 볼 부분은 “재사용하라”는 구호가 아니라, 실제로 어디부터 검색할지 순서를 준다는 점이다.

특정 오픈소스 A의 프론트엔드 AGENTS.md. 프로젝트 식별자는 일반 표기로 바꿨습니다.

## Rule 1 — Reuse before you createBefore building any UI element, search for an existing one.Where to look, in order:1. `frontend/src/lib/[main-ui]/` — the main-app default. Grep here first.2. `frontend/src/lib/ui/` and `frontend/src/lib/components/` — older shared pieces.

이 규칙을 읽은 AI는 버튼을 곧바로 생성하지 않다. 먼저 주 UI 폴더를 검색하고, 그다음 이전 공용 폴더를 확인한다. 공개 자료만으로 중복 코드가 실제로 얼마나 줄었는지는 알 수 없지만, 적어도 생성보다 탐색을 먼저 하도록 작업 순서가 바뀝니다. 리뷰어도 “왜 새 컴포넌트가 필요한가”를 물을 근거를 얻다.

폴더 이름보다 계층의 역할을 설명한다

특정 오픈소스 B는 큰 모노레포를 루트와 web, api, e2e 같은 영역별 지침으로 나눕니다. API 지침에는 실행 명령과 코드가 놓일 자리를 함께 적었다.

특정 오픈소스 B의 API AGENTS.md. 설명에 필요한 문장만 골랐습니다.

Run backend checks from the repository root:- Format and lint: `make lint`- Type check: `make type-check`- Unit tests: `make test`Keep transport parsing in controllers, orchestration in services,and domain policy in `core/` or its domain owner.

컨트롤러는 요청을 받고 형식을 확인하는 입구이다. 서비스는 여러 작업의 순서를 조정하고, core나 도메인 영역은 실제 업무 규칙을 맡다. 이 선을 문서에 적어두면 AI가 “파일 이름이 비슷해 보이는 곳”을 고르는 대신, 코드의 책임에 따라 위치를 정할 수 있다.

명령도 같은 문서에 있다. make lint, make type-check, make test는 실제 Makefile과 CI 설정으로 이어집니다. “충분히 확인한다”보다 훨씬 분명한 완료 조건이다.

모든 코드가 같은 원칙을 공유하면 루트 하나로도 충분하다

특정 오픈소스 C는 여러 서비스가 모인 모노레포가 아니라 하나의 Python 라이브러리이다. 핵심 자료형과 성능 원칙을 대부분의 코드가 공유하기 때문에 루트 AGENTS.md를 중심으로 설계했다.

특정 오픈소스 C의 루트 AGENTS.md. 프로젝트 식별자는 일반 표기로 바꿨습니다.

- `Detections` is the lingua franca — every connector and annotator speaks `Detections`.- Vectorized throughout — NumPy arrays, no Python loops in hot paths.- Lazy-import heavy dependencies inside the function that needs them.

쉽게 풀면, 외부 도구에서 들어온 결과는 하나의 공통 자료형으로 맞추고, 자주 실행되는 구간에서는 느린 반복문을 피하라는 뜻이다. 무거운 라이브러리도 필요할 때만 불러온다. 실제 핵심 클래스 구현이 이 설명과 연결된다.

여기서 중요한 판단 기준이 나온다. AGENTS.md가 많을수록 좋은 것은 아니다. 영역마다 책임과 명령이 크게 다르면 문서를 나누는 편이 낫다. 반대로 대부분의 코드가 같은 설계 원칙을 공유한다면 루트 문서 하나가 더 읽기 쉽다.

5. 이렇게 설계하면 무엇이 좋아질까

세 프로젝트가 AGENTS.md의 효과를 수치로 비교한 것은 아니다. 따라서 “결함이 몇 퍼센트 줄어든다”고 말할 근거는 없다. 다만 공개 지침과 실제 코드·설정의 연결을 보면, 각 설계가 AI의 작업 방식을 어떻게 바꾸려는지는 분명히 읽을 수 있다.

필요한 규칙만 읽을 수 있다

루트는 지도를, 하위 문서는 지역 규칙을 맡다. 웹 작업에는 웹 규칙만 따라오므로 관계없는 정보가 줄어듭니다. 문서가 짧아져서 좋은 것이 아니라, 지금 결정에 필요한 내용이 가까워져서 좋다.

기존 코드를 재사용하기 쉬워집니다

“재사용하세요”만으로는 AI가 무엇을 검색해야 할지 알기 어렵다. 검색할 폴더와 순서를 함께 적으면, 새 코드를 만들기 전에 기존 구현을 살펴보는 행동으로 이어집니다. 예외 import를 새로운 표준으로 오해하는 일도 줄이는 데 도움이 된다.

아키텍처를 덜 추측하게 된다

컨트롤러, 서비스, 도메인이 맡을 일을 설명하면 코드를 둘 위치가 선명해집니다. 이것이 아키텍처 경계이다. 테스트가 모든 잘못된 배치를 잡아내지는 못하지만, 적어도 구현 전에 확인할 기준과 리뷰에서 토론할 근거가 생깁니다.

사람과 AI가 같은 완료 조건을 본다

복사해서 실행할 수 있는 명령을 적어두면 “테스트했다”의 뜻이 구체적으로 맞춰집니다. 빠른 포맷·린트부터 타입 검사, 단위 테스트, 빌드까지 변경 범위에 맞게 넓혀갈 수 있다. 실행하지 못한 검사는 성공으로 적지 않고 검증 공백으로 남기기도 쉬워집니다.

규칙을 바꾸고 관리하기가 쉬워집니다

웹의 API 호출 방식이 바뀌었다면 웹 가까이에 있는 문서만 고치면 된다. 다만 문서가 나뉠수록 충돌 가능성도 생깁니다. 그래서 각 파일의 적용 범위와 우선순위를 함께 적어야 한다.

6. AGENTS.md 혼자 모든 실수를 막지는 못한다

AGENTS.md는 작업 전에 읽는 판단 기준이다. 자동으로 모든 규칙을 강제하는 장치는 아니다. 반복 절차와 자동 검증은 다른 도구에 나누어 맡기는 편이 자연스럽다.

• Skill은 특정 요청에서 꺼내 쓰는 작업 체크리스트이다. 예를 들어 프론트엔드 리뷰를 요청했을 때만 리뷰 순서와 결함 기준을 불러온다.
• Hook은 명령 실행이나 push 같은 사건 직전에 자동으로 끼어드는 빠른 안전장치이다.
• CI는 서버의 동일한 환경에서 테스트와 빌드를 더 넓게 실행한다.
• 사람은 설계 의도, 사용성, 예외 허용 여부와 최종 병합을 판단한다.

특정 오픈소스 B도 상시 적용되는 영역 규칙은 AGENTS.md에 두고, 프론트엔드 리뷰 절차는 별도 Skill로 분리했다. Bash 실행 전에 빠른 검사를 호출하는 Hook과 경로별 CI가 뒤를 받칩니다. 리뷰 Skill이 결함을 행동 테스트로 연결하는 자세한 방식은 AI 프론트엔드 코드 리뷰 Skill: 결함을 행동 테스트로 연결하는 법에서 이어서 살펴볼 수 있다.

문서 자체도 틀릴 수 있다. 특정 오픈소스 C에서는 예전 공개 API를 언제 제거할지 두 문서의 설명이 서로 달랐고, 실제 코드에는 호환용 연결 코드가 남아 있었다. 이때 AI가 더 그럴듯한 문장 하나를 골라 삭제를 진행하면 안 된다. 문서와 코드·테스트를 비교하고, 충돌을 기록한 뒤 사람에게 판단을 넘겨야 한다.

좋은 구조는 실수를 완전히 없애겠다고 약속하지 않다. 대신 무엇을 먼저 확인하고, 어디서 실패를 발견하며, 언제 사람에게 멈춰 물어볼지 알려준다.

7. 우리 프로젝트에는 작게 시작해도 된다

처음부터 모든 폴더에 AGENTS.md를 만들 필요는 없다. 최근 AI 변경에서 반복된 실수 하나를 고르는 것만으로도 충분하다. 공용 컴포넌트를 두고 새 UI를 만들었다면, 그 실수를 막는 검색 순서부터 적어보는 식이다.

Next.js 웹과 NestJS API가 함께 있는 프로젝트라면 다음처럼 시작할 수 있다. 아래 구조는 앞선 공개 패턴을 바탕으로 다시 만든 예시이며, 어느 한 프로젝트의 원문이 아니다.

AGENTS.md  저장소 지도, 공통 명령, 하위 지침을 읽는 순서apps/web/AGENTS.md  공용 UI 탐색 순서, 생성 API 클라이언트 사용, 웹 검증 명령apps/api/AGENTS.md  controller → service → domain → repository 책임, API 검증 명령packages/contracts/AGENTS.md  자동 생성 파일 수정 금지, 요청·응답 형식 변경 절차.agents/skills/add-endpoint/SKILL.md  endpoint 추가 때만 불러오는 반복 작업 순서

문서 한 장은 다음 다섯 항목이면 시작할 수 있다.

# Scope이 지침이 적용되는 파일과 디렉터리## Start here새로 만들기 전에 찾아볼 코드와 문서## Boundaries각 계층의 책임, 금지 의존성, 직접 수정하면 안 되는 파일## Verify작업 위치와 함께 적은 lint, typecheck, test, build 명령## Stop and ask문서 충돌, 공개 API 변경, 보안·데이터 위험처럼 사람이 결정할 조건

작성 순서도 어렵게 잡을 필요가 없다.

1. 최근 반복된 실패 한 가지를 고릅니다.
2. 루트에는 저장소 지도와 모두에게 필요한 명령만 적다.
3. 영역별로 다른 규칙은 해당 코드와 가장 가까운 문서로 옮깁니다.
4. 각 규칙에 이유, 허용되는 방법, 금지되는 방법, 확인 명령을 연결한다.
5. 매번 반드시 막아야 하는 규칙은 Hook이나 CI로 옮기고 문서도 함께 갱신한다.

마지막으로 문서의 명령이 아직 실행되는지 정기적으로 확인해야 한다. 사라진 스크립트를 가리키는 AGENTS.md는 없는 문서보다 더 큰 혼란을 만들 수 있다.

8. 결론: 긴 프롬프트보다 가까운 안내서

도입의 저장 버튼으로 돌아가 보겠다. 루트 지도와 웹 지침이 잘 연결되어 있다면 AI는 새 버튼을 만들기 전에 공용 UI를 찾다. 직접 fetch를 쓰기 전에 생성된 API 클라이언트를 확인하고, 작업이 끝나면 웹 영역에 맞는 명령을 실행한다.

좋은 AGENTS.md는 프로젝트 전체를 외우게 만드는 문서가 아니다. 루트에서는 방향을 보여주고, 하위 문서에서는 현재 위치의 규칙을 알려주며, Skill·Hook·CI와 사람의 검토로 다음 단계를 연결한다.

핵심은 길이가 아니라 거리이다. 필요한 규칙을 코드 가까이에 두면 AI가 덜 추측하고, 개발자는 같은 근거로 변경을 검토할 수 있다.

분석한 오픈소스와 원문 출처

본문에서는 분석 대상을 특정 오픈소스 A·B·C라는 가명으로 표현했다. 아래에서만 실제 프로젝트명을 밝힙니다. 링크는 분석에 사용한 파일 상태를 그대로 가리키는 고정 주소이며, 인용은 설명에 필요한 범위로 줄였다. 이 글은 각 프로젝트의 공식 문서나 공식 입장이 아니다.

• 특정 오픈소스 A = PostHog — 공식 저장소, 루트 AGENTS.md, A-1 · 프론트엔드 AGENTS.md, 공용 테이블 구현, 생성 API 사용 코드, 프론트엔드 검증 스크립트, pre-push Hook, AI 정책.
• 특정 오픈소스 B = Dify — GitHub 공개 저장소의 스타가 10만 개를 넘긴 분석 대상이다. 공식 저장소, 루트 AGENTS.md, B-1 · API AGENTS.md, Makefile, API 테스트 CI, 웹 검증 스크립트, 프론트엔드 리뷰 Skill, Claude Hook.
• 특정 오픈소스 C = Roboflow Supervision — 공식 저장소, C-1 · 루트 AGENTS.md, 공통 자료형 구현, 호환 모듈, deprecated 경고 테스트, 기여 지침, 테스트 CI.