JetBrains AI Assistant Rules와 AGENTS.md를 일치시켜 채팅과 에이전트가 동일한 지침을 따르게 하는 방법 (2026년 가이드)

먼저 Project rules부터 살펴보겠습니다. JetBrains의 문서는 이를 채팅을 위한 가이드라인으로 설명합니다. "기본적으로 프로젝트 규칙은 각 채팅 세션에 자동으로 추가되므로 AI Assistant가 제공된 가이드라인을 준수합니다." 설정에서 규칙을 생성하면 ".aiassistant/rules 폴더가 생성되고 그 안에 .md 파일이 들어갑니다."

각 규칙에는 적용 시점을 결정하는 유형(type)이 있습니다.

• "Always – 모든 채팅 세션에 자동으로 적용됩니다."
• "Manually – 채팅에서 @rule: 또는 #rule:을 사용하여 명시적으로 호출하거나, 첨부 파일 추가(Add attachment) 작업을 통해 추가된 경우에만 적용됩니다."
• "By model decision – 모델이 해당 규칙이 관련이 있다고 판단할 때 적용됩니다." 이 유형의 경우 "AI Assistant가 규칙이 적용되어야 하는 시점을 이해할 수 있도록 Instruction(지침)도 제공해야 합니다."
• "By file patterns – 채팅에서 참조된 파일이 지정된 파일 패턴(예: *.kt 또는 src/**)과 일치할 때 적용됩니다."
• "Off – 규칙이 비활성화되어 적용되지 않습니다."

이 모든 설명에는 '채팅(chat)'이 언급됩니다. 이는 의도된 것입니다. 에이전트 지침에 대한 JetBrains의 페이지에서는 다음과 같이 명확하게 선을 긋고 있습니다. "Project rules는 IDE에서 구성되며 AI Assistant 채팅 모드에서만 적용됩니다."

반면 에이전트는 지침 파일(instruction files)을 사용합니다. "에이전트는 코딩 컨벤션, 아키텍처 제약 조건, 공통 워크플로우를 포함하여 코드베이스에서 어떻게 작동해야 하는지 정의하는 프로젝트 내의 지침 파일을 사용하여 구성할 수 있습니다." 그리고 어떤 파일을 사용하는지는 에이전트에 따라 다릅니다. "대부분의 에이전트는 재사용 가능한 가이드를 위해 AGENTS.md 파일에 의존하지만, 일부는 자체 형식을 사용합니다. 예를 들어, Claude Agent는 CLAUDE.md에서 지침을 가져옵니다."

에이전트 관련 페이지에서도 이를 확인해 줍니다. "Junie는 루트 프로젝트 디렉토리의 AGENTS.md 파일에서 지침을 읽으므로, 버전 관리 하에 두고 프로젝트 전체에서 재사용할 수 있습니다." 그리고 다른 에이전트의 경우 다음과 같습니다. "Claude Agent는 루트 프로젝트 디렉토리의 CLAUDE.md 파일에서 지침을 읽습니다."

JetBrains는 의도된 역할 분담을 다음과 같이 명시하고 있습니다. "도구와 환경 전반에서 가이드를 공유하려면 지침 파일을 사용하고, AI Assistant 내에서 동작을 커스터마이징하려면 Project rules를 사용하세요." 적용 범위의 차이도 중요합니다. 지침 파일은 "선택된 코딩 에이전트에 의해 사용되며 리포지토리와 함께 이동"하는 반면, Project rules는 JetBrains의 표현대로 "IDE에서 구성"됩니다.

결과적으로 하나의 프로젝트에 세 개의 지침 소스가 존재할 수 있으며, 어떤 것이 적용될지는 드롭다운 선택에 달려 있습니다.

Junie의 독립형 CLI는 한 가지 복잡함을 더합니다. 가이드라인을 찾는 자체적인 탐색 순서가 있어 루트 파일보다 .junie/AGENTS.md를 먼저 확인합니다. 이 경로는 rules 폴더를 차단하지 않고 Junie 가이드라인 배치하기에서 다룹니다. 본 가이드는 AI Assistant의 채팅 모드와 IDE 내부의 에이전트에 초점을 맞춥니다.

