Kiro IDE 사용법 완전 정복: 설치부터 스펙, 스티어링, 파이썬 실습까지

Kiro 설치부터 첫 실행까지

Kiro는 AWS가 만든 AI 통합개발환경(IDE)으로, VS Code와 유사한 인터페이스에 에이전트 기반 코딩 기능이 결합된 형태다. 설치와 첫 실행 절차는 다음과 같다.

  1. Kiro 공식 웹사이트에서 운영체제(Windows / macOS / Linux)에 맞는 설치 파일을 내려받는다.
  2. 설치 파일을 실행해 일반적인 프로그램 설치 절차를 따른다. VS Code를 설치해본 적이 있다면 화면 구성이 낯설지 않다.
  3. 설치가 끝나면 Kiro를 실행하고, 로그인 화면이 뜬다.

로그인(사인인) 방법

Kiro는 몇 가지 방식으로 로그인할 수 있다.

  • AWS Builder ID: AWS 계정과 별개로 무료로 만들 수 있는 개인 ID. AWS 계정이 없어도 이메일만으로 발급 가능하다.
  • 소셜 로그인: Google 계정 등으로 간편 로그인.
  • AWS IAM Identity Center: 회사에서 AWS 조직 계정을 쓰는 경우, 관리자가 설정한 SSO로 로그인.

처음 시작한다면 AWS Builder ID로 가입하는 게 가장 빠르다. 이메일을 입력하고 인증 코드를 받아 확인한 뒤, 이름과 비밀번호를 설정하면 몇 분 안에 계정이 만들어진다. 로그인이 완료되면 Kiro 메인 화면이 열리고, 왼쪽에는 파일 탐색기, 가운데에는 에디터, 오른쪽 또는 하단에는 AI 채팅/에이전트 패널이 배치된다. VS Code를 써봤다면 단축키 대부분(파일 저장 Ctrl+S, 명령 팔레트 Ctrl+Shift+P 등)이 동일하게 작동해서 적응이 빠르다.

첫 프로젝트 만들기 (Create New Project)

Kiro에서 새 프로젝트를 시작하는 방법은 두 가지다.

방법 1 — 빈 폴더 열기

시작 화면에서 "Open Folder"를 선택해 미리 만들어둔 빈 폴더를 연다. 이후 채팅 패널에 원하는 프로젝트를 자연어로 설명하면 Kiro가 파일 구조를 제안하고 만들어준다.

방법 2 — 템플릿에서 시작

시작 화면의 "New Project" 또는 "Create New Project" 버튼을 누르면 언어/프레임워크별 템플릿 목록이 뜬다. Python, Node.js, React 등 자주 쓰는 스택의 기본 템플릿이 준비되어 있어서, 하나를 고르면 기본 폴더 구조와 설정 파일(예: requirements.txt, package.json)이 자동 생성된다.

프로젝트를 열면 하단 또는 사이드바에 채팅 입력창이 있다. 여기에 "할 일 관리 API를 FastAPI로 만들어줘"처럼 원하는 작업을 문장으로 입력하면 에이전트가 작업을 시작한다.

Kiro의 핵심 개념 1 — 스펙(Spec)

Kiro를 다른 AI 코딩 도구와 구분 짓는 가장 큰 특징이 스펙 기반 워크플로우다. 채팅창에 기능 요청을 입력하면, Kiro는 곧바로 코드를 쓰지 않고 먼저 세 개의 문서를 순서대로 만들어 보여준다.

  1. requirements.md — 무엇을 만들 것인지, 사용자 스토리와 수용 기준을 정리한 문서. "사용자는 할 일을 추가할 수 있어야 한다", "완료된 할 일은 목록에서 취소선으로 표시된다" 같은 형태로 구체화된다.
  2. design.md — 어떻게 만들 것인지, 아키텍처와 데이터 모델, API 엔드포인트, 폴더 구조 등을 정리한 설계 문서.
  3. tasks.md — 실제 구현 순서를 체크리스트로 쪼갠 작업 목록. 각 항목을 완료할 때마다 체크 표시가 되어 진행 상황을 한눈에 볼 수 있다.

