AGENTS.md와 심볼릭 링크를 활용한 JetBrains 내 Junie, Codex, Claude Agent 통합 운영 방법

안녕하세요. 네바네바(ねばねば)입니다.

저는 평소 IntelliJ IDEA에서 JetBrains AI의 코딩 에이전트(Coding Agent)를 전환하며 테스트를 진행하고 있습니다.

JetBrains AI 구독에는 다음 3가지가 포함되어 있습니다.

• Junie (JetBrains 자체 제작, IDE와 밀접하게 통합된 에이전트)
• Claude Agent (Anthropic, Claude Agent SDK를 통해 IDE에 연결)
• Codex (OpenAI, ACP = Agent Client Protocol을 통해 연결)

또한 구독 외에도 BYOK(Bring Your Own Key)나 ACP 호환 에이전트를 추가할 수 있는 벤더 중립적인 구조로 되어 있습니다.

이 기사의 결론

Junie와 Codex는 AGENTS.md를 읽습니다.
Claude Agent만은 CLAUDE.md를 읽습니다.

CLAUDE.md를 AGENTS.md에 대한 심볼릭 링크(Symbolic Link)로 설정함으로써, 실체 파일 하나로 3개의 에이전트 모두에게 동일한 지시를 전달할 수 있습니다.

동일한 내용을 AGENTS.md와 CLAUDE.md에 이중 관리하다가 한쪽만 업데이트하여 동작이 어긋나는 것을 방지하기 위한 글입니다.

"AGENTS.md와 JetBrains IDE의 궁합이 좋은 이유"를 정리해 두겠습니다. 양쪽 모두 "벤더 중립"을 지향하고 있기 때문이 아닐까 합니다.

JetBrains AI 구독에 포함된 3개의 에이전트는 각기 다른 연동 방식으로 동일한 IDE에 공존하고 있습니다.

에이전트	연동 방식	개발사
Junie	자체 네이티브 (IDE와 가장 밀접하게 통합)	JetBrains
Claude Agent	Claude Agent SDK 경유	Anthropic
Codex	ACP (Agent Client Protocol, Zed에서 시작된 오픈 표준) 경유	OpenAI

"JetBrains 제작 Junie + 타사 제작 에이전트 2종"이 동일한 AI Chat 내에서 전환 가능한 상태입니다. 나아가 구독 외에도 BYOK / OAuth / ACP 호환 에이전트를 나중에 추가할 수 있으며, IDE 측은 "어떤 에이전트가 오더라도 받아들인다"는 스탠스를 취하고 있습니다.

한편 AGENTS.md는 OpenAI Codex, Amp, Google Jules, Cursor, Factory 등의 협업을 통해 탄생한 **오픈 포맷(Open Format)**으로, 2025년 12월에는 Linux Foundation 산하의 Agentic AI Foundation 창설 프로젝트에 채택되었습니다. 이미 60,000개 이상의 리포지토리가 채택하고 있습니다.

특정 벤더 제품에 종속되지 않는 "AI 에이전트용 README"로서, 빌드·테스트·규약·금지 사항을 하나의 파일에 통합하는 사상입니다.

IDE는 "특정 AI 기능"과 밀결합되어 있어, 다른 에이전트로 교체하면 프로젝트 지시 사항도 다시 작성해야 하는 경우가 많습니다. 반면 JetBrains IDE는 여러 에이전트가 공존하는 것을 전제로 하므로,

• 가벼운 질문은 Junie
• 규모가 큰 리팩터링은 Claude Agent
• 코드베이스 전반의 조사는 Codex

...와 같은 구분 사용이 가능합니다. 이때 지시 파일이 에이전트마다 별도로 존재하면 번거로우므로, **툴 중립적인 AGENTS.md**를 하나 두고 모두에게 읽히는 운영 방식이 가장 자연스럽습니다.

유일한 걸림돌은 "Claude Agent만 CLAUDE.md를 읽으러 간다"는 점인데, 이를 다음의 심볼릭 링크로 해결합니다.

먼저 프로젝트 루트에 AGENTS.md를 둡니다. 작성 방법은 여러 가지가 있지만, Matt Nigh가 2,500개 이상의 리포지토리를 분석하여 정리한 6가지 핵심 영역을 참고했습니다.

# AGENTS.md
## Commands
- 개발 서버 실행: `npm run dev`
- 테스트 실행: `npm test`
...

## Code Style
// Good
export function fetchUser(id: string): Promise<User> { ... }

## Git workflow
- Conventional Commits 사용
- main으로의 직접 push 금지

## Boundaries
...

핵심은 Boundaries(경계)를 Always / Ask first / Never의 3단계로 작성하는 것입니다.

다음으로 심볼릭 링크(Symbolic Link)에 대해 살펴보겠습니다.

심볼릭 링크란

파일이나 디렉토리에 대한 "바로가기"를 의미합니다.

실체는 하나뿐이므로, 어느 경로로 열더라도 항상 동일한 내용이 읽히고 쓰여집니다.

