IDE와 CLI가 각각 올바른 Kiro 스티어링 파일을 로드하도록 분할하는 방법 (2026년 가이드)

Kiro의 스티어링 페이지는 기능 지원 표로 시작하며, 각 행이 전체적인 설계를 보여줍니다. "작업 공간 스티어링 (.kiro/steering/)"은 IDE, CLI, 웹, 모바일에서 사용할 수 있습니다. "글로벌 스티어링 (~/.kiro/steering/)"은 IDE와 CLI에서 사용할 수 있으며, 웹과 모바일에서는 사용할 수 없는 것으로 표시되어 있습니다. "웹 설정에서 관리되는 클라우드 스티어링"은 웹 전용입니다. "UI를 통한 기본 파일 생성"은 IDE 전용입니다. "포함 모드 (always, fileMatch, manual)"는 네 가지 환경 모두에서 사용 가능한 것으로 표시되어 있습니다.

혼란은 바로 마지막 행에서 시작됩니다. 페이지 아래쪽의 안내 노트에서 범위를 좁히고 있기 때문입니다. CLI에서는 현재 포함 모드가 지원되지 않으며, 디렉터리의 모든 파일이 자동으로 로드됩니다. 따라서 올바른 멘탈 모델은 "내 규칙이 어디든 나를 따라온다"가 아닙니다. 오히려 "파일은 따라오지만, 제한 조건(gating)은 따라오지 않는다"에 가깝습니다.

글로벌 디렉터리 역시 동일한 맥락의 자체적인 한계가 있습니다. "웹에서 '글로벌 스티어링'은 로컬 ~/.kiro/steering/ 디렉터리를 가리키며, 클라우드 샌드박스는 이를 읽을 수 없습니다." 문서에 안내된 해결책은 구성 동기화(Configuration Sync)입니다. "클라우드 세션 전반에서 개인 스티어링을 재사용하려면 구성 동기화를 통해 업로드하세요. 그러면 클라우드 복사본이 모든 클라우드 세션에 적용됩니다."

자체 에이전트를 구축하기 시작한 사람들을 당황하게 만드는 네 번째 케이스가 있습니다. 문서에는 다음과 같이 적혀 있습니다. "커스텀 에이전트를 사용할 때는 스티어링 파일이 자동으로 포함되지 않습니다. 스티어링 컨텍스트를 로드하려면 에이전트의 resources 구성에 명시적으로 추가해야 합니다." 에이전트의 resources에 file://.kiro/steering/**/*.md와 같은 글로브(glob)를 지정해야 파일을 다시 가져올 수 있습니다.

그리고 특정 파일 이름 하나는 제한 조건을 완전히 우회합니다. Kiro는 AGENTS.md 표준을 지원하지만, 페이지에 다음과 같은 주의 사항이 있습니다. "AGENTS.md 파일은 포함 모드를 지원하지 않으며 항상 포함됩니다." 리포지토리 루트에 공유 크로스 툴 파일을 유지한다면, 다른 곳에서 프론트 매터를 아무리 철저하게 관리했더라도 정의상 항상 활성화되는 파일이 됩니다.

프론트 매터를 삭제하고 처음부터 다시 시작하기. 조건부 파일이 오작동할 때 가장 먼저 드는 직관은 YAML이 잘못되었다고 가정하는 것입니다. 하지만 그렇지 않은 경우가 많습니다. 문서에서는 "포함 구성은 파일의 첫 번째 콘텐츠여야 하며, 그 앞에 빈 줄이나 다른 콘텐츠가 있어서는 안 됩니다"라고 경고하므로 한 번쯤 확인할 가치는 있습니다. 하지만 파일이 IDE에서는 작동하고 CLI에서는 작동하지 않는다면 프론트 매터는 문제가 없으며 서피스가 변수인 것입니다.

모든 내용을 세 개의 기본 파일로 이동하기. product.md, tech.md, structure.md는 실제로 유용하며, 문서에서도 "이 기본 파일들은 기본적으로 모든 상호작용에 포함되어 Kiro의 프로젝트 이해의 기준을 형성합니다"라고 설명합니다. 여기서 발생할 수 있는 실패 사례는 이를 통합해도 된다는 허가로 받아들이는 것입니다. 합쳐진 모든 내용은 어디서나 항상 활성화되며, 이는 정확히 피하려던 결과입니다.

개인 설정을 글로벌 디렉터리에 넣고 어디서나 적용될 것이라 가정하기. 이 설정들은 IDE와 CLI로는 전달됩니다. 하지만 클라우드 샌드박스는 해당 디렉터리를 읽을 수 없다고 문서화되어 있으므로, 웹 세션에서는 아무런 알림 없이 조용히 설정이 적용되지 않습니다.

