AWS Well-Architected Framework 적용을 위한 AI 코딩 에이전트용 재사용 가능한 스킬 및 스티어링 (steering)

AI 코딩 에이전트에게 AWS Well-Architected Framework를 적용하는 방법을 가르치는 재사용 가능한 스킬 (skills) 및 스티어링 (steering)입니다. 하나의 플레이북 (playbooks) 세트로 12개의 지원 도구를 사용할 수 있습니다.

Kiro · Claude Code · Cursor · Codex · Windsurf · GitHub Copopit · Gemini CLI · Antigravity · Junie · Amp · Cline · AWS DevOps Agent

중요 사항

이 샘플은 교육 및 시연 목적으로 제공됩니다. 귀하의 환경에 적합한 추가 검토 및 테스트 없이 프로덕션 (production) 용도로 사용하는 것을 권장하지 않습니다.

개발자들은 문서를 찾아보기 위해 멈추지 않고, 대신 AI 어시스턴트에게 질문합니다. 만약 어시스턴트가 Well-Architected Framework를 알지 못한다면, 가이드라인은 코드에 결코 도달하지 못합니다.

이 프로젝트는 실제 개발이 일어나는 곳, 즉 코드가 작성되는 순간인 IDE (통합 개발 환경)에 Well-Architected (WA) 모범 사례를 내장합니다. 아키텍처 리뷰 (architecture reviews)를 별도의 관문으로 취급하는 대신, 팀은 다음과 같은 지속적이고 맥락적인 가이드를 받게 됩니다:

• ✅ 초기 단계에서 불일치를 포착하여 재작업 (rework) 감소
• ✅ 단일 진실 공급원 (single source of truth)을 통해 12개의 AI 코딩 도구에서 작동
• ✅ AWS 자격 증명(credentials)이나 API 호출이 필요 없음 — 모든 것이 로컬 (locally)에서 실행됨
• ✅ 개방형 에이전트 스킬 (Agent Skills) 사양을 따름

steering/ 항상 켜져 있는 컨텍스트 (Kiro)
well-architected.md 기둥 (Pillars), 설계 원칙 (design principles), 리뷰 프로세스 (review process)
skills/ 단계별 플레이북 (playbooks) (도구 불가지론적/tool-agnostic)
...

npx skills add aws-samples/sample-well-architected-skills-and-steering

AI 에이전트를 자동으로 감지하여 스킬을 직접 설치합니다. 사용 가능한 스킬을 미리 보려면 --list를 사용하거나, 특정 스킬을 설치하려면 --skill <name>을 사용하세요:

# 사용 가능한 스킬 목록 표시
npx skills add aws-samples/sample-well-architected-skills-and-steering --list
# 특정 스킬 설치
...

macOS / Linux:

curl -sL https://raw.githubusercontent.com/aws-samples/sample-well-architected-skills-and-steering/main/bootstrap.sh | bash

Windows (PowerShell):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/aws-samples/sample-well-architected-skills-and-steering/main/bootstrap.ps1)))

AI 도구(.cursor/, .claude/, .kiro/, .junie/ 등)를 자동으로 감지하여 모두 설치하고 정리합니다.

특정 도구에 대해서만 설치하려면 다음을 사용하세요:

# macOS / Linux
curl -sL .../bootstrap.sh | bash -s -- --tool kiro
# Windows (PowerShell)
...

macOS / Linux:

# 프로젝트 내 도구 자동 감지
./install.sh ~/my-project --tool auto
# 특정 도구에 설치
...

Windows (PowerShell):

# 프로젝트 내 도구 자동 감지
.\install.ps1 -TargetDir C:\Projects\my-app -Tool auto
# 특정 도구에 설치
...

Tip

복사본 대신 심볼릭 링크 (Symbolic Link)를 생성하려면 --symlink (bash) 또는 -Symlink (PowerShell)를 사용하세요. 이 리포지토리(repo)가 업데이트되면 재설치 없이도 프로젝트에 변경 사항이 자동으로 적용됩니다. Windows에서 심볼릭 링크를 사용하려면 관리자 권한이 필요합니다.

Note

