Kiro를 중심으로 팀 프로세스를 구축하기 전에 간단한 테스트를 해보세요. 워크플로(workflow)의 어떤 단계든 가져와서, 그 결과물이 당신의 노트북 없이도 살아남을 수 있는지 물어보십시오. 만약 아티팩트(artifact)를 동료에게 git으로 전달할 수 없거나, 당신이 직접 키보드 앞에 앉아 있지 않아도 CI에서 실행할 수 없다면, 그것은 팀 단위의 단계가 아닙니다. 그것은 프로세스처럼 보일 뿐인 개인적인 습관입니다.

팀이 열려 있는 IDE 세션 외부에는 존재하지 않는 기능들을 기반으로 설계하기 시작하기 전까지는 그 차이가 미미해 보입니다. 하지만 일단 시작되면, 작성자에게는 파일 저장 시 작동하던 편리한 에이전트 훅(agent hook)이 빌드 파이프라인(pipeline)에서는 실행되지 않으며, 에이전트를 안내하던 "스마트한" 스티어링 파일(steering-file)이 홈 디렉토리에 있어 동료들이 전혀 볼 수 없었다는 사실이 드러나게 됩니다.

이 글은 장애 발생 사례를 이야기하는 것이 아니라 제품의 경계를 분석합니다. 저는 Kiro가 무언가를 망가뜨린다고 주장하는 것이 아닙니다. Kiro의 문서(kiro.dev, 2026년 7월 18일 접속)에 따르면, 벤더(vendor) 스스로도 키(key)를 가진 자동화 가능한 표면(surface)으로 단 하나의 기능만을 명시하고 있습니다: 바로 CLI의 헤드리스(headless) 모드입니다. 나머지 기능들은 자동화 가능한 인터페이스가 아니라 IDE의 설정 파일(configuration files)로 남습니다. 만약 Kiro를 팀에 정착시키려 한다면, 이 경계가 숨겨진 의존성(dependency)이 되기 전에 이를 파악해야 합니다.

왜 유용한 IDE 기능이 팀 프로세스를 의미하지 않는가

기본적인 논쟁적 가정은 다음과 같습니다: "IDE의 모든 유용한 기능은 팀 프로세스로 이식 가능하다." 하지만 실제로는 원하는 것보다 더 자주 이 가정이 틀립니다. 특정 기능이 한 명의 개발자에게는 속도를 높여줄 수 있지만, 내보내기(export) 형식도, 전달 방법도, 대화형 세션 이외의 트리거(trigger)도 없을 수 있기 때문입니다.

가치(value)와 이식성(portability)은 독립적인 축으로 구성됩니다. 파일 저장 시 테스트를 생성하는 훅(hook)은 작성자의 시간을 절약해 줍니다. 하지만 훅 관련 문서(kiro.dev/docs/hooks/, 2026년 7월 18일 접속)에 따르면, 이는 IDE 이벤트(IDE-events)에 반응합니다: 파일 생성, 저장, 삭제, 프롬프트(prompt) 전송, 에이전트 중지, spec 작업의 실행 단계 또는 수동 실행 등입니다. 이러한 이벤트 중 그 어느 것도 열려 있는 에디터나 IDE 세션이 존재하지 않는 CI 환경에서는 발생하지 않습니다.

이 모든 분석을 관통하는 실질적인 규칙은 다음과 같습니다. 명시적으로 내보낼 수 있는 아티팩트(artifact)와 이를 전달할 방법이 있는 것만이 팀 단위의 단계(team step)로 간주됩니다. 재현 불가능한 인터페이스 동작에 의존하는 모든 것은 그것이 아무리 유용하더라도 개인적인 영역으로 남습니다.

여기서 우리는 사안을 명확히 짚고 넘어가야 합니다. 개발자가 검색창에 "kiro ai api"를 검색할 때, 보통은 스크립트나 파이프라인(pipeline)에서 Kiro를 어떻게 호출하는지 알고 싶어 합니다. 문서는 이 요청에 대해 좁은 범위로 답변합니다. API 키는 specs, steering 또는 hooks가 아닌, 정확히 단 하나의 접점(surface)만을 위해 존재합니다. 이후 본문에서 저는 이 구분을 엄격하게 유지할 것인데, 바로 이 지점에서 팀들이 가장 자주 실수하기 때문입니다.

Kiro에는 어떤 아티팩트들이 존재하는가

분류하기에 앞서 인벤토리(inventory) 조사가 필요합니다. Kiro는 IDE 내부의 여러 가지 서로 다른 구성 접점(configuration surfaces)과 별도의 CLI를 제공합니다. 문서에 따라 이 파일들이 무엇인지, 그리고 어디에 위치하는지 살펴보겠습니다.

