Lab 03: 기억을 파일로 남긴다

세션이 끝나도 남아야 할 것을 어디에 두는가?

Lab 1에서 확인했듯 메모리 스토어는 새로 만들 수 없습니다. 크루를 나눠도 시스템 기억은 한 곳에 공유됩니다. 이 랩에서는 그 대안으로 나눌 수 있고, 눈에 보이고, 커밋할 수 있는 파일 기억 두 가지를 직접 만듭니다. 항상 적용되는 규칙인 Steering과 다음 세션에 작업을 넘기는 인계 문서입니다. 시스템이 알아서 저장하는 레슨 메모리와도 비교합니다.

• Steering 파일을 만들어 모든 세션에 적용되는 규칙을 설정합니다.
• Workspace 스코프의 Steering이 저장소에 커밋 가능한 파일로 남는 것을 확인합니다.
• 스킬(요청 시 로드)과 Steering(항상 적용)의 차이를 화면에서 구분합니다.
• 인계 문서를 만들어 새 세션이 작업을 이어받게 합니다.
• 파일 기억과 시스템 레슨 메모리의 성격 차이를 정리합니다.

공통 준비를 먼저 수행합니다.

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

이 실습만의 조건입니다.

• 이 실습의 세션들은 default 크루 + 프로젝트 폴더(nxt-kirocrew-hands-on) 연결로 진행합니다. 파일 기억은 공유된 폴더가 전제이기 때문입니다.
• Git 작업 트리 상태를 실습 전에 확인해 둡니다. 마지막에 무엇이 새로 생겼는지 봅니다.

Agent Capabilities → Steering을 엽니다.

화면 상단의 설명이 Steering의 정의입니다.

Always-on markdown conventions from ~/.kiro/steering and your project's .kiro/steering

번역: ~/.kiro/steering과 프로젝트의 .kiro/steering에 있는 항상 적용되는 마크다운 규칙입니다.

아직 파일이 없으므로 빈 상태 안내도 함께 보입니다.

No steering files yet
Steering files are always-on markdown conventions.
Looked in: ~/.kiro/steering · ~/Desktop/work/nxt-kirocrew-hands-on/.kiro/steering

번역: 아직 Steering 파일이 없습니다. Steering 파일은 항상 적용되는 마크다운 규칙입니다. 다음 두 경로를 탐색했습니다.

두 가지 정보가 있습니다.

• always-on — 스킬은 요청할 때 로드되지만, Steering은 모든 세션에 항상 주입됩니다.
• 두 개의 탐색 경로 — 홈 디렉터리(모든 프로젝트)와 연결된 프로젝트 폴더(이 프로젝트만)입니다.

주의: Looked in에 프로젝트 경로가 안 보이면. 이 화면은 열려 있는 세션들의 폴더 연결을 봅니다. 프로젝트 폴더에 연결되지 않은 세션이 하나라도 열려 있으면, 어느 프로젝트인지 모호하다고 판단해 홈 경로만 보여줍니다 — 엉뚱한 저장소에 파일을 만드는 것을 막는 동작입니다. Sessions 목록에서 프로젝트 폴더가 연결되지 않은 세션을 지우고 이 화면을 새로고침합니다.

New Steering File을 누릅니다.

Scope를 먼저 정합니다

선택지	파일이 생기는 곳	적용 범위
Workspace — this project only	프로젝트의 .kiro/steering/	이 프로젝트에 연결된 세션
Global — every project	~/.kiro/steering/	모든 세션

Workspace를 선택합니다. 이 선택이 이 실습의 핵심입니다. 파일이 저장소 안에 생깁니다.

파일을 작성합니다

필드	입력
File name	nxt-response-style.md
Scope	Workspace — this project only

Content 입력란에는 # Title과 Describe the convention... 줄이 미리 들어 있습니다.

함정. 이 두 줄은 안내문처럼 보이지만 지우지 않으면 그대로 저장됩니다. 전체 선택(Cmd/Ctrl+A) 후 지우고 시작합니다.

지운 자리에 규칙을 씁니다. 파일명이 제목 역할을 하므로 제목 줄 없이 규칙만 써도 됩니다.

- 모든 답변의 첫 줄은 [NXT] 로 시작한다.
- 답변 마지막 줄에는 검증: 확인 N건 / 미확인 N건 요약을 붙인다.

일부러 눈으로 즉시 확인되는 규칙을 골랐습니다. Create를 누릅니다.