CLI가 정상 작동할 때까지 디렉터리를 축소하기. 로드되는 파일이 줄어든다는 점에서는 효과가 있습니다. 하지만 이는 IDE에서 유용하게 작동하던 조건부 가이드까지 제거해 버립니다. 결국 한쪽 서피스를 개선하기 위해 다른 쪽 서피스의 성능을 떨어뜨리는 결과를 낳습니다.

이 문제를 다른 도구의 규칙 트리거 모드와 동일한 문제로 가정하기. 겉보기에는 비슷해 보이지만 실패의 본질이 다릅니다. 도구가 모든 환경에서 트리거 모드를 지원하는데도 규칙이 실행되지 않는다면 어떤 모드를 선택했는지가 문제이며, 이는 how to choose Windsurf rule trigger modes에서 다룬 내용입니다. 반면 여기서는 모드는 올바르지만 서피스가 이를 무시하는 것이 문제입니다.

Step 1: 디렉터리를 상시 활성화 계층과 조건부 활성화 계층으로 분할하기

.kiro/steering/에 있는 모든 파일을 가져와 한 가지 질문을 기준으로 두 개의 더미로 분류하세요. "이 파일이 모든 서피스의 모든 작업에서 영원히 로드되어도 괜찮은가?"

'예' 더미는 상시 활성화(always-on) 계층으로, 기본 파일들과 진정으로 보편적인 내용들이 포함됩니다. Kiro의 자체 설명이 좋은 필터가 됩니다. product.md는 "제품의 목적, 대상 사용자, 주요 기능 및 비즈니스 목표를 정의합니다", tech.md는 "선택한 프레임워크, 라이브러리, 개발 도구 및 기술적 제약 사항을 문서화합니다", structure.md는 "파일 구성, 명명 규칙, 임포트 패턴 및 아키텍처 결정을 개략적으로 설명합니다." CLI에서는 이 계층만 존재하므로 이 계층은 의도적으로 작게 유지해야 합니다.

'아니오' 더미는 조건부 활성화(gated) 계층으로, 프레임워크별 규칙, 마이그레이션 절차, 트러블슈팅 가이드 등 길이가 긴 모든 파일이 해당됩니다. 이 파일들에는 프론트 매터를 부여하되, CLI에서는 어쨌든 로드된다는 점을 받아들여야 합니다. 이것이 바로 이 더미가 무한정 커지지 않도록 통제해야 하는 이유입니다.

분류하는 동안 명명 규칙 권장 사항을 따르세요. 문서에서는 api-rest-conventions.md, testing-unit-patterns.md, components-form-validation.md와 같이 범위를 나타내는 이름을 제안하며, "파일당 하나의 도메인"을 권장합니다. 모든 파일이 로드되는 서피스에서는 파일 이름이 해당 파일의 용도를 나타내는 유일한 신호이므로 이름이 평소보다 더 중요합니다.

Step 2: 파일이 도달해야 하는 방식에 맞는 포함 모드 선택하기

문서화된 네 가지 모드는 서로 대체할 수 없습니다.

inclusion: always는 기본값이며 프론트 매터 없이도 그렇게 작동합니다. inclusion: fileMatch는 fileMatchPattern을 사용하며, components/**/*.tsx와 같은 단일 글로브나 ["**/*.ts", "**/*.tsx", "**/tsconfig.*.json"]과 같은 배열을 허용합니다. inclusion: manual은 파일을 "채팅 메시지에서 #steering-file-name으로 참조하여 필요할 때 사용할 수 있도록" 하며, 문서에서는 "수동 스티어링 파일은 슬래시 명령어로도 나타나므로 채팅창에 /를 입력하여 선택할 수 있습니다"라고 설명합니다. inclusion: auto는 두 개의 필드, 즉 name("스티어링 파일의 식별자. 표시 및 매칭에 사용됨")과 description("이 파일을 포함할 시점. Kiro가 사용자의 요청과 이를 매칭함")을 요구하며, "요청이 설명과 일치할 때" 파일이 로드됩니다.

문서에 명시된 사용 사례는 직접 새로 만드는 것보다 그대로 따르는 것이 좋습니다. Manual은 "가장 적합한 사례: 특수 워크플로우, 트러블슈팅 가이드, 마이그레이션 절차 또는 가끔씩만 필요한 컨텍스트가 많은 문서"입니다. Auto는 "가장 적합한 사례: 상시 활성화 스티어링을 압도할 수 있는 전문 도메인 지식, 복잡한 워크플로우 또는 상세한 참조 자료와 같이 관련이 있을 때만 로드되어야 하는 컨텍스트가 많은 가이드"입니다.

