Ch2. Steering 마스터하기
.kiro/steering 마크다운으로 프로젝트 규칙을 정의하고, inclusion always/fileMatch/manual로 조건화하며 #[[file:]] 참조와 계층적 모듈화로 컨텍스트를 구성하는 법
핵심 요약
- Steering은
.kiro/steering/의 마크다운 파일을 자동 로드해 모든 대화에 프로젝트 규칙·컨텍스트를 주입하는 시스템입니다. inclusion모드는 세 가지로,always(항상)·fileMatch(패턴 매칭 시)·manual(#키워드수동 참조 시) 포함을 제어합니다.#[[file:docs/api-spec.yaml]]문법으로 OpenAPI·스키마 같은 외부 파일을 Steering 컨텍스트로 끌어옵니다.- 전역·도메인·기능 규칙으로 나눠 모듈화하고, 더 구체적인
fileMatch규칙이 일반 규칙보다 앞섭니다. - Steering 파일은 Git으로 관리해 팀 전체가 같은 컨텍스트를 공유하세요. 처음부터 완성하려 하지 말고 조금씩 쌓아가는 편이 낫습니다.
Steering은 Kiro에 프로젝트별 컨텍스트와 규칙을 제공하는 시스템입니다.
.kiro/steering/ 디렉토리의 마크다운 파일을 자동으로 읽어 들여
모든 대화에 컨텍스트로 넣어 줍니다.
Steering 파일 구조
.kiro/steering/
├── project-overview.md # 프로젝트 개요
├── coding-standards.md # 코딩 표준
├── architecture.md # 아키텍처 가이드
├── api-guidelines.md # API 설계 가이드
└── deployment.md # 배포 가이드기본 Steering 파일 예시
project-overview.md
---
inclusion: always
---
# 프로젝트 개요
이 프로젝트는 Next.js 기반의 문서 사이트입니다.
## 기술 스택
- Next.js 14 (App Router)
- TypeScript
- Tailwind CSS
- MDX
## 주요 디렉토리
- `app/`: Next.js App Router 페이지
- `components/`: 재사용 가능한 컴포넌트
- `content/`: MDX 문서 파일
- `lib/`: 유틸리티 함수coding-standards.md
---
inclusion: fileMatch
fileMatchPattern: "**/*.{ts,tsx,js,jsx}"
---
# 코딩 표준
## TypeScript 규칙
- 모든 함수에 명시적 반환 타입 지정
- `any` 타입 사용 금지
- 인터페이스 이름은 `I` 접두사 없이 작성
## React 컴포넌트
- 함수형 컴포넌트 사용
- Props 인터페이스는 컴포넌트명 + `Props`
- 기본 export 사용
## 파일 명명 규칙
- 컴포넌트: PascalCase (Button.tsx)
- 유틸리티: camelCase (formatDate.ts)
- 페이지: kebab-case (user-profile.tsx)조건부 포함 (Conditional Inclusion)
fileMatch 패턴
특정 파일 패턴과 매칭될 때만 포함:
---
inclusion: fileMatch
fileMatchPattern: "**/*.test.{ts,tsx}"
---
# 테스트 가이드
Jest와 React Testing Library를 사용합니다.manual 포함
수동으로 참조할 때만 포함:
---
inclusion: manual
---
# 배포 가이드
이 문서는 #deployment로 참조할 때만 로드됩니다.파일 참조 시스템
Steering 파일에서 다른 파일을 참조합니다:
# API 가이드
OpenAPI 스펙을 참고하세요:
#[[file:docs/api-spec.yaml]]
데이터베이스 스키마:
#[[file:prisma/schema.prisma]]계층적 규칙 구성
전역 규칙
---
inclusion: always
---
# 전역 코딩 규칙
모든 파일에 적용되는 기본 규칙들...도메인별 규칙
---
inclusion: fileMatch
fileMatchPattern: "src/components/**/*"
---
# 컴포넌트 규칙
컴포넌트 작성 시 특별한 규칙들...기능별 규칙
---
inclusion: fileMatch
fileMatchPattern: "src/auth/**/*"
---
# 인증 모듈 규칙
인증 관련 코드 작성 시 규칙들...모듈화 전략
공통 규칙 분리
<!-- common-patterns.md -->
---
inclusion: always
---
# 공통 패턴
## 에러 처리
모든 비동기 함수는 try-catch 사용
## 로깅
console.log 대신 logger 사용도메인별 분리
<!-- frontend-rules.md -->
---
inclusion: fileMatch
fileMatchPattern: "src/components/**/*"
---
# 프론트엔드 규칙
React 컴포넌트 관련 규칙들...<!-- backend-rules.md -->
---
inclusion: fileMatch
fileMatchPattern: "src/api/**/*"
---
# 백엔드 규칙
API 엔드포인트 관련 규칙들...실전 팁
1. 환경별 설정 관리
개발, 스테이징, 프로덕션 환경마다 다른 컨텍스트를 줍니다:
<!-- .kiro/steering/env-development.md -->
---
inclusion: manual
---
# 개발 환경 설정
## 디버깅 모드
- 상세한 로깅 활성화
- 소스맵 포함
- 핫 리로드 지원
## 개발 도구
- React DevTools 사용
- Redux DevTools 활성화
- 성능 프로파일링 도구2. API 문서 자동 동기화
OpenAPI 스펙이나 GraphQL 스키마를 자동으로 참조해 최신 API 정보를 유지합니다:
<!-- .kiro/steering/api-sync.md -->
---
inclusion: fileMatch
fileMatchPattern: "src/api/**/*.ts"
---
# API 자동 동기화
최신 API 스펙:
#[[file:docs/openapi.yaml]]
GraphQL 스키마:
#[[file:schema.graphql]]
## 변경 감지
API 스펙이 변경되면 자동으로 타입 정의를 업데이트합니다.3. 팀별 컨벤션 적용
팀의 역할마다 다른 가이드라인을 줍니다:
<!-- .kiro/steering/frontend-team.md -->
---
inclusion: fileMatch
fileMatchPattern: "src/components/**/*"
---
# 프론트엔드 팀 가이드
## 컴포넌트 설계 원칙
- 단일 책임 원칙
- 재사용 가능한 구조
- 접근성 고려
## 스타일링 규칙
- CSS-in-JS 사용
- 디자인 토큰 활용
- 반응형 디자인 필수1. 점진적 구축
처음에는 간단한 project-overview.md부터 시작하고,
필요에 따라 세분화된 규칙을 추가합니다.
2. 규칙 우선순위
더 구체적인 규칙이 일반적인 규칙보다 앞섭니다.
fileMatch 패턴으로 컨텍스트별 규칙을 적용하세요.
3. 문서 참조 활용
API 스펙이나 스키마 파일을 #[[file:]] 문법으로 참조하면
Kiro가 그 파일 내용을 컨텍스트로 활용합니다.
4. 팀 공유
Steering 파일은 Git으로 관리되므로 팀 전체가 동일한 컨텍스트를 공유할 수 있습니다.
참고 문서
- Kiro 공식 사이트: https://kiro.dev
- Kiro 문서: https://kiro.dev/docs