ln -s 실체 링크명 명령으로 만들 수 있습니다.

이미지로 표현하면 다음과 같습니다.

[실체] AGENTS.md ←──┐
│ "내용을 보여줘"라고 요청받으면 동일한 실체로 전달
[링크] CLAUDE.md ──┘

CLAUDE.md를 열어도 Finder나 탐색기(Explorer)에서는 일반 파일처럼 보이지만, OS가 백그라운드에서 "이것은 링크이므로 AGENTS.md의 내용을 반환하겠다"라고 처리해 줍니다. 복사본이 아니기 때문에, AGENTS.md를 편집하면 CLAUDE.md 측에서도 즉시 새로운 내용을 읽을 수 있습니다.

# 프로젝트 루트에서
ln -s AGENTS.md CLAUDE.md

ls -la 명령으로 확인하면 링크 화살표가 보입니다.

$ ls -la CLAUDE.mdlrwxr-xr-x 1 user staff 10 5 15 14:22 CLAUDE.md -> AGENTS.md

Windows (PowerShell)

# 프로젝트 루트에서
New-Item -ItemType SymbolicLink -Path CLAUDE.md -Target AGENTS.md

또는 cmd에서:

mklink CLAUDE.md AGENTS.md

단, Windows에서 심볼릭 링크를 생성하려면 개발자 모드(Developer Mode)를 ON으로 설정하거나 관리자 권한으로 실행해야 합니다.

3개의 에이전트(Agent) 모두에게 동일한 질문을 던져, AGENTS.md의 내용이 제대로 반영되는지 확인합니다.

질문은 통일합니다:

"이 프로젝트에서 테스트를 실행하는 명령과, 건드려서는 안 되는 파일을 알려줘"

기대하는 답변은 AGENTS.md의 Commands 및 Boundaries에 따라 npm test와 .env* / node_modules/입니다.

IntelliJ IDEA의 AI Chat에서 에이전트를 Junie로 전환하여 질문합니다.

Junie는 세션 시작 시 AGENTS.md를 가이드라인으로 읽어들이는 사양(Specification)이므로, 기대한 대로 npm test와 .env* / node_modules/를 답변해 주었습니다.

에이전트를 Codex로 전환하여 동일한 질문을 합니다.

Codex도 AGENTS.md를 지원하므로 동일한 답변이 돌아옵니다.

에이전트를 Claude Agent로 전환하여 동일한 질문을 합니다. Claude Agent는 본래 CLAUDE.md를 참조하는 사양이지만, CLAUDE.md의 실체가 AGENTS.md이므로 동일한 내용이 읽힙니다.

확인을 위해 Claude Agent에게 "지금 읽고 있는 지시 파일의 경로와 크기를 알려줘"라고 물으면 CLAUDE.md를 읽고 있다고 답하지만, OS 측에서 AGENTS.md로 리다이렉트(Redirect)되고 있으므로 내용은 AGENTS.md로부터 공급됩니다.

JetBrains AI에서 여러 에이전트를 구분하여 사용하려면,

• 프로젝트 루트에 AGENTS.md를 배치한다.
• (Windows라면 ln -s AGENTS.md CLAUDE.md, mklink 또는 New-Item -ItemType SymbolicLink를 사용하여) 링크를 생성한다.
• 이렇게 하면 Junie / Codex / Claude Agent 3개의 에이전트 모두에게 동일한 지시가 전달된다.

이러한 운영 방식이 현재로서는 매우 효율적입니다.

꼭 한번 시도해 보세요!

저희 회사는 JetBrains 제품에 관한 질문이나 상담 등을 받고 있습니다. 저희의 X(구 Twitter) 또는 이메일로 연락해 주시기 바랍니다.

• AGENTS.md 공식 사이트 — 포맷 정의, 채택 도구 목록, 샘플

• Linux Foundation: Agentic AI Foundation (AAIF) 출범 보도 자료 — MCP / goose / AGENTS.md가 창설 프로젝트에 채택된 경위

• OpenAI: Agentic AI Foundation 공동 설립 발표

• InfoQ: OpenAI와 Anthropic이 AGENTS.md / MCP를 AAIF에 기증 — 60,000개 이상의 리포지토리 채택 맥락

Junie Docs: Guidelines and memory —
.junie/AGENTS.md

→ AGENTS.md

→ .junie/guidelines.md

의 탐색 순서 - YouTrack JUNIE-618: Support AGENTS.md — AGENTS.md 대응 논의 이력

• JetBrains/junie-guidelines (GitHub) — 공식 가이드라인 모음

• Junie Playbook

• Agent Client Protocol 공식 (Zed) — 사양, Apache 라이선스

• JetBrains AI Blog: JetBrains × Zed — ACP 채택

• JetBrains AI Blog: ACP Agent Registry Is Live (2026/01) — Claude Code / Codex CLI / Gemini CLI 등이 등록됨

• JetBrains ACP 랜딩 페이지

• Zed Blog: Codex is Live in Zed