Kilo Code의 규칙 파일을 정렬된 하나의 목록으로 통합하는 방법 (2026년 가이드)

Kilo의 현재 규칙 모델은 명시적이며 그 자체로는 잘 작동합니다. 프로젝트 규칙은 "프로젝트의 kilo.jsonc 파일에 있는 instructions 키를 통해 구성"되며, "각 항목은 파일 경로 또는 글롭(glob) 패턴을 가리킵니다." 글로벌 규칙은 일반적으로 ~/.config/kilo/kilo.jsonc에 있는 글로벌 구성의 동일한 키를 사용합니다.

로드 순서는 배열을 따릅니다. "규칙은 kilo.jsonc의 instructions 배열에 나타나는 순서대로 로드"되며, 먼저 글로벌 구성이 로드된 다음 프로젝트 구성이 로드됩니다. 우선순위는 반대로 적용되어 "충돌하는 지침의 경우 프로젝트 수준 지침이 글로벌 지침보다 우선합니다." "JSONC는 // 주석을 지원"하므로 규칙을 삭제하지 않고 비활성화해 둘 수도 있습니다.

이것이 매니페스트이며, 매니페스트는 좋은 디자인입니다. 아래의 모든 내용은 이 매니페스트의 바깥에 존재하는 것들입니다.

