FerroxLabs/agents-md

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

어떤 저장소(repo)에든 이 파일을 넣으세요. Claude Code, Codex, Cursor, Gemini CLI, Aider, Windsurf, Copilot, 그리고 Devin 모두 별도의 플러그인, 설정(config), 설치 절차 없이 스스로 이 파일을 읽습니다.

그냥 작동합니다.

이것은 Ferrox Labs에서 모든 프로젝트를 수행할 때 사용하는 도구이자 핵심 운영 규율입니다. 단 하나의 파일, 모든 에이전트, 모든 저장소.

프로젝트 루트(root)에서 Claude Code, Codex, Cursor 또는 다른 코딩 에이전트를 여세요. 다음 내용을 붙여넣으세요:

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

• 가져오기 (Fetch)
  https://raw.githubusercontent.com/FerroxLabs/agents-md/main/AGENTS.md 를 가져와서

프로젝트 루트에 ./AGENTS.md로 저장하세요. 만약 AGENTS.md가

이미 존재한다면, 중단하고 덮어쓰기 전에 차이점(diff)을 보여주세요.

• 심볼릭 링크 (Symlink)
  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를 추가하고 나머지는 그대로 두세요.

• 새로 생성된 AGENTS.md를 열고, 섹션 10(Project context)을 찾아 이 코드베이스를 읽음으로써 확인할 수 있는 내용만 채우세요: 스택(stack), package.json, pyproject.toml, Cargo.toml 또는 Makefile에서 확인되는 빌드/테스트/린트(lint) 명령어, 그리고 소스(source)/테스트(test) 디렉토리 레이아웃. 확인할 수 없는 모든 내용은 TODO로 남겨두세요.

• 섹션 11은 건드리지 마세요 — 설계상 비워두도록 되어 있습니다.

• 완료되면, 파일이 로드될 수 있도록 이 세션을 재시작하라고 말하세요.

세션을 재시작하세요. 완료되었습니다.

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, 관리자 권한으로 실행하거나 개발자 모드(Developer Mode)가 켜져 있어야 함)

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

심볼릭 링크 (symlinks)를 사용할 수 없는 경우, 대신 파일을 복사하세요. 다만 AGENTS.md를 업데이트할 때마다 다시 복사해야 합니다.

:

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

세션을 엽니다. 완료되었습니다.

이전 (Before)	이후 (After)
"당신이 전적으로 옳습니다!" → 작동하던 코드를 되돌림	당신이 틀렸을 때 에이전트 (Agent)가 반박함
50줄이면 충분할 것을 200줄로 만듦	문제를 해결하는 가장 단순한 차이 (diff)
오타를 수정하면서 파일 전체의 형식을 바꿈	변경된 모든 줄이 당신의 요청을 추적함
실행되지 않는 코드에 대해 "완료"라고 주장함	검증을 먼저 작성하고, 실행한 다음 보고함
...

섹션 10 — 프로젝트 컨텍스트 (Project context). 스택 (Stack), 명령어 (commands), 레이아웃 (layout), 금지 구역. TODO를 한 번만 채우세요. 5분이면 됩니다.

섹션 11 — 프로젝트 학습 내용 (Project Learnings). 빈 상태로 시작합니다. 에이전트가 무언가 틀릴 때마다 한 줄씩 추가됩니다. 당신이 에이전트를 교정할 때 에이전트 스스로가 그 줄을 추가하므로, 당신이 파일을 일일이 관리할 필요는 없습니다.

이 섹션은 복리로 쌓입니다. Claude Code의 제작자인 Boris Cherny는 수개월 동안 축적된 약 100개의 학습 내용을 바탕으로 팀 버전을 운영합니다. 그의 파일은 선언문 (manifesto)이 아니라 훈련된 반사 신경 (trained reflex)입니다.

섹션 0–9는 행동 스캐폴딩 (behavioral scaffold)입니다. 특별한 이유가 없다면 건드리지 마세요.

드문 경우지만, 대규모 코드베이스에서는 발생할 수 있습니다. 샤딩 (shard)하기 전에 문서를 읽으세요. 대부분의 사람에게는 필요하지 않습니다:

Claude Code: @path/to/file.md를 사용하세요.

CLAUDE.md 내부의 임포트 (imports),

또는 paths:가 포함된 프런트매터 (frontmatter)와 함께 .claude/rules/*.md에 토픽 범위 규칙 (topic-scoped rules)을 넣으세요. 이렇게 하면 Claude가 일치하는 파일에 접근할 때만 규칙이 로드됩니다. Claude Code는 자체 메모리를 자동으로 작성하므로, 이를 재발명하지 마세요.

Cursor: 동일한 이유로 경로 범위 지정 (path scoping)이 가능한 .cursor/rules/*.mdc를 사용하세요.

그 외 모두: 하나의 AGENTS.md가 여전히 정답입니다.

목표는 단순히 파일 수를 늘리는 것이 아니라, 세션당 로드되는 토큰 (tokens) 수를 줄이는 것입니다.

AGENTS.md는 Linux Foundation의 Agentic AI Foundation이 관리하는 오픈 크로스 툴 표준 (open cross-tool standard)입니다. Codex, Cursor, Windsurf, Copilot, Aider, Devin, Amp, opencode, 그리고 RooCode는 이를 네이티브로 읽습니다. Claude Code는 CLAUDE.md를 읽습니다.

Gemini CLI는 GEMINI.md를 읽습니다.

이 세 가지를 모두 심볼릭 링크 (Symlink)로 연결하면 모든 에이전트 (agent)가 동일한 파일을 읽게 됩니다.

단일 진실 공급원 (One source of truth). 세 개를 따로 관리하는 일을 멈추세요.

• Sean Donahoe의 IJFW 원칙 — it just fcking works* (그냥 존나 잘 된다): 단 한 번의 설치, 번거로운 절차 없음, 작동하는 코드 - LLM 코딩 실패 모드에 관한 Andrej Karpathy의 4가지 원칙
• Boris Cherny의 공개 Claude Code 워크플로우 — 반응형 가지치기 (reactive pruning), 간결함 유지
• Anthropic의 공식 Claude Code 베스트 프랙티스 (best practices)
• AGENTS.md 오픈 표준 (open standard)

MIT 라이선스입니다. 포크 (Fork)하고, 다시 쓰고, 당신의 이름을 붙여 배포하세요. 그것이 목적입니다.

만약 이 내용이 당신의 시간을 한 시간이라도 아껴주었다면, 레포지토리 (repo)에 ⭐를 남기는 것이 감사를 표하는 방법입니다.