Specs. 이는 Kiro가 특정 기능(feature)을 위해 생성하는 구조화된 아티팩트들로, requirements.md (또는 bugfix.md), design.md, tasks.md가 이에 해당합니다. 이는 요구사항, 아키텍처(architecture), 추적 가능한 작업(trackable tasks)을 담고 있는 일반적인 마크다운(markdown) 파일들입니다. specs 문서(kiro.dev/docs/specs/, 2026년 7월 18일 접속)는 이를 제품 팀과 엔지니어링 팀의 협업을 지원하는 것으로 설명하고 있지만, 고정된 저장 경로를 지정하거나 버전 관리 시스템(version control system)과의 연동을 문서화된 약속으로 보장하지는 않습니다.

Steering. 에이전트에게 프로젝트에 대한 지속적인 지식을 제공하는 Markdown 문서입니다. Kiro 문서(kiro.dev/docs/steering/, 2026년 7월 18일 접근 가능)에 따르면, 워크스페이스 수준의 steering는 프로젝트 루트 내 .kiro/steering/에 존재하며 git으로 분리되고, 전역(global) steering는 사용자의 홈 디렉토리 ~/.kiro/steering/에 위치하여 모든 작업 공간에 적용됩니다. 기본적으로 두 번째(전역)는 커밋되지 않으며 동료에게 보이지 않습니다. 선택적으로 steering 파일은 YAML 프론트매터(예: inclusion: always)를 사용하여 로드 시점을 제어할 수 있습니다. Kiro는 또한 간단한 AGENTS.md도 지원하는데, 이는 .kiro/steering/*.md와 달리 포함 모드 옵션이 없어 항상 전체가 로드됩니다.**

Agent hooks. 워크스페이스 수준의 .kiro/hooks/에 있는 JSON 파일로, IDE 네이티브 이벤트에 의해 실행됩니다. 문서에 따르면 hooks는 편집기 이벤트에 연결되며, 그곳에서 언급했듯이 IDE 외부에서는 실행 가능한 것으로 설명되지 않았습니다.

MCP. MCP 서버 연결은 mcp.json이라는 JSON 파일에 설정됩니다: .kiro/settings/mcp.json (워크스페이스 수준) 또는 ~/.kiro/settings/mcp.json (사용자 전역 수준). 둘 다 존재하는 경우, 설정이 병합되며 워크스페이스 파일의 우선순위가 높습니다. MCP 문서(kiro.dev/docs/mcp/configuration/, 2026년 7월 18일 접근 가능)에서 언급된 중요한 주의사항은 비밀 정보가 포함된 설정 파일은 커밋해서는 안 되며, ${ENV_VAR} 대체 사용이 권장된다는 것입니다. 따라서 심지어 git으로 추적되는 mcp.json이라도 키(key)가 내장되어 있다면 완전히 이식 가능하지 않습니다.

다음의 비대칭성에 주목하십시오: 일부 아티팩트는 레포지토리의 텍스트로 존재하고, 다른 일부는 사용자의 홈 디렉토리에 파일로 남아 있으며, 또 다른 일부는 아예 파일이 아니라 라이브 세션에 연결된 동작입니다. 'Kiro'라는 단어 하나가 완전히 다른 운명을 지닌 표면들을 포괄합니다.

IDE와 API 사이의 경계가 실제로 존재하는 곳은 어디인가**

이제 벤더의 문서가 "키(key)"와 "자동화(automation)"를 언급하는 유일한 지점으로 넘어가 보겠습니다. Kiro에는 문서화된 헤드리스(headless) 모드를 지원하는 CLI가 있습니다: kiro-cli chat --no-interactive "<prompt>". CLI 문서(kiro.dev/docs/cli/headless/, 2026년 7월 18일 접속)에 따르면, 이는 코드 리뷰, 테스트 생성 또는 실패한 빌드 분석과 같은 작업을 위해 대화형 터미널 없이 CI/CD 파이프라인에서 실행되도록 명확히 설계되었습니다. 이것이 공식 문서에서 IDE와 독립적으로 작동한다고 포지셔닝하는 Kiro의 유일한 기능입니다.

인증(Authentication)은 별개의 엄격한 영역입니다. 헤드리스 모드는 KIRO_API_KEY 환경 변수를 요구하며, API 키 발급은 구독 티어(subscription tiers)에 따라 제한됩니다. 인증 문서(kiro.dev/docs/cli/authentication/, 2026년 7월 18일 접속)에 따르면 이는 Kiro Pro, Pro+, Pro Max 및 Power에 해당하며, 관리자는 키 생성을 추가로 제한할 수 있습니다. 대화형 로그인 방식(GitHub, Google, AWS Builder ID, IAM Identity Center, Entra 또는 Okta를 통한 외부 IdP) 자체로는 헤드리스 및 CI 접근 권한을 제공하지 않습니다.

CLI의 자격 증명(credentials) 확인 순서는 다음과 같습니다: 먼저 활성화된 대화형 브라우저 세션, 그다음 KIRO_API_KEY 변수, 마지막으로 새로운 로그인 요청 순입니다. kiro-cli whoami 명령어를 통해 어떤 방식이 활성화되어 있는지 확인할 수 있습니다. 실질적인 결론은 명확합니다. CI 실행은 브라우저를 통한 개인 로그인이 아닌, 반드시 API 키를 통한 경로를 엄격히 요구합니다. 바로 이 점 때문에 저자의 개인 브라우저 세션은 파이프라인에 있어 안티 패턴(anti-pattern)으로 남습니다. 이는 러너(runner)에서 재현할 수 없기 때문입니다.

# Kiro의 유일하게 문서화된 자동화 접점
export KIRO_API_KEY="<유료 티어에서 발급된 키>"
kiro-cli whoami                       # 활성화된 인증 방식을 보여줌
...

그리고 간과해서는 안 될 핵심적인 불확실성이 있습니다. headless 모드 문서에 따르면, 관리자 거버넌스 정책 (governance policy, MCP 서버 제한, 모델 액세스 정책, web fetch 권한 등)은 headless 세션과 대화형 (interactive) 세션 모두에 동일하게 적용된다고 명시되어 있습니다. 하지만 동일한 문서에서도 IDE 전용 아티팩트 (IDE-only artifacts, 예: specs, steering 활성화 상태, hooks)가 headless/CI 실행 중에 읽히거나 실행되는지는 확인해주지 않습니다. 검토 시점 기준으로 이는 공식 문서에서 해결되지 않은 공백(gap)으로 남아 있습니다.

단일 워크플로우(workflow) 지도: 단계, 아티팩트, 전달, 수동 의존성

특정 시나리오를 실행해 보지 않은 인벤토리(inventory)는 단순한 목록에 불과합니다. 제가 제안하는 방법은 하나의 실제 워크플로우를 다섯 가지 열로 분류하는 것입니다: 입력(input), IDE 내부에서의 Kiro 동작, 내보내지는 아티팩트(exported artifact), 동료나 CI로 전달하는 방식, 그리고 숨겨진 수동 의존성(manual dependency)입니다. 이것은 문서로 확인된 사실이 아니라, 제가 제안하는 자체적인 검증 도구입니다. 이 지도는 제 말을 그대로 믿기보다 여러분의 프로젝트에 직접 구축해 보아야 합니다.

이 지도의 상태에 대해 중요한 주의 사항이 있습니다. 이 지도는 Kiro의 공개 API 존재 여부를 증명하거나, 여러분의 개인적인 hook 또는 steering 파일이 동료의 머신이나 headless 실행 환경에서도 살아남는다는 것을 보장하지 않습니다. 이것은 지도를 통해 검증 가능하게 만든 하나의 가설입니다. 즉, "전달" 열이 구체적인 메커니즘으로 채워지거나 혹은 빈칸으로 남게 되며, 그 빈칸 자체가 하나의 답변이 됩니다. 이를 추측이 아닌 테스트로 검증해야 하며, 그러한 테스트를 거치기 전까지는 팀과 CI에서 사용할 수 있는 Kiro의 구체적인 기능들은 미지의 영역으로 남아 있습니다.

"기능 명세(spec)를 생성하고 파이프라인의 테스트 단계까지 도달한다"는 전형적인 시나리오를 예로 들어, 문서화된 내용과 추정되는 내용을 분리하여 정직하게 분류해 보겠습니다.

이 표는 "전달 방식" 열을 기준으로 읽어야 합니다. 구체적인 메커니즘이 명시된 곳은 팀 프로세스로서의 지위를 가질 수 있는 단계입니다. 반면 "없음" 또는 "확인되지 않음"이라고 적힌 곳은 개인적인 단계로 남게 되며, 별도의 검증 없이는 CI (지속적 통합)에 포함할 수 없습니다. 특히 global steering 행은 매우 까다로운데, 아티팩트는 유용하지만 파일이 프로젝트 외부에 존재하기 때문에 전달 방식 열이 구조적으로 비어 있습니다.

독립적인 API가 여기에 정직하게 통합되는 지점

"내보내지는 아티팩트" 열이 생기는 즉시 다음과 같은 질문이 생깁니다. 만약 이 단계가 스크립트나 파이프라인(pipeline)으로 분리된다면, 무엇을 사용하여 이 단계를 실행할 것인가? 여기서 계층(level)을 혼동하지 않는 것이 중요합니다. provod.ai는 독립적인 모델 API 애그리게이터 (aggregator)로서 작동합니다. 이는 Kiro의 확장 기능도 아니고, Kiro의 CLI를 대체하는 것도 아닙니다. 이를 연결하는 것은 이미 IDE에서 분리해낸 명확하게 내보내지는 워크플로우 단계에 연결하는 것이 의미가 있는 것이지, specs, steering, 또는 hooks 자체에 연결하는 것이 아닙니다.

이 차이점이 아키텍처를 결정하기 때문에 구체적으로 살펴보겠습니다. Kiro의 헤드리스 (Headless) 모드는 자체 KIRO_API_KEY와 구독 기반의 티어 게이팅 (tier-gating)을 통해 모델에 접속합니다. 반면, 만약 당신이 특정 단계를 별도의 CI 스크립트로 분리한다면 (예를 들어,