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
...

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

참고

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

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):