모든 것을 Project rules로 작성하기. 설정에 규칙 UI가 있고 유형과 파일 패턴도 제공되므로 지침을 작성하는 기본 장소처럼 느껴집니다. 실제로 채팅 모드에서는 기본 장소가 맞습니다. 하지만 에이전트는 지침 파일을 따릅니다.

모든 것을 AGENTS.md에 작성하기. 도구 간에 공유하기에 더 좋고 Junie가 이를 읽습니다. 하지만 채팅 모드는 Project rules를 적용하고, Claude Agent는 CLAUDE.md를 읽습니다.

이전 Claude Code 설정에서 남은 CLAUDE.md 하나만 유지하면서 Junie가 이를 읽을 것이라 가정하기. Junie의 페이지에는 AGENTS.md가 명시되어 있습니다. 팀이 두 형식 사이에서 전환하는 중이라면, CLAUDE.md를 AGENTS.md로 마이그레이션하기에서 주의해야 할 점을 확인해 보세요.

모든 규칙을 Always로 설정하기. Always 규칙은 "모든 채팅 세션에 자동으로 적용"되므로 목록이 짧을 때는 괜찮지만 길어지면 비용이 많이 듭니다. 트리거 모드가 있는 다른 도구들도 동일한 트레이드오프를 겪으며, 이는 모든 Windsurf 규칙에 대한 트리거 모드 선택하기에서 보여주는 바와 같습니다.

채팅이 규칙을 인식했으므로 에이전트도 인식했을 것이라 가정하기. 모드가 다르면 소스도 다릅니다. 유일하게 신뢰할 수 있는 확인 방법은 직접 확인하는 것뿐입니다.

목표는 모든 모드가 따르는 하나의 팀 컨벤션 세트를 만들고, 채팅 전용 조정 사항은 실제로 필요한 곳에만 두는 것입니다.

1단계: 현재 프로젝트에서 각 모드가 무엇을 읽는지 파악하기

프로젝트를 열고 다음 세 가지를 나열해 보세요.

rules 폴더: .aiassistant/rules에 있는 모든 파일과 해당 유형. 어떤 것이 Always이고, 어떤 것이 파일 패턴에 의존하며, 어떤 것이 수동(manual) 또는 모델 결정(model-decided)인지, 그리고 어떤 것이 Off인지 기록해 둡니다.

루트의 AGENTS.md: 존재 여부 및 다루는 내용. JetBrains의 에이전트 지침 페이지에 따르면 일반적인 파일에는 프로젝트 컨텍스트, 개발 규칙, 리포지토리 컨벤션, 공통 작업, 제한 사항 및 완료 정의(definition of done)가 포함됩니다.

루트의 CLAUDE.md: 존재 여부 및 AGENTS.md와 동일한 내용을 담고 있는지 또는 차이가 생겼는지 여부.

그런 다음 비교해 보세요. 한 곳에만 나타나는 내용은 일부 모드가 받지 못할 수 있는 지침입니다. 두 곳에 서로 다른 문구로 나타나는 내용은 나중에 갈등을 유발할 수 있는 충돌 지점입니다.

2단계: 팀 컨벤션은 AGENTS.md에 넣고, Claude Agent를 위해 미러링하며, 채팅 전용 가이드는 rules에 유지하기

모든 모드가 따라야 하는 컨벤션을 루트 AGENTS.md로 이동하세요. 빌드 및 테스트 명령, 아키텍처 경계, 명명 규칙, 수정하지 말아야 할 사항, '완료'의 의미 등이 여기에 해당합니다. 이 파일은 JetBrains가 "도구와 환경 전반에서 가이드를 공유하기 위해" 권장하는 파일이며 리포지토리와 함께 이동하므로 팀원들과 다른 에이전트들도 이를 공유할 수 있습니다.

팀원 중 누군가 Claude Agent를 사용한다면 CLAUDE.md에도 동일한 컨벤션을 제공하세요. 하나의 파일을 단일 진실 공급원(source of truth)으로 선택하고, 다른 파일을 업데이트하는 것도 동일한 변경 작업의 일부로 만드세요. 각 파일의 상단에 어떤 파일이 기준(canonical)인지 짧게 적어두면 나중에 혼란을 크게 줄일 수 있습니다.

