규칙 폴더 누락 없이 Junie 가이드라인을 배치하는 방법 (2026년 가이드)

먼저 가이드라인의 목적부터 살펴보겠습니다. JetBrains는 이를 상시 지침으로 설명합니다. "가이드라인을 통해 에이전트에게 지속적이고 재사용 가능한 컨텍스트를 제공할 수 있습니다. Junie CLI는 AGENTS.md 파일에서 가이드라인을 읽어 에이전트가 수행하는 모든 작업에 이 컨텍스트를 추가합니다."

다음은 공식 문서에서 인용한 탐색 순서입니다. "Junie CLI가 작업을 시작할 때 다음 순서로 가이드라인을 찾습니다." 첫째, "프로젝트 루트의 .junie/AGENTS.md 파일." 둘째, "프로젝트 루트의 AGENTS.md 파일(존재하는 경우 .junie/playbook.md 및 모든 .junie/rules/*.md 파일과 결합됨)." 셋째, ".junie/guidelines.md 파일 또는 .junie/guidelines/ 폴더 – Junie의 레거시 가이드라인 형식(여전히 지원됨)."

이 세 줄을 줄글이 아닌 표로 읽어보면 비대칭성이 명확히 드러납니다. .junie/playbook.md 및 .junie/rules/*.md와의 결합은 오직 두 번째 경로에만 명시되어 있습니다. 첫 번째 경로는 단일 파일만 지정하며, 세 번째 경로는 레거시 위치를 가리킵니다. 규칙 폴더와 플레이북이 있는 경우, 이를 함께 불러오는 경로는 메인 가이드라인이 프로젝트 루트에 AGENTS.md로 존재하는 경로이며, .junie/ 내부의 경로가 아닙니다.

대부분의 사용자가 이 문제에 직면하는 경로를 생각하면 이는 매우 중요합니다. 처음 프로젝트를 열 때의 가져오기 기능 역시 문서에 다음과 같이 설명되어 있습니다. "Junie CLI는 프로젝트를 처음 열 때 다른 AI 에이전트의 가이드라인이나 메모리 파일이 있는지 확인합니다. 이러한 파일이 감지되면 지침을 .junie/AGENTS.md로 가져오도록 제안합니다." 이 제안은 다른 설정이 없는 프로젝트에는 합리적입니다. 하지만 이미 .junie/rules/ 폴더가 있는 프로젝트의 경우, 이 제안을 수락하면 문서상 해당 파일들이 결합된다고 설명되어 있지 않은 첫 번째 경로로 자동으로 이동하게 됩니다.

이 과정에서 어떠한 오류도 발생하지 않습니다. Junie는 여전히 가이드라인을 인식하고, 이를 따르며, 훌륭하게 작업을 수행합니다. 다만 구조적인 이유로 분리해 둔 규칙들이 더 이상 지침에 포함되지 않을 뿐이며, 이를 알아차릴 수 있는 유일한 방법은 탐색 순서 목록을 직접 확인하는 것뿐입니다.

두 곳에 동일한 콘텐츠 배치하기. 규칙 폴더의 내용을 .junie/AGENTS.md에 복사하는 것은 콘텐츠가 전달된다는 좁은 의미에서는 작동합니다. 하지만 이는 향후 수정할 때마다 두 곳을 모두 업데이트해야 함을 의미하며, 결국 한쪽은 최신 상태를 잃게 됩니다.

모든 것을 레거시 위치로 이동하기. .junie/guidelines.md 및 .junie/guidelines/는 "Junie의 레거시 가이드라인 형식(여전히 지원됨)"으로 설명되어 있지만, 단순히 지원된다는 것이 공식 문서가 권장하는 표준 경로라는 뜻은 아닙니다. 이는 탐색 순서에서 세 번째에 위치하며, 사용자들이 "junie guidelines"를 검색하다가 오래된 자료를 발견하고 실수로 선택하게 되는 경로입니다.

글로벌 파일이 공백을 메워줄 것이라 가정하기. 글로벌 파일은 고유한 역할이 있습니다. "Junie CLI는 ~/.junie/AGENTS.md의 글로벌 가이드라인도 지원하며," Windows의 경우 "글로벌 가이드라인 경로는 %USERPROFILE%\.junie\AGENTS.md입니다." 문서에서는 이 파일의 용도를 명확히 규정하고 있습니다. "이 파일을 사용하면 모든 프로젝트에 중복해서 적용할 필요 없이, 개인적인 선호도나 조직 전반의 규칙을 정의할 수 있습니다." 개인적인 선호도가 프로젝트 전용 규칙 폴더를 대체할 수는 없습니다.

안전을 위해 프로젝트 규칙을 글로벌 파일에 중복 작성하기. Junie는 단순 중복의 경우 정상적으로 처리합니다. "글로벌 가이드라인과 프로젝트 가이드라인의 내용이 동일한 경우, Junie는 자동으로 중복을 제거하고 한 번만 사용합니다." 하지만 진짜 위험은 '거의 유사한' 중복 내용이며, 이는 병합되지 않고 우선순위에 따라 한쪽이 무시되는 방식으로 해결됩니다.

문제를 메모리 탓으로 돌리기. 재사용 가능한 기술과 지침 파일은 "어떻게 작업해야 하는가"에 대한 답을 제공하며, 이것과 프로젝트 기록 간의 격차는 완전히 별개의 문제입니다. 이에 대한 자세한 내용은 에이전트 기술이 메모리가 아닌 이유에서 다루고 있습니다.

1단계: 세 가지 경로를 인벤토리화하고 프로젝트가 어떤 경로에 있는지 확인하기

네 가지 요소를 확인하세요: .junie/AGENTS.md, 프로젝트 루트의 AGENTS.md, .junie/playbook.md, 그리고 마크다운 파일이 포함된 .junie/rules/ 폴더입니다. 그런 다음 레거시 쌍인 .junie/guidelines.md 또는 .junie/guidelines/ 폴더도 확인하세요.

찾은 파일들을 탐색 순서 목록과 대조해 봅니다. .junie/AGENTS.md가 있다면 첫 번째 경로에 있는 것입니다. 프로젝트 루트에 AGENTS.md가 있고 .junie/AGENTS.md가 없다면 두 번째 경로에 있는 것이며, 공식 문서에 따르면 이 경로는 플레이북과 모든 .junie/rules/*.md 파일이 "존재하는 경우" 결합된다고 설명되어 있습니다. 레거시 파일만 있는 경우 세 번째 경로에 있는 것입니다.

가장 주의 깊게 살펴봐야 할 경우는 이 중 여러 개가 동시에 존재하는 경우입니다. 보통 처음 열었을 때 가져오기 기능으로 생성된 .junie/AGENTS.md와 그 이전부터 존재하던 .junie/rules/ 폴더, 그리고 몇 달 동안 아무도 열어보지 않은 레거시 guidelines.md가 함께 있는 경우입니다. 이는 프로젝트가 잘못된 것이 아니라, 탐색 순서를 다시 확인하기 전에 파일들이 빠르게 누적되었을 뿐입니다.

2단계: 나머지 설정들을 함께 불러오는 경로에 메인 지침 배치하기

인벤토리를 확인하고 나면 결정은 간단해집니다.

모든 작업에 적용하고 싶은 .junie/rules/ 폴더나 .junie/playbook.md가 있다면, 메인 가이드라인을 프로젝트 루트의 AGENTS.md에 배치하세요. 이 경로가 공식 문서에서 이 파일들을 결합한다고 설명하는 경로입니다. 여기에는 언급할 만한 부가적인 이점도 있습니다. 루트 AGENTS.md는 다른 에이전트들도 탐색하는 도구 간 공통 파일명이므로, 이 포맷의 자체 설명인 "코딩 에이전트를 안내하기 위한 개방형 파일 포맷"이라는 취지에 맞게 하나의 파일로 Junie와 다른 모든 도구를 동시에 지원할 수 있습니다.

규칙 폴더와 플레이북이 없다면 .junie/AGENTS.md를 사용하는 것이 좋으며, 루트 디렉토리를 깔끔하게 유지할 수 있습니다. 다만 이 선택을 어딘가에 기록해 두세요. 나중에 누군가 규칙 폴더를 추가하는 순간, 해당 경로가 설정과 일치하지 않게 되기 때문입니다.

레거시 파일을 사용 중이라면 위의 두 경로 중 적합한 곳으로 콘텐츠를 이동하고, 가이드라인이 현재 어디에 위치해 있는지 저장소에 짧은 메모를 남겨두세요. 아무런 설명 없이 비워진 .junie/guidelines.md 파일은 다음 작업자에게 누군가 실수로 삭제한 파일처럼 보일 수 있습니다.

가이드라인 자체는 JetBrains가 예시로 제시한 카테고리에 맞춰 작성하세요. 이 카테고리들은 에이전트가 실제로 자주 실수하는 질문들과 매핑됩니다: 에이전트가 작업을 시작하기 전에 반드시 따라야 할 가장 중요한 규칙들을 담은 "빠른 시작 체크리스트(Quick-start checklist)", 설치, 린트, 테스트, 빌드 및 개발 서버 항목을 표로 정리한 "로컬 개발 명령(Local development commands)", "기능 개발 및 의사 결정(Feature development and decision making)", "UI 및 아키텍처(UI and architecture)", "보안 및 데이터 처리(Security and data handling)", "테스트 및 기여(Testing and contribution)", 그리고 에이전트가 절대 해서는 안 되는 명시적 금지 사항을 설명하는 "에이전트 비목표(Non-goals for agents)" 섹션입니다. 마지막 카테고리는 사람들이 자주 생략했다가 나중에 후회하는 부분입니다. 이 정보를 제공하는 목적은 명확합니다. "Junie가 사용자의 환경을 더 잘 이해하고, 호환되지 않는 라이브러리를 피하며, 프로젝트의 특정 아키텍처 패턴을 따르도록 돕기 위함"입니다.

3단계: 글로벌 계층을 개인 범위로 설정하고 우선순위에 맡기기

이제 글로벌 파일을 의도에 맞게 배치합니다. ~/.junie/AGENTS.md에는 프로젝트가 아닌 사용자 개인에게 해당하는 내용을 담아야 합니다. 예를 들어 커밋 메시지 작성 스타일, 모든 프로젝트에 적용하고 싶은 코드 리뷰 습관, 여러 저장소에 걸쳐 적용되는 조직 전반의 컨벤션 등이 이에 해당합니다.

두 계층 간의 상호작용은 세 가지 케이스로 문서화되어 있으며, 다행히도 매우 직관적입니다. "글로벌 또는 프로젝트 가이드라인 중 하나만 존재하는 경우, Junie는 사용 가능한 것을 사용하며 추가적인 주석은 추가되지 않습니다." "글로벌 및 프로젝트 가이드라인이 모두 존재하는 경우, Junie는 두 가이드라인을 모두 포함하고 명확하게 표시합니다. 충돌이 발생할 경우 프로젝트 수준의 가이드라인이 항상 글로벌 가이드라인보다 우선합니다." 그리고 "글로벌 가이드라인과 프로젝트 가이드라인의 내용이 동일한 경우, Junie는 자동으로 중복을 제거하고 한 번만 사용합니다."

여기서 두 가지 실질적인 결론을 얻을 수 있습니다. 첫째, 방어적인 중복 작성이 필요하지 않습니다. 동일한 내용은 중복 제거되고, 충돌하는 내용은 프로젝트 기준으로 해결됩니다. 둘째, '거의 유사한' 중복 내용에서 예기치 못한 문제가 발생할 수 있습니다. 글로벌 파일의 "항상 통합 테스트 추가"라는 문구와 프로젝트 파일의 "기능 개발에는 단위 테스트만 수행"이라는 문구는 동일하지 않으므로 두 내용이 모두 포함되며 프로젝트 기준이 우선하게 됩니다. 이는 올바른 결과이지만, 직접 찾아보지 않으면 알기 어렵습니다. 따라서 두 계층의 범위를 명확히 다르게 유지하는 것이 우선순위 규칙을 혼란이 아닌 유용한 기능으로 만드는 방법입니다. 이러한 원칙은 Copilot의 지침 파일 순서 지정 방식과 같이 레이어화된 지침 파일을 다루는 모든 곳에서 유용하게 적용됩니다.

가이드라인은 모든 작업에 포함되는 지침이므로 짧게 유지되어야 합니다. 즉, 가이드라인이 제정된 배경과 논리는 다른 곳에 보관되어야 합니다. 왜 레거시 패키지를 사용하지 않는지, 어떤 라이브러리를 어떤 근거로 거부했는지, 명명 규칙이 무엇을 보호하고 있는지 등은 에이전트가 매번 읽어야 하는 파일에 포함될 필요가 없으며, 가이드라인의 유효성을 판단할 때만 필요합니다. MemoryLake에 이러한 기록을 의도적으로 작성해 두면, 지침 파일의 크기를 늘리지 않고도 필요할 때 기록을 검색할 수 있습니다. 기록은 본인의 언어로 직접 작성하면 됩니다. .junie 디렉토리나 다른 도구의 파일에서 데이터를 읽거나, 쓰거나, 삭제하지 않습니다.

1단계: API 키 생성하기

로그인한 후 워크스페이스 설정에서 API 키를 생성합니다. 이 키는 에이전트와 연동 도구들이 사용하는 인증 정보이므로, 데이터를 이동하기 전에 먼저 생성해 두세요.

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

가이드라인의 전제가 되는 결정사항들부터 시작하세요: 기술 스택이 이렇게 구성된 이유, 어떤 접근 방식이 탈락했고 그 이유는 무엇인지, "비목표" 섹션이 실제로 무엇을 방지하고자 하는지 등을 작성합니다. 각 내용을 독립적으로 검색할 수 있도록 짧고 독립적인 노트로 작성하세요.

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

사용 중인 어시스턴트와 에이전트를 연결합니다. 이렇게 하면 특정 도구가 지침 파일을 찾는 경로와 관계없이, 가이드라인의 배경 논리가 항상 함께 연동됩니다.

처음 열었을 때의 가져오기 기능이 기본 설정이 아닌 선택 사항이 됩니다. 다른 에이전트의 파일을 .junie/AGENTS.md로 통합하겠다는 Junie의 제안은 새로운 프로젝트에서는 매우 유용합니다. 하지만 규칙 폴더가 있는 프로젝트에서는 잠시 멈추고 어떤 경로를 선택할지 검토해야 하는 시점입니다.

규칙 폴더가 단순한 정리 습관을 넘어 실제 구조적인 역할을 하게 됩니다. 지침을 .junie/rules/*.md로 분할하는 것은 해당 파일들을 결합하도록 문서화된 경로를 사용할 때만 효과가 있습니다. 그렇지 않으면 이 분할은 기능적이 아닌 단순 조직적인 정리에 불과합니다. 이는 Windsurf와 Devin 규칙 폴더를 병합하는 방법에서 다룬 것처럼, 흩어진 규칙 디렉토리를 의도적으로 병합해야 하는 이유와 같습니다.

도구 간 공유에 대한 명확한 해답을 얻을 수 있습니다. 루트 AGENTS.md 경로를 선택하면 Junie가 읽고 다른 에이전트도 인식하는 단일 파일을 갖게 되므로, Junie 전용 파일과 다른 도구용 복사본을 따로 관리하는 것보다 훨씬 유리합니다.

"에이전트가 실제로 어떤 지침을 따르고 있는가"에 대한 검토 시간이 단축됩니다. 경로가 명확히 정의되어 있으면, 복잡한 조사 없이 경로와 탐색 순서 목록만으로 답을 얻을 수 있습니다. 이는 어떤 Tabnine 가이드라인이 적용 중인지 확인하는 방법에서 설명한 변화와 동일합니다.

가이드라인 자체에 경로를 명시하세요. 상단에 "가이드라인은 프로젝트 루트의 AGENTS.md에 위치하며, .junie/rules의 규칙들이 이와 결합됩니다"라는 한 줄을 추가하면, 다음 작업자가 탐색 순서를 다시 추적할 필요가 없습니다.

글로벌 파일은 개인적인 내용으로 유지하세요. 만약 ~/.junie/AGENTS.md에 작성된 내용이 다른 사람의 저장소에 노출되었을 때 부끄러운 내용이라면, 해당 내용은 프로젝트 파일에 작성해야 합니다.

계층 간에 '거의 유사한' 중복 내용을 의도적으로 피하세요. 완전히 동일한 내용은 중복 제거되지만, 거의 유사한 내용은 두 번 포함되어 우선순위에 따라 해결되므로 직관적으로 파악하기 어렵습니다.

금지 사항을 명문화하세요. "에이전트 비목표(Non-goals for agents)" 카테고리가 존재하는 이유는 에이전트가 저지르는 가장 비용이 많이 드는 실수가 '불완전하게 수행한 일'이 아니라 '애초에 하지 말았어야 할 일'을 한 경우이기 때문입니다.

구조를 변경한 후에는 탐색 순서를 다시 확인하세요. 파일을 .junie/와 프로젝트 루트 사이로 이동하면 적용되는 경로가 자동으로 변경되며, 이 변경은 아무런 알림 없이 조용히 일어납니다.

직접 작성하지 않고 자동 생성된 가이드라인은 다시 검토하세요. 가져오거나 추출된 규칙은 유용한 시작점일 뿐 최종 상태로는 적합하지 않습니다. 이에 대한 논의는 Qodo에서 추출한 규칙을 에이전트에 적용하는 방법에서 확인할 수 있습니다.

Junie는 세 가지 경로를 통해 가이드라인을 탐색하며, 공식 문서에 따르면 .junie/playbook.md 및 모든 .junie/rules/*.md 파일은 오직 프로젝트 루트의 AGENTS.md 경로에만 결합됩니다. .junie/ 내부의 경로는 단일 파일만 지정하며, 레거시 쌍은 핵심 경로가 아닌 하위 호환을 위해 지원되는 경로입니다.

따라서 배치 결정은 매우 간단합니다. 플레이북이나 규칙 폴더를 관리하고 있다면, 메인 지침을 루트의 AGENTS.md에 배치하여 문서에 명시된 결합 기능이 정상적으로 작동하도록 하세요. 그렇지 않다면 .junie/AGENTS.md에 유지하고 그 선택을 기록해 두세요. 그런 다음 글로벌 파일은 개인 범위로 설정하고 우선순위 규칙을 신뢰하며, 가이드라인의 배경이 되는 논리는 에이전트가 매 작업마다 읽어야 하는 파일 외부의 별도 공간에 보관하세요.