Lab 00: 설치와 세션 준비

Kiro Crew 설치는 처음 한 번 진행하고, 세션 준비는 각 Lab을 시작할 때마다 반복합니다. 이 교육 폴더를 안전한 실습 대상으로 연결하고, 대시보드에서 실행 결과를 검증할 수 있는 상태를 만듭니다.

Kiro IDE 설치와 로그인(Pro 라이선스)은 별도 전달 자료를 따릅니다. 이 문서는 그다음 단계인 Kiro Crew 설치와 학생 실습 폴더 준비부터 다룹니다.

Kiro Crew가 읽고 쓸 수강생용 실습 레포를 클론합니다. 이 레포에는 각 Lab에서 사용할 fixture와 README가 미리 들어 있습니다.

Git이 설치되어 있어야 합니다. 아래 3번 사전 준비 절차에서 git --version으로 확인합니다.

macOS

mkdir -p "$HOME/Desktop/work"
cd "$HOME/Desktop/work"
git clone https://github.com/nxtcloud-edu/nxt-kirocrew-hands-on.git

Windows PowerShell

New-Item -ItemType Directory -Force "$HOME\Desktop\work" | Out-Null
Set-Location "$HOME\Desktop\work"
git clone https://github.com/nxtcloud-edu/nxt-kirocrew-hands-on.git

클론된 레포에는 이미 main 브랜치가 있으므로 별도로 git init이나 첫 커밋을 만들지 않습니다. cd로 클론된 폴더에 들어간 뒤 git status --short가 깨끗하고 git branch --show-current가 main을 출력하는지 확인합니다.

Kiro IDE에서 File → Open Folder...를 선택하고 클론한 ~/Desktop/work/nxt-kirocrew-hands-on 폴더를 엽니다. Windows에서는 C:\Users\<사용자명>\Desktop\work\nxt-kirocrew-hands-on를 선택합니다.

이제부터 설치 지시는 터미널이 아니라 클론한 폴더를 연 Kiro IDE의 채팅에서 진행합니다. 저장소의 SETUP.md에는 이 실습에 필요한 설치 순서와 확인 방법이 정리되어 있습니다.

Kiro IDE에서 폴더를 연 뒤, IDE 터미널에서 로그인 상태를 먼저 확인합니다.

kiro-cli whoami

Windows PowerShell에서도 같은 명령을 실행합니다.

kiro-cli whoami

결과에 따라 두 갈래입니다.

• 로그인된 계정이 출력되면 — 준비 완료입니다. 다음 단계로 갑니다.
• 명령을 찾을 수 없다고 나오면(command not found) — kiro-cli가 아직 설치되지 않은 것입니다. 이것도 에이전트에게 맡기는 것이 가장 확실합니다. Kiro IDE 채팅에 붙여넣습니다.

이 폴더의 SETUP.md에서 "0. 사전 요구 점검과 설치" 절차를 수행해 줘.
kiro-cli login 은 실행하지 마 — 로그인은 내가 직접 할게.
끝나면 0번의 완료 보고 형식으로 결과를 보여 줘.

설치가 끝나면 터미널에서 kiro-cli login으로 로그인하고, 다시 kiro-cli whoami로 계정을 확인한 뒤 진행합니다.

나머지 사전 요구도 같은 터미널에서 확인합니다.

git --version
python3 --version    # 3.12 이어야 합니다
brew --version       # macOS — uv 설치에 사용합니다

Windows는 git --version과 py -3.12 --version을 확인합니다. 하나라도 없으면 이것 역시 에이전트에게 설치를 맡길 수 있습니다 — 무엇이 없는지 말하고 설치를 요청하면 됩니다.

저장소의 SETUP.md에는 2. Kiro Crew 설치 절차가 들어 있습니다. Kiro IDE 채팅에 다음 프롬프트를 그대로 붙여넣습니다.

이 폴더의 SETUP.md 를 읽고 "0. 사전 요구 점검과 설치"와 "2. Kiro Crew 설치"를 순서대로 진행해 줘. kiro-cli login 과 kirocrew setup 은 실행하지 마 — 그건 내가 직접 할 거야. 끝나면 0번의 완료 보고 형식과 kirocrew --version 결과를 보여 줘.

에이전트가 SETUP.md의 절차를 읽고 설치 명령을 준비하는지 확인합니다. kirocrew setup은 이 단계에서 실행하지 않습니다.

이 과정의 기본 경로는 CLI 설치와 브라우저 대시보드입니다. CLI 설치가 환경 문제로 계속 실패하면 — 공식 다운로드 페이지(kiro.dev/downloads)의 Download Crew로 데스크톱 앱을 받아 실행하는 백업 경로가 있습니다. 앱은 같은 대시보드를 제공하므로 실습 화면 절차는 동일하게 진행되고, 터미널 검증 단계는 앱의 Terminal 메뉴나 강사 시연으로 대체합니다.