**전역 설치 (Global installs)**는 파일을 홈 디렉토리(~/CLAUDE.md, ~/.kiro/, ~/.cursor/ 등)에 배치하며, 자체 설정 없이 모든 프로젝트에 적용됩니다. 특정 프로젝트에 대해서만 WA (Well-Architected) 가이드를 적용하고 싶다면 프로젝트 수준 설치(기본값)를 사용하세요.

기존 파일 (Existing files) — 설치 프로그램이 덮어쓰기 전에 확인을 요청합니다. 확인 과정을 건너뛰려면 --force를 사용하세요.

🔹 Kiro

macOS / Linux:

mkdir -p .kiro/steering .kiro/skills
cp path/to/this-repo/steering/well-architected.md .kiro/steering/
cp -r path/to/this-repo/skills/* .kiro/skills/

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path .kiro\steering, .kiro\skills
Copy-Item path\to\this-repo\steering\well-architected.md .kiro\steering\
Copy-Item -Recurse path\to\this-repo\skills\* .kiro\skills\

🔹 Claude Code

macOS / Linux:

cp path/to/this-repo/adapters/claude-code/CLAUDE.md ./CLAUDE.md
cp -r path/to/this-repo/adapters/claude-code/commands .claude/commands

Windows (PowerShell):

Copy-Item path\to\this-repo\adapters\claude-code\CLAUDE.md .\CLAUDE.md
Copy-Item -Recurse path\to\this-repo\adapters\claude-code\commands .\commands

🔹 Cursor

macOS / Linux:

cp -r path/to/this-repo/adapters/cursor/rules .cursor/rules

Windows (PowerShell):

Copy-Item -Recurse path\to\this-repo\adapters\cursor\rules .\.cursor\rules

🔹 Codex (OpenAI)

macOS / Linux:

cp path/to/this-repo/adapters/codex/AGENTS.md ./AGENTS.md
cp -r path/to/this-repo/skills ./skills

Windows (PowerShell):

Copy-Item path\to\this-repo\adapters\codex\AGENTS.md .\.AGENTS.md
Copy-Item -Recurse path\to\this-repo\skills .\.skills

🔹 Windsurf

macOS / Linux:

cp path/to/this-repo/adapters/windsurf/.windsurfrules ./.windsurfrules

Windows (PowerShell):

Copy-Item path\to\this-repo\adapters\windsurf\.windsurfrules .\.windsurfrules

🔹 GitHub Copilot

macOS / Linux:

mkdir -p .github
cp path/to/this-repo/adapters/github-copilot/.github/copilot-instructions.md .github/

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path .github
Copy-Item path\to\this-repo\adapters\github-copilot\.github\copilot-instructions.md .github\ 

🔹 Gemini CLI

macOS / Linux:

cp path/to/this-repo/adapters/gemini-cli/GEMINI.md ./GEMINI.md
cp -r path/to/this-repo/skills ./skills

Windows (PowerShell):

Copy-Item path\to\this-repo\adapters\gemini-cli\GEMINI.md .\.GEMINI.md
Copy-Item -Recurse path\to\this-repo\skills .\.skills

🔹 Antigravity

macOS / Linux:

mkdir -p .agents/rules .agents/skills
cp -r path/to/this-repo/adapters/antigravity/rules/* .agents/rules/
for skill_dir in path/to/this-repo/skills/*/; do
...

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path .agents\rules, .agents\skills
Copy-Item -Recurse path\to\this-repo\adapters\antigravity\rules\* .agents\rules\
Get-ChildItem path\to\this-repo\skills -Directory | ForEach-Object {
...

mkdir -p .junie/guidelines .junie/skills
cp path/to/this-repo/adapters/junie/guidelines.md .junie/guidelines/well-architected.md
cp -r path/to/this-repo/skills/* .junie/skills/

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path .junie\guidelines, .junie\skills
Copy-Item path\to\this-repo\adapters\junie\guidelines.md .junie\guidelines\well-architected.md
Copy-Item -Recurse path\to\this-repo\skills\* .junie\skills\

🔹 Amp

macOS / Linux:

cp path/to/this-repo/adapters/amp/AGENTS.md ./AGENTS.md
mkdir -p .agents/skills
cp -r path/to/this-repo/skills/* .agents/skills/

Windows (PowerShell):

Copy-Item path\to\this-repo\adapters\amp\AGENTS.md ..\AGENTS.md
New-Item -ItemType Directory -Force -Path .agents\skills
Copy-Item -Recurse path\to\this-repo\skills\* .agents\skills\

🔹 Cline

macOS / Linux:

cp path/to/this-repo/adapters/cline/.clinerules ./.clinerules

Windows (PowerShell):

Copy-Item path\to\this-repo\adapters\cline\.clinerules ..\.clinerules

🔹 AWS DevOps Agent

macOS / Linux:

# 모든 스킬을 zip 파일로 패키징하여 Agent Space에 업로드합니다.
./install.sh ~/output-dir --tool devops-agent
# 그런 다음 Operator Web App을 통해 ~/output-dir/devops-agent-skills/의 각 .zip 파일을 업로드합니다.

Windows (PowerShell):

# 모든 스킬을 zip 파일로 패키징하여 Agent Space에 업로드합니다.
.	extbackslash install.ps1 -TargetDir C:\output-dir -Tool devops-agent
# 그런 다음 Operator Web App을 통해 C:\output-dir\devops-agent-skills\의 각 .zip 파일을 업로드합니다.

graph LR
S[skills/] --> A[adapters/]
ST[steering/] --> A
...

구성 요소	역할
Skills (skills/*/SKILL.md)	독립적이고 도구에 구애받지 않는 플레이북 (playbooks). 어떤 AI 에이전트라도 이를 단계별로 따를 수 있습니다. 스티어링 (steering)이나 다른 스킬에 의존하지 않습니다.
Steering (steering/*.md)	모든 Kiro 대화에 로드되는 상시 활성화된 컨텍스트 (context). 다른 도구들은 어댑터 (adapters)를 통해 이와 동등한 메커니즘을 사용합니다.
Powers (powers/*/)	Kiro를 위한 번들형 설치 단위. 스티어링 (steering) + MCP 도구 + 훅 (hooks)을 하나의 활성화 가능한 파워 (power)로 패키징합니다.
Adapters (adapters/)	스티어링 (steering)을 각 도구의 고유한 설정 형식으로 변환하고, 스킬 (skills)을 명령어나 규칙으로 연결합니다.
Assets (assets/)	스킬 (skills)과 함께 번들링되는 공유 참조 자료 (v13 베스트 프랙티스, 메트릭, 패턴 등). 이를 지원하는 도구에서 사용됩니다.

