[Tool] Kiro CLI 도입기 - Steering Rules로 AI 에이전트 길들이기
Kiro CLI를 실무 Serverless 프로젝트에 도입하고, workflow-rules와 project docs로 에이전트의 행동을 제어한 경험 정리
배경
Serverless 기반 대시보드 프로젝트를 진행하면서 AI 코딩 에이전트를 본격적으로 도입하기로 함. Kiro가 GA 출시되면서 CLI도 함께 나왔길래 터미널 기반 워크플로우에 바로 붙여봄.
문제는 AI 에이전트가 내 프로젝트의 규칙을 모른다는 것. 코드 스타일, 커밋 규칙, 배포 금지 사항 등을 매번 말해줘야 하는 건 비효율적임.
.kiro 디렉토리 구조
Kiro는 .kiro/ 디렉토리를 프로젝트 루트에 두면 자동으로 인식함. 내가 구성한 구조:
1
2
3
4
5
6
7
8
9
.kiro/
├── agents/ # 커스텀 에이전트 정의
├── docs/
│ ├── project/ # 설계 문서, 스키마, 아키텍처 결정
│ └── workflow-rules.md # 에이전트 행동 규칙
├── hooks/ # 이벤트 기반 자동화 스크립트
├── settings/
│ └── cli.json # CLI 기본 설정
└── pipeline.yaml # subagent DAG 정의
Workflow Rules: 에이전트에게 규칙을 심는 법
workflow-rules.md가 핵심임. 에이전트가 세션 시작 시 이 파일을 읽고 준수하도록 설정함.
내가 정의한 주요 규칙들:
코드 변경 전 검증 필수
1
2
3
4
5
## Before Code Change
- Don't modify code immediately when user reports a problem
- First verify with actual data/logs to identify root cause
- User's report may be incorrect — verify facts first
- Only propose code changes after root cause is confirmed
AI가 “문제 있다”고 하면 바로 고치려 드는 습성이 있음. 이걸 막기 위해 “먼저 확인하고, 확인된 후에만 수정” 규칙을 넣음.
Logic Change Approval
1
2
3
4
5
6
## Logic Change Approval
- When modifying or changing logic, always present first:
1. AS-IS: current behavior (code level)
2. TO-BE: planned change (code level)
3. Impact scope: related files/features
- Present above to user and get confirmation before modifying code
로직 변경 시 반드시 AS-IS/TO-BE를 먼저 보여주고 승인받도록 함. 이게 없으면 에이전트가 “좋은 의도”로 관련 없는 코드까지 리팩토링해버림.
배포/실행 금지
1
2
3
4
5
6
## Deploy
- `sls deploy` is done by user only — AI must not execute
- `npm run dev`, `npm run build` etc. server execution also forbidden
## DB
- Never delete DynamoDB tables (data clear only, on user request)
프로덕션 환경에 영향을 줄 수 있는 명령은 절대 에이전트가 실행하지 못하게 차단.
Project Docs: 컨텍스트를 파일로 관리
.kiro/docs/project/ 하위에 설계 문서를 두면 에이전트가 필요할 때 참조함.
1
2
3
4
5
6
7
docs/project/
├── db-schema.md # DynamoDB Single Table 스키마
├── frontend-serving-architecture.md
├── org-change-design.md # 조직개편 기능 설계
├── redis-session-sync.md # 세션 동기화 설계
├── refactoring-plan.md # 리팩토링 계획
└── self-ref-skip-bug.md # 버그 분석 기록
에이전트 프롬프트에 이렇게 지시:
1
2
세션 시작 시 .kiro/docs/ 디렉토리를 읽어 전체 문서 목록을 확인하고,
작업에 필요한 문서를 로드할 것.
이러면 “이 테이블 스키마가 뭐야?”라고 물을 필요 없이, 에이전트가 알아서 db-schema.md를 참조함.
CLI 기본 설정
1
2
3
4
// .kiro/settings/cli.json
{
"chat.defaultAgent": "ebt-dashboard"
}
kiro chat 실행 시 기본으로 프로젝트 전용 에이전트가 로드됨. 매번 에이전트를 지정할 필요 없음.
효과
- 반복 설명 제거: 프로젝트 규칙을 매번 말할 필요 없음
- 사고 방지: 배포, DB 삭제 같은 위험 행동을 구조적으로 차단
- 일관성: 누가 에이전트를 쓰든 같은 규칙이 적용됨
- 문서 자동 참조: 설계 결정을 파일로 남기면 에이전트가 알아서 활용
정리
Kiro CLI의 핵심은 “AI를 내 프로젝트에 맞게 커스터마이징할 수 있다”는 점임. .kiro/docs/workflow-rules.md 하나만 잘 작성해도 에이전트의 행동이 완전히 달라짐. 코드를 짜기 전에 규칙부터 정의하는 게 AI 시대의 프로젝트 세팅이라고 생각함.