상세 화면에 저장 경로가 표시되고 목록 카드에는 첫 규칙이 설명처럼 붙습니다.

~/Desktop/work/nxt-kirocrew-hands-on/.kiro/steering/nxt-response-style.md

저장소에서 확인합니다

내장 터미널에서 확인합니다.

cd ~/Desktop/work/nxt-kirocrew-hands-on && git status --short

?? .kiro/

.kiro/는 세션이 만든 메타 폴더입니다. Git은 미추적 폴더를 최상위로 합쳐 보여주므로 ?? .kiro/ 한 줄로 나옵니다. 방금 만든 파일이 그 안에 있는지는 다음 명령으로 확인할 수 있습니다.

ls .kiro/steering/

이 실습의 첫 번째 결론입니다. Workspace 스코프의 Steering은 저장소 안의 마크다운 파일입니다. Git이 추적하고, 커밋하면 이력이 남고, 팀원이 클론하면 같은 규칙을 받습니다. 에이전트의 규칙이 코드와 같은 방식으로 관리됩니다.

Apply & Restart를 누릅니다.

새 세션을 만들고 프로젝트 폴더를 연결한 뒤, 규칙과 아무 상관 없는 요청을 보냅니다.

이 폴더 README.md의 첫 번째 제목 한 줄만 알려 줘. 파일은 수정하지 마.

새 세션의 제안 칩이 한국어 업무 문구로 바뀌어 있을 수 있습니다. 과거 세션 기록으로 만들어지는 개인화 제안입니다. 칩이 아니라 표시줄로 연결 상태를 확인하는 습관은 그대로입니다.

먼저 예측해 보세요 — 답변이 어떤 모양일까요? 스킬 때처럼 로드 표시가 뜰까요?

[NXT] /Users/<사용자명>/Desktop/work/nxt-kirocrew-hands-on/README.md 의 첫 번째 제목 한 줄은
다음과 같습니다.

AI 에이전트 크루 실습 파일

파일은 수정하지 않았습니다.
검증: 확인 1건 / 미확인 0건

번역: 파일을 수정하지 않고 첫 번째 제목을 확인했으며, 확인 1건과 미확인 0건이라는 검증 요약을 덧붙였다는 뜻입니다.

두 규칙이 모두 적용됐습니다. 첫 줄 [NXT], 마지막 줄 검증 요약입니다. 이번 응답에서 확인한 README의 제목은 AI 에이전트 크루 실습 파일입니다.

그리고 로드 표시가 없습니다. 스킬은 Loaded skill(s) via $가 떴지만, Steering은 아무 표시 없이 적용됩니다. 요청에 트리거도, $ 지정도 없었습니다.

스킬과 나란히 놓습니다

	스킬	Steering
적용 시점	트리거·$ 지정 시	항상
화면 표시	Loaded skill(s) via $	없음
컨텍스트 비용	로드될 때만	모든 세션에서
알맞은 내용	특정 작업의 절차	모든 답변에 적용할 규칙

이 실습의 두 번째 결론입니다. 절차는 스킬로, 규칙은 Steering으로 둡니다. 항상 적용된다는 것은 항상 컨텍스트를 차지한다는 뜻이기도 합니다. Steering에는 짧은 규칙만 둡니다.

추가 미션 — 건방진 AI 만들기

Steering이 바꾸는 것은 형식만이 아닙니다. 태도도 규칙 한 줄입니다. Steering에서 nxt-response-style.md를 Edit로 열고 규칙을 하나 추가합니다.

- 모든 답변은 "알겠습니까 휴먼?" 이라는 건방진 인사로 끝낸다.

Save 후 Apply & Restart를 누르고 새 세션에서 아무 질문이나 보냅니다. 예를 들어 다음과 같이 요청합니다.

labs 폴더에 뭐가 있나요?

이 화면에서 두 가지를 관찰합니다.

1. 말투가 바뀌었습니다. 파일 한 줄이 에이전트의 인격을 바꿉니다. 규칙을 지우고 다시 적용하면 원래대로 돌아옵니다. 추가도 제거도 파일 편집 한 번입니다.
2. 규칙끼리 충돌할 수 있습니다. 기존 규칙은 마지막 줄에 검증 요약을 요구하고, 새 규칙은 마지막에 인사를 요구합니다. 이번 실행에서는 모델이 검증 요약 다음, 진짜 마지막에 인사를 두는 것으로 정리했습니다. 다르게 정리될 수도 있습니다. 충돌의 해석은 모델의 몫이고 보장이 없습니다. 순서까지 통제하려면 규칙에 순서를 명시해야 합니다.

