Kiro cli 기본 사용방법 정리

1. 설치 → 로그인 → 프로젝트에서 실행

macOS/Linux에서는 공식 설치 명령이 다음과 같습니다.

curl -fsSL https://cli.kiro.dev/install | bash

로그인:

kiro-cli login

로그인 상태 확인:

kiro-cli whoami

프로젝트로 이동해서:

cd ~/projects/my-project

kiro-cli

이렇게 하면 현재 디렉터리를 workspace로 삼아 Kiro가 실행됩니다. 일반적인 대화형 사용은 브라우저 로그인을 쓰며, API Key는 주로 CI/CD와 headless 모드용입니다. (Kiro)

---

2. 가장 기본적인 사용법은 그냥 자연어

실행 후에는 별도의 명령 문법을 배울 필요 없이 요청하면 됩니다.

> 이 프로젝트 구조를 분석해줘.

> 현재 인증 시스템이 어떻게 동작하는지 설명해줘.

> 로그인 API에서 발생할 수 있는 보안 문제를 찾아줘.

> 이 기능을 구현해줘.

> 테스트까지 작성하고 실행해줘.

Kiro는 필요에 따라 파일을 읽고, 코드를 수정하고, shell 명령을 실행합니다. 위험하거나 권한이 필요한 작업에는 승인 절차가 들어갑니다. (Kiro)

---

3. @파일은 반드시 알아두기

특정 파일을 정확하게 대상으로 지정할 때는 @를 사용합니다.

> @src/api/routes.ts 코드를 리뷰해줘.

> @package.json 을 보고 현재 기술 스택을 설명해줘.

> @src/auth/login.ts 에서 발생할 수 있는 버그를 찾아줘.

Tab 자동완성도 지원합니다.

이 기능은 꽤 중요합니다. 에이전트가 알아서 프로젝트 전체를 뒤지게 하는 것보다 내가 원하는 파일을 명시적으로 context로 주는 것이 빠르고 명확한 경우가 많습니다. (Kiro)

---

4. Shift + Tab — Plan Mode

큰 작업에서는 바로 코딩을 시키기보다 이것을 많이 쓰는 것이 좋습니다.

Shift + Tab

그러면 Plan mode가 됩니다.

예:

[plan] > 기존 JWT 인증 시스템을 OAuth + JWT 구조로 변경해줘.

바로 코드를 바꾸는 대신 먼저 구현 계획을 작성합니다.

1. 현재 인증 구조 분석
2. OAuth provider abstraction 설계
3. DB schema 변경
4. API route 수정
5. refresh token 처리
6. migration
7. 테스트

계획을 확인한 다음 실행 단계로 넘어갈 수 있습니다. 공식 문서에서도 복잡한 변경 전에 Plan mode를 사용하는 흐름을 안내합니다. (Kiro)

작은 수정

버튼 색깔 바꿔줘

→ 일반 모드

큰 수정

인증 구조 전체 리팩터링
결제 시스템 추가
DB schema 변경

→ Shift+Tab 권장

---

5. /spec — Kiro를 쓰는 중요한 이유 중 하나

상당히 큰 기능이라면 Plan보다 한 단계 더 체계적인 Spec workflow를 사용할 수 있습니다.

/spec new auth-system

그리고:

JWT 인증 + Role 기반 권한 시스템을 구현하고 싶어.

Kiro는 다음 구조를 만듭니다.

.kiro/specs/auth-system/

├── requirements.md
├── design.md
└── tasks.md

흐름은:

요구사항
   ↓
설계
   ↓
Task 분해
   ↓
구현
   ↓
검증

입니다. (Kiro)

기존 Spec 보기:

/spec

기존 Spec 계속하기:

/spec auth-system

Task 전체 실행:

/spec run auth-system

Kiro의 Spec은 CLI와 IDE가 같은 .kiro/specs/를 사용하므로 CLI에서 만들고 IDE에서 이어서 작업할 수도 있습니다. (Kiro)

제가 구분한다면:

작업사용

작은 수정	일반 Prompt
약간 복잡	Shift+Tab Plan
큰 Feature	/spec
반복하면서 완료까지 밀어붙이기	/goal

---

6. /goal — "될 때까지 반복해"

Kiro CLI에서 특히 알아둘 만한 기능입니다.

/goal 로그인 API를 리팩터링하고 모든 테스트가 통과하도록 해줘

Kiro가 한 번 작업하고 끝나는 것이 아니라:

구현
 ↓
테스트
 ↓
실패
 ↓
수정
 ↓
다시 테스트
 ↓
완료

식으로 반복합니다.

기본 최대 iteration은 5회입니다.

/goal --max 10 Jest 테스트를 전부 Vitest로 마이그레이션하고 모든 테스트가 통과하도록 해줘

중단:

/goal clear

중요한 점은 완료 조건을 구체적으로 써주는 것입니다.

좋지 않은 예:

/goal 코드를 개선해줘

좋은 예:

/goal auth 모듈을 리팩터링하고
npm test가 모두 통과하며
TypeScript error가 0개가 되도록 해줘