에이전트가 설치 명령을 실행하기 전에 승인 카드를 띄웁니다.

승인 카드에는 Allow · Always allow · Deny · Always deny 네 가지 버튼이 있습니다. 명령 내용을 확인하고 이번 설치에는 Allow를 선택합니다. 무조건 허용하는 것이 아니라, 지금 실행될 명령과 범위를 확인한 뒤 승인합니다.

이 승인은 Kiro IDE의 승인입니다. 이후 Gateway 대시보드에서 만나는 승인 카드는 별개의 승인 흐름입니다.

승인 후 에이전트가 설치 명령을 실행합니다.

진행 출력에는 설치 프로그램의 manifest 서명과 SHA-256 검증 문구가 표시됩니다. 설치가 진행되는 동안 kirocrew setup을 직접 실행하지 않고 완료 보고를 기다립니다.

설치가 끝나면 에이전트가 새 셸 기준으로 버전을 확인합니다.

kirocrew --version 결과가 출력되고, 에이전트가 **“setup은 직접 진행하시면 됩니다”**라고 안내합니다. 설치와 초기 설정의 경계를 지킨 장면입니다. 버전 숫자는 환경과 설치 시점에 따라 달라질 수 있으므로 본문에서는 특정 숫자를 기준으로 삼지 않습니다.

이제부터는 사람이 직접 대화형 초기 설정을 진행합니다. 에이전트 설치가 끝난 터미널에서 다음 명령을 입력합니다.

kirocrew setup

대화형 설정을 시작한다

설정이 시작되면 민감정보를 입력하지 말라는 경고와 함께 Workspace를 어디에 둘지 묻습니다.

Workspace 질문은 기본값으로 진행하려면 Enter를 누릅니다. setup의 Workspace는 LLM 세션과 Task 출력 저장소입니다. Dashboard가 읽고 수정할 실습 소스의 project_dir와 다르므로, 기본 Workspace를 교육 폴더 밖에 두는 것을 권장합니다.

SETUP.md 응답표와 대조하며 답한다

저장소의 SETUP.md 응답표를 옆에 열어 두고 화면의 질문에 하나씩 답합니다.

Timezone 질문이 나오면 응답표의 안내대로 답합니다. Slack 연동 질문은 n으로 답하고, 결과가 Skipped로 표시되는 것을 확인합니다. 설치 과정에서 실제 서비스 토큰이나 비밀번호 같은 민감정보는 입력하지 않습니다.

마지막 질문까지 완료한다

마지막 질문까지 답하면 Done과 함께 다음 단계로 kirocrew doctor와 kirocrew gateway를 실행하라는 안내가 나옵니다. 이 과정에서는 Playwright MCP가 자동 설치되며, Desktop app과 AWS 설정은 건너뜁니다.

doctor 결과를 확인한다

안내에 따라 다음 명령을 실행합니다.

kirocrew doctor

doctor에서는 kiro-cli 로그인, Kiro Crew agent config, kirocrew-core와 kirocrew-cron MCP 등록, Python runtime과 핵심 의존성을 확인합니다. project dir: not set, whisper: not found, Gateway 실행 전의 Gateway not running은 이 과정의 설치 실패로 단정하지 않습니다. Slack 미설정도 이 실습에서는 정상적인 상태입니다.

Gateway를 시작한다

kirocrew gateway

Gateway를 처음 실행하고 브라우저에서 http://localhost:5476을 열면, 이 컴퓨터에 있는 다른 AI 도구의 설정을 가져올지 묻는 Import Setup 화면이 나타날 수 있습니다.

이 과정에서는 Skip all을 누릅니다. Import Setup 화면이 나타나지 않으면 그대로 Gateway 화면으로 진행합니다.

에이전트 설치 흐름을 사용하지 않고 터미널에서 직접 설치하려면 다음을 실행합니다.

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh
exec zsh
command -v kirocrew
kirocrew --version

설치 프로그램 출력에서 manifest 서명, SHA-256, wheel 다운로드가 검증되었는지 확인합니다. command -v가 비어 있으면 다음을 실행한 뒤 새 셸에서 다시 확인합니다.

export PATH="$HOME/.local/bin:$PATH"
exec zsh
command -v kirocrew
kirocrew --version

직접 설치를 선택해도 kirocrew setup부터는 사람이 직접 진행합니다.

Windows에서 에이전트 설치 흐름을 사용하지 않고 직접 설치하려면 Kiro Crew 설치 안내에 따라 설치한 뒤 다음을 확인합니다.

