AGENTS.md 유지 관리
AGENTS.md는 에이전트 전용 문서입니다. 간결하게 유지하세요 — 에이전트는 능숙하며 과잉 안내가 필요하지 않습니다. 60줄 미만을 목표로 하고, 100줄을 넘지 마세요. 문서가 길어질수록 지침 수행 품질이 저하됩니다.
사용 시점
- 사용자가
AGENTS.md또는CLAUDE.md의 생성, 업데이트, 감사를 요청할 때 - 프로젝트에 실제 도구 체인과 저장소 구조에서 도출된 간결하고 고효율의 에이전트 지침이 필요할 때
- 기존 에이전트 문서가 너무 길거나, 중복되거나, 실제 프로젝트 관행에서 벗어날 때
파일 설정
- 프로젝트 루트에
AGENTS.md생성 - 심볼릭 링크 생성:
ln -s AGENTS.md CLAUDE.md
작성 전 분석
프로젝트를 분석하여 파일에 포함할 내용을 파악하세요:
- 패키지 매니저 — 잠금 파일 확인 (
pnpm-lock.yaml,yarn.lock,package-lock.json,uv.lock,poetry.lock) - 린터/포매터 설정 —
.eslintrc,biome.json,ruff.toml,.prettierrc등 확인 (이것들을 AGENTS.md에 중복하지 마세요) - CI/빌드 명령어 —
Makefile,package.json스크립트, CI 설정에서 표준 명령어 확인 - 모노레포 표시 —
pnpm-workspace.yaml,nx.json, Cargo 워크스페이스, 하위 디렉토리package.json파일 확인 - 기존 관행 — 기존 CONTRIBUTING.md, docs/, README 패턴 확인
작성 규칙
- 헤더 + 불릿 — 문단 없음
- 코드 블록 — 명령어와 템플릿용
- 참조, 포함 금지 — 기존 문서를 가리키세요: "설정은
CONTRIBUTING.md참조" 또는 "src/api/routes/의 패턴 따를 것" - 불필요한 내용 금지 — 서문, 결론, 인사말 없음
- 능력 신뢰 — 명백한 맥락은 생략
- 파일 단위 명령어 선호 — 프로젝트 전체 빌드보다 파일별 테스트/린트/타입체크 명령어
- 린터 중복 금지 — 코드 스타일은 린터 설정에, AGENTS.md에 넣지 마세요
필수 섹션
패키지 매니저
어떤 도구와 주요 명령어만:
## 패키지 매니저
**pnpm** 사용: `pnpm install`, `pnpm dev`, `pnpm test`
파일 단위 명령어
파일 단위 명령어는 전체 프로젝트 빌드보다 빠르고 저렴합니다. 가능하면 항상 포함하세요:
## 파일 단위 명령어
| 작업 | 명령어 |
|------|--------|
| 타입체크 | `pnpm tsc --noEmit path/to/file.ts` |
| 린트 | `pnpm eslint path/to/file.ts` |
| 테스트 | `pnpm jest path/to/file.test.ts` |
커밋 귀속
항상 이 섹션을 포함하세요. 에이전트는 자신의 정체성을 사용해야 합니다:
## 커밋 귀속
AI 커밋에는 반드시 포함:
Co-Authored-By: (에이전트 모델 이름과 귀속 표시줄)
예시: `Co-Authored-By: Claude Sonnet 4 <[email protected]>`
주요 관행
에이전트가 따라야 할 프로젝트별 패턴. 간단히 유지.
선택적 섹션
정말 필요한 경우에만 추가:
- API 라우트 패턴 (설명 없이 템플릿만 표시)
- CLI 명령어 (표 형식)
- 파일 명명 규칙
- 프로젝트 구조 힌트 (중요 파일 가리키기, 피해야 할 레거시 코드 표시)
- 모노레포 재정의 (하위 디렉토리
AGENTS.md파일이 루트를 재정의)
안티패턴
다음은 생략:
- "...에 오신 것을 환영합니다" 또는 "이 문서는 ...을 설명합니다"
- "당신은 ...해야 합니다" 또는 "...하는 것을 기억하세요"
- 설정 파일(
.eslintrc,biome.json,ruff.toml)에 이미 있는 린터/포매터 규칙 - 설치된 스킬이나 플러그인 나열 (에이전트가 자동으로 발견)
- 파일 단위 대안이 있을 때 전체 프로젝트 빌드 명령어
- 명백한 지침 ("테스트 실행", "깔끔한 코드 작성")
- 이유 설명 (그냥 무엇을 할지만 말하세요)
- 긴 산문 문단
예시 구조
# 에이전트 지침
## 패키지 매니저
**pnpm** 사용: `pnpm install`, `pnpm dev`
## 커밋 귀속
AI 커밋에는 반드시 포함:
Co-Authored-By: (에이전트 모델 이름과 귀속 표시줄)
## 파일 단위 명령어
| 작업 | 명령어 |
|------|--------|
| 타입체크 | `pnpm tsc --noEmit path/to/file.ts` |
| 린트 | `pnpm eslint path/to/file.ts` |
| 테스트 | `pnpm jest path/to/file.test.ts` |
## API 라우트
[템플릿 코드 블록]
## CLI
| 명령어 | 설명 |
|--------|------|
| `pnpm cli sync` | 데이터 동기화 |
제한 사항
- 이 스킬은 위에서 설명한 범위와 명확히 일치하는 작업에만 사용하세요.
- 출력물을 환경별 검증, 테스트, 전문가 검토의 대체물로 취급하지 마세요.
- 필수 입력, 권한, 안전 경계 또는 성공 기준이 누락된 경우 멈추고 명확히 요청하세요.