공식 문서도 /goal에서는 “all tests pass”, “no TypeScript errors” 같은 명확한 acceptance criteria를 주는 것을 권장합니다. (Kiro)

---

7. !명령어 — AI를 거치지 않고 바로 Shell 실행

CLI 안에서:

!npm run build

!npm test

!git status

라고 하면 Kiro에게 “이 명령을 실행해줘”라고 요청하는 것이 아니라 직접 Shell 명령을 실행합니다.

예를 들어:

> 로그인 기능 수정해줘.

Kiro 작업 완료

> !npm test

처럼 쓰면 편합니다. (Kiro)

---

8. /context — AI가 무엇을 보고 있는지 확인

코딩 에이전트에서 아주 중요한 명령입니다.

/context show

현재 context에 어떤 파일이 들어가 있고 얼마나 token을 사용하는지 볼 수 있습니다.

직접 추가:

/context add src/app.js

Glob도 됩니다.

/context add "src/**/*.ts"

제거:

/context remove src/app.js

전체 제거:

/context clear

(Kiro)

예를 들어 프로젝트가 커지면:

/context add "src/auth/**/*.ts"
/context add "src/db/**/*.ts"

처럼 현재 작업에 필요한 영역만 넣는 방식이 유용합니다.

---

9. .kiro/steering/ — 프로젝트 규칙을 Kiro에게 기억시키기

매번 다음처럼 말하고 싶지 않을 수 있습니다.

TypeScript 사용해
pnpm 사용해
Vitest 사용해
Server Component 우선해
any 사용하지 마

이런 프로젝트 규칙을 Steering에 넣습니다.

.kiro/
└── steering/
    └── project.md

예:

# Project Rules

- Next.js 15 + TypeScript
- Package manager: pnpm
- Database: PostgreSQL
- ORM: Drizzle
- Testing: Vitest
- Avoid `any`
- Prefer server components
- API responses follow REST conventions

Kiro는 workspace의 .kiro/steering/ 내용을 프로젝트 컨텍스트로 사용할 수 있습니다. 전역 규칙은:

~/.kiro/steering/

에 둘 수 있고, workspace 규칙이 global 규칙보다 우선합니다. (Kiro)

AGENTS.md도 지원합니다.

project/
├── AGENTS.md
├── src/
└── .kiro/

Kiro는 프로젝트 루트의 AGENTS.md도 자동으로 인식합니다. (Kiro)

---

10. /model — 모델 변경

현재 모델 선택:

/model

특정 모델 지정:

/model claude-opus-4.6

현재 모델을 기본값으로:

/model set-current-as-default

공식 CLI에서는 Tab completion도 지원합니다. (Kiro)

---

11. /agent — 작업별 전문 Agent 만들기

예를 들어 항상 같은 방식으로 코드 리뷰를 한다면:

/agent create code-reviewer

설명을 지정할 수도 있습니다.

/agent create code-reviewer -D "Security and code quality reviewer"

Agent 목록:

/agent list

전환:

/agent swap code-reviewer

편집:

/agent edit code-reviewer

기본 Agent 지정:

/agent set-default code-reviewer

(Kiro)

프로젝트 전용 Agent:

.kiro/agents/

전역 Agent:

~/.kiro/agents/

에 저장됩니다. 현재 공식 문서는 JSON과 Markdown 형식을 모두 지원한다고 설명합니다. (Kiro)

주의할 점

Custom Agent에서는 Steering이 자동으로 포함되지 않습니다.

필요하다면 Agent configuration에:

{
  "resources": [
    "file://.kiro/steering/**/*.md"
  ]
}

처럼 넣어야 합니다. 이 부분은 놓치기 쉽습니다. (Kiro)

---

12. Skills — 반복 작업을 /명령으로 만들기

Kiro도 Agent Skills를 지원합니다.

프로젝트용:

.kiro/skills/

전역:

~/.kiro/skills/

예:

.kiro/skills/pr-review/
└── SKILL.md

그러면 CLI에서:

/pr-review

처럼 사용할 수 있습니다.

Kiro는 Skill description과 요청이 맞으면 자동으로 활성화할 수도 있습니다. (Kiro)

즉,

Steering
= 프로젝트 규칙

Agent
= 역할

Skill
= 작업 절차

라고 이해하면 편합니다.

예를 들어:

.kiro/

steering/
  coding-rules.md

agents/
  backend.md
  reviewer.md

skills/
  pr-review/
  deploy/
  db-migration/

같은 구조가 가능합니다.

---

13. /tools — 권한 관리

Kiro가 계속:

Allow?
[y/n]

을 물어보면 도구를 신뢰하도록 만들 수 있습니다.

현재 Tool 확인:

/tools

특정 Tool trust:

/tools trust write

다시 승인 필요:

/tools untrust write

모두 trust:

/tools trust-all

초기화:

/tools reset

(Kiro)

다만 trust-all보다는 필요한 권한만 주는 방식이 안전합니다.

---

14. /chat, /rewind, /compact

이 세 개도 실제 사용 빈도가 높습니다.

새 대화:

/chat new

예전 작업 계속:

/chat resume

