포스트

Kiro IDE 1.2 이후, 규칙을 덜어내고 남긴 것들

게시
By DAN
Kiro IDE 1.2 이후, 규칙을 덜어내고 남긴 것들

Kiro 워크플로 총정리, Spec의 한계와 Vibe로 우회하기에 이어지는 글입니다. 1.0 시절에는 Kiro의 빈틈을 steering 규칙과 hooks로 잔뜩 메웠는데, 1.2로 오면서 그 상당수를 걷어냈습니다. 무엇을 남기고 무엇을 뺐는지, 그리고 지금 권장하는 구성을 정리했습니다. 출처: Kiro IDE Changelog, 정리한 설정: Danithub/awesome-kiro

TL;DR

  • 세션은 Default(Vibe)로. Spec 대신 “작업 전 문답 + 결과 문서 2개”만 규칙으로 가져옵니다.
  • 긴 작업은 Workflows(IDE 1.2)로 백그라운드에 맡기고, 끊기면 현재 세션에서 이어서 합니다.
  • 권한은 사용자 레벨에서 전체 허용. permissions.yaml에 규칙 한 줄이면 됩니다.
  • 1.0 때 붙였던 규칙 6종과 hooks는 뺐습니다. 1.2에서는 기본 동작으로 충분해서요.
  • 규칙은 적을수록 잘 지켜집니다. 필요해지면 inclusion: auto steering이나 Skills로 다시 둡니다.

목차

  1. 들어가며: 1.0 때 왜 규칙을 잔뜩 붙였나
  2. 한눈에 보기
  3. 세션은 Default로
  4. Workflows (IDE 1.2)
  5. 권한: 사용자 레벨 전체 허용
  6. 덜어낸 규칙과 hooks
  7. 적용 방법
  8. 마치며

1. 들어가며: 1.0 때 왜 규칙을 잔뜩 붙였나

IDE 1.0을 쓰던 여름에는 Kiro가 실무에서 자주 걸려 넘어졌습니다. 긴 .md를 쓰다 마지막 20%에서 잘리고, PowerShell 출력은 에코가 겹쳐 지저분하고, 큰 파일을 통째로 읽다가 턴이 끊기곤 했죠. 그때마다 steering 규칙을 하나씩 붙이고, 규칙만으로 안 지켜지는 건 hooks로 강제했습니다.

그렇게 쌓다 보니 규칙이 열 개를 넘었습니다. 문제는 규칙이 많을수록 에이전트가 모든 규칙을 매 턴 컨텍스트에 싣고 다닌다는 점입니다. 규칙끼리 겹치거나 서로 다른 걸 요구하기도 했고, 정작 중요한 규칙이 묻히는 일도 생겼습니다.

1.1과 1.2를 거치며 Kiro 자체가 그 빈틈을 상당 부분 메웠습니다. 대화 압축 후에도 맥락이 유지되고(1.1), Windows에서는 설정한 터미널 프로필로 명령이 실행되고(1.0.337), 여러 단계 작업을 백그라운드에서 돌리는 Workflows가 들어왔습니다(1.2). 그래서 awesome-kiro 저장소도 꼭 필요한 것만 남기는 방향으로 다시 정리했습니다.

2. 한눈에 보기

항목권장관련 파일
세션Default(Vibe) + 작업 전 문답.kiro/steering/default-as-spec-workflow.md
백그라운드 작업Workflows, 끊기면 직접 이어서 수행.kiro/steering/workflow-fallback-rules.md
권한사용자 레벨에서 전체 허용~/.kiro/settings/permissions.yaml
기타 규칙한국어 존댓말, 턴 상태 표시, ~ 취소선 방지.kiro/steering/
hooks수록하지 않음없음

대상 버전은 Kiro IDE 1.2 이상(1.3.x 포함)입니다.

3. 세션은 Default로

앞선 글에서 Spec은 requirements / design / tasks 세 문서를 단계마다 합의하며 진행해서 신중하지만, 작은 작업에도 무겁다고 적었습니다. 실제로는 단계 경계가 애매한 경우도 많고요.

그래서 지금은 Default 세션을 기본으로 쓰고, Spec의 좋은 점만 default-as-spec-workflow.md 규칙으로 가져옵니다. 이 규칙이 하는 일은 두 가지입니다.

  1. 코드를 바꾸기 전에 질문을 한 번에 묶어 문답하고, 요구사항을 확정한 뒤 진행
  2. 작업이 끝나면 .kiro/specs/{spec명}/에 문서 두 개를 남김
    • requirements.md: 배경, 문답 요약(Q&A), 요구사항, 범위 밖
    • changes.md: 변경 요약, 변경 파일, 상세 내용, 검증 결과, 후속 작업

규칙을 모든 요청에 적용하면 단순 질문에도 문서가 생겨 오히려 지저분해집니다. 그래서 켜고 끄는 기준을 분명히 뒀습니다.

