Kiro & Claude Code 프롬프트 가이드

시스템 프롬프트 작성에 특화된 가이드는 AIOps 프롬프트 엔지니어링을 참조하세요.

AI 코딩 도구를 활용하여 AIOps 에이전트를 더 빠르게 개발하는 방법을 알아봅니다.

개요

Kiro란?

Kiro는 AWS가 만든 AI IDE로, Spec 워크플로우(Requirements → Design → Tasks)를 통해 체계적으로 코드를 생성합니다. 단순히 코드를 자동완성하는 것이 아니라, 요구사항 정의부터 설계, 구현까지 구조화된 프로세스를 제공합니다.

Claude Code란?

Claude Code는 Anthropic의 CLI 기반 AI 코딩 도구입니다. 터미널에서 직접 코드베이스를 탐색하고, 디버깅하고, 스크립트를 생성할 수 있습니다.

왜 함께 사용하나요?

도구	강점	워크샵 활용
Kiro	구조화된 설계, Spec 기반 코드 생성	에이전트 아키텍처 설계 → 코드 생성
Claude Code	CLI 디버깅, 기존 코드 분석, 스크립트 생성	배포 문제 해결, 테스트 코드 작성

---

사전 준비

항목	설명
Kiro	kiro.dev에서 다운로드 및 설치
Claude Code	npm install -g @anthropic-ai/claude-code (공식 문서)
AWS CLI	aws configure 완료
워크샵 진행	시나리오 A는 모듈 1 이상 완료 권장, 시나리오 B는 완료 없이 시작 가능

워크샵을 아직 완료하지 않았다면, 먼저 모듈 1을 완료하여 AgentCore Runtime의 기본 패턴을 익히는 것을 권장합니다.

---

Kiro Spec 워크플로우

Kiro의 핵심은 3단계 Spec 워크플로우입니다. 이 워크플로우를 AIOps 에이전트 개발에 매핑하면 다음과 같습니다:

Kiro Spec 단계	AIOps 에이전트 개발
1. Requirements Spec	에이전트 역할, 필요한 도구, 인증 방식 정의
2. Design Spec	클래스 구조, 시스템 프롬프트, MCP 스키마 설계
3. Task List	구현 단계: agent.py → Lambda → Gateway → Runtime

Kiro에서 /spec 명령으로 Spec 워크플로우를 시작할 수 있습니다. 각 단계에서 생성된 문서는 .kiro/specs/ 디렉토리에 저장됩니다.

---

시나리오 A: 워크샵 에이전트 확장

이미 완성된 워크샵 에이전트에 새로운 기능을 추가하는 프롬프트 예시입니다.

A-1. 새 도구 추가 (Cost Explorer)

Kiro에서 다음과 같이 Spec을 시작합니다:

Requirements Spec 프롬프트:

이 워크샵의 TroubleshootingAgent에 AWS Cost Explorer 도구를 추가하고 싶습니다.

요구사항:
- 특정 서비스의 최근 7일/30일 비용을 조회하는 Lambda 함수
- 비용 이상 탐지 (전월 대비 20% 이상 증가 시 경고)
- 기존 MCP Gateway에 새 타겟으로 등록
- 시스템 프롬프트에 비용 관련 워크플로우 추가

참고할 기존 코드:
- agent_config/agent.py: TroubleshootingAgent 클래스 패턴
- scripts/agentcore_gateway.py: Gateway 타겟 등록 패턴

Design Spec에서 기대되는 결과물:

• Lambda 함수의 입출력 스키마 (JSON Schema)

• API Gateway 타겟 등록 코드

• 시스템 프롬프트 수정 diff

컨텍스트 제공 팁: Kiro에게 기존 코드 파일을 @파일명으로 참조시키면 일관된 패턴으로 코드를 생성합니다. 예: @agent_config/agent.py 패턴을 따라서 새 도구를 추가해줘

A-2. 메모리 전략 커스터마이징

Requirements Spec 프롬프트:

모듈 3의 MemoryHook에 Custom Memory 전략을 추가하여 인시던트 이력을 저장하고 싶습니다.

요구사항:
- 네임스페이스: "incident-history"
- 저장 데이터: 인시던트 타입, 영향받은 서비스, 해결 방법, 타임스탬프
- 검색: 유사 인시던트를 semantic search로 조회
- 기존 4가지 전략(semantic, summary, user_preference, custom)과 공존