실습을 마치면 인사 규칙 줄은 지우고 Apply & Restart로 되돌립니다. 검증 요약 규칙은 이후 랩에서 계속 사용합니다.

보장이 필요하면 — Hooks

방금 결론이 “충돌의 해석은 모델의 몫이고 보장이 없습니다”였습니다. 그렇다면 어겨지면 안 되는 규칙은 어디에 두어야 할까요?

Steering 바로 아래 메뉴, Agent Capabilities → Hooks를 엽니다.

화면 상단의 정의문을 읽습니다.

Shell commands that run automatically on agent events
like prompts, tool calls, and session start/stop

번역: 프롬프트, 도구 호출, 세션 시작·종료 같은 에이전트 이벤트에서 자동으로 실행되는 셸 명령입니다.

Steering은 모델에게 전달되는 문장이고, 훅은 시스템이 실행하는 셸 명령입니다. 문장은 모델이 해석하지만, 명령은 이벤트가 발생하면 실행됩니다.

두 가지를 관찰합니다.

• 카운터가 전부 0입니다 — TOTAL 0 · ENABLED 0 · TOTAL RUNS 0 · ERRORS 0. 아직 아무 훅도 만들지 않았습니다.
• 아래 ACP Agent Hooks 표에는 이미 한 줄이 있습니다. PostToolUse 이벤트에 execute_bash matcher, 🔒 bundled 표시입니다. 시스템이 셸 명령 실행 시 타임스탬프를 기록하는 훅을 이미 사용하고 있습니다.

직접 하나 만들어 봅니다. + New Hook을 누르면 인라인 폼이 열립니다.

폼은 다섯 칸입니다.

칸	의미
Hook name	훅 이름
이벤트 드롭다운	언제 실행할지 — 기본값 UserPromptSubmit
커맨드	실행할 셸 명령 — 예시로 echo 'hook fired'가 보입니다
Matcher (optional)	이벤트를 더 좁히는 패턴 — 예시 *deploy*
Timeout	명령 제한 시간, 기본 30초

Matcher와 Timeout은 코드의 어휘입니다 — “어떤 경우에”를 패턴으로, “얼마나 기다릴지”를 초로 지정합니다. 문장으로 규칙을 쓸 때는 이런 것을 정할 수 없었습니다.

이벤트 드롭다운을 열어 봅니다.

다섯 개입니다 — 에이전트의 한 턴이 흘러가는 순서 그대로입니다.

이벤트	시점
AgentSpawn	에이전트가 시작될 때
UserPromptSubmit	사용자가 메시지를 보낼 때
PreToolUse	도구가 실행되기 직전
PostToolUse	도구가 실행된 직후
Stop	턴이 끝날 때

PreToolUse에 주목합니다. 도구가 실행되기 전에 끼어들 수 있는 유일한 지점이라, 위험한 명령을 실행 전에 검사해 막는 훅이 이 이벤트에 걸립니다.

메시지를 보낼 때마다 로그 한 줄을 남기는 훅을 등록합니다.

칸	입력
Hook name	nxt-prompt-log
이벤트	UserPromptSubmit (기본값 그대로)
커맨드	아래 macOS 명령을 붙여 넣습니다
Matcher	비움
Timeout	30 그대로

echo "$(date '+%Y-%m-%d %H:%M:%S') 프롬프트 제출" >> ~/Desktop/work/nxt-kirocrew-hands-on/.kiro/hook-log.txt

훅 커맨드는 셸 문법 그대로입니다. 위 명령은 macOS 기준입니다 — Windows는 훅이 PowerShell로 실행되므로 date·>> 같은 bash 문법이 통하지 않습니다. 아래 한 줄을 대신 붙여 넣습니다.

powershell -NoProfile -Command "Add-Content -Path \"$env:USERPROFILE\Desktop\work\nxt-kirocrew-hands-on\.kiro\hook-log.txt\" -Value \"$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') 프롬프트 제출\""

Save를 누릅니다. 저장 전에는 아무 일도 일어나지 않습니다 — 폼만 채우고 화면을 떠나면 훅은 없습니다. 저장되면 목록에 행이 생기고 카운터가 TOTAL 1 · ENABLED 1로 바뀝니다.