적용 (ON)적용 안 함 (OFF)
소스·설정 파일을 실제로 바꾸는 작업코드를 바꾸지 않는 질문·설명·조회
여러 파일에 걸치거나 동작을 바꾸는 기능 추가·수정오타, 한 줄 변경 같은 자명한 편집
“spec처럼”, “문답하고 진행” 요청“그냥 바로 해줘”, “문서 만들지 마” 요청

steering 규칙으로 세션 타입 자체를 Spec으로 바꿀 수는 없습니다. 세션 타입은 IDE에서 고르는 것이라서, 이 규칙은 Default 세션이 Spec처럼 행동하게 만드는 약속일 뿐입니다. 정식 Spec의 3단계 문서나 PBT를 대체하지는 않습니다.

써 보면 사용자 입장에서 남는 건 결국 두 문서입니다. “무엇을 합의했나”는 requirements.md, “무엇이 바뀌었나”는 changes.md를 보면 됩니다. 세션 진행 방식별 비교는 kiro-workflows.md에 정리해 뒀습니다.

4. Workflows (IDE 1.2)

Workflows는 여러 단계로 된 계획을 백그라운드에서 실행하는 기능입니다. 단계마다 별도 에이전트 세션이 돌고, 그동안 원래 채팅에서는 계속 대화할 수 있습니다. 세션을 시작할 때 고르는 Spec / Plan 같은 “워크플로”와 이름이 비슷하지만 다른 기능입니다.

  • 켜기: 기본값은 꺼짐입니다. Agent Focus의 Workspace Configuration에서 켜거나, Settings에서 kiroAgent.workflows.enabled를 켠 뒤 새 채팅을 시작합니다.
  • 진행 확인: 채팅 위 Workflows 영역에서 단계별 진행을 보고, 단계를 열어 보거나 일시정지·재개·중지할 수 있습니다.
  • 레시피: 재사용할 실행 정의는 .kiro/workflows/에 둡니다. 1.3부터는 채팅에 /workflow-run을 입력해 저장된 레시피를 고르고, 입력값만 채우면 바로 시작됩니다.

끊겼을 때: workflow-fallback-rules.md

백그라운드 실행은 가끔 실패하거나 중간에 멈춥니다. 이때 Kiro가 “다시 실행할까요?” 라고 묻고 기다리면, 사용자가 자리를 비운 사이 작업이 그대로 멈춰 있습니다. 이 규칙은 그런 경우 남은 작업을 현재 세션에서 바로 이어서 하게 합니다.

  • 끊김으로 보는 경우: 실행 호출 실패, 단계 error, run이 failed / aborted로 종료, 알림 없이 진행이 멈춤
  • 질문 대기(warning)로 멈춘 것은 끊김이 아님. 답을 기다리는 정상 상태입니다
  • 이미 끝난 단계는 다시 하지 않고 남은 부분부터 진행
  • 전환했다는 사실은 한 줄로만 알림

1.0 때 쓰던 subagent-fallback-rules(서브에이전트 위임 실패 시 직접 수행)를 이 규칙이 대신합니다. 위임 대상이 서브에이전트에서 Workflows로 바뀐 셈입니다.

5. 권한: 사용자 레벨 전체 허용

IDE 1.0부터 권한은 capability 기반 규칙으로 동작하고, 규칙에 없는 동작은 매번 승인을 묻습니다. 명령마다 승인 버튼을 누르는 게 번거롭다면 사용자 레벨 파일에 아래 규칙 하나만 두면 됩니다.

C:\Users\{사용자}\.kiro\settings\permissions.yaml

1
2
3

rules:
  - capability: all
    effect: allow
  • all은 셸 명령만이 아니라 파일 읽기·쓰기, 웹 조회, MCP 호출 등 모든 capability를 뜻합니다.
  • 사용자 레벨에 두므로 이 PC의 모든 프로젝트에 적용됩니다.
  • 범위와 상관없이 가장 제한적인 효과가 이깁니다(deny > ask > allow). 특정 동작만 막고 싶으면 같은 파일이나 워크스페이스 규칙에 deny를 추가하면 됩니다.

전체 허용이어도 아래 경우에는 여전히 확인을 받습니다(IDE 1.2).

  • 에이전트가 agent, Hook, Power 파일이나 .kiro/workflows/ 레시피를 수정할 때
  • 신뢰하지 않은 워크스페이스에서 Kiro 설정을 바꾸거나 명령을 실행할 때 (이 경우 Workflow 레시피도 Trust 전까지 로드되지 않습니다)