kirocrew --version

그다음 사람이 직접 초기 설정을 진행합니다.

kirocrew setup
kirocrew doctor
kirocrew gateway

브라우저에서 기본 주소 http://localhost:5476을 엽니다.

Lab을 시작할 때마다 이 절차를 반복합니다. 새 세션은 매번 실습 폴더 밖에서 시작하기 때문입니다. 처음 한 번만 읽고, 이후에는 아래 세 줄 체크리스트를 확인하면 됩니다.

□ 새 세션을 만들었다
□ 하단 표시줄이  default · nxt-kirocrew-hands-on · main
□ 실행 모드가  Normal

사전 조건

• Gateway가 별도 터미널에서 실행 중이어야 합니다.
• 브라우저에서 http://localhost:5476에 접속해야 합니다.
• Git 브랜치는 main이고 작업 트리가 깨끗해야 합니다.

cd "$HOME/Desktop/work/nxt-kirocrew-hands-on"
git status --short

정상 상태에서는 git status --short에 출력이 없습니다.

1. 새 세션과 기본 폴더

+ New로 새 세션을 만듭니다. 새로 만든 세션은 실습 폴더에 연결되어 있지 않고, Kiro Crew 자체 데이터 폴더를 기본값으로 사용합니다.

세션 하단 표시줄도 확인합니다.

🤖 default    📁 workspace

📁 workspace는 /Users/<사용자명>/.kiro/crew/workspace이며 Git 브랜치가 표시되지 않습니다. 이 상태에서는 클론한 실습 폴더의 파일을 찾을 수 없습니다.

제안 칩의 조건을 구분합니다. 새로 설치한 직후에는 일반적인 제안이 표시됩니다. 과거 세션이 있는 환경에서는 과거 기록을 바탕으로 만든 제안 칩이 표시될 수 있습니다. 어느 경우든 칩이 아니라 표시줄을 기준으로 연결 상태를 확인합니다.

처음 접속하면 상단에 Privacy at a glance 배너가 나타날 수 있습니다. 내용을 읽고 Dismiss를 눌러 닫습니다.

2. 프로젝트 폴더 연결

하단의 폴더 칩을 클릭하면 프로젝트 디렉터리 선택기가 열립니다.

새로 설치한 직후에는 Recent가 비어 있어 Browse 탭이 열립니다. 경로 입력창에 클론한 폴더 경로를 직접 입력하거나 폴더 목록을 타고 들어가 선택합니다.

/Users/<사용자명>/Desktop/work/nxt-kirocrew-hands-on

경로를 입력하고 Select를 누릅니다. Windows에서는 클론한 nxt-kirocrew-hands-on 폴더의 실제 경로를 입력합니다.

🤖 default    📁 nxt-kirocrew-hands-on    · main

main 브랜치가 나타나는 것이 연결 성공의 즉각적인 신호입니다. 브랜치가 없으면 Git 저장소가 아닌 곳에 연결된 것입니다.

표시	의미
🤖 default	이 세션이 사용하는 Crew(에이전트)
📁 nxt-kirocrew-hands-on	연결된 프로젝트 폴더(project_dir)
· main	그 폴더의 Git 브랜치

일반적인 교훈: 이름이 비슷한 폴더가 있으면 잘못 고르기 쉽습니다. 화면은 열려도 실습 파일을 찾지 못할 수 있으므로, 연결 후 표시줄의 폴더 이름과 Git 브랜치를 항상 대조합니다.

3. 실행 모드 확인

입력창의 모드 칩을 클릭합니다.

모드	동작
Normal	무엇이든 하기 전에 확인 — 모든 실습의 필수 설정
Reads	조회는 스스로, 변경 전에만 확인
Trust	이 채팅에서는 묻지 않음
YOLO	모든 채팅에서 묻지 않음

Normal인지 확인하고 닫습니다. Trust나 YOLO이면 승인 카드가 나타나지 않아 승인 경계를 다루는 실습이 성립하지 않습니다.

이 과정의 몇몇 실습은 시스템이 깨끗한 상태를 전제합니다. 이 노트북을 이전에 사용한 적이 있다면 그 흔적이 남아 있을 수 있습니다. 첫 실습 전에 다음 상태를 확인합니다.

kirocrew learn list                # 기록해 둡니다 — 종료 시 이 목록과 비교
kirocrew cron list                 # No cron jobs. 여야 함

화면	사전 정상 상태
Knowledge	0 items (Artifacts 기본 소스는 무관)
Schedule	No scheduled jobs yet
Crews	기본 크루만 — 실습 크루는 Lab 1에서 만듭니다