행에 토글(켜짐)과 RUNS 0 · LAST RUN never, 그리고 Test · Edit · Delete 버튼이 보입니다. 목록의 커맨드에 >>가 >>로 표시되는데, 표시만 그렇고 저장된 명령은 정상입니다.

Test를 눌러 봅니다.

Test Result: nxt-prompt-log  OK  30ms

RUNS가 1이 됐습니다 — 테스트 실행도 집계됩니다. (실행 시간 수치는 매번 다릅니다.) 이제 Apply & Restart 후 세션에서 아무 메시지나 두 번 보내고 Hooks 화면으로 돌아옵니다.

TOTAL RUNS 3 · ERRORS 0 · STATUS OK

로그 파일을 열어 봅니다.

2026-08-10 23:14:30 프롬프트 제출     ← Test
2026-08-10 23:14:57 프롬프트 제출     ← 첫 메시지
2026-08-10 23:15:08 프롬프트 제출     ← 두 번째 메시지

보낸 메시지 수 = 실행 수 = 로그 줄 수. 훅은 이벤트가 나면 실행되고 TOTAL RUNS가 정확히 셉니다.

이번엔 훅을 화제로 직접 꺼내 봅니다. 같은 세션에 보냅니다.

훅 사용 테스트 중이야

에이전트가 웹훅이나 Git 훅 이야기를 꺼낼 수 있습니다 — 답변 내용은 실행마다 다르지만, 어느 쪽이든 방금 자기에게 실행된 훅은 언급하지 못합니다.

에이전트는 자기에게 걸린 훅을 모릅니다. 훅은 실행됐지만 모델의 지식과 훅의 실행은 서로 다른 층에 있습니다. Steering은 모델의 컨텍스트로 들어가지만, 훅의 존재와 실행 기록은 모델에게 전달되지 않습니다.

훅은 어디에 저장됐을까요? git status를 봐도 변화가 없습니다. Steering 파일은 저장소 안에 생겨 커밋으로 팀과 공유할 수 있지만, 훅은 시스템 설정(~/.kiro/crew/hooks.json)입니다. 각자의 시스템에 각자 존재합니다.

	Steering	Hooks
정체	모델에게 주는 문장	시스템이 실행하는 명령
작동	모델이 읽고 해석	이벤트 발생 시 실행
어겨지면	조용히 무시될 수 있음	실행 실패가 ERRORS에 남음
알맞은 규칙	어조·형식·판단 기준	로깅·검증·강제 규칙

이 실습의 세 번째 결론입니다. 지켜졌으면 하는 규칙은 Steering에, 어겨지면 안 되는 규칙은 Hooks에 둡니다. 중요한 규칙은 둘 다 씁니다 — Steering에 적어 두고, 훅으로 한 번 더 확인합니다.

추가 미션 — 잊지 않는 안전망

로그 훅은 원리 확인용이었습니다. 이번엔 실제로 쓸 만한 훅을 만듭니다.

이 실습의 주제는 “기억을 파일로 남긴다”입니다. 세션을 급히 닫으면서 기록을 잊는 날이 생길 수 있습니다. Steering에 규칙을 적어 둘 수도 있지만 문장은 잊힐 수 있습니다. 잊히면 안 되는 리마인더는 훅에 겁니다.

nxt-prompt-log 행의 Edit를 눌러 세 가지를 바꿉니다.

칸	입력
이름	nxt-handoff-reminder
이벤트	Stop
커맨드	아래 한 줄을 그대로 복사해 붙여 넣습니다

macOS:

osascript -e 'display notification "이 세션의 작업, 파일로 남겼습니까?" with title "Kiro Crew"'

Windows에서는 아래 커맨드를 대신 사용합니다. 환경에 따라 팝업 동작이 다를 수 있습니다. (팝업이 안 뜨면 앞의 로그 훅으로 대체합니다. macOS에서 알림이 안 보이면 시스템 설정의 알림 권한과 집중 모드를 확인합니다.)

powershell -Command "(New-Object -ComObject Wscript.Shell).Popup('이 세션의 작업, 파일로 남겼습니까?',5,'Kiro Crew')"

Save 후 Apply & Restart를 누릅니다. 세션에서 아무 요청이나 하나 보내고 답변이 끝나기를 기다립니다.