이 문서들은 에디터 안에서 마크다운 파일로 그대로 열람·수정할 수 있다. 사용자가 각 단계에서 "이대로 진행"을 누르거나, 마음에 안 드는 부분을 직접 고쳐서 승인하면 다음 단계로 넘어간다. tasks.md가 승인되어야 비로소 실제 코드 작성이 시작된다. 이 절차 덕분에 요구사항을 잘못 이해한 채로 엉뚱한 코드가 대량으로 생성되는 사고를 줄일 수 있다.

Kiro의 핵심 개념 2 — 스티어링(Steering, Instructions)

스펙이 "기능 하나하나"에 대한 계획이라면, 스티어링 파일은 "프로젝트 전체"에 적용되는 규칙이다. 검색 유입으로 많이 들어오는 "kiro instructions"가 바로 이 스티어링 기능을 가리킨다.

프로젝트 루트의 .kiro/steering/ 폴더에 마크다운 파일을 만들어두면, Kiro가 코드를 생성할 때마다 이 내용을 항상 참고한다. 예를 들면 다음과 같은 내용을 담을 수 있다.

  • 코딩 컨벤션: "함수명은 항상 스네이크 케이스로 작성한다"
  • 아키텍처 원칙: "데이터베이스 접근은 반드시 repository 레이어를 거친다"
  • 기술 스택 제약: "외부 HTTP 요청은 requests 대신 httpx를 사용한다"
  • 테스트 규칙: "새 함수를 추가하면 반드시 대응하는 pytest 테스트를 작성한다"

스티어링 파일은 여러 개로 나눠 관리할 수 있고, 특정 파일 패턴에만 적용되도록 범위를 지정하는 것도 가능하다. 예를 들어 backend/ 폴더 관련 규칙과 frontend/ 폴더 관련 규칙을 별도 파일로 분리해두면, Kiro가 작업 중인 영역에 맞는 규칙만 적용한다. 이 기능을 잘 활용하면 매번 채팅창에 "이렇게 짜줘, 저렇게 짜지 마"를 반복 입력할 필요가 없어진다.

Python 프로젝트로 직접 따라 해보기

가장 많이 찾는 "kiro python" 활용을 실제 단계로 정리하면 다음과 같다.

1. 프로젝트 생성

시작 화면에서 "New Project"를 선택하고 Python 템플릿을 고른다. 또는 빈 폴더를 열고 채팅창에 "Python으로 콘솔 기반 가계부 프로그램을 만들고 싶어"처럼 입력해도 된다.

2. 가상환경 준비

Kiro 하단에는 통합 터미널이 있다. VS Code와 동일하게 여기서 명령어를 직접 실행할 수 있다.

python -m venv venv
venv\Scripts\activate   # Windows
source venv/bin/activate  # macOS/Linux

3. 요구사항을 채팅으로 전달

채팅 패널에 구체적으로 요청한다. 예: "지출 항목을 입력받아 CSV로 저장하고, 월별 합계를 출력하는 CLI 프로그램을 만들어줘. 입력값 검증도 포함해줘." Kiro는 이를 바탕으로 requirements.md를 먼저 생성해 화면에 보여준다.

4. requirements.md 검토

생성된 요구사항 문서를 읽고, 빠진 부분이 있으면 직접 수정하거나 채팅으로 "환불(마이너스 금액) 입력도 허용해줘" 같은 피드백을 준다. 만족스러우면 승인해 다음 단계로 넘어간다.

5. design.md 검토

설계 문서에는 보통 다음과 같은 내용이 담긴다.

  • 파일 구조 (예: main.py, expense.py, storage.py)
  • 데이터 모델 (지출 항목의 필드: 날짜, 금액, 카테고리, 메모)
  • 함수/클래스 설계 개요

여기서도 원하는 라이브러리(예: pandas 대신 표준 라이브러리 csv 모듈 사용)를 지정하고 싶다면 이 단계에서 요청하는 게 효율적이다.

6. tasks.md 승인 후 코드 생성

작업 목록이 만들어지고 승인하면, Kiro가 각 작업을 순서대로 진행하며 실제 .py 파일들을 작성한다. 진행되는 동안 에디터에서 실시간으로 파일이 채워지는 걸 볼 수 있고, 작업이 끝날 때마다 tasks.md의 체크박스가 자동으로 업데이트된다.