글롭(Glob) 항목은 순서 지정을 포기합니다. 문서에서는 다음과 같이 직접적으로 설명합니다. "글롭 패턴과 일치하는 파일은 파일 시스템 순서대로 로드됩니다." 배열 위치가 유일한 우선순위 제어 수단이므로, .kilo/rules/*.md와 같은 단일 항목은 일치하는 모든 파일에 대해 정렬된 목록을 정렬되지 않은 목록으로 변환합니다. 문서의 예시 구성은 특정 파일과 동일한 디렉터리를 다루는 글롭을 함께 배치하는데, 이는 편리해 보이지만 어떤 규칙이 우선하는지 지정할 수 있는 기능을 조용히 제거합니다.

레거시 디렉터리는 목록에 없어도 로드됩니다. 이 부분이 사람들의 시간을 며칠씩 낭비하게 만드는 원인입니다:

"프로젝트에 .kilocode/rules/ 디렉터리가 존재하는 경우, 하위 호환성을 위해 해당 콘텐츠가 자동으로 포함됩니다. 완전히 마이그레이션하려면 규칙 파일을 이동하고 kilo.jsonc에서 참조하세요."

이것을 단순한 참고 사항이 아니라 실제 동작으로 이해해야 합니다. Kilo는 디렉터리 이름을 .kilocode/에서 .kilo/로 변경했지만, 이전 디렉터리는 여전히 자동으로 로드됩니다. 배열에 항목이 없고 우선순위 표에 위치도 지정되지 않은 채로 말이죠. 이전 버전을 거쳐온 저장소에는 병렬로 실행되는 두 번째 규칙 트리가 존재하며, 여러분이 읽고 있는 kilo.jsonc에는 이에 대한 언급이 없습니다.

디렉터리별 AGENTS.md 파일은 파일 액세스 시 주입됩니다. Kilo는 하위 디렉터리의 AGENTS.md를 지원하며, 그 메커니즘을 정확히 설명합니다. "디렉터리별 AGENTS.md 파일은 에이전트가 해당 디렉터리의 파일을 읽을 때 동적으로 로드되며, 세션 시작 시 미리 로드되지 않습니다. 에이전트가 src/backend/에 있는 파일을 읽을 때 해당 AGENTS.md가 발견되고 그 내용이 <system-reminder> 태그로 대화에 주입됩니다."

이는 좋은 기능입니다. 하지만 이는 에이전트가 어떤 파일을 열었는지에 따라 대화 중간에 유효 지침 세트가 변경됨을 의미하며, 루트 파일만 다루는 우선순위 표는 이러한 주입이 어디에 위치하는지 설명하지 못합니다.

루트 AGENTS.md는 비활성화할 수 없습니다. "AGENTS.md 자체는 개별적으로 비활성화할 수 없으며, 존재하는 경우 항상 로드됩니다. 해당 지침을 재정의하려면 instructions 구성 키나 에이전트 전용 프롬프트와 같이 우선순위가 더 높은 소스를 사용하세요." 또한 AGENTS.md와 AGENT.md는 모두 "Kilo Code에서 쓰기 보호된 파일"이므로 "AI 에이전트는 명시적인 사용자 승인 없이 이 파일을 수정할 수 없습니다." 이는 안전에 좋으며, 에이전트에게 정리를 요청하기 전에 알아두어야 할 사항입니다.

파일명은 사람들이 놀랄 정도로 대소문자를 구분합니다. Kilo는 다음과 같이 경고합니다. "파일명은 소문자(agents.md)가 아닌 대문자(AGENTS.md)여야 합니다." 우선순위에 따라 지원되는 이름은 AGENTS.md 다음으로 AGENT.md입니다. 다른 에이전트들은 이 부분에서 다를 수 있으며(일부는 두 대소문자를 동일하게 취급함), 따라서 공유 저장소에서는 대문자로 표준화해야 합니다.

이전 memory bank가 여전히 활성화되어 있습니다. Kilo의 지원 중단 공지에서는 "Kilo Code memory bank 기능은 AGENTS.md를 위해 지원 중단되었습니다"라고 밝히면서도 바로 이어서 "기존 memory bank 규칙은 계속 작동합니다"라고 덧붙입니다. 주의 깊게 봐야 할 부분은 상태 표시기입니다. "[Memory Bank: Active] 및 [Memory Bank: Missing]과 같은 레거시 Memory Bank 상태 표시기는 여전히 나타날 수 있지만, 모든 클라이언트나 모드에서 보장되지는 않습니다." 이 경고는 실제로 유효합니다. 배지는 지원되는 클라이언트 및 모드로 제한되므로, 이를 정답이 아닌 힌트로 취급하고 실제 동작을 통해 검증해야 합니다.

이것들을 합치면 배열 외에 5개의 소스가 더 존재하게 됩니다. 이것이 대부분의 "규칙이 적용되지 않습니다"라는 보고의 실제 원인이며, 모델의 문제라기보다는 구성의 문제입니다. 이는 왜 에이전트가 지침 파일을 무시하는가에서 다루었던 차이점입니다.

kilo.jsonc를 읽고 신뢰하기. 가장 흔한 접근 방식이지만, 구조적으로 잘못되었습니다. 배열은 여러 입력 중 하나일 뿐이며, 보이지 않는 두 가지 입력(레거시 디렉터리와 디렉터리별 주입)은 구성 파일이 보여줄 수 없는 바로 그 부분입니다.

모든 것을 캡처하기 위해 광범위한 글롭 추가하기. ".kilo/rules/**/*.md"는 누락되는 것이 없음을 보장하지만, 글롭 일치가 "파일 시스템 순서대로" 로드되기 때문에 전체 세트에 대한 순서 지정을 포기하게 만듭니다. 불완전한 목록을 정렬되지 않은 목록과 맞바꾼 셈입니다.

.kilocode/를 즉시 삭제하기. 올바른 목적지이지만 위험한 첫 단계입니다. 해당 파일들은 아마도 몇 달 동안 유효했을 것이며, 여러분이 의존하는 동작 중 일부는 이 파일들에서 비롯되었을 수 있습니다. 로드 경로에서 벗어난 곳으로 이동하여 검토한 다음 결정하세요.

모든 것을 AGENTS.md에 넣기. 우선순위 3위이며, 비활성화할 수 없고, 다른 도구들이 읽는 형식입니다. 하지만 프런트매터(frontmatter)나 조건부 로드를 지원하지 않으므로, 단일 루트 파일이 모든 작업에 대해 항상 켜져 있는 컨텍스트가 됩니다. 항상 켜져 있는 예산 문제는 코딩 에이전트가 실제로 읽는 것에서 살펴본 것과 동일합니다.