답변이 끝나는 순간 macOS 알림이 올라옵니다. Stop은 세션을 닫을 때가 아니라 매 턴이 끝날 때 발생합니다. 작업을 마무리하는 모든 순간에 리마인더가 옵니다.

이제 모델이 규칙을 기억하든 잊든 기록을 남겼는지 묻는 알림이 옵니다. 규칙을 지키라고 모델에게 부탁하는 대신 규칙이 지켜지는 환경을 만든 것입니다.

어디에 더 쓸 수 있을까

다섯 이벤트가 각각 어떤 자리인지 알면 아이디어는 스스로 나옵니다.

이벤트	활용 제안
AgentSpawn	작업 준비 — 필요한 폴더 생성, 시작 시각 기록
UserPromptSubmit	업무 일지 — 에이전트에게 일을 시킨 횟수와 시각 통계
PreToolUse + Matcher	위험 감시 — 특정 도구·패턴이 실행되기 전에 기록하고 알리기
PostToolUse	감사 추적 — 실행된 도구 기록 남기기
Stop	마무리 점검 — 리마인더, 산출물 백업, 완료 알림

공통 원리는 하나입니다. 모델이 잊어도 시스템이 잊으면 안 되는 것이면 훅에 맡깁니다. 반대로 문맥 판단이 필요한 일은 훅 혼자 못 합니다. 규칙(Steering)과 사람(승인)의 자리입니다.

훅 정리는 이 랩을 마칠 때 합니다 — 5단계의 인계 실습에서 위 안전망 훅이 한 번 더 일하기 때문입니다. 마칠 때는 행의 토글을 끄거나 Delete 후 Apply & Restart. 훅 자체는 저장소 파일이 아니라 git status에 나타나지 않습니다. 로그 파일(.kiro/hook-log.txt)은 저장소 안에 남지만, .kiro/가 미추적 폴더로 합쳐 표시되는 동안에는 따로 드러나지 않습니다.

Kiro Crew에는 파일이 아닌 기억도 있습니다. 터미널에서 조회합니다.

kirocrew learn list

새로 설치한 시스템에는 다음처럼 표시됩니다.

No lessons.

번역: 저장된 레슨이 없습니다.

지금까지의 실습에서 아무것도 자동 저장되지 않았다는 확인이기도 합니다. 쓰다 보면 이런 항목이 쌓일 수 있습니다.

[knowledge] Always respond to this user in Korean (한국어) by default, ...

번역: 이 사용자에게는 기본적으로 항상 한국어로 답변합니다.

이런 레슨은 사용자의 교정을 시스템이 스스로 저장한 것입니다. 파일이 아니라 내부 데이터베이스에 있습니다.

	파일 (Steering·인계 문서)	레슨 메모리 (learn_add)
저장 위치	저장소 안 .md	시스템 DB (~/.kiro/crew/memory.db)
만드는 주체	사람이 명시적으로	에이전트가 스스로도 저장
확인 방법	파일 열기, git diff	kirocrew learn list
팀 공유	커밋하면 끝	각자의 시스템에 각자 존재
이력	Git이 남김	없음
예측 가능성	내용이 눈에 보임	모르는 사이에 쌓일 수 있음

마지막 줄이 중요합니다. 에이전트가 스스로 저장한 레슨은 다음 세션의 행동을 사용자가 모르는 사이에 바꿉니다. 파일 기억에는 이 문제가 없습니다. 저장소에 없는 규칙은 존재하지 않습니다.

토론

먼저 스스로 답해 본 뒤 접힌 답과 비교해 보세요.

팀 온보딩 문서로 쓴다면 어느 쪽이어야 하는가?

생각해 볼 답

파일입니다. 온보딩 문서의 요건인 새 사람이 받을 수 있고, 내용이 눈에 보이며, 누가 언제 바꿨는지 남는다는 조건은 모두 저장소 파일의 성질입니다. 레슨 메모리는 각자의 기기에 각자 존재해서 애초에 전달되지 않습니다.

레슨 메모리가 더 알맞은 경우는 언제인가?

생각해 볼 답

커밋할 가치가 없거나 커밋하면 안 되는 것에 알맞습니다. 개인의 말투 선호나 이 기기에만 해당하는 설치 경로·로컬 포트처럼 팀의 규칙이 아니라 나와 이 기계 사이의 사정이면 레슨에 둡니다. 단, 스스로 쌓이는 만큼 가끔 kirocrew learn list로 무엇이 있는지 확인해야 합니다.