여기에 한 가지 메커니즘이 더 추가됩니다. 스티어링 파일에 사양을 직접 붙여넣는 대신, #[[file:<relative_file_name>]]을 사용하여 실제 파일을 참조하세요. 문서에서는 #[[file:api/openapi.yaml]], #[[file:components/ui/button.tsx]], #[[file:.env.example]]을 예시로 들고 있습니다. 포인터는 최신 상태를 유지하지만, 직접 붙여넣은 내용은 작성한 날부터 차이가 벌어지기 시작합니다. 동일한 논리가 how to scope Amp instructions to files에서처럼 텍스트가 아닌 경로로 지침 범위를 지정하는 데에도 적용됩니다.

Step 3: 서피스별로 각 파일 배치 후, 실제로 사용하는 서피스에서 검증하기

이제 습관이 아닌 기능 지원 표를 기준으로 각 파일이 물리적으로 위치할 곳을 결정합니다.

리포지토리 표준은 .kiro/steering/에 저장하고 커밋합니다. 개인 설정은 ~/.kiro/steering/에 저장하며, 충돌 규칙은 다음과 같이 문서화되어 있습니다. "글로벌 스티어링과 작업 공간 스티어링의 지침이 충돌하는 경우, Kiro는 작업 공간 스티어링 지침을 우선시합니다." 클라우드 세션의 경우, Kiro Web의 설정 및 동기화(Settings and Sync)에서 개인 스티어링을 업로드한 다음, 설정 및 스티어링(Settings and Steering)에서 클라우드 복사본을 생성하거나 편집합니다.

팀을 위한 방법도 문서화되어 있습니다. "글로벌 스티어링 기능은 팀 전체에 적용되는 중앙 집중식 스티어링 파일을 정의하는 데 사용할 수 있습니다. 팀 스티어링 파일은 MDM 솔루션이나 그룹 정책을 통해 사용자의 PC로 배포하거나, 사용자가 중앙 리포지토리에서 PC로 다운로드하여 ~/.kiro/steering 폴더에 배치할 수 있습니다."

그런 다음 중요한 곳에서 검증하세요. 하루 중 대부분의 시간을 보내는 서피스를 열고, 조건부 파일이 트리거되지 않아야 하는 작업과 트리거되어야 하는 작업을 각각 실행해 보세요. CLI에서는 작업 공간 디렉터리의 모든 파일이 로드될 것을 예상해야 하며, 그 예상이 곧 검증입니다. 커스텀 에이전트를 사용하는 경우 resources 글로브가 존재하는지 확인하세요. 이것이 없으면 해당 에이전트에 스티어링 컨텍스트가 전혀 로드되지 않습니다.

스티어링 파일은 규칙, 기술 스택, 구조와 같은 상시 지침입니다. 하지만 프로젝트 지식의 나머지 절반, 즉 무엇을 결정했는지, 언제 결정했는지, 대안을 거부한 이유는 무엇인지와 같은 정보에는 적합하지 않습니다. 이 정보는 모든 작업에 로드되기보다는 필요할 때 요청하여 검색할 수 있어야 하며, IDE를 열었는지 터미널을 열었는지에 따라 형태가 달라져서는 안 됩니다. MemoryLake에 의도적으로 기록을 작성해 두면 해당 기록을 한곳에 보관할 수 있습니다. 사용자는 자신의 언어로 직접 기록을 작성합니다. Kiro 디렉터리에서 아무것도 읽거나 쓰거나 삭제하지 않습니다.

Step 1: API 키 생성하기

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

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

스티어링 파일이 암시하지만 명시하지는 않는 결정들부터 시작해 보세요. 왜 이 스택을 선택했는지, 어떤 접근 방식을 어떤 이유로 거부했는지, 아무도 기억하지 못하는 이유로 존재하는 제약 조건은 무엇인지 등입니다. 각 내용을 독립된 짧은 노트로 작성하여 개별적으로 검색할 수 있도록 하세요.

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

사용 중인 어시스턴트와 에이전트를 연결합니다. 그러면 특정 세션이 읽을 수 있는 디렉터리에 의존하지 않고, 여러 서피스와 도구를 넘나들며 기록이 사용자를 따라다닙니다.

상시 활성화 계층은 단순한 폴더가 아니라 일종의 '예산'이 됩니다. 특정 서피스가 모든 것을 로드한다는 점을 받아들이고 나면, 해당 디렉터리의 크기는 자연스럽게 누적되는 것이 아니라 의도적으로 결정해야 하는 대상이 됩니다. 이 예산은 긴 세션의 후반부에 남은 컨텍스트 공간과 직접적으로 상호작용하며, 이는 what survives Kiro compaction에서 살펴본 트레이드오프와 동일합니다.