규칙을 스킬로 전환하기. 스킬은 필요에 따라 로드되므로 자유로운 조건부 로드처럼 들립니다. Kilo는 선택이 어떻게 작동하는지 매우 솔직하게 밝히고 있습니다. "에이전트(LLM)는 스킬의 description 필드를 기반으로 스킬 사용 여부를 결정합니다. 키워드 매칭이나 의미론적 검색은 없습니다. 에이전트는 사용 가능한 모든 스킬 설명에 대해 요청을 평가하고 하나가 '명확하고 모호하지 않게 적용되는지' 판단합니다." 항상 유지되어야 하는 규칙은 관련성 판단에서 살아남지 못합니다. 이것이 바로 스킬이 규칙의 대체재가 될 수 없고, 메모리의 대체재도 될 수 없는 이유입니다. 이에 대해서는 왜 에이전트 스킬이 메모리가 아닌가에서 논의한 바 있습니다.

세 단계입니다. 세 번째 단계는 사람들이 흔히 건너뛰는 단계이지만, 보이지 않는 소스를 잡아낼 수 있는 유일한 방법입니다.

1단계: Kilo가 로드할 수 있는 모든 경로 인벤토리 작성

무엇이든 변경하기 전에 저장소를 탐색하고 다음 각 위치에 무엇이 존재하는지 기록하세요.

선언된 세트부터 시작하세요. 프로젝트 kilo.jsonc의 instructions 배열과 ~/.config/kilo/kilo.jsonc에 있는 동일한 키입니다. 모든 글롭을 파일 시스템 순서대로 일치하는 실제 파일 이름으로 직접 확장하여 Kilo가 사용할 순서를 확인하세요.

그 다음은 선언되지 않은 세트입니다. 프로젝트 내 어디든 .kilocode/rules/가 있는지 확인하세요. 공지사항에 "디렉터리들(directories)"이라고 복수형으로 명시되어 있으므로 하위 디렉터리도 확인해야 합니다. .kilo/rules/memory-bank/ 및 레거시 .kilocode/rules/memory-bank/를 확인하세요. 루트뿐만 아니라 트리 내의 모든 AGENTS.md 및 AGENT.md를 찾고, 각각이 어떤 디렉터리를 제어하는지 기록하세요. CLI를 사용하는 경우, "다른 도구와의 호환성을 위해" 읽히는 .claude/ 및 .agents/도 확인하세요. 외부 스킬 디렉터리를 제외하고 싶다면 KILO_DISABLE_EXTERNAL_SKILLS 환경 변수를 사용하여 끌 수 있습니다.

이제 목록이 완성되었습니다. 이 목록은 kilo.jsonc보다 길 것이며, 그 차이가 바로 여러분이 실행 중인지 몰랐던 부분입니다.

2단계: 목록을 선언되고 정렬된 하나의 배열로 축소

각 항목의 대상을 결정한 다음, 배열이 실제 상황과 일치하도록 만드세요.

항상 적용되어야 하는 저장소 전반의 규칙은 루트 AGENTS.md로 이동합니다. 이는 비활성화할 수 없고, 다른 도구들이 읽으며, 에이전트의 실수로 인한 수정을 방지하기 위해 쓰기 보호되어 있습니다. 항상 켜져 있으므로 짧게 유지하세요.

명시적인 순서 지정이 필요한 규칙은 개별 파일로 .kilo/rules/에 들어가며, 각각 프로젝트 instructions 배열에 전체 경로로 나열됩니다. 원하는 순서대로 한 줄에 하나씩 나열하세요. 여기서는 글롭을 사용하지 마세요. 글롭은 순서 지정을 무효화하는 주범입니다.

디렉터리별 지침은 디렉터리별 AGENTS.md 파일로 이동합니다. 이는 에이전트가 작업 중인 위치를 기준으로 콘텐츠를 로드하기 위해 Kilo가 문서화한 유일한 메커니즘입니다.

개인적인 선호 사항은 글로벌 kilo.jsonc 배열로 이동합니다. 글로벌은 프로젝트 배열과 루트 AGENTS.md보다 아래인 우선순위 4위에 위치한다는 점을 기억하세요.