이제 두 번째 파일 기억인 인계 문서를 만듭니다. 규칙이 아니라 작업 상태를 남깁니다. 3단계의 안전망 훅이 “파일로 남겼습니까?”라고 물을 때, 그 답이 바로 이 문서입니다.

프로젝트 폴더가 연결된 세션이면 어디든 됩니다 — 3단계에서 쓰던 세션에 이어서 입력합니다.

HANDOFF.md 파일을 이 폴더 최상위에 만들어 줘. 내용은 세 부분이다.
완료: README 첫 제목 확인됨.
다음 할 일: labs 폴더 바로 아래의 항목 수를 세서 보고.
주의: 어떤 파일도 수정하지 않는다.

승인 카드가 뜹니다. 프로젝트 저장소에 쓰기 때문입니다. Input 탭의 diff를 확인하고 Allow once를 선택합니다.

승인 직후 파일이 생성됩니다.

[NXT] .../nxt-kirocrew-hands-on/HANDOFF.md 를 세 부분(완료 / 다음 할 일 / 주의)으로 생성했습니다.

diff — HANDOFF.md
1  # HANDOFF
3  ## 완료
4  - README 첫 제목 확인됨.
6  ## 다음 할 일
7  - labs 폴더 바로 아래의 항목 수를 세서 보고.
9  ## 주의
10 - 어떤 파일도 수정하지 않는다.

검증: 확인 1건 / 미확인 0건

번역: 완료한 일, 다음에 할 일, 주의할 일을 세 부분으로 나누어 HANDOFF.md에 기록했고, 파일 생성 내용을 검증했다는 뜻입니다.

이 답변에도 [NXT]와 검증 요약이 붙어 있습니다. Steering은 파일을 만드는 답변에도 예외 없이 적용됩니다. git status --short에는 ?? HANDOFF.md가 나타납니다. 작업 상태가 저장소의 파일이 됐습니다.

새 세션을 만들고 프로젝트 폴더를 다시 연결합니다. 이 세션은 이전 대화를 전혀 모릅니다.

HANDOFF.md를 읽고, 거기 적힌 다음 할 일만 실행해 줘. 주의 사항도 지켜 줘.

먼저 예측해 보세요 — 이전 대화를 모르는 세션이 무엇을 할 수 있을까요?

에이전트의 reasoning 단계가 화면에 표시됩니다. 파일을 찾고, 읽고, 그다음에야 실행합니다.

Locate the HANDOFF.md file in the project.
Read the HANDOFF.md to find the next task and cautions.
List items directly under the labs folder to count them.

번역: 프로젝트에서 HANDOFF.md를 찾고, 다음 작업과 주의사항을 확인한 뒤, labs 폴더 바로 아래 항목을 나열해 개수를 셉니다.

이번 폴더의 labs 바로 아래에는 다음 4개 항목이 있습니다.

- 01-agent-creation
- 04-knowledge-rag
- 05-loop-design
- 07-human-decision

그리고 결과를 보고합니다.

[NXT] labs 폴더 바로 아래 항목은 4개입니다.
- 01-agent-creation
- 04-knowledge-rag
- 05-loop-design
- 07-human-decision

모두 디렉터리이며, 주의 사항대로 어떤 파일도 수정하지 않았습니다.
검증: 확인 1건 (labs 하위 항목 수) / 미확인 0건

번역: labs 바로 아래 항목을 4개로 확인했고, 주의사항에 따라 파일을 수정하지 않았다는 뜻입니다.

보고된 수가 실제 폴더와 일치하는지 직접 열어 대조하는 것이 이 단계의 검증입니다. 승인 카드는 뜨지 않았습니다. 프로젝트 폴더 읽기와 나열뿐이기 때문입니다.

마지막 줄을 봅니다. Steering 규칙이 이 세션에도 적용되어 있습니다. 인계 문서는 읽으라고 해야 읽지만, Steering은 항상 붙습니다. 두 파일 기억의 차이가 한 화면에 있습니다.

이 실습의 세 번째 결론입니다. 대화는 세션과 함께 사라지지만, 파일은 남습니다. 완료한 것 · 다음 할 일 · 주의사항 — 이 세 가지를 파일로 남기면 어떤 세션이든, 누구의 세션이든 이어받을 수 있습니다. 전제는 하나입니다. 양쪽 세션이 같은 폴더를 보고 있어야 합니다. 세션 작업 폴더는 매번 새로 생기므로, 인계는 프로젝트 폴더에 연결된 세션에서 해야 합니다.