리뷰가 두 번째 채널이 됩니다. Kiro Web에서는 풀 리퀘스트에 대한 피드백이 스티어링이 됩니다. "항상 표준 에러 핸들링을 사용하세요"와 같은 가이드와 함께 댓글을 달면 "에이전트가 이러한 패턴을 학습하여 모든 리포지토리의 향후 작업에 적용"합니다. 이와 함께 명시된 중요한 제한 사항이 있습니다. "작업을 생성한 사용자의 피드백만 에이전트의 학습에 영향을 미칩니다. 다른 리뷰어의 댓글은 에이전트 학습에 영향을 주지 않습니다." 즉, 다른 사람의 작업에 달린 시니어 리뷰어의 댓글은 에이전트에게 아무것도 가르치지 못합니다.

크로스 툴 파일이 무조건 이득이 되지는 않습니다. 루트의 AGENTS.md는 편리하고 항상 포함되므로, 예산 외가 아니라 상시 활성화 예산의 일부로 취급해야 합니다. 여러 에이전트에 걸쳐 하나의 파일을 유지하는 경우, 각 도구의 로드 계약이 다르므로 공유 파일의 유용성은 해당 파일을 읽는 도구 중 가장 제한이 느슨한 도구의 수준에 맞춰집니다.

도구 간 이동 계획을 세우기가 더 쉬워집니다. 제한 조건이 도구 전용 UI가 아닌 프론트 매터에 존재하면, 다른 곳에서 무엇을 다시 표현해야 하는지 한눈에 파악할 수 있습니다. 이는 how to migrate from Kiro to Claude Code의 실무적인 부분에 해당합니다.

파일 내에 서피스 가정을 명시하세요. 조건부 파일 상단에 "src/components에만 로드될 것으로 예상됨"이라는 한 줄을 적어두는 것은 비용이 들지 않으면서도, 다른 곳에서 파일이 나타났을 때 다음 사람이 무엇을 확인해야 하는지 알려줍니다.

상시 활성화 계층을 정기적으로 검토하세요. 이 계층은 모든 서피스의 모든 작업에서 비용(컨텍스트)을 소모하는 계층이며, 의도치 않게 비대해지기 쉬운 계층입니다.

복사해 붙여넣은 콘텐츠보다 파일 참조를 선호하세요. 실제 사양을 가리키는 #[[file:...]] 포인터는 복사된 발췌본처럼 오래되어 쓸모없어지지 않습니다.

자동 포함 파일의 설명을 요약이 아닌 트리거처럼 작성하세요. 해당 필드의 문서화된 역할은 "이 파일을 포함할 시점"이므로, "API 엔드포인트를 생성하거나 수정할 때 사용"과 같이 조건으로 표현된 설명이 주제 레이블보다 더 효과적입니다. 공유 컨텍스트 파일은 how Cursor Projects share context files에서처럼 다른 도구에서도 동일하게 작동합니다.

작성한 기억에 의존하지 말고 실제로 무엇이 사용 가능한지 감사(audit)하세요. 디렉터리 목록은 로드 목록과 동일하지 않으며, 둘 사이의 격차는 how to find Zed skills missing from your catalog에서 설명한 문제와 동일합니다.

Kiro는 5개의 서피스에 걸쳐 4개의 포함 모드, 2개의 디렉터리, 1개의 에이전트를 제공하며, 제한 조건이 적용되는 곳과 적용되지 않는 곳을 명확하게 문서화하고 있습니다. CLI는 작업 공간 디렉터리의 모든 것을 로드합니다. 클라우드 샌드박스는 글로벌 디렉터리를 읽을 수 없습니다. 커스텀 에이전트는 resources에 나열하지 않으면 스티어링을 로드하지 않습니다. 루트의 AGENTS.md는 항상 포함됩니다.

어디서나 허용할 수 있는 상시 활성화 계층과 의도적으로 작게 유지할 조건부 활성화 계층으로 파일을 분류하고, 사용하는 서피스가 실제로 읽을 수 있는 곳에 개인 설정을 배치한 다음, 우연히 먼저 작동했던 서피스가 아닌 실제 사용 서피스에서 검증하세요. 그런 다음 이러한 규칙 뒤에 숨겨진 결정들을 검색 가능한 곳에 보관하여, 다음에 파일 레이아웃이 변경되더라도 그 맥락이 유지되도록 하십시오.