전체 허용은 편한 대신 잘못된 명령도 묻지 않고 실행됩니다. 개인 PC나 신뢰하는 프로젝트에서만 쓰고, 공용·운영 환경에서는 쓰지 마세요. 1.3의 Command sandbox를 켜면 에이전트가 실행하는 셸 명령의 파일·네트워크 접근 범위를 함께 제한할 수 있습니다. 다만 완전한 격리를 보장하지는 않으니 제안된 명령은 계속 살펴보는 게 좋습니다.

규칙 파일의 저장 위치와 형식은 command-permission-policy.md에 정리해 뒀습니다.

6. 덜어낸 규칙과 hooks

이번 정리의 핵심입니다. 아래 항목은 1.2 환경에서 별도 규칙 없이도 잘 동작해서 저장소에서 뺐습니다. 지운 게 아니라 git 이력에 남아 있으니 필요하면 되살려 쓰면 됩니다.

항목하던 일뺀 이유
long-markdown-doc-rules + markdown-chunk-guard hook긴 .md를 40줄 청크로 나눠 작성긴 문서도 잘림 없이 작성됨
powershell-rules + no-workspace-scripts hook스크립트 파일 없이 실행, PSReadLine 에코 방지명령이 설정한 터미널 프로필에서 안정적으로 실행됨
context-budget-rules + context-budget-guard hook대용량 파일 통째 읽기·광역 검색 방지범위 읽기와 대화 압축(compaction)이 기본 동작
dead-code-cleanup-rules, clean-final-state-rules + post-task-cleanup-check hook작업 후 미사용 코드·이력 주석 점검기본 동작으로 충분하고, 매번 강제하면 부담이 큼
guide-routing-rules + .kiro/guides/키워드로 통합 가이드 자동 참조steering inclusion: auto와 Skills가 같은 일을 기본으로 함
subagent-fallback-rules서브에이전트 위임 실패 시 직접 수행workflow-fallback-rules로 대체

돌아보면 1.0 때 붙인 규칙 대부분은 도구의 버그나 한계를 우회하는 임시 처방이었습니다. 도구가 고쳐지면 처방도 걷어내야 하는데, 그냥 두면 오히려 해가 됩니다. 예를 들어 “40줄씩 끊어 쓰라”는 규칙은 지금도 지켜지긴 하지만, 그만큼 도구 호출이 늘어 느려지고 컨텍스트만 차지합니다.

반복 작업 방법론(예: 다국어 전환 절차, 화면 입력 검증 체크리스트)을 다시 두고 싶다면, 키워드 라우팅 규칙을 따로 만들기보다 아래 방법을 권장합니다.

  • inclusion: auto steering: front matter에 name, description을 적어 두면 요청이 설명과 맞을 때만 불러옵니다.
  • .kiro/skills/: 절차와 참고 자료를 한 묶음으로 두고 필요할 때 꺼내 씁니다.

inclusion 모드별 차이는 steering.md에 정리해 뒀습니다.

7. 적용 방법

  1. 내려받기: git clone https://github.com/Danithub/awesome-kiro.git 또는 저장소 페이지의 Code → Download ZIP
  2. 복사: 저장소의 .kiro/ 폴더를 적용할 프로젝트 루트에 통째로 복사합니다. 필요한 파일만 같은 하위 경로로 골라 복사해도 됩니다.
  3. Trust: IDE 1.2부터는 신뢰하지 않은 워크스페이스에서 설정 변경과 명령 실행마다 확인을 받습니다. 복사한 뒤 워크스페이스를 Trust해 두세요.
  4. 확인: Kiro IDE는 파일을 두면 자동으로 인식합니다(필요하면 창 새로고침). Kiro CLI는 프로젝트 루트에서 실행하면 .kiro/를 읽어 반영합니다.

모든 프로젝트에 항상 적용하고 싶다면 프로젝트가 아니라 사용자 레벨 (~/.kiro/steering/ 등)에 두면 됩니다. 규칙은 그대로 쓰기보다 언어, 턴 한도 수치처럼 팀이나 개인 상황에 맞게 고쳐 쓰는 걸 권합니다.

8. 마치며

1.0 때는 “Kiro가 이걸 못 하니 규칙으로 막자”가 기본 태도였다면, 1.2부터는 “Kiro가 알아서 하는 건 맡기고, 내 작업 방식만 규칙으로 남기자”로 바뀌었습니다. 남은 규칙을 보면 차이가 분명합니다. 도구의 한계를 우회하는 규칙은 거의 사라지고, 문답 후 진행, 끊기면 이어서, 존댓말과 턴 표시처럼 사람이 원하는 작업 방식을 담은 규칙만 남았습니다.

규칙은 짧고 적을수록 잘 지켜집니다. 버전이 오를 때마다 “이 규칙이 아직 필요한가”를 한 번씩 점검해 보시길 권합니다. 정리한 설정은 Danithub/awesome-kiro에서 그대로 가져다 쓰실 수 있습니다.

Kiro, Workflow
kiro workflow steering permissions workflows