💡 팁 Hook을 너무 많이 만들면 IDE가 느려질 수 있다. 처음에는 꼭 필요한 2-3개만 만들어서 사용해보고, 효과를 확인한 후 점진적으로 추가하는 것을 추천한다. 특히 파일 저장 시 실행되는 Hook은 실행 빈도 제한을 반드시 설정해야 한다.
ex) 방법1
1. Cmd/Ctrl + Shift + P 로 Command Palette 열기
2. "Open Kiro Hook UI" 검색 및 실행
3. 각 Hook 파일을 참조하여 설정 생성
- 설정창 Open
- 하기와 같이 Hooks 생성 페이지가 노출될 것이다. 하단의 샘플 예시인 "Update my documentation"클릭.
- 다음과 같이 Hooks가 하나 생성된다. (파일 변경을 계속 지켜보다가 변경된 파일에 대한 문서화를 지정하는 Hooks) > 우측 상단의 Enter 버튼 클릭 한다.
# 번역
이 저장소(repository)의 모든 소스 파일을 감시(listen)합니다.
예를 들어, TypeScript 프로젝트라면 *.ts 파일을, Python 프로젝트라면 *.py 파일을 감시합니다.
또한 소스와 관련된 특정 기타 파일이나 패턴들도 함께 감시합니다.
이러한 파일들에 변경(change)이 발생하면, 에이전트(agent)에게 README를 수정하거나 /docs 폴더가 있다면 해당 문서를 업데이트하도록 요청합니다.
- Agent Hook 생성 요청을 진행 하는 모습
- 조금 기다리면 다음과 같이 훅이 생성된것을 볼 수 있다.
- 궁금하신 분들을 위해 한글화 하면..
- 생성된 실제 hook 파일을 열어보면 대상 패턴까지 다 지정 되어있다.
- 이런식으로 등록가능하니, kiro가 추천해준 훅 5개중에서 2개 먼저 등록 해 보도록 하겠다. ( 이후 불필요한 훅들은 삭제하도록 하자 )
1. RAG 코드 품질 자동 검증 Hook
// 트리거: rag_chatbot.py 파일 저장 시
Hook 설정:
- 이름: RAG 코드 품질 검증
- 트리거: rag_chatbot.py 파일 저장 시
- 실행 조건: 파일 크기가 1KB 이상일 때
- 이전과 동일하게 에이전트 훅 생성 요청을 시도하였다.
- 신규 hook 파일이 생성 되었다.
{
"enabled": true,
"name": "RAG 코드 품질 검증",
"description": "rag_chatbot.py 파일이 저장될 때 코드 품질을 자동으로 검증하고 개선 사항을 제안합니다. 파일 크기가 1KB 이상일 때만 실행됩니다.",
"version": "1",
"when": {
"type": "fileEdited",
"patterns": [
"rag_chatbot.py"
]
},
"then": {
"type": "askAgent",
"prompt": "rag_chatbot.py 파일이 업데이트되었습니다. 다음 항목들을 검증해주세요:\n\n1. **코드 품질 분석**:\n - 함수와 클래스의 구조적 완성도\n - 에러 핸들링의 적절성\n - 타입 힌트와 docstring 완성도\n\n2. **RAG 파이프라인 검증**:\n - DocumentProcessor, EmbeddingManager, VectorStoreManager, RAGChainManager 클래스들의 일관성\n - AWS Bedrock과 OpenSearch 연동 코드의 정확성\n - 설정 관리와 환경 변수 처리\n\n3. **성능 및 보안**:\n - 메모리 사용 최적화 여부\n - AWS 자격 증명 보안 처리\n - 에러 복구 로직의 견고성\n\n4. **개선 제안**:\n - 코드 구조 개선점\n - 성능 최적화 방안\n - 추가 테스트가 필요한 영역\n\n파일 크기가 1KB 미만이면 \"파일이 너무 작아 품질 검증을 건너뜁니다\"라고 응답하세요."
}
}
해결한 문제 이전에는 코드를 수정하고 실행해봐야 문법 오류나 import 누락을 알 수 있었다. 특히 대용량 파일에서는 오타 하나 때문에 몇 분씩 기다렸다가 에러를 보는 경우가 많았다. 이 Hook 덕분에 파일을 저장하는 순간 즉시 피드백을 받을 수 있게 되었다.
2. AWS 환경 상태 자동 체크 Hook
// 트리거: 수동 버튼 클릭 ("AWS 상태 확인")
name: "AWS 환경 상태 체크"
trigger: "수동 버튼 클릭"
action: "AWS 자격 증명 및 서비스 연결 상태 확인"
//결과
{
"enabled": true,
"name": "AWS 환경 상태 체크",
"description": "수동 버튼 클릭으로 AWS 자격 증명 및 서비스 연결 상태를 확인합니다. Bedrock, OpenSearch 등 RAG 시스템에 필요한 AWS 서비스들의 접근 권한과 연결 상태를 검증합니다.",
"version": "1",
"when": {
"type": "fileEdited",
"patterns": [
".env",
"rag_chatbot.py",
"tests/test_aws_integration.py"
]
},
"then": {
"type": "askAgent",
"prompt": "AWS 환경 상태를 체크해주세요. 다음 항목들을 확인하고 결과를 보고해주세요:\n\n1. AWS 자격 증명 유효성 검사\n2. Bedrock 서비스 접근 권한 확인 (Claude 3.5 Sonnet, Titan Embed 모델)\n3. OpenSearch 클러스터 연결 상태 확인\n4. 필요한 IAM 권한 검증\n5. 리전 설정 확인 (us-west-2 권장)\n6. 환경 변수 설정 상태 점검\n\n각 항목에 대해 ✅ 정상 또는 ❌ 오류 상태를 표시하고, 오류가 있는 경우 해결 방법을 제안해주세요. RAG 시스템이 정상 작동하기 위한 모든 AWS 서비스 의존성을 검증해주세요."
}
}
Agent Steering: AI 어시스턴트
Agent Steering은 AI 어시스턴트(Claude 같은)가 프로젝트에서 작업할 때 일관된 가이드라인과 컨텍스트를 제공하는 시스템이다.
매번 "이 프로젝트는 이런 구조고, 이런 규칙을 따라주세요"라고 설명하지 않아도 AI가 프로젝트의 특성을 이해하고 적절한 답변을 해준다.
구분
Agent Hooks
Agent Steering
목적
자동화된 작업 실행
AI 어시스턴트 가이드라인 제공
실행 시점
특정 이벤트 발생 시
AI와 대화할 때마다
내용
실행할 명령어/스크립트
프로젝트 규칙/표준/컨텍스트
사용자
개발자 (자동화)
AI 어시스턴트 (지침)
현재 생성되어있는 Steering 파일 3개 분석
RAG 챗봇 프로젝트를 초기 구성시 생성된 3개의 Steering 파일을 실제로 분석해보자.
각각이 어떤 역할을 하는지, 어떻게 작성해야 효과적인지 살펴보자.
1. tech.md - 기술 스택 가이드
- 실제 데이터
# 기술 스택 (Technology Stack)
## 빌드 시스템 & 패키지 관리 (Build System & Package Management)
- **Python 버전**: 3.12+
- **패키지 매니저**: UV (권장) 또는 pip
- **빌드 시스템**: Hatchling
- **프로젝트 설정**: pyproject.toml
## 핵심 의존성 (Core Dependencies)
### AWS 서비스 (AWS Services)
- **AWS Bedrock**: LLM 및 임베딩 모델
- 임베딩 모델: `amazon.titan-embed-text-v2`
- LLM 모델: `anthropic.claude-3-5-sonnet-20241022-v2:0`
- **Amazon OpenSearch**: 벡터 저장소 및 유사도 검색
- **boto3**: AWS SDK for Python
#### AWS Bedrock 모델 설정 가이드
**토큰 단위 이해:**
- **토큰 단위**: 개별 토큰 (k 단위가 아님)
- **영어**: 1 토큰 ≈ 0.75 단어
- **한국어**: 1 토큰 ≈ 1-2 글자
- **예시**: 500 토큰 = 약 375 영어 단어 또는 500-1000 한국어 글자
**Claude 3.5 Sonnet 권장 설정:**
- **일반 RAG 응답**: 1000-2000 토큰
- **상세 설명**: 2000-4000 토큰
- **최대 출력 한도**: 8192 토큰
- **현재 설정**: 2000 토큰 (적절한 균형)
**Temperature 설정:**
- **0.0**: 가장 일관된 응답 (결정적)
- **0.3-0.7**: 균형잡힌 창의성과 일관성
- **1.0**: 가장 창의적 응답
- **현재 설정**: 0.6 (RAG에 적합)
### LangChain 프레임워크 (LangChain Framework)
- **langchain**: RAG 파이프라인 핵심 프레임워크
- **langchain-aws**: AWS Bedrock 통합
- **langchain-community**: OpenSearch 등 커뮤니티 확장
### 보조 라이브러리 (Supporting Libraries)
- **python-dotenv**: 환경 변수 관리
- **opensearch-py**: OpenSearch 클라이언트
- **pydantic**: 데이터 검증 및 설정 관리
## 개발 도구 (Development Tools)
### 코드 품질 (Code Quality)
- **black**: 코드 포맷팅 (라인 길이: 88)
- **flake8**: 린팅
- **mypy**: 타입 체크
- **pytest**: 테스트 프레임워크
## 공통 명령어 (Common Commands)
### 환경 설정 (Environment Setup)
# 가상 환경 생성
uv venv --python 3.12
source .venv/bin/activate
# 의존성 설치
uv pip install -e .
# 개발 의존성 설치
uv pip install -e ".[dev]"
### 개발 워크플로우 (Development Workflow)
# 애플리케이션 실행
python rag_chatbot.py
# 코드 포맷팅
black rag_chatbot.py
# 타입 체크
mypy rag_chatbot.py
# 테스트 실행
pytest
### 설정 (Configuration)
# 환경 변수 설정
cp .env.template .env
# .env 파일을 열어 AWS 자격 증명 및 OpenSearch 엔드포인트 입력
## AWS 설정 요구사항 (AWS Configuration Requirements)
### 필요한 권한 (Required Permissions)
- `bedrock:InvokeModel` - Bedrock LLM 및 임베딩 모델 호출
- OpenSearch 클러스터 접근 권한
### 환경 변수 (Environment Variables)
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `AWS_REGION` (기본값: us-west-2)
- `OPENSEARCH_ENDPOINT`
- `OPENSEARCH_USERNAME`
- `OPENSEARCH_PASSWORD`
### 모델 설정 오버라이드 (선택사항)
# .env 파일에서 기본 모델 변경 가능
BEDROCK_EMBEDDING_MODEL_ID=amazon.titan-embed-text-v2
BEDROCK_LLM_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
### AWS 리전 선택 가이드
**권장 리전: us-west-2 (오레곤)**
- 가장 많은 Bedrock 모델 지원
- 최신 모델들이 먼저 출시되는 리전
- Claude 3.5 Sonnet, Opus 등 고급 모델 사용 가능
- us-east-1보다 모델 제약이 적음
### 모델 성능 비교 (Model Performance Comparison)
| 모델 | 용도 | 장점 | 토큰 한도 |
|------|------|------|-----------|
| Titan Embed Text v2 | 임베딩 | 다국어 지원, 높은 정확도 | 8K 입력 |
| Claude 3.5 Sonnet | LLM | 뛰어난 추론, 긴 컨텍스트 | 200K 입력, 8K 출력 |
| Claude 3 Haiku | LLM (빠른 응답) | 빠른 속도, 비용 효율적 | 200K 입력, 4K 출력 |
역할: 기술적 구현 세부사항과 AWS 설정 가이드 완성도: 매우 높음 (95%)
주요 내용:
✅ AWS Bedrock 모델 설정: 토큰 단위, Temperature, 모델별 특성
✅ 개발 환경: Python 3.12+, UV 패키지 매니저, 의존성 관리
✅ AWS 구성: 권한, 환경 변수, 리전 선택 가이드
✅ 개발 도구: Black, Flake8, MyPy, Pytest
✅ 실행 명령어: 환경 설정부터 테스트까지 완전한 명령어 세트
강점:
한국어 토큰 처리 가이드 포함
모델별 성능 비교표 제공
실무적인 AWS 설정 팁
2. structure.md - 프로젝트 구조 가이드
- 실제 데이터
# 프로젝트 구조 (Project Structure)
## 디렉토리 레이아웃 (Directory Layout)
```
rag-chatbot-poc/
├── .kiro/ # Kiro IDE 설정 (Kiro IDE configuration)
│ ├── specs/ # 프로젝트 명세 (Project specifications)
│ │ ├── requirements.md # 요구사항 문서 (Requirements document)
│ │ ├── design.md # 설계 문서 (Design document)
│ │ └── tasks.md # 구현 작업 (✅ 완료) (Implementation tasks, completed)
│ ├── steering/ # AI 어시스턴트 가이드 규칙 (AI assistant guidance rules)
│ │ ├── tech.md # 기술 스택 가이드 (Technology stack guide)
│ │ ├── structure.md # 프로젝트 구조 가이드 (Project structure guide)
│ │ └── product.md # 제품 개요 (Product overview)
│ └── hooks/ # Agent Hooks 설정 (Agent Hooks configurations)
│ ├── rag-code-quality-check.md # 코드 품질 자동화 (Code quality automation)
│ ├── aws-status-checker.md # AWS 환경 점검 (AWS environment checker)
│ ├── performance-monitor.md # 성능 모니터링 (Performance monitoring)
│ ├── documentation-updater.md # 문서 동기화 (Documentation sync)
│ ├── deployment-readiness-checker.md # 배포 검증 (Deployment validation)
│ └── README.md # Hooks 사용 가이드 (Hooks usage guide)
├── pyproject.toml # 프로젝트 설정 및 의존성 (Project configuration and dependencies)
├── rag_chatbot.py # 🚀 메인 애플리케이션 (5000+ 라인) (Main application)
├── sample_data.txt # RAG 시스템 테스트용 샘플 데이터 (Sample data)
├── RAG_CHATBOT_SPECIFICATION.md # 상세 기술 명세 (Detailed technical specification)
├── .env.template # 환경 변수 템플릿 (Environment variables template)
├── .env # 실제 환경 변수 (gitignored) (Actual environment variables)
├── README.md # 종합 프로젝트 문서 (Comprehensive project documentation)
├── test_aws_integration_simple.py # 🧪 AWS 통합 테스트 (간단) (AWS integration test, simple)
├── test_aws_integration.py # 🔬 AWS 통합 테스트 (종합) (AWS integration test, comprehensive)
├── test_performance_metrics.py # 📊 성능 지표 테스트 (Performance metrics test)
├── test_document_processor.py # 📄 문서 처리 테스트 (Document processing test)
├── test_similarity_search.py # 🔍 유사도 검색 테스트 (Similarity search test)
└── performance_results.json # 📈 성능 테스트 결과(자동 생성) (Performance test results, generated)
```
## 파일 구성 원칙 (File Organization Principles)
### Single-File 아키텍처 (Single-File Architecture)
- **주요 구현 (Main Implementation)**: 모든 핵심 RAG 기능은 `rag_chatbot.py`에 포함
- **모듈형 함수 (Modular Functions)**: 각 주요 컴포넌트(문서 처리, 임베딩, 벡터 스토어, LLM)를 분리된 함수로 구성
- **명확한 분리 (Clear Separation)**: 관심사별 명확히 구분된 클래스 구조 (예: `ConfigManager`, `DocumentProcessor` 등)
### 구성 관리 (Configuration Management)
- **환경 템플릿 (Environment Template)**: 필요한 변수를 `.env.template`에 명시
- **로컬 환경 (Local Environment)**: 실제 자격 증명은 `.env`에 저장(커밋 금지)
- **기본 구성 (Default Config)**: `DEFAULT_CONFIG` 딕셔너리에 하드코딩된 기본값 제공
### 데이터 파일 (Data Files)
- **샘플 데이터 (Sample Data)**: 데모/테스트용 `sample_data.txt`
- **벡터 저장소 (Vector Storage)**: 실행 시 생성되는 OpenSearch 인덱스(로컬에 저장하지 않음)
- **성능 데이터 (Performance Data)**: 성능 추적용 `performance_results.json`
- **테스트 결과 (Test Results)**: 테스트 스위트 실행 시 생성되는 다양한 JSON 결과
### 테스트 파일 구성 (Test Files Organization)
- **통합 테스트 (Integration Tests)**: AWS 서비스 검증용 `test_aws_integration*.py`
- **성능 테스트 (Performance Tests)**: 성능 모니터링용 `test_performance_metrics.py`
- **컴포넌트 테스트 (Component Tests)**: `test_document_processor.py`, `test_similarity_search.py`
- **테스트 결과 (Test Results)**: 자동 분석을 위한 JSON 출력
### Agent Hooks 구조 (Agent Hooks Structure)
- **품질 보증 (Quality Assurance)**: 자동 코드 검증용 `rag-code-quality-check.md`
- **환경 모니터링 (Environment Monitoring)**: AWS 상태 점검용 `aws-status-checker.md`
- **성능 추적 (Performance Tracking)**: 지속 최적화용 `performance-monitor.md`
- **문서 동기화 (Documentation Sync)**: 문서 최신 상태 유지용 `documentation-updater.md`
- **배포 검증 (Deployment Validation)**: 사전 배포 점검용 `deployment-readiness-checker.md`
## 코드 구성 패턴 (Code Organization Patterns)
### 클래스 구조 (Class Structure)
```python
# 설정 및 초기화 (Configuration and setup)
class ConfigManager
class RAGChatbotError # (and subclasses)
# 핵심 처리 컴포넌트 (Core processing components)
class DocumentProcessor
class EmbeddingManager
class VectorStoreManager
class RAGChainManager
# 데이터 모델 (Data models)
@dataclass
class DocumentChunk: ...
@dataclass
class QueryRequest: ...
@dataclass
class RAGResponse: ...
```
### 함수 명명 규칙 (Function Naming Conventions)
- **설명적 이름 사용 (Descriptive names)**: `load_document()`, `create_embeddings()`
- **에러 처리 전담 함수 (Error handling)**: 입력 검증용 `validate_*()` 패턴
- **프라이빗 메서드 (Private methods)**: 언더스코어 접두사 사용 `_internal_helper()`
### 상수 및 구성 (Constants and Configuration)
- **ALL_CAPS**: 환경 변수명 (예: `ENV_AWS_ACCESS_KEY_ID`)
- **UPPER_SNAKE_CASE**: 서비스명/파일 경로 (예: `AWS_BEDROCK_SERVICE`)
- **Dictionary**: 런타임 구성 (예: `DEFAULT_CONFIG`)
## 임포트 구성 (Import Organization)
```python
# 표준 라이브러리 우선 (Standard library imports first)
import os, sys, logging
from typing import List, Dict, Any
from dataclasses import dataclass
# 서드파티 라이브러리 (Third-party imports)
import boto3
from langchain import *
# 로컬 임포트(있는 경우) (Local imports, if any)
from .local_module import something
```
## 에러 처리 구조 (Error Handling Structure)
- **커스텀 예외 (Custom Exceptions)**: `RAGChatbotError`를 상속하여 정의
- **구체적 에러 (Specific Errors)**: `AWSConfigurationError`, `DocumentProcessingError` 등
- **우아한 강등 (Graceful Degradation)**: 항상 의미 있는 오류 메시지 제공
## 문서화 표준 (Documentation Standards)
- **모듈 도크스트링 (Module Docstring)**: 파일 상단에 전체 개요 제공
- **함수 도크스트링 (Function Docstrings)**: 목적, 파라미터, 반환값, 예외 명시
- **인라인 주석 (Inline Comments)**: 복잡 로직과 AWS 특화 설정 설명
- **타입 힌트 (Type Hints)**: 모든 함수 파라미터 및 반환값에 사용
## 규칙 (rule)
- 한국어로 말하기 (speak korean).
역할: 코드 조직화 원칙과 파일 구조 가이드 완성도: 매우 높음 (98%) - 최근 업데이트로 완성도 대폭 향상
주요 내용:
✅ 최신 디렉토리 구조: Agent Hooks, 테스트 파일 모두 반영
✅ 단일 파일 아키텍처: 5000+ 라인의 rag_chatbot.py 구조 설명
✅ 클래스 조직화: ConfigManager, DocumentProcessor 등 명확한 분리
✅ 테스트 파일 조직화: 통합/성능/컴포넌트 테스트 분류
✅ Agent Hooks 구조: 5개 Hook의 역할과 목적 명시
✅ 코딩 컨벤션: 네이밍, import 순서, 에러 핸들링 패턴
강점:
실제 프로젝트 상태를 정확히 반영
개발자 온보딩에 최적화된 구조
3. product.md - 제품 개요
- 실제 데이터
# 제품 개요 (Product Overview)
## RAG 챗봇 PoC - 프로덕션 레디
A **complete** Retrieval-Augmented Generation (RAG) 챗봇 PoC로, AWS 서비스를 활용한 프로덕션 레디 RAG 파이프라인을 보여줍니다.
이 시스템은 문서 처리, 벡터 임베딩, 유사도 검색, 대형 언어 모델(LLM) 생성을 결합하여 사용자 질의에 맥락 기반 답변을 제공합니다.
**개발 상태**: ✅ **완료** (13단계 개발 사이클 종료)
**버전**: 1.0.0 - 프로덕션 레디
**완료일**: 2025년 9월 22일
## 주요 기능 (Key Features)
### 핵심 RAG 파이프라인
- **문서 처리**: 중첩 및 인코딩 지원이 포함된 고급 텍스트 청킹
- **벡터 임베딩**: AWS Bedrock Titan 모델, 배치 처리 최적화
- **벡터 저장소**: Amazon OpenSearch, k-NN 검색 및 메타데이터 인덱싱
- **답변 생성**: AWS Bedrock Claude 3.5 Sonnet, 맥락 기반 프롬프트
- **단일 파일 아키텍처**: 프로덕션 레디 Python 코드 5000+ 라인
### 품질 보증 및 테스트
- **종합 테스트 스위트**: 모든 컴포넌트를 커버하는 5개 전문 테스트 스크립트
- **성능 모니터링**: 자동화된 메트릭 수집 및 최적화 권장사항
- **AWS 통합 테스트**: 오류 시나리오 포함, 엔드 투 엔드 파이프라인 검증
- **에이전트 훅(Agent Hooks)**: 개발 효율성을 위한 자동 워크플로우 5개
### 개발자 경험
- **완전한 문서화**: README, 명세서, 인라인 문서 제공
- **에러 처리**: AWS 서비스별 오류 진단 및 해결 가이드
- **성능 최적화**: 내장 메트릭 및 튜닝 권장사항
- **개발 자동화**: 코드 품질, 테스트, 배포를 위한 Agent Hooks
## 대상 사용자 (Target Users)
### 주요 사용자
- **엔터프라이즈 개발자**: AWS 기반 프로덕션 RAG 시스템 구축
- **솔루션 아키텍트**: 확장 가능한 문서 Q&A 시스템 설계
- **DevOps 엔지니어**: RAG 애플리케이션 배포 및 모니터링
### 보조 사용자
- **학생 및 연구자**: RAG 시스템 아키텍처 학습
- **스타트업 팀**: AI 기반 애플리케이션 빠른 프로토타이핑
- **컨설턴트**: 고객 대상 AWS AI 기능 데모
## 성공 기준 ✅ 달성됨 (Success Criteria ✅ ACHIEVED)
### 기술적 우수성
- ✅ **제로 셋업 배포**: AWS 자격 증명과 샘플 데이터만 필요
- ✅ **프로덕션 아키텍처**: 확장성, 유지보수성, 확장성 보장
- ✅ **종합 테스트**: 자동화 검증 포함 95%+ 테스트 커버리지
- ✅ **성능 최적화**: 최적화 가이드 포함 5초 미만 응답 시간
### 문서화 및 사용성
- ✅ **완전한 문서화**: 모든 사용자 수준을 위한 단계별 가이드
- ✅ **에러 복구**: 모든 실패 시나리오에 대한 상세 트러블슈팅
- ✅ **개발 효율성**: 자동화 워크플로우로 수작업 80% 감소
- ✅ **지식 전수**: 풍부한 인라인 가이드를 포함한 자체 문서화 코드
### 비즈니스 가치
- ✅ **비용 최적화**: 내장된 비용 모니터링 및 최적화 권장사항
- ✅ **확장성**: 엔터프라이즈 규모 배포 지원
- ✅ **유지보수성**: 단일 파일 설계 + 모듈형 클래스 구조
- ✅ **확장성**: 커스텀 컴포넌트를 위한 플러그인 아키텍처
## 성능 지표 (Performance Metrics)
### 현재 벤치마크
- **평균 응답 시간**: 2.34초 (목표: <5초) ✅
- **처리 처리량**: 15.6 문서/초 (목표: >10 문서/초) ✅
- **메모리 효율성**: 평균 245MB 사용 (목표: <500MB) ✅
- **테스트 성공률**: 95.2% (목표: >90%) ✅
### 확장성 목표
- **동시 사용자**: 10명 이상 동시 질의 지원
- **문서 용량**: 10,000+ 문서 청크로 테스트 완료
- **응답 품질**: 표준 벤치마크에서 85%+ 관련성 점수
## 배포 준비 상태 (Deployment Readiness)
### 인프라 요구사항
- **AWS 서비스**: Bedrock (모델 2개), OpenSearch (최소 t3.small)
- **컴퓨트**: 단일 인스턴스 배포, 오토스케일링 지원
- **스토리지**: 최소 로컬 저장소, 클라우드 네이티브 벡터 저장
- **네트워크**: HTTPS 엔드포인트, VPC 호환
### 운영 기능
- **상태 모니터링**: 내장 AWS 서비스 상태 확인
- **성능 추적**: 자동 메트릭 수집 및 알림
- **에러 복구**: 점진적 성능 저하 및 자동 재시도 로직
- **보안**: IAM 기반 접근 제어, 하드코딩 자격 증명 없음
## 다음 단계 및 로드맵 (Next Steps & Roadmap)
### 즉시 배포 (즉시 사용 가능)
1. **AWS 환경 설정**: IAM 사용자, Bedrock 접근 권한, OpenSearch 클러스터
2. **애플리케이션 배포**: 검증 포함 단일 명령 배포
3. **프로덕션 테스트**: 부하 테스트 및 성능 검증
4. **모니터링 설정**: CloudWatch 통합 및 알림
### 향후 개선 (1.0 이후)
- **멀티 문서 지원**: PDF, Word, 웹 콘텐츠 수집
- **고급 RAG 기법**: 하이브리드 검색, 재랭킹, 쿼리 확장
- **API 인터페이스**: 외부 시스템 통합을 위한 REST API
- **UI 대시보드**: 비기술 사용자용 웹 인터페이스
역할: 비즈니스 컨텍스트와 프로젝트 목표 정의 완성도: 매우 높음 (95%) - 최근 업데이트로 완전히 새로워짐
주요 내용:
✅ 프로젝트 완료 상태: Production Ready, 13단계 개발 완료 명시
✅ 성능 메트릭: 구체적인 벤치마크와 달성 목표
✅ 타겟 사용자: Primary/Secondary 사용자 명확한 분류
✅ 배포 준비도: 인프라 요구사항과 운영 기능
✅ 로드맵: 즉시 배포 가능 항목과 향후 개선 계획
강점:
비즈니스 가치와 기술적 성취 균형
실제 성능 데이터 기반 메트릭
Steering 파일 관리 전략
Steering 파일은 한번 만들어두면 끝은 아니다. 프로젝트가 진화하면서 함께 업데이트해야 문서이다.
하기와 같은 정도의 전략을 잡으면 좋지 않을까?
업데이트 유형
방법
주체
빈도
기술 스택 변경
수동
개발자
필요시
프로젝트 구조 변경
AI 어시스턴트 요청
개발자 + AI
주요 변경시
제품 상태 업데이트
AI 어시스턴트 요청
개발자 + AI
마일스톤 달성시
성능 메트릭
Agent Hook 연동
자동
테스트 실행시
키로에게 물어봤더니 요청시 계속 관리해주겠다라는 적극적인 자세를 보여줬다
실제 사용 사례 "structure.md에 Agent Hooks 디렉토리 구조 추가해줘"라고 AI에게 요청하면, 기존 파일 구조를 분석해서 일관된 형태로 업데이트해준다. 직접 편집하는 것보다 AI가 더 체계적으로 정리해주는 경우가 많다.
베스트 프랙티스
실제 프로젝트에서 사용하면서 커스터마이징이 필요하다고 느끼게 되었다.
이론적인 내용보다는 "실제로 써보니 이런 점이 중요하더라".
Agent Hooks 최적화 팁 1. 실행 빈도 제한은 필수 파일 저장 시 실행되는 Hook은 빈도 제한을 설정하자. "같은 파일에 대해 1분에 1회만 실행" 같은 조건이 없으면 IDE가 버벅거린다.
2. 조건부 실행으로 성능 확보 "파일 크기가 1KB 이상일 때만", "특정 확장자일 때만" 같은 조건을 활용해서 불필요한 실행을 방지하자. 3. 실행 시간이 긴 작업은 백그라운드로 전체 테스트 스위트 실행 같은 작업은 백그라운드에서 실행하고 완료 시 알림만 받는 방식으로 구성하자.
Agent Steering 작성 팁 예시 1. 파일당 하나의 도메인에 집중 tech.md는 기술 스택만, structure.md는 프로젝트 구조만 다루자. 여러 주제를 섞으면 AI가 혼란스러워한다.
2. 구체적인 예시와 함께 설명 "코드 품질을 유지하세요"보다는 "클래스명은 PascalCase, 함수명은 snake_case를 사용하세요"처럼 구체적으로 작성하자.
3. 정기적인 업데이트가 핵심 프로젝트가 진화하면 Steering 파일도 함께 업데이트해야 한다. 월 1회 정도는 검토하자.
단계별 도입 로드맵 예시
4단계 순차 도입 계획
1Step: 기본 환경 구축
Kiro IDE 설치 및 설정
기본적인 Steering 파일 3개 작성 (tech, structure, product)
AWS 상태 체크 Hook 1개만 우선 구현
2Step: 핵심 Hook 추가
코드 품질 검증 Hook 추가
배포 준비 체크 Hook 추가
실제 개발 워크플로우에서 테스트
3Step: 고도화 및 최적화
성능 모니터링 Hook 추가
문서 자동 업데이트 Hook 추가
실행 빈도 최적화 및 성능 튜닝
4Step: 팀 확산 및 표준화
팀 표준 Steering 파일 작성
Hook 사용 가이드 문서화
정기 업데이트 프로세스 구축
자주 묻는 질문 ❓
Q: Agent Hooks가 IDE 성능에 영향을 주나요?
A: 적절하게 설정하면 거의 영향이 없습니다. 실행 빈도 제한과 조건부 실행을 활용하면 됩니다. 제 경우 5개의 Hook을 사용하는데 체감상 성능 저하는 없었습니다.
Q: Steering 파일은 얼마나 자주 업데이트해야 하나요?
A: 월 1회 정도 검토하면 충분합니다. 단, 프로젝트 구조나 기술 스택이 변경되면 즉시 업데이트해야 합니다. 저는 AI에게 "Steering 파일 업데이트해줘"라고 요청해서 자동으로 관리하고 있습니다.
Q: 여러 프로젝트에서 같은 설정을 재사용할 수 있나요?
A: 네, 가능합니다. 공통 Hook 템플릿을 만들어두고 프로젝트별로 커스터마이징하는 방식을 추천합니다. 저는 AWS 관련 Hook들은 다른 프로젝트에서도 그대로 사용하고 있습니다.
Q: Hook 실행이 실패하면 어떻게 디버깅하나요?
A: Kiro IDE의 Output 패널에서 Hook 실행 로그를 확인할 수 있습니다. 대부분 권한 문제나 파일 경로 오류인 경우가 많습니다. Hook 파일에 상세한 에러 메시지와 해결 방법을 미리 정의해두는 것이 중요합니다.
주의사항 Hook에서 실행하는 스크립트에 민감한 정보(API 키, 비밀번호 등)를 하드코딩하지 않아야 한다. 해당 Hook들도 git 관리 대상이 되기 때문에 반드시 환경 변수를 사용하고, .env 파일은 git에 커밋하지 않도록 주의하자.
후기
Agent Hooks와 Agent Steering을 실제 프로젝트에서 사용해본 결과, 개발 효율성이 당연히 향상됐다.
물론 커서로도 가능하고, MCP로도 가능한 기능들이지만, IDE를통해 기능 사용을 유도하거나 강제하는 부분에 있어서
협업시, 프로젝트 진행시 매우 유용할 것 이라고 느껴졌다.
또한 반복적인 검증 작업들이 자동화되면서 실제 개발에 집중할 수 있는 시간이 늘어났다는 피드백도 있었다.
ex) 피드백1 개발할 때 "이거 확인했나?" "저거 놓친 게 없나?" 하는 불안감이 많이 줄어들었다. Hook들이 자동으로 체크해주니까 실제 로직 구현에만 집중할 수 있게 됐다. 특히 AWS 관련 설정 확인이 버튼 한 번으로 끝나는 게 정말 편하다.
물론 완벽하지는 않다. 가끔 Hook 설정을 잘못해서 무한루프에 빠지거나, Steering 파일이 오래되어서 AI가 엉뚱한 답변을 하는 경우도 있다. 하지만 이런 문제들도 경험이 쌓이면서 점점 줄어들고 있다.
다른 프로젝트를 시작할 때도 Agent Hooks와 Steering 설정부터 먼저 해보려 한다. 초기 설정에 시간을 투자하는 것이 장기적으로는 훨씬 효율적이라는 걸 경험을 통해 새삼 느끼게 되었다.
