← 보드로 돌아가기

TheRealSeanDonahoe/agents-md

Drop-in AGENTS.md that makes every coding agent behave like a senior engineer instead of an eager intern. Kills sycophancy, stops drive-by refactors, forces verification loops. Synthesizes Karpathy's four principles and Boris Cherny's Claude Code workflow. Works with Claude Code, Codex, Gemini CLI, Cursor, and the open standard.

GitHub에서 열기 ↗
545
GitHub 스타
66
포크
—
언어
MIT
라이선스
2026.04.19
최근 푸시
2026.04.21
별표한 날

AI 분석

설치 난이도: 쉬움
큐레이터 노트
유지 및 채택 권장. 단일 파일로 여러 에이전트의 행동을 일관되게 제어할 수 있어 생산성 향상에 도움이 됨. 특히 여러 코딩 에이전트를 사용하는 팀에 적합.

강점

  • 단일 파일로 모든 주요 코딩 에이전트에서 동작하여 설정 부담이 거의 없음
  • 에이전트의 아첨, 불필요한 리팩터, 검증 부족 등 일반적인 문제를 해결하는 행동 규칙 제공
  • 프로젝트 컨텍스트와 학습을 별도 섹션으로 분리하여 유지보수 용이
  • 오픈 표준(AGENTS.md) 기반으로 장기적 호환성 보장

약점

  • README에 실제 AGENTS.md 파일의 전체 내용이 포함되어 있지 않아 구체적인 규칙을 미리 알 수 없음
  • 대규모 코드베이스에서 파일이 커질 경우 샤딩이 필요할 수 있으나 문서가 충분하지 않음
  • 심볼릭 링크 사용 시 Windows에서 관리자 권한 또는 개발자 모드가 필요하여 일부 사용자에게 장벽이 될 수 있음

주의사항

  • 섹션 0-9는 행동 프레임워크이므로 특별한 이유 없이 수정하지 말 것
  • 섹션 11은 에이전트가 자동으로 채우므로 사용자가 직접 편집하지 않아야 함
  • 기존 CLAUDE.md나 GEMINI.md가 있는 경우 덮어쓰지 않도록 설치 과정에서 주의 필요
  • 심볼릭 링크가 실패하면 파일 복사로 대체되지만, 업데이트 시 수동 동기화가 필요함

시작 가이드

  • 레포지토리를 클론하거나 curl로 AGENTS.md를 다운로드하여 프로젝트 루트에 배치
  • 필요시 CLAUDE.md와 GEMINI.md로 심볼릭 링크 생성
  • 섹션 10의 TODO를 프로젝트 정보로 채우기
  • 에이전트 세션을 다시 시작하여 변경사항 적용 확인
  • 에이전트가 잘못된 행동을 하면 섹션 11에 학습을 추가하도록 지시

README 한국어 번역

이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.

<p align="center"> <img src="https://github.com/FerroxLabs/agents-md/releases/download/v0.1.0/hero.png" alt="Sean Donahoe의 AGENTS.md — 코딩 에이전트를 위한 더 스마트한 운영 지침" width="100%"> </p>

하나의 파일. 모든 코딩 에이전트가 시니어 엔지니어처럼 행동합니다.

아무 레포지토리에나 넣으세요. Claude Code, Codex, Cursor, Gemini CLI, Aider, Windsurf, Copilot, Devin이 모두 자체적으로 읽습니다. 플러그인도, 설정도, 설치 의식도 필요 없습니다.

그냥 작동합니다.

이것은 Ferrox Labs에서 모든 프로젝트에 적용하는 도구이자 핵심 운영 규율입니다. 하나의 파일, 모든 에이전트, 모든 레포지토리.

설치

쉬운 방법 — 에이전트에게 전달

프로젝트 루트에서 Claude Code, Codex, Cursor 또는 다른 코딩 에이전트를 열고 다음을 붙여넣으세요:

https://github.com/FerroxLabs/agents-md를 이 프로젝트에 설치하세요.

>

1. https://raw.githubusercontent.com/FerroxLabs/agents-md/main/AGENTS.md를 가져와 프로젝트 루트에 ./AGENTS.md로 저장하세요. AGENTS.md가 이미 존재하면 중단하고 덮어쓰기 전에 diff를 보여주세요.

2. CLAUDE.md와 GEMINI.md를 AGENTS.md에 심볼릭 링크하여 Claude Code와 Gemini CLI가 동일한 파일을 읽도록 하세요. OS에 맞는 명령어를 사용하세요(macOS/Linux는 ln -s, Windows는 New-Item -ItemType SymbolicLink). 심볼릭 링크가 실패하면 파일을 복사하는 것으로 대체하세요. CLAUDE.md나 GEMINI.md가 이미 내용을 가지고 있으면 덮어쓰지 말고 — 첫 줄에 @AGENTS.md를 추가하고 나머지는 그대로 두세요.

3. 새 AGENTS.md를 열고 섹션 10(프로젝트 컨텍스트)을 찾아, 이 코드베이스를 읽어 확인할 수 있는 것만 채우세요: 스택, package.json, pyproject.toml, Cargo.toml, 또는 Makefile의 빌드/테스트/린트 명령어, 소스/테스트 디렉토리 구조. 확인할 수 없는 것은 TODO로 남겨두세요.

4. 섹션 11은 건드리지 마세요 — 설계상 비어 있습니다.