그런 다음 레거시 경로를 비우세요. .kilocode/rules/ 콘텐츠를 로드 경로 외부(예: docs/ 하위 디렉터리)로 이동하고, 실제로 원하는 내용만 배열의 명시적 경로를 통해 다시 추가하세요. memory bank도 마찬가지입니다. Kilo의 자체 마이그레이션 지침은 ".kilo/rules/memory-bank/ (또는 레거시 .kilocode/rules/memory-bank/)의 콘텐츠를 검토"하고 "해당 콘텐츠를 프로젝트의 AGENTS.md 파일로 이동"하는 것입니다. 여전히 유효한 부분만 이동하고, 이전 버전의 코드베이스를 설명하는 부분은 삭제하세요.

3단계: 읽기가 아닌 모순을 통해 목록 증명

구성 파일은 언급되지 않은 파일에 대해 스스로를 검증할 수 없습니다. 따라서 경계를 직접 테스트하세요.

의도적으로 특이하고 무해한 지침을 의도한 가장 낮은 우선순위 소스의 맨 아래에 배치하세요. 예를 들어 평소에는 절대 사용하지 않을 명확한 변수 명명 규칙 같은 것입니다. 에이전트에게 작은 함수를 작성하도록 요청해 보세요. 해당 규칙이 나타나면 소스가 로드되고 있으며 그 위의 어떤 것도 이를 모순하지 않는 것입니다.

그런 다음 테스트를 뒤집어 보세요. 로드되지 않고 있다고 믿는 소스(비우기 전의 레거시 .kilocode/rules/ 경로)에 직접적으로 모순되는 지침을 넣으세요. 다시 요청해 보세요. 모순되는 버전이 이긴다면, 해당 경로가 활성화되어 있으며 권위 있다고 생각했던 것보다 우선순위가 높은 것입니다. Kilo는 지침 소스 간의 충돌을 표면화하지 않으므로, 모순 테스트가 해결 과정을 확인할 수 있는 유일한 방법입니다. 일반적인 패턴은 메모리 충돌 감지에서 다룹니다.

자체 AGENTS.md가 있는 하위 디렉터리에서 한 번 더 반복하세요. 디렉터리별 파일은 에이전트가 해당 디렉터리의 파일을 읽을 때만 주입되기 때문입니다. 저장소 루트에서의 테스트 실행은 이를 실행하지 않습니다.

통합을 통해 정렬된 목록을 얻을 수 있습니다. 하지만 어떤 줄이 왜 그곳에 있는지 그 이유는 알려주지 않습니다. 기록된 이유가 없는 규칙은 다음 정리 작업 때 가장 먼저 삭제되는 대상이 됩니다.

MemoryLake는 그 이유를 보관합니다. 어떤 규칙이 어떤 사건 때문에 존재하는지, 무엇을 시도했다가 거부되었는지, 어떤 제약 조건이 코드가 아닌 사람에게서 비롯되었는지 등을 기록합니다. 이는 instructions 배열 외부에 존재하므로 재정렬, 이름 변경, 디렉터리 마이그레이션 중에도 유실되지 않습니다. 여기서 시작하세요.

1단계: API 키 생성

저장소를 위한 워크스페이스를 생성하고 API 키를 생성하세요. 다음 도구 마이그레이션이 재작성이 아닌 구성 변경이 되도록 Kilo가 아닌 저장소로 범위를 제한하세요.

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

통합의 1단계 동안, 로드되고 있는지 몰랐던 파일들을 읽으면서 이 작업을 수행하세요. .kilocode/rules/에서 찾은 각 규칙에 대해 유지 여부를 결정하기 전에 왜 작성되었는지 기록하세요. 나중에는 그 판단을 내리기가 훨씬 더 어렵습니다. 여전히 정확한 memory bank 콘텐츠를 추가하고, 어떤 부분을 왜 삭제했는지 기록하세요.

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

사용하는 모든 환경에서 Kilo Code를 연결하세요. VS Code 확장 프로그램과 CLI는 우선순위 표를 공유하지만 외부 디렉터리 처리 방식이 다르므로, 둘 다 동일한 결정 세트를 읽어야 합니다. 동일한 저장소에서 여전히 Cline을 실행 중이라면 이 역시 연결하세요. 두 도구는 규칙 파일 유산을 공유하므로, 공유 레이어를 통해 서로 달라지는 것을 방지할 수 있습니다.