CLI 시작할 때 바로 resume:

kiro-cli chat --resume

특정 session:

kiro-cli chat --resume-id SESSION_ID

(Kiro)

대화가 엉뚱한 방향으로 갔다면:

/rewind

특정 시점:

/rewind 4

원래 대화를 파괴하는 것이 아니라 그 지점에서 새로운 conversation branch를 만듭니다. (Kiro)

Context가 너무 길어졌다면:

/compact

대화 핵심을 요약하고 context 공간을 확보합니다. (Kiro)

---

15. /guide — 명령어를 외울 필요가 없게 해주는 기능

이건 처음 Kiro CLI를 사용할 때 상당히 유용합니다.

/guide

그리고:

How do I configure MCP?

이 프로젝트에 적합한 steering을 만들어줘.

code review agent를 만들어줘.

처럼 물을 수 있습니다.

Guide Agent는 현재 설치된 Kiro CLI에 맞는 문서를 바탕으로 설명하고 .kiro/ 설정 파일까지 만들어줄 수 있습니다. 원래 Agent로 돌아갈 때는 Shift+Tab 또는 /agent swap을 사용할 수 있습니다. (Kiro)

---

16. MCP

GitHub, DB, API, 각종 외부 도구를 붙일 때 사용합니다.

현재 상태:

/mcp

인증 문제:

/mcp auth my-server

로그아웃:

/mcp logout my-server

Kiro의 MCP는 외부 데이터나 도구를 Agent에게 연결하는 역할입니다. (Kiro)

---

17. Headless — CI/CD 자동화

Kiro CLI는 터미널 대화 없이 한 번 실행하는 것도 가능합니다.

kiro-cli chat --no-interactive \
  "이 프로젝트의 보안 문제를 찾아줘"

Read/grep만 허용:

kiro-cli chat \
  --no-interactive \
  --trust-tools=read,grep \
  "src의 TODO를 전부 찾아줘"

모든 Tool 허용:

kiro-cli chat \
  --no-interactive \
  --trust-all-tools \
  "테스트를 만들고 실행해줘"

(Kiro)

CI에서는:

export KIRO_API_KEY=ksk_xxxxx

를 사용합니다.

예를 들어:

git diff | kiro-cli chat \
  --no-interactive \
  --trust-tools=read,grep \
  "이 변경사항을 코드 리뷰해줘"

같은 PR Review 자동화도 가능합니다. 공식 문서 역시 CI에서는 API Key를 secret으로 저장하고 --trust-all-tools보다 필요한 tool만 지정하는 것을 권장합니다. (Kiro)

---

18. 알아두면 좋은 단축키

키기능

Shift+Tab	Plan mode
Shift+Enter	여러 줄 Prompt
Ctrl+J	여러 줄 입력, 대부분 Terminal 지원
Ctrl+G	Subagent monitor
Ctrl+O	긴 Shell output 펼치기
Ctrl+S	명령/context 검색 및 queue steering
Esc	Agent 작업 취소
Tab	autocomplete / 승인 세부 옵션
Ctrl+D	CLI 종료

(Kiro)

---

제가 생각하는 Kiro CLI의 핵심 사용 흐름

처음 프로젝트를 열었으면 다음 순서가 가장 이해하기 쉽습니다.

cd project
     ↓
kiro-cli
     ↓
/guide
     ↓
프로젝트 분석
     ↓
.kiro/steering 작성
     ↓
@파일 + 일반 Prompt
     ↓
복잡하면 Shift+Tab
     ↓
큰 Feature면 /spec
     ↓
반복 실행이 필요하면 /goal
     ↓
테스트
     ↓
/rewind 또는 수정

특히 Steering + Plan + Spec + Goal + Skills 이 다섯 개를 이해하면 Kiro CLI를 단순한 Claude Code/Codex류의 “AI 터미널”이 아니라 프로젝트 개발 워크플로우 시스템으로 사용할 수 있습니다. Kiro 공식 문서도 CLI의 핵심 능력으로 Steering, Hooks, MCP, Custom Agents, Skills, Sub-agents, Models, Permissions 등을 같은 기반 기능으로 설명하고 있습니다. (Kiro)

이것만 외워도 됩니다

# 시작
kiro-cli

# 도움말
/guide

# 파일 지정
@src/auth.ts

# 계획
Shift+Tab

# 대형 기능
/spec new feature-name
/spec run feature-name

# 자율 반복
/goal --max 10 목표 + 완료조건

# Context
/context show

# 모델
/model

# Agent
/agent list
/agent swap agent-name

# 세션
/chat new
/chat resume

# 되돌리기
/rewind

# Context 압축
/compact

# 권한
/tools

# 비용 확인
/usage

# Shell
!npm test

이 정도가 Kiro CLI 입문 시 실제로 먼저 익힐 80~90%의 기능이라고 보면 됩니다. 특히 Kiro 특유의 기능을 하나만 꼽는다면 /spec, 그리고 최근 CLI에서 실전성이 높은 기능을 꼽는다면 /goal입니다. (Kiro)

Kiro CLI 공식 문서
Kiro CLI Slash Commands