7. 실행과 디버깅

터미널에서 바로 실행해본다.

python main.py

에러가 나면 에러 메시지를 복사해서 채팅창에 붙여넣고 "이 에러 고쳐줘"라고 요청하면, Kiro가 관련 파일을 찾아 원인을 분석하고 수정안을 제시한다. 이때도 수정 범위가 큰 경우 자동으로 새 작업 항목을 tasks.md에 추가하기도 한다.

8. 테스트 추가

스티어링 파일에 "테스트 코드를 항상 작성한다"는 규칙을 미리 넣어뒀다면, 새 기능을 요청할 때마다 pytest 기반 테스트 파일이 함께 생성된다. 그렇지 않다면 "expense.py에 대한 pytest 테스트를 작성해줘"라고 별도로 요청하면 된다.

자주 막히는 부분과 해결 팁

  • 스펙 문서 승인 단계가 번거롭게 느껴질 때: 간단한 스크립트 하나 정도의 작업이라면 채팅에서 "스펙 없이 바로 코드 작성해줘"라고 요청하면 간이 모드로 진행되는 경우가 많다. 다만 이 경우 설계 검토 없이 바로 코드가 나오므로, 결과물을 더 꼼꼼히 확인해야 한다.
  • 크레딧이 빨리 줄어드는 느낌일 때: 스펙 문서 생성과 코드 생성이 각각 별도의 요청으로 처리되기 때문에, 큰 기능을 한 번에 요청하는 것보다 작업을 작게 쪼개 순차적으로 요청하는 편이 크레딧 관리에 유리하다.
  • 기존 프로젝트에 Kiro를 붙일 때: 이미 코드가 있는 저장소를 열면, 채팅에 "이 프로젝트 구조를 분석해줘"라고 요청해 먼저 코드베이스를 파악시키는 게 좋다. 이후 스티어링 파일에 기존 프로젝트의 컨벤션을 정리해두면 이어지는 작업의 일관성이 크게 좋아진다.
  • 팀과 함께 쓸 때: .kiro/ 폴더(스펙, 스티어링 파일 포함)를 Git 저장소에 함께 커밋해두면, 팀원 모두가 동일한 설계 문서와 규칙을 공유하면서 작업할 수 있다.

단축키와 화면 구성 익히기

Kiro는 VS Code 계열 UI를 그대로 채택했기 때문에 기존에 쓰던 단축키가 대부분 그대로 통한다.

  • Ctrl+P (macOS는 Cmd+P): 파일 빠르게 열기
  • Ctrl+Shift+P: 명령 팔레트 열기, Kiro 전용 명령(스펙 새로 만들기, 스티어링 파일 열기 등)도 여기서 검색 가능
  • Ctrl + 백틱 키: 통합 터미널 열기/닫기
  • Ctrl+B: 사이드바(파일 탐색기) 접기/펼치기

채팅/에이전트 패널은 보통 오른쪽 사이드바나 하단 패널로 열 수 있고, 명령 팔레트에서 "Kiro: Open Chat" 같은 명령을 검색해도 바로 열린다. 여러 개의 대화 세션을 탭처럼 구분해서 관리할 수 있어서, 기능별로 대화를 나눠두면 나중에 특정 기능을 다시 손볼 때 관련 대화 기록을 빠르게 찾을 수 있다.

확장 프로그램과 연동

Kiro는 VS Code 확장 마켓플레이스와 완전히 동일하지는 않지만, 자체 확장 기능과 일부 호환 확장을 지원한다. Python 개발이라면 린터(예: ruff, flake8)나 포매터(black) 확장을 설치해 코드 스타일을 자동으로 맞출 수 있고, Kiro 에이전트가 코드를 생성할 때도 이런 린트 규칙을 스티어링 파일에 명시해두면 처음부터 규칙에 맞는 코드를 뽑아준다. Git 연동도 기본으로 내장되어 있어서, 사이드바에서 변경 사항을 확인하고 커밋 메시지를 작성할 수 있으며, 에이전트에게 "지금까지 변경한 내용으로 커밋 메시지를 작성해줘"라고 요청하는 것도 가능하다.

