agents-md-setup
AGENTS.md 를 에이전트/프로젝트 지시 사항의 단일 진실 공급원으로 만들고,
모든 도구의 파일을 심볼릭 링크로 이를 가리키게 합니다. 하나의 파일로 모든 에이전트가 읽어 — 중복도 없고, 불일치도 없습니다.
이 구조가 좋은 이유
AGENTS.md는 떠오르는 크로스-툴 표준입니다(Cursor, Codex 등이 이를 읽음).- Claude Code는
CLAUDE.md를 읽습니다. 프롬프트나 스킬로 대신AGENTS.md를 읽도록 할 수 없습니다. 하지만CLAUDE.md → AGENTS.md심볼릭 링크를 만들면 Claude가CLAUDE.md를 열면서AGENTS.md의 내용을 얻게 됩니다. 이것이 바로 메커니즘입니다; 다른 것은 필요 없습니다. - 결과:
AGENTS.md만 편집하면 모든 에이전트가 동기화됩니다.
결정: 기존에 무엇이 있나요?
- 두 파일 모두 없음 → 아래 템플릿으로
AGENTS.md를 생성합니다. CLAUDE.md만 있음 (실제 파일) → 이를 진실 공급원으로 만듭니다:git mv CLAUDE.md AGENTS.md # 히스토리 보존 (또는 추적되지 않은 경우 mv)AGENTS.md만 있음 → 그대로 유지합니다(좋습니다).- 둘 다 실제 파일로 존재 → 눈 가리고 덮어쓰지 마세요. 비교하고
AGENTS.md로 병합합니다(공인 파일로서 우선), 내용이 다르면 사용자와 확인한 후, 독립적인CLAUDE.md를 제거합니다. CLAUDE.md가 이미AGENTS.md에 대한 심볼릭 링크임 → 이미 완료됨; 중단합니다.
심볼릭 링크 생성
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md # git은 실제 심볼릭 링크(모드 120000)로 저장합니다
심볼릭 링크로 커밋되었는지, 복사본이 아닌지 확인합니다:
git ls-files -s CLAUDE.md # 모드가 120000이어야 함
선택적으로 다른 도구도 같은 파일을 가리키게 할 수 있습니다:
ln -s AGENTS.md GEMINI.md
mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
모노레포 (Turborepo / 워크스페이스)
리포지토리 전체 규칙을 위해 루트 AGENTS.md 를 유지하고(위와 같이 CLAUDE.md 심볼릭 링크 포함), 자체 규칙이 필요한 각 워크스페이스에 스코프된 AGENTS.md 를 추가합니다 — apps/<app>/AGENTS.md, packages/<pkg>/AGENTS.md — 각각의 형제 심볼릭 링크는 해당 디렉토리 내부에서 생성하여 대상이 상대 경로가 되도록 합니다:
cd apps/web && ln -s AGENTS.md CLAUDE.md # CLAUDE.md -> ./AGENTS.md (같은 디렉토리)
- Claude Code는 작업 중인 파일에서 가장 가까운
CLAUDE.md를 읽으므로, 중첩된 파일은 루트를 대체하는 것이 아니라 보완합니다. 리포지토리 전체는 루트에 두고, 각 워크스페이스에는 해당 패키지의 차이점만 넣으세요 — 루트를 중복하지 마세요. - 각 심볼릭 링크는 항상 자체 폴더에 상대적으로 만드세요(
cd로 워크스페이스에 들어간 후ln -s AGENTS.md CLAUDE.md), 루트로 돌아가지 말고 — 동일 디렉토리 내 상대 링크는 체크아웃/이동 상황에도 유지됩니다. - Turborepo 자체는 이러한 파일을 읽지 않습니다 (에이전트용입니다), 따라서
turbo.json변경은 필요 없습니다. 만약 이들을 표면화하고 싶다면, 루트AGENTS.md에 관례를 기록할 수 있습니다.
README
README.md가 없다면, 최소한의 파일(프로젝트 이름, 한 줄 설명, 설정/실행 명령어)을 생성합니다. 사람 대상 문서는 README.md에, 에이전트 지시는 AGENTS.md에 유지하세요 — 둘을 합치지 마세요.
Windows / CI 주의 사항 (중요)
Git 심볼릭 링크는 core.symlinks=true 설정이 필요하며, Windows 체크아웃이나 일부 CI 러너에서 깨질 수 있습니다(심볼릭 링크가 AGENTS.md 내용을 담은 텍스트 파일로 저장됨). 프로젝트가 Windows를 대상으로 한다면, 대체 방식을 선호하세요: 아주 작은 실제 CLAUDE.md 파일의 전체 내용이 포인터가 되도록 —
프로젝트 및 에이전트 지시 사항은 [AGENTS.md](./AGENTS.md)를 참조하세요.
— 단, 수동으로 동기화를 유지해야 함(또는 검사를 통해)을 인지하세요. 심볼릭 링크가 신뢰할 수 있는 모든 곳에서는 심볼릭 링크가 더 좋습니다.
나중에 되돌리지 마세요
CLAUDE.md가 AGENTS.md에 대한 심볼릭 링크인 것을 보았다면, 의도된 것입니다 — AGENTS.md를 편집하고, 심볼릭 링크를 복사본으로 절대 대체하지 마세요.
AGENTS.md 템플릿
# AGENTS.md
이 리포지토리에서 작업하는 AI 에이전트와 인간을 위한 지침입니다.
`CLAUDE.md`는 이 파일의 심볼릭 링크입니다; 이 파일이 진실 공급원입니다.
## 프로젝트 개요
<이것이 무엇인지, 1~3문장으로>
## 명령어
- 설치: `…`
- 개발: `…`
- 빌드: `…`
- 테스트 / 린트 / 포맷: `…`
## 관례
- <코드 스타일, 언어/런타임, 포맷팅>
- 커밋 메시지: <예: Conventional Commits>
- <에이전트가 하지 말아야 할 것, 또는 항상 해야 할 것>
## 구조
<주요 디렉토리와 각각의 역할>