테마
Kiro 동작 원리 — unified agent harness
목표
기능 카탈로그의 각 기능(Steering, Hooks, MCP, 커스텀 에이전트 등)이 어디에서 동작하는지 한 장의 그림으로 이해합니다. 공식 문서 How Kiro works를 기준으로 정리했습니다.
harness란
Kiro의 IDE, CLI, Web, Mobile은 모두 같은 unified agent harness에 말을 거는 서로 다른 앱입니다. harness는 에이전트 실행에 필요한 일을 모두 맡습니다.
- 대화 조율
- 도구 실행
- 컨텍스트 관리
- 권한 평가
- LLM 공급자와의 통신
그래서 Steering 규칙을 쓰거나, 커스텀 에이전트를 만들거나, MCP 서버를 연결하면 특정 앱이 아니라 Kiro 자체를 설정하는 것입니다. 앱마다 다른 것은 에이전트를 다루는 방식이지, 에이전트가 할 수 있는 일이 아닙니다.
- harness는 각 앱에 컴파일된 라이브러리가 아니라 독립 프로세스입니다. 코드 옆에서 실행되며, 노트북에서 시작하든 클라우드 샌드박스에서 시작하든 똑같이 동작합니다.
- 기능이 아직 모든 앱에 오지 않았다면, 공식 기능 페이지 맨 앞의 지원 표(availability table)에 표시됩니다.
경계는 프로토콜: ACP
앱과 harness는 공개 프로토콜인 ACP(Agent Client Protocol)로 통신합니다. Kiro 자신의 앱도 마찬가지이며, 실시간 steering, spec 워크플로, 풍부한 권한 확인 프롬프트, 컨텍스트 사용량 추적 같은 기능은 _kiro/ 네임스페이스의 Kiro 확장 메서드로 추가됩니다.
| 연결 | 방식 |
|---|---|
| 로컬 harness에 연결하는 클라이언트 (IDE·CLI의 기본 동작) | stdio |
| Web, Mobile | 샌드박스의 harness에 WebSocket |
경계가 표준 ACP이기 때문에 JetBrains IDE나 Zed 같은 호환 에디터도 Kiro를 에이전트로 쓸 수 있습니다. 연결 방법과 ACP와 MCP의 차이는 ACP · 다른 에디터에서 쓰기에서 다룹니다.
한 번의 요청(turn)은 이렇게 처리됩니다
어느 앱에서 프롬프트를 보내든 harness는 같은 순서로 처리합니다. 각 기능은 이 흐름의 특정 단계에 붙습니다.
| 단계 | harness가 하는 일 | 여기에 붙는 기능 |
|---|---|---|
| 1. 컨텍스트 조립 | 프롬프트, 지금까지의 대화, steering 파일, 첨부를 모음 | Steering, Prompt Submit hook |
| 2. 모델 계획 | 선택한 모델(또는 Auto 라우팅)이 텍스트·도구 호출을 반환 | Models |
| 3. 도구 호출 검사 | 실행 전 권한 규칙 평가(deny > ask > allow), kiroignore 패턴(활성화된 경우) 평가 | Permissions, kiroignore, Pre Tool Use hook |
| 4. 도구 실행 | 내장 도구가 파일 읽기·편집, 셸 명령, 웹 검색을 수행. MCP 서버와 Powers가 도구 집합을 확장하고, sub-agent가 위임 작업 수행 | MCP, Powers, 커스텀 에이전트, Post Tool Use hook |
| 5. 결과 반영 | 도구 결과를 모델에 돌려주고 작업이 끝날 때까지 반복 | Agent Stop hook |
| 6. 컨텍스트 관리 | 컨텍스트 한도에 가까워지면 오래된 기록을 요약 | Compaction |
공식 문서는 이 흐름 때문에 각 기능을 한 앱에 덧붙인 것이 아니라 루프의 한 단계로 정리한다고 설명합니다. 한 번 쓴 권한 규칙은 어디서나 3단계를 통제하고, steering 파일은 어디서나 1단계를 결정합니다. 단, Web에서는 에이전트가 격리된 클라우드 샌드박스에서 실행되므로 permissions.yaml과 대화형 승인이 적용되지 않습니다(Permissions 참고).
harness가 맡는 기능
공식 문서가 harness 기능으로 꼽는 목록입니다. 핸드북에 페이지가 있으면 핸드북으로, 없으면 공식 문서로 연결했습니다.
| 기능 | 내용 |
|---|---|
| Specs | 요구사항·설계·작업의 구조화된 개발 흐름 |
| Steering | 지속되는 프로젝트 맥락과 규칙 |
| Hooks | 에이전트 루프 주변의 이벤트 기반 자동화 |
| MCP | 외부 도구 서버, OAuth, 도구 검색 |
| Permissions | 에이전트가 할 수 있는 일에 대한 capability 기반 규칙 |
| 커스텀 에이전트 | 에이전트 프로필, 내장 에이전트, sub-agent 위임 |
| Agent Skills | 이식 가능한 지침 패키지(오픈 표준). Context Engineering 참고 |
| Powers | 지식을 묶어 필요할 때 로드되는 MCP 서버. Context Engineering 참고 |
| Cloud sessions | 관리형 클라우드 샌드박스에서 세션을 실행하고 어느 앱에서나 연결 |
| Compaction | 긴 세션의 자동 컨텍스트 요약 |
| Kiroignore | gitignore 형식으로 에이전트 접근에서 파일 제외 |
| Checkpoints | 에이전트 변경 되돌리기, 이전 turn에서 대화 분기 |
| Built-in tools | 파일·셸·웹·코드 도구 |
| Models | 모델 카탈로그, Auto 라우팅, reasoning effort (공식 문서에서는 별도 섹션) |
에이전트가 실행되는 곳
루프는 같지만, 실제로 작업하는 컴퓨터는 앱에 따라 다릅니다.
- IDE와 CLI: 기본적으로 내 컴퓨터에서 harness가 실행됩니다. 도구는 로컬 파일시스템과 셸, 설치된 도구와 자격 증명을 씁니다. 로컬 명령 샌드박스를 켜면 셸 명령을 네트워크 접근이 제한된 OS 수준 경계 안에서 실행합니다. 두 앱 모두 클라우드 세션을 만들거나 연결할 수도 있습니다.
- Web과 Mobile: 같은 harness가 관리형 클라우드 샌드박스에서 실행됩니다. 연결한 저장소를 격리 환경에 복제해 작업하고, 변경을 pull request나 merge request로 돌려줍니다. 내 컴퓨터에서는 아무것도 실행되지 않습니다.
클라우드 세션은 특정 앱이 아니라 계정에 속하므로, 한 앱에서 시작해 다른 앱에서 이어갈 수 있습니다.
설정이 따라다니는 방식
| 범위 | 위치 | 함께 이동하는 대상 |
|---|---|---|
| 프로젝트 | 저장소의 .kiro/ | 저장소. 팀원과 이 저장소를 여는 모든 앱이 같은 steering·spec·에이전트·hook·MCP 서버를 씀 |
| 사용자 | 내 컴퓨터의 ~/.kiro/ | 나. 모든 로컬 프로젝트에 적용되는 개인 에이전트·skill·steering·설정 |
| 클라우드 | 로컬 ~/.kiro/ 설정을 cloud configuration으로 계정에 동기화 | 나. 개인 steering·에이전트·hook·skill·Powers·MCP 서버·workflow가 모든 클라우드 세션에 적용. steering·에이전트·skill·Powers·hook은 새 로컬 세션에도 적용 가능 |
| 워크스페이스 신뢰 | ~/.kiro/workspace-roots/<hash>/ | 이 컴퓨터만. 저장소 밖에 둔 프로젝트별 권한 규칙이라, 복제한 저장소가 스스로 신뢰를 부여할 수 없음 |
공식 문서가 정리한 실무상 의미는 세 가지입니다.
- 한 번 배워 어디서나 사용: CLI용으로 쓴
permissions.yaml을 IDE도 그대로 참조합니다. - 일관된 업그레이드: harness 개선은 한곳에서 이뤄지고, 클라이언트 프로토콜을 건드리지 않는 변경은 앱 업데이트 없이 모든 앱에 반영됩니다.
- 팀 전체의 일관성:
.kiro/를 커밋하면 IDE·터미널·브라우저 중 무엇을 쓰든 같은 에이전트 동작을 얻습니다.
"harness"라는 말이 쓰이는 다른 곳
harness는 문맥에 따라 세 가지 뜻으로 쓰입니다.
- Kiro의 unified agent harness: 이 페이지의 주제. Kiro의 모든 앱이 공유하는 에이전트 엔진입니다.
- AI-DLC의 harness: AI-DLC를 실행하는 도구(Claude Code, Kiro CLI·IDE 등)를 가리킵니다. AI-DLC 개념과 원칙 참고.
- 하네스 엔지니어링: 에이전트가 잘 일하도록 실행 환경이나 방법론을 설계·재구성하는 일입니다. AI-DLC 실전 적용 가이드 참고.
더 알아보기
- How Kiro works
- One agent, every surface — Kiro 블로그의 아키텍처 배경
- Configuration scopes — 모든 설정의 위치와 충돌 해결 규칙
- Kiro란·왜 스펙 기반 — harness와 app·Crew의 관계
- Kiro Crew — harness 위에 올라가는 오케스트레이션 레이어
출처: kiro.dev 공식 문서 "How Kiro works" (2026-10-26 확인). 기능별 지원 앱은 각 공식 기능 페이지의 지원 표를 확인하세요.