참고할 기존 코드:
- agent_config/memory_hook_provider.py: MemoryHook 클래스 패턴
- 특히 MessageAddedEvent 핸들러에서 메모리 저장 로직

Design Spec에서 기대되는 결과물:

# 네임스페이스 설계 예시
NAMESPACE = "incident-history"
CONTENT_FORMAT = {
    "incident_type": "connectivity|dns|performance",
    "affected_services": ["service-a", "service-b"],
    "resolution": "Applied security group rule...",
    "timestamp": "2025-01-15T09:30:00Z"
}

A-3. 새 A2A 에이전트 추가 (보안 감사)

Requirements Spec 프롬프트:

모듈 4의 A2A 아키텍처에 보안 감사(Security Audit) 에이전트를 추가하고 싶습니다.

요구사항:
- Agent Card: 보안 취약점 스캔 및 규정 준수 검사 역할
- 도구: IAM Access Analyzer, Security Hub findings 조회
- HostAgent의 라우팅 로직에 "보안" 키워드 매칭 추가
- ECS Fargate에 배포 (기존 Connectivity/Performance Agent와 동일 패턴)

참고할 기존 코드:
- a2a/a2a-connectivity-agent/agent_executer.py: A2A Executor 패턴
- a2a/a2a-connectivity-agent/config.yaml: Agent Card 스키마
- 모듈 4 step-6-collaborator-setup: Collaborator 등록 패턴

Task List에서 기대되는 구현 순서:

1. Agent Card (config.yaml) 작성

2. SecurityAuditAgentCoreExecutor 구현

3. Lambda 도구 함수 (IAM Analyzer, Security Hub) 구현

4. Gateway 타겟 등록

5. ECS Task Definition + 서비스 배포

6. HostAgent Collaborator에 등록

7. 통합 테스트

---

시나리오 B: 새 AIOps 에이전트를 처음부터 만들기

워크샵 코드 패턴을 기반으로 완전히 새로운 에이전트를 만드는 과정입니다.

B-1. Requirements Spec 작성

Kiro에서 /spec 실행 후 다음 프롬프트를 입력합니다:

Amazon Bedrock AgentCore에서 실행되는 Database Health Monitor 에이전트를 만들고 싶습니다.

역할:
- RDS/Aurora 인스턴스의 상태를 모니터링
- Slow query 감지 및 분석
- 스토리지 용량 예측
- 장애 시 자동 페일오버 권고

기술 스택:
- Python 3.11, Strands Agents Framework
- Amazon Bedrock (Claude Sonnet 4)
- Lambda 함수로 도구 구현
- MCP Gateway를 통한 도구 연결
- Cognito OAuth2 인증

이 프로젝트의 기존 패턴을 참고해주세요:
- @agent_config/agent.py (TroubleshootingAgent 패턴)
- @main.py (BedrockAgentCoreApp 엔트리포인트)
- @.bedrock_agentcore.yaml (Runtime 배포 설정)

핵심 패턴: 이 워크샵의 모든 에이전트는 동일한 구조를 따릅니다.

1. BedrockModel — LLM 연결

2. MCPClient — Gateway를 통한 도구 접근

3. Agent(model, system_prompt, tools) — Strands Agent 생성

4. BedrockAgentCoreApp — 서버리스 엔트리포인트

참고: 이 가이드의 코드 예시는 핵심 패턴을 보여주기 위해 단순화되었습니다. 실제 워크샵 코드는 TroubleshootingContext, StreamingQueue 등 추가 컴포넌트를 포함합니다. 상세 구현은 각 모듈의 main.py를 참조하세요.

B-2. Design Spec 작성

Requirements가 확정되면 Design Spec 단계에서 다음과 같이 요청합니다:

Requirements Spec을 기반으로 Design Spec을 작성해주세요.

클래스 구조는 이 프로젝트의 TroubleshootingAgent 패턴을 따라주세요:

class DatabaseHealthAgent:
    def __init__(self, bearer_token, memory_hook=None, ...):
        self.model = BedrockModel(model_id=...)
        self.system_prompt = "..."
        self.gateway_client = MCPClient(...)
        self.agent = Agent(model=self.model, system_prompt=..., tools=...)

    async def stream(self, user_query):
        async for event in self.agent.stream_async(user_query):
            yield event["data"]