"규칙이 적용되지 않습니다"라는 문제가 반나절짜리 작업에서 5분짜리 확인 작업으로 바뀝니다. 인벤토리가 있으므로, 알 수 없는 파일이 존재하는지 여부가 아니라 알려진 소스 중 어떤 것이 우선하는지가 질문이 됩니다.

순서 지정이 실질적으로 작동합니다. 글롭을 명시적 경로로 대체하면 배열 위치가 실제로 우선순위를 결정하므로, 충돌이 발생했을 때 가리킬 수 있는 예측 가능한 답이 생깁니다.

레거시 디렉터리가 두 번째 단일 진실 공급원(source of truth) 역할을 중단합니다. .kilocode/rules/가 비워지면, 우선순위 표와 디렉터리별 AGENTS.md 맵이 전체 그림이 됩니다.

그리고 정리 후에도 그 이유는 살아남습니다. 통합은 의도적으로 파일을 삭제하는 과정입니다. 규칙을 삭제하는 것은 괜찮지만, 그것이 왜 존재했는지에 대한 유일한 기록을 삭제하는 것은 6개월 후에 똑같은 논쟁을 다시 불러일으키는 원인이 됩니다.

글롭이 아닌 경로를 명시적으로 나열하세요. instructions 배열에서 파일당 한 줄씩 사용하는 것이 더 장황하지만, 순서를 제어할 수 있는 유일한 방법입니다. 순서가 정말 중요하지 않은 디렉터리에만 글롭을 사용하세요.

삭제하는 대신 주석 처리하세요. JSONC 주석을 사용하면 규칙이 보류된 이유에 대한 메모와 함께 규칙을 보류해 둘 수 있으며, 이는 단순히 줄이 누락되는 것보다 훨씬 더 많은 정보를 제공합니다.

루트 AGENTS.md를 짧게 유지하세요. 비활성화할 수 없고 항상 로드되므로, 모든 줄이 영구적인 컨텍스트 비용이 됩니다. 특정 영역에 국한된 내용은 디렉터리별 파일로 밀어 넣으세요.

대문자 AGENTS.md로 표준화하세요. Kilo는 이를 요구하며, 도구마다 대소문자 구분에 대한 의견이 다르므로 대문자가 공유 저장소에서 비용이 들지 않는 선택입니다.

memory bank 상태 표시기를 신뢰하지 마세요. Kilo는 이 표시기가 "여전히 나타날 수 있지만, 모든 클라이언트나 모드에서 보장되지는 않는다"고 말합니다. 대신 모순 테스트를 통해 검증하세요.

종속성이나 버전이 업데이트된 후에는 모순 테스트를 다시 실행하세요. 하위 호환성 경로는 릴리스 간에 변경되기 가장 쉬운 부분이며, 여기서 발생하는 보이지 않는 변화는 모델이 나빠진 것처럼 보일 수 있습니다. 이는 Kilo가 포크한 도구에 대해 다룬 Cline이 프로젝트 컨텍스트를 잊어버리는 현상에서 언급한 많은 오진의 배후에 있습니다. 여전히 마이그레이션을 계획 중이라면, Cline에서 Kilo Code로 마이그레이션하기에서 파일 매핑을 다룹니다. 이 가이드는 마이그레이션을 완료한 후 수행할 작업에 대한 것입니다.

Kilo Code의 instructions 배열은 실제 매니페스트이며, 매니페스트는 올바른 아이디어입니다. 문제는 Kilo의 세 가지 로드 동작이 이 매니페스트의 외부에 존재한다는 점입니다. 레거시 .kilocode/rules/ 디렉터리는 자동으로 로드되고, 디렉터리별 AGENTS.md 파일은 에이전트가 그 근처의 파일을 읽을 때 주입되며, CLI는 다른 도구의 호환성 디렉터리를 읽습니다.

통합이란 모든 경로를 명시적으로 지정하고, 지정하지 않은 경로를 비운 다음, 모순 테스트를 수행하는 것을 의미합니다. 구성 파일은 언급하지 않은 소스를 스스로 감사할 수 없기 때문입니다. 이 작업을 한 번만 수행하면 우선순위 표가 프로젝트의 일부가 아닌 정확한 설명이 됩니다.