Configuration

1. Configuration

Kiro CLI는 개발자 개인의 선호(Preferences)와 팀 표준(Team standards)에 맞게 다양한 구성을 설정할 수 있도록 설계되어 있습니다.

구성(Configuration)은 적용 범위(Scope)에 따라 다음 세 가지 수준에서 정의할 수 있습니다.

전역(Global) 구성
- Kiro가 사용되는 모든 프로젝트에 공통으로 적용되는 구성
- 경로: <user-home>/.kiro/
프로젝트(Project) 구성
- 특정 프로젝트에만 적용되는 구성
- 경로: <project-root>/.kiro/
에이전트(Agent) 구성
- 특정 커스텀 에이전트(Custom agent)에만 적용되는 구성
- 경로: <user-home | project-root>/.kiro/agents

다음 표는 구성 항목별로 전역(Global) 및 프로젝트(Project) 범위에서 사용되는 파일 및 디렉터리 경로를 나타냅니다.

아래 표는 각 구성 항목이 어느 범위(Scope)에서 정의될 수 있는지를 보여줍니다.

Configuration	User Scope	Project Scope	Agent Scope
MCP servers	Yes	Yes	Yes
Prompts	Yes	Yes	No
Custom agents	Yes	Yes	N/A
Steering	Yes	Yes	Yes
Settings	Yes	N/A	N/A

Kiro CLI는 동일한 구성 항목이 여러 범위에 정의되어 있는 경우, 현재 사용자가 Kiro CLI와 상호작용하고 있는 위치(Location)에 가장 가까운 구성을 우선 적용합니다.

커스텀 에이전트(Custom agent)는 전역(Global)과 프로젝트(Project) 범위 모두에서 정의될 수 있습니다.

동일한 수준(Level)에서 구성 충돌이 발생할 경우, 에이전트 구성(Agent configuration) 이 항상 우선 적용됩니다.

즉, 에이전트에 명시적으로 정의된 구성은 동일 범위의 다른 구성보다 높은 우선순위를 가집니다.

아래 표는 구성 항목별 우선순위(Priority)를 정리한 것입니다.

MCP 서버(Model Context Protocol servers)는 전역(Global), 프로젝트(Project), 에이전트(Agent) 총 세 가지 범위에서 모두 정의할 수 있기 때문에, 다른 구성 항목과는 약간 다른 방식으로 처리됩니다.

특히, 에이전트 구성 파일에는 includeMcpJson 설정이 존재하여:

을 함께 포함하거나 제외할 수 있습니다.

이에 따른 상세 동작 방식은 MCP server loading priority 문서를 참조해야 합니다.