다음 항목을 설계해주세요:
1. 시스템 프롬프트 전체 내용 (역할, 도구 설명, 워크플로우, 규칙)
2. Lambda 함수 3개의 입출력 스키마
   - rds-health-check: 인스턴스 상태 조회
   - slow-query-analyzer: 슬로우 쿼리 분석
   - storage-predictor: 스토리지 용량 예측
3. MCP Gateway 타겟 등록 설정
4. SSM Parameter 네임스페이스 (/app/database-health/agentcore/*)

B-3. Task 자동 생성 및 구현

Design Spec 완료 후 Kiro가 자동으로 Task 목록을 생성합니다. 일반적으로 다음 순서로 진행됩니다:

Task 1: 프로젝트 초기화 (pyproject.toml, Dockerfile)
Task 2: agent_config/agent.py — DatabaseHealthAgent 클래스 구현
Task 3: main.py — BedrockAgentCoreApp 엔트리포인트
Task 4: Lambda 함수 구현 (rds-health-check)
Task 5: Lambda 함수 구현 (slow-query-analyzer)
Task 6: Lambda 함수 구현 (storage-predictor)
Task 7: scripts/agentcore_gateway.py — Gateway 생성 스크립트
Task 8: scripts/agentcore_agent_runtime.py — Runtime 배포 스크립트
Task 9: .bedrock_agentcore.yaml — Runtime 설정
Task 10: test/test_agent.py — 통합 테스트

Kiro Steering 팁: Task가 생성되면 하나씩 순서대로 구현을 요청하세요. 각 Task 완료 시 Kiro가 다음 Task의 컨텍스트를 자동으로 연결합니다. 한 번에 모든 Task를 구현하려고 하면 품질이 떨어질 수 있습니다.

---

Claude Code 보조 활용법

Claude Code는 터미널에서 직접 실행하며, 기존 코드를 분석하거나 문제를 해결할 때 활용합니다.

에이전트 디버깅

# 에이전트 연결 문제 분석
claude "agent_config/agent.py에서 MCPClient가 Gateway에 연결할 때
타임아웃이 발생합니다. gateway_url은 SSM에서 정상적으로 가져오지만
streamablehttp_client 연결에서 실패합니다. 원인을 분석해주세요."

# 메모리 훅 동작 확인
claude "memory_hook_provider.py의 MessageAddedEvent 핸들러에서
semantic memory 저장이 안 됩니다. MemoryClient.add_memory() 호출 시
namespace 파라미터가 올바른지 확인해주세요."

# A2A 통신 문제
claude "a2a-connectivity-agent의 agent_executer.py에서 AgentCore Runtime에
HTTP 요청을 보낼 때 401 Unauthorized가 발생합니다. _OAuthTokenCache의
토큰 갱신 로직을 확인하고 30초 early refresh가 충분한지 분석해주세요."

배포 스크립트 생성

# 새 Gateway 생성 스크립트
claude "scripts/agentcore_gateway.py 패턴을 참고해서 database-health
에이전트용 Gateway 생성 스크립트를 만들어줘. 타겟은 rds-health-check,
slow-query-analyzer, storage-predictor 3개야."

# Lambda 배포 스크립트
claude "prerequisite/lambda-dns/deploy-dns-tool.sh 패턴을 따라서
lambda-rds-health 배포 스크립트를 만들어줘. ARM64 런타임에
boto3 RDS/CloudWatch 권한이 필요해."

테스트 코드 작성

# 통합 테스트 생성
claude "test/test_agent.py를 참고해서 database-health 에이전트용
통합 테스트를 작성해줘. --interactive 모드와 --prompt 모드 모두
지원해야 하고, 테스트 시나리오는 다음 3가지야:
1. RDS 인스턴스 상태 조회
2. 슬로우 쿼리 분석 요청
3. 스토리지 용량 예측 요청"

# 메모리 통합 테스트
claude "tests-by-strategy/integration/test_01_runtime_connectivity_with_memory.py
패턴을 참고해서 database-health 에이전트의 메모리 통합 테스트를 작성해줘."

---

레퍼런스 코드 패턴

Kiro나 Claude Code에 컨텍스트로 제공하면 좋은 핵심 파일 목록입니다:

파일	용도	위치
agent_config/agent.py	Agent 클래스 패턴	모듈 1, 2, 3 공통
agent_config/memory_hook_provider.py	MemoryHook 패턴	모듈 1, 2, 3 공통
main.py	BedrockAgentCoreApp 엔트리포인트	모듈 1, 2, 3 공통
scripts/agentcore_gateway.py	Gateway/Target 등록 패턴	모듈 1, 3
scripts/agentcore_agent_runtime.py	Runtime 배포 패턴	모듈 1, 3
scripts/setup_memory.py	Memory 리소스 설정	모듈 3
a2a/a2a-connectivity-agent/agent_executer.py	A2A Executor 패턴	모듈 4
.bedrock_agentcore.yaml	Runtime 배포 설정	모듈 1, 2, 3 공통
test/test_agent.py	에이전트 테스트 패턴	모듈 1, 3

Kiro에서 파일 참조: @agent_config/agent.py처럼 @ 접두사로 파일을 지정하면 해당 파일의 전체 내용이 컨텍스트로 포함됩니다.

Claude Code에서 파일 참조: 프롬프트에 파일 경로를 명시하면 자동으로 해당 파일을 읽어 분석합니다.

---

자주 발생하는 문제

증상	원인	해결
Kiro가 기존 패턴을 무시함	컨텍스트 파일 미참조	@파일명으로 명시적 참조 추가
Claude Code가 파일을 찾지 못함	작업 디렉토리 오류	프로젝트 루트에서 실행 또는 절대 경로 사용
Gateway 연결 타임아웃	SSM 파라미터 누락/오류	aws ssm get-parameter --name "/app/.../gateway_url" 확인
Lambda 권한 오류	Gateway IAM Role 미설정	GATEWAY_IAM_ROLE에 Lambda invoke 권한 확인

---

프롬프트 팁 & 베스트 프랙티스

1. 기존 패턴을 항상 참조하세요

❌ "RDS 모니터링 에이전트를 만들어줘"
✅ "agent_config/agent.py의 TroubleshootingAgent 패턴을 따라서
    RDS 모니터링 에이전트를 만들어줘"

기존 코드를 참조하면 프로젝트의 컨벤션(SSM 파라미터 네이밍, MCP Gateway 패턴, 에러 핸들링 방식)이 자동으로 적용됩니다.

2. 구체적인 제약조건을 명시하세요

❌ "Lambda 함수를 만들어줘"
✅ "Python 3.11 ARM64 런타임의 Lambda 함수를 만들어줘.
    입력: {"instance_id": "string", "days": "number"}
    출력: {"status": "string", "metrics": [...]}
    IAM 권한: rds:DescribeDBInstances, cloudwatch:GetMetricData"

3. Kiro Spec 단계를 건너뛰지 마세요

❌ 바로 "코드를 작성해줘"
✅ Requirements → Design → Tasks 순서대로 진행

각 Spec 단계에서 AI가 놓친 부분을 검토하고 수정할 수 있습니다. 바로 코드를 생성하면 나중에 큰 수정이 필요할 수 있습니다.

4. 시스템 프롬프트는 별도로 설계하세요

시스템 프롬프트는 에이전트의 동작을 결정하는 핵심입니다. 다음 구조를 권장합니다:

역할 정의 → 사용 가능한 도구 → 워크플로우 → 규칙 및 제약조건 → 예시

워크샵의 agent.py에 포함된 시스템 프롬프트를 참고하세요. 특히 CRITICAL RULES와 PERMISSION VALIDATION 섹션이 에이전트의 안전한 동작을 보장합니다.

5. 작은 단위로 반복하세요

단계	Kiro	Claude Code
1. 도구 1개 추가	Spec → 구현	—
2. 로컬 테스트	—	디버깅 및 수정
3. Gateway 등록	Spec → 스크립트	실행 및 검증
4. Runtime 배포	—	배포 스크립트 실행
5. 통합 테스트	—	테스트 실행 및 분석

주의: 한 번에 여러 도구와 기능을 추가하지 마세요. 도구 하나를 추가하고, 테스트하고, 배포한 뒤 다음 도구를 추가하는 것이 디버깅 시간을 줄여줍니다.