도구	스티어링 (steering) 메커니즘	스킬 (skills) 메커니즘
Kiro	.kiro/steering/*.md	.kiro/skills/*/SKILL.md
Claude Code	CLAUDE.md	.claude/commands/*.md (슬래시 명령어)
Cursor	.cursor/rules/*.md	조건부 활성화가 가능한 규칙 (rules)
Codex	AGENTS.md	skills/ 디렉터리 참조
Windsurf	.windsurfrules	skills/ 디렉터리 참조
GitHub Copilot	.github/copilot-instructions.md	인라인 (별도의 스킬 메커니즘 없음)
Cline	.clinerules	skills/ 디렉터리 참조
Gemini CLI	GEMINI.md	skills/ 디렉터리 참조
Antigravity	.agents/rules/*.md	.agents/skills/*/SKILL.md
Junie	.junie/guidelines/*.md	.junie/skills/*/SKILL.md
Amp	AGENTS.md	.agents/skills/*/SKILL.md
AWS DevOps Agent	해당 없음 (스킬은 독립적임)	Agent Space에 SKILL.md 압축 파일 업로드

Kiro Powers는 대화 키워드에 따라 문맥에 맞게 활성화되는 번들형 설치 단위입니다. 상시 활성화되는 스티어링 (steering)과 달리, Powers는 관련 주제가 나타날 때 가이드를 동적으로 로드합니다.

파워 (Power)	상태	설명
well-architected	🚧 진행 중	전체 WA 프레임워크 — 6개 기둥(pillars) 전체, 아키텍처 논의 시 활성화

참고

Powers는 향후 Kiro에서 WA 가이드를 사용하는 권장 방식입니다. Powers는 더 풍부한 활성화(키워드 기반), 선택적인 MCP 도구 통합, 그리고 Powers 갤러리를 통한 원클릭 설치를 제공합니다.

스킬 (Skill)	기둥 (Pillar(s))	사용 사례
wa-review	전체 6개	전체 Well-Architected 리뷰를 실행할 때
security-assessment	🔒 보안 (Security)	IAM, 탐지, 데이터 보호, 침해 사고 대응을 평가할 때
reliability-improvement-plan	🔄 신뢰성 (Reliability)	단일 장애점 (Single points of failure)을 찾고 제거할 때
cost-optimization-audit	💰 비용 최적화 (Cost Optimization)	낭비 요소와 적정 규모 산정 (Right-sizing) 기회를 식별할 때
performance-efficiency	⚡ 성능 효율성 (Performance Efficiency)	리소스 선택, 확장 (Scaling), 캐싱 (Caching)을 평가할 때
sustainability-optimization	🌱 지속 가능성 (Sustainability)	탄소 발자국과 리소스 낭비를 줄일 때
operational-excellence	🛠️ 운영 우수성 (Operational Excellence)	CI/CD, 관찰 가능성 (Observability), 침해 사고 관리를 평가할 때
migration-readiness	전체 6개	워크로드를 AWS로 마이그레이션할 준비가 되었는지 평가할 때
architecture-decision-record	전체 6개	WA 기둥에 미치는 영향을 포함하여 설계 결정을 문서화할 때

AI 코딩 에이전트에게 다음과 같이 질문해 보세요:

이 아키텍처를 위해 어떤 Well-Architected 기둥들을 고려해야 할까요?

올바르게 구성되어 있다면, 에이전트는 일반적인 답변을 하는 대신 구체적인 가이드와 함께 6개 기둥 전체를 참조할 것입니다.

팁

Claude Code 사용자: /wa-review를 입력하여 전체 리뷰 스킬을 슬래시 명령어로 호출해 보세요.

Kiro 사용자: 스티어링 (Steering)이 자동으로 로드됩니다. 아키텍처에 대해 논의하기 시작하면 에이전트가 WA 원칙을 적용합니다.

각 스킬은 Agent Skills 평가 사양을 따라 skills/*/evals/evals.json에 구조화된 평가 (Evaluations)를 포함합니다. 평가를 통해 스킬이 일반 에이전트보다 더 나은 결과물을 생성하는지 측정할 수 있습니다.

