테마
Steering
목표
Steering 파일의 개념과 역할을 이해하고, 프로젝트별 개발 표준을 설정하여 Kiro가 자동으로 적용하도록 합니다.
Steering이란?
Steering = Kiro가 코드를 생성할 때 항상 따라야 할 가이드라인을 정의하는 마크다운 파일입니다.
- 모든 코드가 동일한 스타일·패턴을 따름
- 매번 프롬프트에 표준을 반복 설명할 필요 없음
- 팀 전체가 동일 기준으로 개발 가능
가장 빠른 시작
프로젝트 전체에 적용할 짧은 규칙은 .kiro/steering/project-rules.md에 아래처럼 작성합니다.
markdown
---
inclusion: always
---
- 새 코드는 기존 프로젝트의 테스트와 포맷 규칙을 따른다.
- 비밀값을 소스 코드에 넣지 않는다.inclusion: always는 기본 에이전트의 모든 상호작용에 이 파일을 자동으로 포함합니다. 커스텀 에이전트에서 사용하려면 해당 에이전트의 resources에 추가해야 합니다. 범위가 좁은 규칙은 이후의 fileMatch나 auto 모드로 분리합니다.
파일 위치
text
프로젝트 루트/
└── .kiro/
└── steering/
├── product.md (프로젝트 목적과 기능)
├── structure.md (프로젝트 구조와 규칙)
└── tech.md (기술 스택과 도구)사전 준비
- Kiro IDE 로그인 및 프로젝트 폴더 열기 완료
해볼 것
1단계: 기본 Steering 생성
- Kiro 패널(좌측 사이드바)에서 Steering 섹션 클릭
- 생성 버튼 클릭
- Kiro가 자동으로 기본 파일 3개를 생성합니다 (
product.md,tech.md,structure.md)
2단계: 커스텀 Steering 추가
Steering 섹션에서 생성 클릭 후, 파일명 todo-app-standards.md로 아래 내용을 붙여넣습니다:
markdown
---
title: Todo App Development Standards
inclusion: always
---
# Todo App 개발 표준
## 코딩 스타일
### HTML
- 시맨틱 태그 사용 (header, main, section, article 등)
- 접근성 속성 포함 (aria-label, alt 등)
- 들여쓰기: 2칸 스페이스
### CSS
- BEM 방법론 사용 (Block__Element--Modifier)
- CSS 변수 활용 (--primary-color 등)
- 모바일 퍼스트 반응형 디자인
### JavaScript
- ES6+ 문법 사용
- const/let 사용 (var 금지)
- 함수명은 동사로 시작 (addTodo, deleteTodo)
- 주석은 한글로 작성
## 파일 구조
todo-app/
├── index.html
├── css/
│ └── style.css
├── js/
│ └── script.js
└── assets/
└── images/
## 기능 구현 원칙
- 로컬 스토리지 사용으로 데이터 영속성 보장
- 사용자 입력 검증 필수
- 에러 처리 포함3단계: 효과 테스트
Steering 저장 후 채팅에서 요청합니다:
할 일 추가 버튼 HTML을 만들어주세요.결과에서 확인할 것:
- 시맨틱 태그 사용 여부
aria-label등 접근성 속성 포함 여부- 2칸 들여쓰기 적용 여부
Inclusion 모드
| 모드 | 추가 frontmatter | 적용 시점 |
|---|---|---|
always | 없음 | 기본 에이전트의 모든 상호작용 |
fileMatch | fileMatchPattern | 패턴과 일치하는 파일 작업 |
manual | 없음 | /<파일명>으로 직접 호출 |
auto | name, description | 요청과 설명이 관련될 때 자동 포함 |
각 모드는 파일 맨 앞의 --- 사이에 하나만 지정합니다. auto 모드에서는 name과 description이 모두 필수이며, 자동 매칭을 기다리지 않고 채팅에서 / 뒤에 Steering 이름을 입력해 명시적으로 호출할 수도 있습니다.
조건부 Steering (fileMatchPattern)
프론트매터의 fileMatchPattern을 사용하면 특정 파일을 작업할 때만 도메인별 가이던스를 로드할 수 있습니다. 다음 설정은 TSX, JSX, CSS 파일에서만 디자인 시스템 규칙을 활성화합니다.
yaml
---
inclusion: fileMatch
fileMatchPattern: "**/*.{tsx,jsx,css}"
---표준을 강제해야 하는 규칙은 MUST, REQUIRED, ONLY USE처럼 명확한 규범적 언어로 작성합니다.
일반적인 도메인 패턴:
| 영역 | fileMatchPattern | 적용 예 |
|---|---|---|
| API | **/{handlers,routes,controllers}/**/*.{ts,js} | REST 규약·오류 처리 |
| Testing | **/*.{test,spec}.{ts,js,tsx,jsx} | 테스트 구조·네이밍 |
| Security | **/{auth,security,middleware}/**/*.{ts,js} | 인증·권한·데이터 처리 |
✅ 체크포인트
TSX 파일을 열었을 때만 디자인 시스템 규칙이 적용되고, 백엔드 .ts 파일에서는 적용되지 않는지 확인하세요.
워크스페이스 vs 글로벌 Steering
- 워크스페이스
.kiro/steering/— 현재 프로젝트에만 적용하며 버전 관리로 팀과 공유합니다. 디자인 시스템·API 규약 같은 팀 표준에 적합합니다. - 글로벌
~/.kiro/steering/— 모든 프로젝트에 적용하지만 팀과 공유되지 않습니다. 포맷팅·주석 스타일 같은 개인 선호에 적합합니다.
💡 Best practice
팀 표준은 워크스페이스에, 개인 선호는 글로벌에 둡니다.
Nested AGENTS.md
하위 디렉토리 어디에나 AGENTS.md 파일을 배치해 해당 디렉토리 트리에만 적용되는 컨텍스트를 제공할 수 있습니다. 파일이 위치한 디렉토리와 그 하위 경로에서 작업할 때만 스코프가 적용되므로, 모노레포의 패키지별 규약이나 특정 서브시스템에만 필요한 가이던스를 지역적으로 둘 수 있습니다.
- 프로젝트 어느 디렉토리에나 배치 가능하며, 해당 디렉토리 트리에 스코프됨
- 여러
AGENTS.md가 중첩되면 상위·하위 경로의 컨텍스트가 함께 적용됨 inclusion모드를 지원하지 않으며, 스코프에 해당하는 작업에서는 항상 포함됨
💡 Steering과의 차이
.kiro/steering/의 inclusion 모드로 로드 시점을 세밀하게 제어하는 것과 달리, AGENTS.md는 경로 기반으로 동작하며 항상 포함됩니다. 디렉토리 구조 자체가 컨텍스트 범위를 결정합니다.
기대 결과
.kiro/steering/폴더에 가이드라인 파일이 생성됨- 이후 모든 코드 생성 시 Steering 기준이 자동 적용됨
- 매번 프롬프트에 스타일 규칙을 반복할 필요 없음
통합 관점
Steering과 같은 공식 Features 형제 항목 및 선택 기준은 Context Engineering에서 확인하세요.
- `.kiro/steering/` 폴더에 파일 생성 확인필수
- 기본 Steering 3개 (product, tech, structure) 확인필수
- 커스텀 Steering (`todo-app-standards.md`) 생성필수
- Steering 적용 후 코드 스타일 변화 확인선택
🚨 문제 해결
- Steering이 적용되지 않는 것 같음: Kiro를 재시작하세요. Steering 파일의 마크다운 문법과
inclusion설정을 확인하세요. - Steering 섹션이 안 보임: Kiro 패널(좌측 사이드바) → Kiro 아이콘 클릭. 프로젝트 폴더가 열려 있어야 합니다.
- 기존 코드에는 적용 안 됨: Steering은 새로 생성하는 코드에만 적용됩니다. 기존 코드를 리팩터링하려면 명시적으로 요청하세요.
실습해보기
Steering을 직접 적용하는 실습: Scene B · Steering 표준 적용