Multi-root Workspaces
서로 떨어져 있는 여러 폴더를 하나의 Kiro 작업 공간에 묶어, 단일 프로젝트처럼 함께 다루는 기능입니다.
개요
일반적인 Kiro 워크스페이스는 /users/bob/my-project처럼 단일 루트 폴더 하나만 가집니다. 반면 multi-root 워크스페이스에서는 /users/bob/my-project와 /shared/utils/crypto처럼 서로 다른 위치의 최상위 폴더 여러 개를 한꺼번에 열어 둘 수 있습니다. 공유 라이브러리나 모노레포 외부 모듈을 본 프로젝트와 함께 다룰 때 특히 유용합니다.
워크스페이스에 폴더 추가하기
- 메뉴에서 File > Add Folder to Workspace...를 선택해 추가할 폴더를 고릅니다.
- 또는 macOS Finder, Windows File Explorer에서 폴더를 끌어다 Kiro의 Explorer 뷰에 직접 드롭합니다.
저장 위치 동작
- 단일 루트: spec, steering, hook 같은 산출물이 루트 아래의
.kiro폴더(예:/users/bob/my-project/.kiro)에 저장됩니다. - multi-root: 각 루트 폴더마다 별도의
.kiro하위 폴더를 가질 수 있어, 루트별로 설정과 자료를 분리해 보관할 수 있습니다.
기본 동작 방식
탐색이나 편집 시 파일 경로는 모든 루트를 가로질러 자동으로 해석됩니다. Codebase Indexing과 Repository Maps 또한 모든 루트의 코드를 포함해 색인하므로, 단일 루트 환경과 동일한 방식으로 프롬프트에서 참조할 수 있습니다.
#file context provider 사용 시 여러 루트에 같은 이름의 파일이 있다면, Kiro가 후보 목록을 경로와 함께 보여 주므로 원하는 파일을 정확히 고를 수 있습니다.
Specs
spec은 각 루트의 .kiro 하위에서 모두 수집되어 Kiro 패널의 Specs 섹션에 통합 목록으로 표시됩니다. 항목 옆에는 해당 spec이 속한 루트 폴더 이름이 함께 표시되어 출처를 한눈에 알 수 있습니다.
어느 루트의 spec이든 동일하게 작업을 지시할 수 있으며, 새 spec을 만들 때는 Kiro가 적절한 루트 폴더를 골라 저장 위치를 결정합니다.
Steering files
steering 파일도 각 루트의 .kiro 폴더에서 모두 모아, Agent Steering 섹션의 Workspace 그룹에 통합 표시됩니다. 각 항목 옆에는 루트 폴더 이름이 표시됩니다.
- Always Included로 지정된 steering: 에이전트가 어느 루트에서 작업하든 항상 로드됩니다.
- Conditional Inclusion으로 지정된 steering: 에이전트가 같은 루트 내 파일을 다루고 있고, 그 파일이 inclusion 패턴과 일치할 때만 로드됩니다.
새 워크스페이스 steering 파일을 만들 때는 어느 루트 폴더에 저장할지 선택하는 프롬프트가 표시됩니다.
Hooks
hook은 각 루트의 .kiro에서 수집되어 Agent Hooks 섹션에 함께 나열되며, 정의된 루트 이름이 옆에 표시됩니다.
새 hook을 생성할 때도 어느 루트 폴더에 저장할지 묻는 프롬프트가 나타납니다.
MCP servers
MCP 서버 정의 역시 모든 루트의 .kiro에서 모아 MCP Servers 섹션에 통합 표시됩니다.
- 워크스페이스를 열면 모든 루트에 정의된 MCP 서버가 시작 시점에 함께 기동됩니다.
- 두 루트가 동일한 이름의 서버를 정의했다면, 마지막으로 정의를 제공한 루트의 설정이 채택됩니다.
- 모든 서버는 정의된 위치와 무관하게 첫 번째 루트 폴더를 작업 디렉터리로 삼아 실행됩니다.
설정 파일을 열 때 동작도 약간 다릅니다. MCP Servers 섹션의 Open MCP config는 기본적으로 사용자(글로벌) 단위 설정을 엽니다. Workspace Config 버튼을 누르면 워크스페이스 단위 설정이 열리는데, multi-root 환경에서는 어느 루트 폴더의 설정을 볼지 먼저 선택하게 됩니다.