정리는 삭제가 아니라 남길 것을 정하는 일입니다. 이 랩의 산출물은 지울 것이 아니라 남길 것들입니다. 파일 기억의 완성은 저장소 이력에 넣는 것입니다.

규칙과 인계 문서를 커밋합니다

내장 터미널에서 실행합니다.

cd ~/Desktop/work/nxt-kirocrew-hands-on
git add .kiro/steering/ HANDOFF.md
git commit -m "docs: 응답 규칙과 인계 문서 추가"
git status --short

[main b217202] docs: 응답 규칙과 인계 문서 추가
 2 files changed, 12 insertions(+)
 create mode 100644 .kiro/steering/nxt-response-style.md
 create mode 100644 HANDOFF.md
?? .kiro/settings/

번역: 응답 규칙과 인계 문서 두 파일을 커밋했지만, .kiro/settings/는 여전히 미추적 상태라는 뜻입니다.

이것으로 첫 번째 결론이 실행됐습니다. 에이전트의 규칙과 작업 인계가 코드처럼 커밋되어 이력에 남았습니다. 팀원이 이 커밋을 받으면 같은 규칙과 같은 인계를 받습니다. 실습 클론에서는 로컬 커밋만 하고 푸시는 하지 않습니다.

남는 것도 결정입니다

커밋 후에도 ?? .kiro/settings/가 남아 있습니다. 세션이 만든 기기 로컬 설정입니다. 팀의 것인 규칙과 인계는 커밋하고, 이 기계의 사정인 설정은 커밋하지 않고 둡니다. 무엇을 커밋하고 무엇을 남길지 고른 것, 그것이 이 정리의 전부입니다.

Steering은 계속 일합니다

다음 Lab에서도 Steering은 그대로 적용됩니다. 이후 답변에 [NXT]와 검증 요약이 계속 붙습니다. always-on이 무엇인지 과정 내내 확인하게 됩니다.

완전 정리

과정을 여기서 끝내는 경우에만 Steering 화면에서 Delete 후 Apply & Restart를 합니다. 필요하면 클론 폴더 자체를 삭제합니다. 커밋까지 로컬에만 있으므로 폴더를 지우면 전부 정리됩니다.

• Workspace 스코프로 Steering 파일을 만들었습니다.
• 파일이 프로젝트의 .kiro/steering/에 생기고 Git이 추적하는 것을 확인했습니다.
• 템플릿 줄을 지우고 작성했습니다.
• 새 세션의 무관한 요청에 규칙 두 개가 모두 적용됐습니다.
• 스킬과 달리 로드 표시가 없다는 것을 확인했습니다.
• 훅을 만들어 실행이 100% 집계되는 것을 봤고, Steering과의 차이(해석 vs 실행)를 확인했습니다.
• Test 결과 OK, 메시지 2회 후 TOTAL RUNS 3, 로그 3줄을 대조했습니다.
• PreToolUse를 포함한 5개 이벤트와 ACP 번들 훅을 관찰했습니다.
• 모델이 자기 훅을 모르며, 훅 설정은 ~/.kiro/crew/hooks.json에 저장되고 git status에는 나타나지 않음을 확인했습니다.
• Stop 훅이 매 턴 종료 시 알림을 실행하는 것을 확인했습니다.
• kirocrew learn list로 시스템 레슨과 대비했습니다.
• HANDOFF.md 작성에 승인 카드가 떴고, 승인 후 파일이 생겼습니다.
• 이전 대화를 모르는 새 세션이 파일만 읽고 작업을 이어받았습니다.
• 규칙과 인계 문서를 커밋했고, 기기 로컬 설정은 커밋하지 않고 남겼습니다.

증상	먼저 확인할 항목
규칙이 적용되지 않음	Apply & Restart를 눌렀는지, 새 세션인지
일부 세션에만 적용됨	Scope가 Workspace면 프로젝트 폴더에 연결된 세션에만 적용
Scope 선택지가 Workspace — (no project set)	프로젝트 폴더 미연결 세션이 열려 있음 — 해당 세션을 지우거나 같은 폴더로 연결 후 새로고침
파일에 # Title 줄이 남음	템플릿 텍스트를 지우지 않음 — Edit으로 제거
새 세션이 HANDOFF.md를 못 찾음	세션이 프로젝트 폴더에 연결됐는지 — 표시줄의 브랜치 확인
git status가 지저분함	실습 산출물을 커밋했는지, 기기 로컬 설정을 구분했는지 — 7단계