그런 다음 rules 폴더를 답변 형식 지정 방법, 선호하는 설명 방식, 대화에서만 의미가 있는 알림 등 진정으로 채팅에 특화된 내용으로만 축소하세요. 남은 각 규칙에 대해 유형을 신중하게 선택하세요. 모든 채팅에 적용되는 소수의 규칙에는 Always를 사용하세요. *.kt로 범위가 지정된 규칙과 같이 언어 또는 폴더별 가이드에는 파일 패턴을 사용하세요. 더 광범위한 규칙에는 적용 시점을 설명하는 명확한 지침과 함께 모델 결정을 사용하세요.

규칙이 현재 AGENTS.md에 있는 내용과 중복된다면 rules 폴더에서 중복을 제거하거나 포인터로 축소하세요. 동일한 컨벤션의 두 복사본은 결국 서로 달라지게 됩니다.

3단계: 단지 하나가 아닌, 각 모드에서 모두 검증하기

채팅 모드에는 내장된 확인 기능이 있습니다. JetBrains는 다음과 같이 설명합니다. "규칙이 적용되었는지 확인하려면 AI Assistant 응답 시작 부분에 있는 첨부 파일 목록을 확장하세요." 특정 규칙을 트리거해야 하는 질문을 던진 다음 확인해 보세요.

에이전트의 경우 직접 물어보세요. Junie와 함께 짧은 작업을 시작하고 시작하기 전에 따르고 있는 프로젝트 컨벤션을 나열해 달라고 요청하세요. Claude Agent에서도 동일하게 수행하세요. 둘 중 하나라도 컨벤션을 놓치고 있다면, 해당 에이전트가 읽는 파일에 그 내용이 누락된 것입니다.

마지막으로 Chat, Junie, Claude Agent에서 동일한 소규모 요청을 실행하고 비교해 보세요. 채팅 모드는 "응답과 제안을 제공하지만 프로젝트에 변경 사항을 자동으로 적용하지는 않는" 반면, 에이전트는 "프로젝트에서 다단계 작업을 수행하고, 여러 파일을 수정하며, 실행 중에 진행 상황을 보고할 수 있기" 때문에 답변 스타일은 다를 것입니다. 하지만 이들이 따르는 컨벤션은 일치해야 합니다.

이 작업을 수행하는 동안 .aiignore도 확인하세요. JetBrains는 "Junie는 기존 .aiignore 파일을 존중하므로 프로젝트에 구성된 파일이 있는 경우 명시적으로 허용하지 않는 한 거기에 나열된 파일이나 디렉토리를 처리하지 않습니다"라고 언급합니다. 제외해야 할 항목이 제대로 제외되어 있고, 에이전트에게 필요한 항목이 제외되어 있지 않은지 확인하세요.

세 개의 파일을 일치시키는 것은 하나의 리포지토리에 속한 컨벤션을 다룹니다. 하지만 일부 컨텍스트는 그보다 더 큽니다. 여러 프로젝트에 걸친 결정 사항, 컨벤션 뒤에 숨겨진 이유, 팀이 어렵게 얻은 교훈, 그리고 JetBrains 외부 도구에서도 필요한 동일한 배경 지식 등이 있습니다. MemoryLake는 팀이 사용하는 모든 어시스턴트가 이 레이어에서 시작할 수 있도록 해당 레이어를 보관하는 곳입니다.

항목은 본인의 언어로 직접 작성합니다. .aiassistant/rules 폴더, 지침 파일 또는 공급업체의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다.

1단계: API 키 생성하기

로그인하고 대시보드에서 키를 생성합니다. 이 키는 에이전트가 어떤 IDE나 모드에서 실행되든 작성된 항목을 읽을 수 있도록 해줍니다.

2단계: 첫 번째 메모리 업로드하기

1단계에서 파악한, 단일 리포지토리 파일에 담을 수 없는 내용부터 시작하세요. 프로젝트 간 결정 사항과 컨벤션의 배경 이유가 이에 해당합니다. 항목당 하나의 결정을 작성하고 이유를 첨부하세요.

3단계: AI 및 에이전트 연결하기

팀이 사용하는 어시스턴트와 코딩 에이전트를 연결하세요. 그러면 AGENTS.md나 rules 폴더를 읽지 못하는 도구를 포함하여, 동일한 배경 지식을 AGENTS.md와 함께 사용할 수 있게 됩니다.