MCP(외부 도구 연결)로 확장하기

Kiro도 Model Context Protocol(MCP)을 지원해서, 데이터베이스 조회, 외부 API 호출, 사내 문서 검색 같은 외부 도구를 에이전트에 연결할 수 있다. 설정 파일(.kiro/settings/mcp.json 형태)에 사용할 MCP 서버 정보를 등록해두면, 스펙 작성이나 코드 생성 과정에서 에이전트가 필요할 때 해당 도구를 직접 호출한다. 예를 들어 사내 API 문서를 제공하는 MCP 서버를 연결해두면, "이 API 스펙에 맞춰 클라이언트 코드를 만들어줘"라는 요청에 실제 최신 문서를 참고해 정확한 코드를 생성할 수 있다.

기존 코드베이스에 스펙을 나중에 적용하기

이미 어느 정도 완성된 프로젝트에 Kiro를 도입하는 경우, 처음부터 스펙 문서를 다시 쓸 필요는 없다. 새로 추가할 기능 단위로만 스펙을 적용하면 된다. 예를 들어 기존 Flask 프로젝트에 로그인 기능을 새로 추가한다면, 채팅에 "로그인/회원가입 기능을 추가하고 싶어. 기존 프로젝트 구조를 참고해서 스펙을 만들어줘"라고 요청한다. Kiro는 먼저 기존 코드를 스캔해 프레임워크, 폴더 구조, 코딩 스타일을 파악한 뒤, 그에 맞춰 requirements.md와 design.md를 작성한다. 이렇게 새 기능 단위로만 스펙을 쌓아가면, 프로젝트가 커질수록 .kiro/specs/ 폴더 안에 기능별 설계 이력이 자연스럽게 축적된다.

여러 명이 같은 프로젝트에서 작업할 때

팀 프로젝트에서는 .kiro/ 폴더를 Git으로 함께 관리하는 게 핵심이다. 한 팀원이 새 기능의 스펙을 작성해 커밋해두면, 다른 팀원은 별도 설명을 듣지 않아도 requirements.md와 design.md만 읽으면 무엇을, 왜 그렇게 만들었는지 파악할 수 있다. 코드 리뷰 단계에서도 "이 구현이 design.md의 설계와 일치하는가"를 기준으로 리뷰하면 논의가 훨씬 구체적으로 진행된다. 스티어링 파일도 마찬가지로 커밋해두면, 새로 합류한 팀원이 Kiro를 처음 켰을 때부터 팀의 코딩 컨벤션을 자동으로 따르게 된다.

버전 관리와 Git 연동

Kiro의 소스 제어 패널은 VS Code의 Git 통합과 동일한 방식으로 동작한다. 변경된 파일이 왼쪽 사이드바에 표시되고, 파일별로 diff를 확인한 뒤 스테이징, 커밋, 푸시를 진행할 수 있다. 에이전트가 여러 파일을 한 번에 수정했을 때는 diff 뷰에서 실제로 어떤 줄이 바뀌었는지 하나하나 검토하는 습관을 들이는 게 중요하다. 특히 tasks.md에서 여러 작업이 순차적으로 진행된 경우, 커밋을 작업 단위로 잘게 나눠두면 나중에 특정 변경만 되돌리기가 쉬워진다.

정리

Kiro를 처음 쓸 때 핵심은 세 가지다. 첫째, AWS Builder ID로 가입하고 템플릿이나 빈 폴더로 프로젝트를 시작한다. 둘째, 채팅으로 기능을 요청하면 requirements → design → tasks 순서로 문서가 만들어지므로, 코드가 바로 안 나온다고 당황하지 말고 각 단계를 검토하며 승인한다. 셋째, 반복되는 규칙은 .kiro/steering/ 폴더에 정리해두면 매번 같은 지시를 반복하지 않아도 된다. Python 프로젝트든 다른 언어든 이 흐름은 동일하게 적용되며, 이 구조에 익숙해지면 혼자 개발할 때도 설계 문서가 자연스럽게 남는다는 게 Kiro의 가장 큰 실무적 이점이다.

koenjaesfr