테마
Configuration scopes
목표
Kiro가 설정을 global·project·agent 세 범위로 나누어 해석하는 방식과, 각 설정이 어디에 저장되는지, 같은 설정이 여러 범위에 있을 때 무엇이 이기는지 이해합니다.
개념
Kiro는 계층형 설정 시스템을 쓰며 범위가 셋입니다. 현재 컨텍스트에 더 가까운 설정이 더 넓은 설정보다 우선합니다.
- Global — 모든 프로젝트에 적용.
~/.kiro/에 저장. - Project — 특정 워크스페이스에 한정.
<project-root>/.kiro/에 저장. - Agent — 에이전트별 정의.
~/.kiro/agents/(global) 또는.kiro/agents/(project)에 저장.
| 범위 | IDE | CLI | Web | Mobile |
|---|---|---|---|---|
Global scope (~/.kiro/) | ✓ | ✓ | — | — |
| Cloud configuration | Opt-in | Opt-in | ✓ | — |
Project scope (.kiro/) | ✓ | ✓ | ✓ | ✓ |
Agent scope (.kiro/agents/ 또는 ~/.kiro/agents/) | ✓ | ✓ | — | — |
💡 KIRO_HOME으로 global 디렉토리 재지정:
KIRO_HOME을 절대 경로로 설정하면 work·personal처럼 별도 Kiro 프로필을 둘 수 있습니다. V3에서 Kiro는 global 설정·로그인·세션·에이전트 상태를 거기에 저장합니다. 상대 경로, 파일시스템 루트, 홈 디렉토리나 그 상위는 무시되고~/.kiro가 쓰입니다.
세션 설정 확인 (V3)
로컬 또는 클라우드 V3 세션에서 /config로 그 세션이 쓰는 설정을 검토합니다.
bash
# 카테고리 요약 열기
/config
# 특정 카테고리 바로 열기
/config steering요약은 agents, MCP servers, Powers, Steering, Skills, Hooks를 다룹니다. /config는 V1·V2에서는 쓸 수 없습니다. 요약과 패널 내 목록(Powers·Steering·Skills)은 읽기 전용이며, /config 자체는 설정 파일을 편집·업로드하지 않습니다.
파일 경로
| 설정 | Global scope | Project scope |
|---|---|---|
| MCP servers | ~/.kiro/settings/mcp.json | .kiro/settings/mcp.json |
| Permissions | ~/.kiro/settings/permissions.yaml | ~/.kiro/workspace-roots/<hash>/permissions.yaml (저장소 밖, 사용자별) |
| Local command sandbox | ~/.kiro/settings/sandbox.json | .kiro/settings/sandbox.json |
| Custom agents | ~/.kiro/agents/ | .kiro/agents/ |
| Steering | ~/.kiro/steering/ | .kiro/steering/ |
| Skills | ~/.kiro/skills/ | .kiro/skills/ |
| Hooks | ~/.kiro/hooks/ | .kiro/hooks/ |
| Powers | ~/.kiro/powers/ | — |
| Specs | — | .kiro/specs/ |
| Workflows | ~/.kiro/workflows/ | .kiro/workflows/ |
| Settings (CLI) | ~/.kiro/settings/cli.json | — |
각 범위가 지원하는 것
설정마다 쓸 수 있는 범위가 다르고, 에이전트 프로필에 끼워 넣을 수 있는지도 다릅니다.
| 설정 | Global | Project | Agent scope |
|---|---|---|---|
| MCP servers | ✓ | ✓ | ✓ (mcpServers 필드 또는 includeMcpJson) |
| Permissions | ✓ | ✓ | ✓ (permissions 필드) |
| Local command sandbox | ✓ | ✓ | — |
| Custom agents | ✓ | ✓ | N/A |
| Steering | ✓ | ✓ | ✓ (resources 필드) |
| Skills | ✓ | ✓ | ✓ (resources 필드) |
| Hooks | ✓ | ✓ | ✓ (CLI 전용, hooks 필드) |
| Powers | ✓ | — | ✓ (includePowers 필드) |
| Specs | — | ✓ | — |
| Workflows | ✓ | ✓ | — |
| Settings | ✓ | — | — |
충돌 해결
같은 설정이 여러 범위에 있으면, 현재 컨텍스트에 가장 가까운 범위가 이깁니다.
| 설정 | 우선순위 (높음 → 낮음) |
|---|---|
| MCP servers | Agent > Project > Global |
| Permissions | 범위와 무관하게 deny가 이김(deny-overrides) |
| Local command sandbox | 활성 global 정책이 하한선. project는 켜거나 더 조일 수 있으나 약화 불가 |
| Custom agents | Project > Global (동명: project가 경고와 함께 이김) |
| Steering | 모든 범위 병합(덮어쓰기 아님) |
| Skills | 모든 범위 병합 |
| Hooks | 모든 범위 병합 |
| Workflows | Project > Global > 동기화된 계정 recipe > 번들 recipe |
💡 Permissions는 deny-overrides 알고리즘을 씁니다. 어느 범위든
deny규칙이 있으면 다른 곳의allow와 상관없이 그 동작을 막습니다. Permissions 참고.
Web·Mobile
Web·Mobile은 복제한 저장소에서 project 설정을 읽지만 범위가 다릅니다. Mobile은 project Steering·Skills를 읽고, Kiro Web은 추가로 project MCP servers·custom agents·Hooks를 읽습니다. 둘 다 로컬 파일시스템이 없어 global ~/.kiro/ 설정은 읽지 않습니다.
| 설정 | Web | Mobile |
|---|---|---|
Project steering (.kiro/steering/) | ✓ | ✓ |
Project skills (.kiro/skills/) | ✓ | ✓ |
| Project MCP servers | ✓ | — |
| Project custom agents | ✓ | — |
| Project Hooks | ✓ | — |
| Sandbox MCP (Web 설정에서 구성) | ✓ | — |
| Permissions YAML·대화형 승인 | — | — |
계정에 업로드한 workflow 등 나머지 항목은 공식 Configuration scopes를 확인하세요.
해볼 것
- V3 세션에서
/config를 열어 agents·MCP·Steering·Skills·Hooks 구성 요약을 확인합니다. /config steering으로 Steering 카테고리를 바로 열어 봅니다.- 같은 이름의 설정을 project와 global에 두고, 위 우선순위 표대로 어느 쪽이 적용되는지 확인합니다.
더 알아보기
- Configuration scopes
- Kiro 동작 원리 — 설정이 범위별로 따라다니는 방식
- Permissions — deny-overrides 기반 접근 제어
- Steering — 프로젝트 맥락·컨벤션
- MCP — 외부 도구 연결
출처: kiro.dev 공식 문서 "Configuration scopes" (2026-10-26 확인).