Steering¶
Steering이란?¶
Steering은 마크다운 파일을 통해 워크스페이스에 대한 영구적인 지식을 Kiro에게 제공합니다. 모든 채팅에서 규칙을 설명하는 대신, steering 파일은 Kiro가 확립된 패턴, 라이브러리 및 표준을 일관되게 따르도록 보장합니다.
주요 이점¶
일관된 코드 생성 - 모든 컴포넌트, API 엔드포인트 또는 테스트가 팀의 확립된 패턴과 규칙을 따릅니다.
반복 감소 - 각 대화에서 워크스페이스 표준을 설명할 필요가 없습니다. Kiro가 선호도를 기억합니다.
팀 정렬 - 워크스페이스를 처음 접하는 개발자든 숙련된 기여자든 모든 개발자가 동일한 표준으로 작업합니다.
확장 가능한 프로젝트 지식 - 프로젝트가 발전함에 따라 결정과 패턴을 포착하면서 코드베이스와 함께 성장하는 문서입니다.
Steering 파일 범위¶
Steering 파일은 워크스페이스 범위 또는 전역 범위로 생성할 수 있습니다.
워크스페이스 steering¶
워크스페이스 steering 파일은 .kiro/steering/ 아래 워크스페이스 루트 폴더에 있으며 해당 특정 워크스페이스에만 적용됩니다. 워크스페이스 steering 파일은 개별 워크스페이스에 적용되는 패턴, 라이브러리 및 표준을 Kiro에게 알리는 데 사용할 수 있습니다.
전역 steering¶
전역 steering 파일은 ~/.kiro/steering/ 아래 홈 디렉토리에 있으며 모든 워크스페이스에 적용됩니다. 전역 steering 파일은 모든 워크스페이스에 적용되는 규칙을 Kiro에게 알리는 데 사용할 수 있습니다.
전역 steering과 워크스페이스 steering 간에 충돌하는 지시사항이 있는 경우 Kiro는 워크스페이스 steering 지시사항을 우선시합니다. 이를 통해 일반적으로 모든 워크스페이스에 적용되는 전역 지시문을 지정하면서 특정 워크스페이스에 대해 해당 지시문을 재정의할 수 있는 기능을 유지할 수 있습니다.
팀 steering¶
전역 steering 기능을 사용하여 전체 팀에 적용되는 중앙 집중식 steering 파일을 정의할 수 있습니다. 팀 steering 파일은 MDM 솔루션이나 그룹 정책을 통해 사용자의 PC로 푸시되거나, 사용자가 중앙 저장소에서 PC로 다운로드하여 ~/.kiro/steering 폴더에 배치할 수 있습니다.
기본 steering 파일¶
Kiro는 핵심 프로젝트 컨텍스트를 설정하기 위한 기본 steering 파일을 제공합니다. 다음과 같이 이러한 파일을 생성할 수 있습니다:
- Kiro 패널에서 Steering 섹션으로 이동합니다
- Generate Steering Docs 버튼을 클릭하거나 + 버튼을 클릭하고 Foundation steering files 옵션을 선택합니다
- Kiro가 세 개의 기본 파일을 생성합니다:
제품 개요 (product.md) - 제품의 목적, 대상 사용자, 주요 기능 및 비즈니스 목표를 정의합니다. 이를 통해 Kiro는 기술적 결정의 "이유"를 이해하고 제품 목표에 부합하는 솔루션을 제안할 수 있습니다.
기술 스택 (tech.md) - 선택한 프레임워크, 라이브러리, 개발 도구 및 기술적 제약 사항을 문서화합니다. Kiro가 구현을 제안할 때 대안보다 확립된 스택을 선호합니다.
프로젝트 구조 (structure.md) - 파일 구성, 명명 규칙, 가져오기 패턴 및 아키텍처 결정을 개략적으로 설명합니다. 이를 통해 생성된 코드가 기존 코드베이스에 원활하게 통합됩니다.
이러한 기본 파일은 기본적으로 모든 상호작용에 포함되어 Kiro의 프로젝트 이해의 기준선을 형성합니다.
사용자 정의 steering 파일 생성¶
- Kiro 패널에서 Steering 섹션으로 이동합니다
- + 버튼을 클릭합니다
- steering 파일의 범위를 선택합니다: 워크스페이스 또는 전역
- 설명이 포함된 파일명을 선택합니다 (예:
api-standards.md) - 표준 마크다운 구문을 사용하여 가이드를 작성합니다
- 자연어를 사용하여 요구사항을 설명합니다
- 선택적으로, 워크스페이스 steering 파일의 경우 Refine 버튼을 사용하여 Kiro가 요구사항을 개선하도록 할 수 있습니다
생성되면 steering 파일은 모든 Kiro 상호작용에서 즉시 사용할 수 있습니다.
Agents.md¶
Kiro는 AGENTS.md 표준을 통해 steering 지시문을 제공하는 것을 지원합니다. AGENTS.md 파일은 Kiro steering 파일과 유사하게 마크다운 형식입니다. 그러나 AGENTS.md 파일은 포함 모드를 지원하지 않으며 항상 포함됩니다.
AGENTS.md 파일을 전역 steering 파일 위치(~/.kiro/steering/) 또는 워크스페이스의 루트 폴더에 추가할 수 있으며 Kiro가 자동으로 선택합니다.
포함 모드¶
Steering 파일은 필요에 따라 다양한 시간에 로드되도록 구성할 수 있습니다. 이러한 유연성은 성능을 최적화하고 필요할 때 관련 컨텍스트를 사용할 수 있도록 보장하는 데 도움이 됩니다.
steering 파일 상단에 프론트 매터를 추가하여 포함 모드를 구성합니다. 프론트 매터는 YAML 구문을 사용하며 파일의 맨 처음에 배치되어야 하며 삼중 대시(---)로 둘러싸여 있어야 합니다.
정보
포함 구성은 파일의 첫 번째 콘텐츠여야 하며, 그 앞에 빈 줄이나 콘텐츠가 없어야 합니다.
항상 포함 (기본값)¶
yaml
--- inclusion: always ---
이러한 파일은 모든 Kiro 상호작용에 자동으로 로드됩니다. 모든 코드 생성 및 제안에 영향을 미쳐야 하는 핵심 표준에 이 모드를 사용합니다. 예를 들어 기술 스택, 코딩 규칙 및 기본 아키텍처 원칙이 포함됩니다.
가장 적합한 경우: 워크스페이스 전체 표준, 기술 선호도, 보안 정책 및 보편적으로 적용되는 코딩 규칙.
조건부 포함¶
yaml
--- inclusion: fileMatch fileMatchPattern: "components/**/*.tsx" ---
파일은 지정된 패턴과 일치하는 파일로 작업할 때만 자동으로 포함됩니다. 이를 통해 필요할 때만 전문화된 가이드를 로드하여 컨텍스트를 관련성 있게 유지하고 노이즈를 줄입니다.
배열을 사용하여 여러 패턴을 지정할 수도 있습니다:
yaml
--- inclusion: fileMatch fileMatchPattern: ["**/*.ts", "**/*.tsx", "**/tsconfig.*.json"] ---
일반적인 패턴:
"*.tsx"- React 컴포넌트 및 JSX 파일"app/api/**/*"- API 라우트 및 백엔드 로직"**/*.test.*"- 테스트 파일 및 테스트 유틸리티"src/components/**/*"- 컴포넌트별 가이드라인"*.md"- 문서 파일["**/*.ts", "**/*.tsx"]- 모든 TypeScript 파일["*.js", "*.jsx", "*.ts", "*.tsx"]- 모든 JavaScript 및 TypeScript 파일
가장 적합한 경우: 컴포넌트 패턴, API 설계 규칙, 테스트 접근 방식 또는 특정 파일 유형에만 적용되는 배포 절차와 같은 도메인별 표준.
수동 포함¶
yaml
--- inclusion: manual ---
파일은 채팅 메시지에서 #steering-file-name으로 참조하여 필요에 따라 사용할 수 있습니다. 이를 통해 모든 상호작용을 어지럽히지 않고 전문화된 컨텍스트가 필요한 시기를 정확하게 제어할 수 있습니다.
사용법: 채팅에서 #troubleshooting-guide 또는 #performance-optimization을 입력하여 현재 대화에 해당 steering 파일을 포함합니다.
가장 적합한 경우: 전문화된 워크플로우, 문제 해결 가이드, 마이그레이션 절차 또는 가끔만 필요한 컨텍스트가 많은 문서.
자동 포함¶
yaml
--- inclusion: auto name: api-design description: REST API design patterns and conventions. Use when creating or modifying API endpoints. ---
파일은 요청이 설명과 일치할 때 자동으로 포함됩니다. 이는 스킬과 유사하게 작동합니다. Kiro는 설명을 사용하여 steering 파일이 관련이 있는 시기를 결정합니다.
| 필드 | 필수 | 설명 |
|---|---|---|
name |
예 | steering 파일의 식별자. 디스플레이 및 매칭에 사용됩니다. |
description |
예 | 이 파일을 포함할 시기. Kiro는 이를 요청과 매칭합니다. |
가장 적합한 경우: 관련이 있을 때만 로드되어야 하는 컨텍스트가 많은 가이드 - 전문화된 도메인 지식, 복잡한 워크플로우 또는 항상 켜져 있는 steering을 압도할 수 있는 상세한 참조 자료.
파일 참조¶
실시간 워크스페이스 파일에 링크하여 steering을 최신 상태로 유지합니다:
markdown
#[[file:<relative_file_name>]]
예시:
- API 스펙:
#[[file:api/openapi.yaml]] - 컴포넌트 패턴:
#[[file:components/ui/button.tsx]] - 구성 템플릿:
#[[file:.env.example]]
모범 사례¶
파일을 집중적으로 유지 도메인당 하나의 파일 - API 설계, 테스트 또는 배포 절차.
명확한 이름 사용
api-rest-conventions.md- REST API 표준testing-unit-patterns.md- 단위 테스트 접근 방식components-form-validation.md- 양식 컴포넌트 표준
컨텍스트 포함 표준이 무엇인지뿐만 아니라 왜 결정이 내려졌는지 설명합니다.
예시 제공 코드 스니펫과 이전/이후 비교를 사용하여 표준을 시연합니다.
보안 우선 API 키, 비밀번호 또는 민감한 데이터를 절대 포함하지 마세요. Steering 파일은 코드베이스의 일부입니다.
정기적으로 유지 관리
- 스프린트 계획 및 아키텍처 변경 중에 검토
- 재구조화 후 파일 참조 테스트
- steering 변경을 코드 변경처럼 처리 - 검토 필요
일반적인 steering 파일 전략¶
API 표준 (api-standards.md) - REST 규칙, 오류 응답 형식, 인증 플로우 및 버전 관리 전략을 정의합니다. 엔드포인트 명명 패턴, HTTP 상태 코드 사용 및 요청/응답 예시를 포함합니다.
테스트 접근 방식 (testing-standards.md) - 단위 테스트 패턴, 통합 테스트 전략, 모킹 접근 방식 및 커버리지 기대치를 확립합니다. 선호하는 테스트 라이브러리, 어설션 스타일 및 테스트 파일 구성을 문서화합니다.
코드 스타일 (code-conventions.md) - 명명 패턴, 파일 구성, 가져오기 순서 및 아키텍처 결정을 지정합니다. 선호하는 코드 구조, 컴포넌트 패턴 및 피해야 할 안티패턴의 예시를 포함합니다.
보안 가이드라인 (security-policies.md) - 인증 요구사항, 데이터 검증 규칙, 입력 삭제 표준 및 취약점 방지 조치를 문서화합니다. 애플리케이션에 특정한 안전한 코딩 관행을 포함합니다.
배포 프로세스 (deployment-workflow.md) - 빌드 절차, 환경 구성, 배포 단계 및 롤백 전략을 개략적으로 설명합니다. CI/CD 파이프라인 세부 정보 및 환경별 요구사항을 포함합니다.