첫 번째 차이점은 모드를 전환해도 규칙이 바뀌지 않는다는 것입니다. 컨벤션이 AGENTS.md와 CLAUDE.md에 위치하고 rules 폴더에는 채팅 전용 가이드만 남게 되면, Chat에서 Junie로, 다시 Claude Agent로 이동하더라도 동일한 표준이 계속 적용됩니다.

두 번째는 리포지토리가 단일 진실 공급원이 된다는 점입니다. 지침 파일은 코드와 함께 이동하므로 새로운 팀원, 다른 IDE 또는 다른 에이전트도 동일한 컨벤션을 적용받게 됩니다. 이는 CLAUDE.md가 없을 때 Claude Code가 AGENTS.md를 읽는 현상 뒤에 숨겨진 원리와 같습니다. 즉, 공유 파일이 도구 전용 설정보다 우선합니다.

세 번째는 "에이전트가 우리 규칙을 무시했다"는 문제를 진단할 수 있게 된다는 점입니다. 어떤 모드가 어떤 파일을 읽는지 파악하고 있으면 지침이 누락되었는지, 오래되었는지, 아니면 단순히 로드되지 않았는지 알 수 있습니다. 이 문제의 더 광범위한 버전은 AI 에이전트가 내가 작성한 지침 파일을 무시하는 이유에서 다룹니다.

네 번째는 소리 없는 충돌이 줄어든다는 점입니다. 두 파일에 동일한 컨벤션의 복사본이 존재하면 서로 달라지게 됩니다. 하나의 기준 파일을 두고 다른 파일이 이를 미러링하도록 하면 불일치를 명확히 드러낼 수 있습니다.

Project rules는 채팅 설정으로 취급하세요. JetBrains는 이 규칙들이 "AI Assistant 채팅 모드에서만 적용된다"고 명시하고 있습니다.

팀 컨벤션은 루트 AGENTS.md에 유지하세요. Junie가 이를 읽으며, 리포지토리와 함께 이동합니다.

누군가 Claude Agent를 사용한다면 CLAUDE.md에 컨벤션을 미러링하세요. Claude Agent는 프로젝트 루트에서 CLAUDE.md를 읽습니다.

하나의 파일을 기준(canonical)으로 지정하세요. 동일한 변경 작업 내에서 미러링된 파일도 함께 업데이트하세요.

규칙 유형을 신중하게 선택하세요. Always 규칙은 최소한으로 유지하고, 나머지는 파일 패턴과 모델 결정을 사용하세요.

채팅에서 첨부 파일 목록을 확인하세요. 응답에 어떤 규칙이 적용되었는지 보여줍니다.

에이전트에게 컨벤션을 말해달라고 요청하세요. 에이전트가 실제로 무엇을 읽었는지 확인하는 가장 빠른 방법입니다. 다른 도구들도 어떤 Tabnine 가이드라인이 적용 중인지 확인하기와 같이 유사한 확인 방법을 제공하며, 동일한 원칙을 통해 Cursor가 프로젝트 규칙을 잊어버리는 현상을 방지할 수 있습니다.

JetBrains AI Assistant는 각 모드가 지침을 어디서 가져오는지 명확하게 밝히고 있습니다. 채팅 모드는 .aiassistant/rules에서 Project rules를 적용합니다. Junie는 루트 AGENTS.md를 읽습니다. Claude Agent는 루트 CLAUDE.md를 읽습니다. 문서에서는 역할 분담 방법까지 명시하고 있습니다. 도구와 환경 전반에서 가이드를 공유하려면 지침 파일을 사용하고, AI Assistant 내에서 동작을 커스터마이징하려면 Project rules를 사용하라는 것입니다.

위험 요인은 하나의 드롭다운 뒤에서 이 세 가지 소스가 서로 달라질 수 있다는 점입니다. 각 모드가 무엇을 읽는지 파악하고, 팀 컨벤션을 AGENTS.md에 넣고 Claude Agent를 위해 미러링하며, 채팅 전용 가이드는 신중하게 선택한 유형과 함께 rules에 유지하고, 모든 모드에서 검증하세요.

단일 리포지토리보다 더 큰 컨텍스트는 모든 도구가 접근할 수 있는 레이어에 보관하세요. 그러면 채팅과 에이전트 간의 전환이 서로 다른 규칙 세트 간의 전환을 의미하지 않게 될 것입니다.