5. 완료되면 파일이 로드되도록 이 세션을 다시 시작하라고 알려주세요.

세션을 다시 시작하세요. 완료입니다.

수동 방법

curl -o AGENTS.md https://raw.githubusercontent.com/FerroxLabs/agents-md/main/AGENTS.md

Codex, Cursor, Aider, Windsurf, Copilot, Devin, Amp, opencode, RooCode는 AGENTS.md를 자체적으로 읽습니다. 다른 작업은 필요 없습니다.

Claude Code와 Gemini CLI는 자신의 파일 이름을 찾으므로 심볼릭 링크를 만드세요:

macOS / Linux

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

Windows (PowerShell, 관리자 권한 또는 개발자 모드 켜서 실행)

New-Item -ItemType SymbolicLink -Path CLAUDE.md -Target AGENTS.md
New-Item -ItemType SymbolicLink -Path GEMINI.md -Target AGENTS.md

심볼릭 링크를 사용할 수 없으면 파일을 복사하세요 — AGENTS.md를 업데이트할 때 다시 복사해야 합니다:

Copy-Item AGENTS.md CLAUDE.md; Copy-Item AGENTS.md GEMINI.md

세션을 여세요. 완료입니다.

즉시 변경되는 사항

이전 이후
"완전히 맞습니다!" → 작동 중인 코드를 되돌림 에이전트가 당신이 틀렸을 때 반박함
50줄이면 될 것을 200줄 문제를 해결하는 가장 간단한 diff
오타 수정하면서 전체 파일 재포맷 변경된 모든 줄이 요청에 기인함
실행되지 않는 코드에 "완료"라고 주장 먼저 검증을 작성하고, 실행한 후 보고함
두 가지 해석 사이에서 조용히 추측 모호함을 표면화하고 한 번 질문함
파일이 너무 길어서 규칙의 절반을 무시함 간결하게 설계됨. ~200줄. 규칙이 로드된 상태로 유지됨

편집할 두 섹션. 나머지는 그대로 둡니다.

섹션 10 — 프로젝트 컨텍스트. 스택, 명령어, 레이아웃, 금지 영역. TODO를 한 번 채우세요. 5분.

섹션 11 — 프로젝트 학습. 비어 있는 상태로 시작합니다. 에이전트가 무언가 잘못할 때마다 한 줄이 추가됩니다. 당신이 수정할 때 에이전트가 직접 줄을 추가합니다 — 파일을 관리할 필요가 없습니다.

이 섹션은 누적됩니다. Claude Code의 창시자인 Boris Cherny는 팀 버전을 수개월에 걸쳐 약 100개의 학습으로 운영합니다. 그의 파일은 선언문이 아니라 훈련된 반사 신경입니다.

섹션 0–9는 행동 프레임워크입니다. 특별한 이유가 없으면 건드리지 마세요.

AGENTS.md가 하나의 파일을 넘어설 때

드뭅니다. 하지만 대규모 코드베이스에서는 발생합니다. 샤딩하기 전에 문서를 읽으세요 — 대부분의 사람들은 필요하지 않습니다:

  • Claude Code: CLAUDE.md 내에서 @path/to/file.md 임포트를 사용하거나, 주제별 규칙을 paths: 프론트매터와 함께 .claude/rules/*.md에 넣어 Claude가 일치하는 파일을 건드릴 때만 로드되도록 하세요. Claude Code는 자체적으로 메모리를 자동으로 기록합니다 — 다시 발명하지 마세요.
  • Cursor: 동일한 이유로 .cursor/rules/*.mdc를 경로 스코핑과 함께 사용하세요.
  • 그 외: 하나의 AGENTS.md가 여전히 정답입니다.

목표는 세션당 로드되는 토큰을 줄이는 것이지, 파일 자체를 늘리는 것이 아닙니다.

왜 CLAUDE.md가 아니라 AGENTS.md인가

AGENTS.md는 Linux Foundation의 Agentic AI Foundation이 관리하는 오픈 크로스-툴 표준입니다. Codex, Cursor, Windsurf, Copilot, Aider, Devin, Amp, opencode, RooCode가 기본적으로 읽습니다. Claude Code는 CLAUDE.md를 읽습니다. Gemini CLI는 GEMINI.md를 읽습니다. 세 개를 모두 심볼릭 링크하면 모든 에이전트가 동일한 파일을 읽습니다.

하나의 진실 공급원. 세 개를 유지할 필요가 없습니다.

기반

  • Sean Donahoe의 IJFW 원칙 — 그냥 씨발 잘 작동합니다: 한 번 설치, 제로 의식, 작동하는 코드
  • Andrej Karpathy의 네 가지 원칙 (LLM 코딩 실패 모드에 관한)
  • Boris Cherny의 공개 Claude Code 워크플로우 — 반응형 정리, 간결하게 유지
  • Anthropic의 공식 Claude Code 모범 사례
  • AGENTS.md 오픈 표준

라이선스

MIT. 포크하고, 다시 작성하고, 자신의 이름으로 배포하세요. 그것이 요점입니다.

한 시간을 절약해 주었다면, ⭐ 하나가 감사 인사입니다.

원본 저장소: TheRealSeanDonahoe/agents-md

라이선스: MIT

게재 제외를 원하시면 삭제 요청을 보내주세요.