파일 기억은 두 가지입니다. 규칙은 Steering으로 — 항상, 표시 없이 적용됩니다. 작업 상태는 인계 문서로 — 읽는 세션이 이어받습니다.

Workspace Steering은 저장소 안의 파일입니다. 에이전트의 규칙이 코드처럼 커밋되고, 리뷰되고, 공유됩니다.

시스템 레슨 메모리는 에이전트가 스스로도 저장합니다. 무엇이 쌓였는지는 조회해야 보입니다. 예측 가능해야 하는 규칙은 파일에 둡니다.

먼저 스스로 답해 본 뒤 접힌 답과 비교해 보세요.

Steering 파일이 10개, 각 100줄이면 세션마다 무슨 일이 일어나는가?

생각해 볼 답

1,000줄이 모든 세션에, 매번, 표시 없이 주입됩니다. 컨텍스트 비용이 커지고, 규칙끼리 충돌하면 어느 쪽이 이길지 보장이 없으며, 정작 중요한 규칙이 묻힙니다. Steering이 always-on이라는 것은 곧 always-cost라는 뜻입니다. 그래서 짧은 규칙만 둡니다. 절차처럼 긴 것은 필요할 때만 로드되는 스킬로 보냅니다.

Global 스코프가 알맞은 규칙은 무엇인가? Workspace여야 하는 규칙은?

생각해 볼 답

Global은 프로젝트와 무관하게 항상 참인 개인 규칙인 언어, 말투, 안전 습관 같은 것입니다. Workspace는 그 프로젝트의 약속인 응답 형식, 명명 규칙, 금지 사항입니다. 판별 질문은 하나입니다. 팀원이 클론했을 때도 적용돼야 하는가? 그렇다면 Workspace로 저장소에 커밋합니다.

HANDOFF.md에 “다음 할 일”이 모호하게 적혀 있으면 이어받는 세션은 어떻게 행동하는가? 실험해 보라.

생각해 볼 답

모호한 만큼 해석이 개입합니다. 넓게 해석해 과잉 실행하거나, 스스로 범위를 정해 일부만 하거나, 되물을 수도 있습니다. 어느 쪽이든 쓴 사람의 의도는 보장되지 않습니다. 인계 문서의 품질이 곧 다음 세션의 품질입니다. 사람에게 인계할 때와 똑같이 완료·다음 할 일·주의를 구체적으로 씁니다. 직접 모호한 버전으로 실험해 보면 차이가 선명합니다.

인계 문서를 에이전트가 매 세션 끝에 자동으로 갱신하게 하려면 무엇을 조합해야 하는가?

생각해 볼 답

갱신 절차의 형식과 포함 항목은 스킬로, “세션을 마칠 때는 HANDOFF를 갱신한다”는 규칙은 Steering으로, 세션 종료 시점에 자동으로 걸리게 하려면 3단계에서 본 Hooks(session stop 이벤트)가 후보입니다. 쓰기가 포함되므로 승인 경계는 그대로 남습니다. 완전 자동이 아니라 “제안하고 승인받는 자동”이 현실적인 형태입니다.

핸즈온에서 만든 Steering 규칙과 인계 문서를 다른 업무 도메인에서 한 번 더 만들어 봅니다. 실제 민감 데이터나 회사 자료는 넣지 말고, 가상의 프로젝트명과 작업 항목으로 연습하세요.

hands-on 레포의 themes/program-office/ 테마 팩에서 Lab 3 — 담당자 교체 인계 항목을 선택합니다.

담당자가 교체되는 가상의 프로젝트 폴더를 만들고 다음을 수행하세요.

1. 새 담당자가 항상 지켜야 할 보고 형식을 Workspace Steering 파일로 작성합니다.
2. 현재 담당자가 완료한 일, 다음 담당자가 할 일, 반드시 지킬 주의사항을 HANDOFF.md에 기록합니다.
3. HANDOFF.md를 읽은 새 세션이 다음 할 일만 실행하는지 확인합니다.
4. 팀의 규칙과 인계 문서는 커밋하고, 기기 로컬 설정은 커밋하지 않는 기준을 설명합니다.

마지막으로 자신의 업무 소재를 가상의 내용으로 바꾸어 같은 흐름을 응용해도 좋습니다.