각 테스트 케이스에는 다음이 포함됩니다:

• 현실적인 사용자 프롬프트 (User prompt)
• 예상 출력 설명
• 5~7개의 구체적인 단언 (Assertions) (PASS/FAIL로 채점 가능)

evals/ 디렉토리에는 Amazon Bedrock 기반의 자동화된 평가 러너 (Evaluation runner)가 포함되어 있습니다.

사전 요구 사항:

• Python 3.13+ 및 uv
• Bedrock 접근 권한이 설정된 AWS 자격 증명 (aws configure 또는 SSO)
• 해당 리전에서 Claude Sonnet 및 Haiku에 대한 Bedrock 모델 액세스 활성화

설정 (Setup):

cd evals
uv sync

평가 실행 (Run evaluations):

macOS / Linux:

# 사용 가능한 스킬 목록 표시
uv run python run.py --list
# 단일 스킬 평가
...

Windows (PowerShell):

# 사용 가능한 스킬 목록 표시
uv run python run.py --list
# 단일 스킬 평가
...

참고

Windows에서는 aws configure 또는 환경 변수 (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)를 통해 AWS 자격 증명이 설정되어 있는지 확인하십시오. AWS IAM Identity Center (SSO)를 사용하는 경우, 먼저 aws sso login --profile your-profile을 실행하십시오.

작동 원리 (How it works):

• 각 테스트 케이스에 대해 Bedrock Converse API를 통해 두 가지 응답을 생성합니다:
  • Baseline (기준점) — 프롬프트만 사용, 스킬 컨텍스트 없음
  • With skill (스킬 적용) — 프롬프트 + SKILL.md를 시스템 컨텍스트 (System context)로 주입
• LLM-as-judge가 두 출력물에 대해 각 어설션 (Assertion)을 PASS/FAIL로 채점합니다.
• 스킬의 영향을 보여주는 점수 비교 보고서를 생성합니다.

설정 (Configuration) (evals/config.yaml):