한 줄 요약: aws/agent-toolkit-for-aws는 AWS가 직접 운영하는 “코딩 에이전트용 AWS 공구함”입니다. 리포에는 스킬 118개(canonical 기준), Claude Code·Codex·Cursor·Devin용 플러그인 5종, 프로젝트 규칙 파일, 그리고 Claude Code용 비밀값 가드 훅이 들어 있고, 실제 AWS 호출은 AWS가 관리하는 원격 AWS MCP Server가 맡습니다. 이번 글에서는 구조를 뜯어보고, 박스에서 AWS 계정 없이 돌릴 수 있는 검증기·계약 테스트·원격 MCP 호출·훅 입력 테스트를 직접 실행해 숫자로 정리했습니다. 결론부터 말하면 지식 패키징과 CI 품질은 상당히 탄탄하지만, 비밀값 가드 훅에는 이미 이슈 #307로 보고된 우회 경로가 아직 열려 있어서 진짜 방어선은 IAM에서 다시 쳐야 합니다.
1. 지금 이 리포가 트렌딩에 오른 이유
2026-10-25(일) 오전 기준 GitHub Trending 데일리에서 전체 3위, Python 1위에 올랐습니다. 별 숫자로만 보면 같은 날 상위권의 다른 리포보다 작지만, 하루짜리 바이럴보다는 “AWS 공식 리포가 매일 커밋되면서 꾸준히 올라오는” 패턴에 가깝습니다. 최근 2주간 거의 매일 머지가 있었고, 10월 22~23일에도 Devin 플러그인 매니페스트, ECS Gateway 레퍼런스, Lightsail 컨테이너 배포 스킬, Bedrock Managed Knowledge Base 마이그레이션 가이드가 연달아 들어왔습니다.
| 항목 | 값 (2026-10-25 KST 확인) | 메모 |
|---|---|---|
| 리포 | aws/agent-toolkit-for-aws |
AWS 공식 조직 소유 |
| 라이선스 | Apache-2.0 | 상업적 사용·수정·재배포 가능, NOTICE 유지 |
| 스타 / 포크 | 약 3,159 / 400 | GitHub API 기준 |
| 트렌딩 | 전체 데일리 3위, Python 데일리 1위 | 10/25 오전 |
| 생성일 | 2026-04-23 | README 배지는 GA 상태 표시 |
| 최근 커밋 | 2026-10-23 23:59 KST (e8c6309) | Bedrock KB 마이그레이션 가이드 |
| 열린 이슈 | 62개 | 보안 훅 관련 #307 포함 |
| 릴리스 방식 | GitHub Release 없음, 플러그인별 plugin.json 버전 |
aws-core 1.2.0 · startup-advisor 2.0.3 등 |
README가 직접 밝히는 포지셔닝도 중요합니다. 2025년부터 AWS Labs(awslabs)가 개별 MCP 서버·스킬·플러그인을 쏟아냈는데, 이 툴킷이 그 후계자라는 겁니다. 근거로 세 가지를 듭니다. 에이전트 행동과 사람 행동을 구분하는 IAM 조건 키, 모든 요청에 대한 CloudWatch 메트릭과 CloudTrail 감사 로그, 그리고 엔드투엔드 평가를 거친 스킬입니다. AWS Labs 쪽 도구는 계속 동작하지만 “좋은 것은 점차 이쪽으로 옮긴다”고 적혀 있어서, 새로 도입한다면 출발점은 이 리포가 맞습니다.
2. 구성 요소: 다섯 겹 레이어
이 리포를 “MCP 서버 하나”로 이해하면 틀립니다. 리포에 들어 있는 것은 대부분 지식과 설정이고, 실행 엔진(AWS MCP Server)은 AWS가 운영하는 관리형 엔드포인트입니다. 리포는 그 엔드포인트에 붙는 방법과, 붙은 뒤 에이전트가 무엇을 어떻게 해야 하는지를 패키징합니다.
| 레이어 | 위치 | 무엇을 하나 | 로드 시점 | AWS 자격 증명 필요 |
|---|---|---|---|---|
| 스킬 (Skills) | skills/**/SKILL.md + references/ |
서비스별 “에이전트가 자주 틀리는 것” 교정과 워크플로 | 작업이 매칭될 때만 (on-demand) | 아니요 |
| 플러그인 (Plugins) | plugins/*/plugin.json, mcp.json |
스킬 묶음 + MCP 서버 설정 + 훅을 한 번에 설치 | 설치 시 | 설치는 아니요 |
| 규칙 (Rules) | rules/aws-agent-rules.md 등 |
프로젝트 레벨 행동 규칙 (MCP 우선, IaC 우선, 비밀값 금지 등) | 세션 시작 시 컨텍스트 | 아니요 |
| 훅 (Hooks) | plugins/aws-core/com.anthropic.claude-code/hooks/ |
PreToolUse에서 비밀값 직접 조회를 deny | 도구 호출 직전 | 아니요 |
| AWS MCP Server | https://aws-mcp.us-east-1.api.aws/mcp (관리형) |
300+ 서비스 API, 샌드박스 Python, 문서 검색, 스킬 검색 | 도구 호출 시 | API 호출은 예, 문서·스킬 검색은 아니요 |
2-1. 디렉터리 구조
| 경로 | 내용 | 실무 포인트 |
|---|---|---|
skills/core-skills/ |
24개: IAM, CDK, CloudFormation, Serverless, Containers, Database, Observability, Billing 등 | 가장 먼저 읽을 곳. IAM 스킬은 정책 평가 엣지 케이스 위주 |
skills/specialized-skills/ |
16개 카테고리, 94개 스킬 (Analytics 19, Database 15, Networking 12, Serverless 12, Resilience 8 …) | Quantum·Marketplace처럼 1개짜리 카테고리도 있음 |
plugins/ |
5종 플러그인, 스킬 사본 77개 | canonical 스킬의 복사본. sync-plugin-skills.py로 동기화 |
.claude-plugin/, .cursor-plugin/, .agents/ |
에이전트별 마켓플레이스 매니페스트 | 같은 플러그인을 하네스마다 다른 형식으로 노출 |
rules/ |
aws-agent-rules.md(28줄), aws-starter-rules.md(74줄) |
starter는 “새 AWS 경험(소셜 로그인 프로젝트)” 전용 제약 |
tools/ |
validate.py, validate_spec.py, sync-plugin-skills.py, JSON 스키마 1.0.0 |
CI의 핵심. 로컬에서 1초 안에 전부 돈다 |
.github/workflows/ |
9개: build, codeql, scorecard, skill-frontmatter-check, startup-advisor 등 | 액션은 커밋 SHA로 고정(pin)되어 있음 |
전체 파일은 약 3,540개, 그중 Markdown이 2,689개입니다. SKILL.md만 합쳐도 3만9천 줄이 넘습니다. 코드 리포라기보다 “에이전트가 읽는 운영 매뉴얼 저장소 + 이를 검증하는 CI”라고 보는 편이 정확합니다.
3. 플러그인 5종 비교
| 플러그인 | 버전 | 스킬 수 | 범위 | 특이사항 |
|---|---|---|---|---|
aws-core |
1.2.0 | 25 | 서비스 선택, CDK/CFN, 서버리스, 컨테이너, DB, 관측성, 비용, SDK, Well-Architected | “Start here”. Claude Code용 secret-safety 훅 포함 |
aws-agents |
1.0.0 | 9 | Bedrock·AgentCore로 에이전트 만들기 (build/connect/debug/deploy/harden/optimize/pay) | 에이전트 라이프사이클 단위로 스킬이 나뉨 |
aws-data-analytics |
1.5.0 | 18 | S3 Tables, Glue, Athena, MWAA, MSK, Redshift, OpenSearch, 벡터 저장 | 버전이 가장 빠르게 오름 |
aws-agents-for-devsecops |
1.1.0 | 13 | AWS DevOps Agent·Security Agent로 장애 조사, 릴리스 준비도, 펜테스트, 위협 모델링 | 슬래시 커맨드 9개, MCP 설정 대신 setup 커맨드 |
aws-startup-advisor |
2.0.3 | 12 | 스타트업 아키텍처·비용, Azure/GCP/Heroku 이전, OpenAI·Gemini 호출을 Bedrock으로 이전 | 서브에이전트 7개, 자체 CI·테스트 38개 파일. 이 리포 마켓플레이스에서만 설치 |
흥미로운 건 aws-startup-advisor입니다. 다른 플러그인은 거의 순수 Markdown인데, 이 플러그인은 자체 mise.toml에 10개의 CI 태스크(모델 ID 린트, 모델 레지스트리 신선도, 가격표 검증, 아티팩트 스키마, vendored 파일 바이트 동일성, 스킬 참조 경로, 동의 문구 감사 등)를 갖고 있습니다. LLM 호출을 Bedrock으로 옮기는 기능 특성상 모델 이름·가격이 낡으면 바로 틀린 조언이 되기 때문에 “지식의 신선도” 자체를 테스트로 묶어 둔 겁니다.
4. 스킬은 어떻게 생겼나
스킬은 Agent Skills 형식을 따릅니다. 프런트매터에 name, 긴 description(언제 적용되고 언제 적용되지 않는지까지), metadata.version이 있고, 본문은 짧게, 깊은 내용은 references/로 분리합니다. aws-iam 스킬을 예로 들면 첫 문단부터 성격이 분명합니다. “포괄적인 IAM 가이드가 아니라 에이전트가 자주 틀리는 것에 대한 검증된 교정”이라고 선언하고, 사전학습 기억보다 공식 문서를 믿으라고 지시합니다.
| 설계 선택 | 예시 (aws-iam) | 효과 | 비용 / 한계 |
|---|---|---|---|
| 교정 중심 (pitfalls) | CloudTrail의 AcceptHandshake는 수락한 계정에만 기록, ConsoleLogin 리전은 항상 us-east-1이 아님 | 모델이 그럴듯하게 틀리는 지점만 집중 | 범위 밖 질문은 결국 문서 검색에 의존 |
| description에 트리거·비트리거 명시 | “Cognito user-pool 정책이나 앱 레벨 RBAC는 다루지 않음” | 스킬 오로딩(오탐) 감소 | description이 길어져 인덱스 토큰 증가 |
| 점진적 공개 (progressive disclosure) | 역할 관리·정책 생성은 references/ 파일로 분리 |
필요할 때만 컨텍스트 사용 | 에이전트가 참조 파일을 안 읽으면 효과 없음 |
| MUST 수준 강제 | 소스코드나 Terraform plan JSON이 주어지면 iam-policy-autopilot 사용 강제 |
수작업 정책 작성 오류 차단 | 해당 도구 설치·실행 환경을 전제 |
규칙 파일(aws-agent-rules.md)은 28줄짜리지만 핵심이 다 들어 있습니다. 프로젝트 자체 지시가 우선, AWS MCP Server 우선(없으면 CLI), 작업 전 retrieve_skill로 관련 스킬 확인, 불확실하면 문서 확인 후 불확실성 명시, 인프라는 CDK/CloudFormation 우선, 그리고 비밀값은 get-secret-value 직접 호출 금지 후 {{resolve:secretsmanager:...}}와 asm-exec로 런타임 해석. 리소스 이름에 em dash를 쓰지 말라는 아주 실무적인 줄도 있습니다.
5. 원격 AWS MCP Server: 실제로 노출되는 도구
박스에서 MCP 엔드포인트에 initialize → tools/list를 직접 보냈습니다. 자격 증명 없이도 세션이 열리고(서버 이름 AWSMCP, 프로토콜 2025-06-18), 도구 8개가 돌아왔습니다. 왕복 시간은 각각 약 0.53초, 0.55초였습니다.
| 도구 | 역할 | 무인증 호출 | 메모 |
|---|---|---|---|
aws___run_script |
샌드박스 Python에서 call_boto3로 AWS API 호출 |
불가 (SigV4 필요) | 네트워크는 call_boto3만 허용, operation은 PascalCase 권장 |
aws___search_documentation |
AWS 문서 검색, 원문 청크 반환 | 가능 | 토픽: reference, troubleshooting, cdk, cloudformation, agent_skills 등 10종 |
aws___read_documentation |
문서 페이지 전체를 Markdown으로 | 가능 | search 청크로 부족할 때만 |
aws___retrieve_skill |
서버 측 스킬 레지스트리에서 SKILL.md·참조 파일 로드 | 가능 | skill_name은 검색 결과에서 그대로 복사하라고 명시 |
aws___get_regional_availability |
리전별 리소스 가용성 | — | 최대 10개 리전 |
aws___list_regions |
리전 목록 | 가능 (실측) | 0.83초 |
aws___get_presigned_url |
S3 업·다운로드용 presigned URL | 불가 | run_script와 파일 교환용 |
aws___get_tasks |
장기 작업 상태 폴링 | — | 한 번에 ID 3개까지 |
여기서 설계 의도가 드러납니다. 예전 AWS Labs 방식은 서비스마다 MCP 서버를 따로 띄웠는데, 지금은 “범용 실행기(run_script) 하나 + 지식 검색”으로 수렴했습니다. 도구 수가 적으니 컨텍스트에 올라가는 도구 스키마가 작고, 대신 무엇을 어떻게 호출할지는 스킬과 문서 검색이 알려 줍니다. 도구 설명 안에 “List는 이름만 준다, 속성은 Describe로”, “모든 리전을 돌려라”, “결과를 다 반환하라” 같은 운영 규칙이 박혀 있는 것도 같은 맥락입니다.
5-1. 하네스별 연결 방법
| 하네스 | 설치 | MCP 연결 | 스킬 |
|---|---|---|---|
| Claude Code | /plugin install aws-core@claude-plugins-official |
플러그인에 포함 | 플러그인에 포함 (+ 훅) |
| Codex | codex plugin marketplace add aws/agent-toolkit-for-aws |
플러그인에 포함 | 플러그인에 포함 |
| Cursor | Settings → Plugins → Team Marketplaces → Import from Repo | 플러그인에 포함 | 플러그인에 포함 |
| Devin | devin plugins install aws/agent-toolkit-for-aws#plugins/aws-core |
플러그인에 포함 | 플러그인에 포함 |
| Kiro / fx / 기타 | 수동 | uvx mcp-proxy-for-aws-cli@latest https://aws-mcp.us-east-1.api.aws/mcp |
npx skills add aws/agent-toolkit-for-aws/skills |
| AWS CLI | aws configure agent-toolkit |
CLI 통합 가이드 참조 | — |
# 수동 연결 예 (Kiro: .kiro/settings/mcp.json)
{
"mcpServers": {
"aws": {
"command": "uvx",
"args": ["mcp-proxy-for-aws-cli@latest",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"]
}
}
}
# 스킬만 따로 (MCP 없이도 동작)
npx skills add aws/agent-toolkit-for-aws/skills참고로 plugins/aws-core/mcp.json은 mcp-proxy-for-aws-cli==1.7.0으로 버전을 고정하고 --skip-auth로 시작합니다. 설치 직후 자격 증명이 없어도 문서·스킬 검색은 되게 하려는 선택인데, 수동 설정 예시는 @latest를 쓰니 팀 표준을 만들 때는 고정 버전 쪽을 따르는 걸 권합니다.
6. 진짜 통제점: IAM 조건 키
MCP 서버는 자체 IAM 액션을 정의하지 않습니다. 요청을 SigV4로 인증한 뒤 두 개의 전역 조건 키를 붙여 하위 서비스로 넘기고, 권한 판단은 기존 IAM 정책이 합니다. 프리뷰 때 쓰던 aws-mcp:InvokeMcp 같은 액션은 이제 효과가 없으므로, 예전 Deny 정책이 남아 있다면 조용히 무력화된 상태일 수 있습니다.
| 조건 키 | 타입 | 값 | 용도 |
|---|---|---|---|
aws:ViaAWSMCPService |
Boolean | 관리형 MCP 서버 경유 시 true |
MCP 경유 요청 전체를 허용/거부 |
aws:CalledViaAWSMCP |
String (단일값) | aws-mcp.amazonaws.com, eks-mcp.amazonaws.com, ecs-mcp.amazonaws.com |
특정 MCP 서버만 제어 |
(폐기) aws-mcp:InvokeMcp 등 3종 |
IAM 액션 | — | 더 이상 효과 없음. Deny에 쓰고 있었다면 교체 필요 |
실무적으로 가장 쓸모 있는 패턴은 “사람은 그대로, 에이전트 경로에서만 위험 액션 차단”입니다. 비밀값 문제도 결국 여기서 막는 게 정석입니다.
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "DenySecretReadViaAgent",
"Effect": "Deny",
"Action": ["secretsmanager:GetSecretValue",
"secretsmanager:BatchGetSecretValue"],
"Resource": "*",
"Condition": { "Bool": { "aws:ViaAWSMCPService": "true" } }
}]
}단, 이 키는 관리형 MCP 서버를 거친 요청에만 붙습니다. 에이전트가 Bash로 로컬 AWS CLI를 직접 부르면 사람의 호출과 구분되지 않습니다. 그래서 규칙 파일이 “MCP 우선”을 강조하고, 로컬 경로는 훅이 보조하는 구조입니다.
7. secret-safety 훅 해부와 실측
aws-core는 Claude Code의 PreToolUse 훅으로 secret-safety.py를 등록합니다. 매처는 두 개입니다. Bash, 그리고 use_aws|mcp__aws.*|mcp__plugin_.*aws-mcp.*. 타임아웃은 5초입니다. 코드 주석에는 “정규식이 모호하면 긴 플래그 나열에서 백트래킹이 폭발하고, 타임아웃이 나면 fail-open이 된다”는 이유로 플래그 반복을 {0,12}로 제한했다는 설명까지 있습니다. 꽤 신경 쓴 코드입니다.
| 검사 분기 | 대상 도구 | 매칭 방식 | 의도 |
|---|---|---|---|
| 구조화 필드 | use_aws, mcp__* |
service_name=secretsmanager + operation 정규화 후 GetSecretValue/BatchGetSecretValue |
MCP 구조화 호출 차단 |
| SDK 호출 형태 | MCP 입력 JSON 전체 | .get_secret_value(, GetSecretValueCommand( 등 “괄호 붙은 호출”만 |
단순 언급은 통과시키기 |
| CLI 문자열 | Bash, MCP 문자열 | aws [플래그≤12] secretsmanager [플래그≤12] (batch-)get-secret-value |
전역 플래그 끼워넣기 대응 |
| SMA 데몬 | Bash | localhost|127.0.0.1|::1 :2773/secretsmanager/get |
Secrets Manager Agent 직접 호출 차단 |
| 읽기 전용 예외 | Bash | grep·cat·git 등으로 시작하고 ; & | ` $(가 없으면 허용 |
코드 검색 오탐 방지 |
| 인라인 인터프리터 | Bash | python -c, node -e 등 + SDK 호출 형태 |
원라이너 우회 차단 |
박스에서 Claude Code가 넘기는 것과 같은 형태의 JSON을 stdin으로 넣어 22가지 입력을 테스트했습니다. 결과는 다음과 같습니다.
| # | 입력 | 결과 | 해석 |
|---|---|---|---|
| 1 | aws secretsmanager get-secret-value --secret-id prod/db |
DENY | 기본 케이스 |
| 2 | aws --region … --profile … secretsmanager get-secret-value |
DENY | 전역 플래그 끼워넣기 대응 |
| 3 | batch-get-secret-value |
DENY | 배치 API 포함 |
| 4 | curl … localhost:2773/secretsmanager/get |
DENY | SMA 데몬 차단 |
| 5 | python3 -c "…get_secret_value(…)" |
DENY | 인라인 SDK 차단 |
| 6 | grep -rn get_secret_value src/ |
ALLOW | 의도대로 오탐 없음 |
| 7 | grep x f; aws secretsmanager get-secret-value |
DENY | 체이닝 우회 차단 |
| 8 | aws secretsmanager list-secrets |
ALLOW | 메타데이터 조회는 허용 (정상) |
| 9 | python3 fetch_secret.py |
ALLOW | 파일 내용은 보지 않음 (훅의 본질적 한계) |
| 10 | aws ssm get-parameter --with-decryption |
ALLOW | SSM SecureString은 범위 밖 |
| 11 | S=secretsmanager; aws $S get-secret-value |
ALLOW | 셸 변수 치환은 못 잡음 |
| 12 | MCP 구조화 service_name/operation_name |
DENY | 정상 |
| 13 | MCP cli_command 문자열 |
DENY | 정상 |
| 14 | MCP run_script 안의 boto3 … .get_secret_value( |
DENY | SDK 형태라 잡힘 |
| 15 | MCP describe-secret |
ALLOW | 정상 |
| 16 | 플래그 5,000개짜리 명령 | ALLOW, 17.5ms | ReDoS 내성 확인 |
| 17 | 전역 플래그 12개 + get-secret-value | DENY | 상한 이내 |
| 18 | 전역 플래그 13개 + get-secret-value | ALLOW | 상한 {0,12}의 대가 |
| 19~22 | run_script의 call_boto3(service_name='secretsmanager', operation_name='GetSecretValue') (Pascal/snake, 도구 이름 2종) |
4/4 ALLOW | 현재 서버의 실제 비밀값 조회 경로가 통과 |
19~22번이 핵심입니다. 지금 AWS MCP Server에서 비밀값을 꺼내는 정식 경로는 run_script 안의 call_boto3(...)입니다(예전 aws___call_aws 도구는 사라졌고, 박스에서 받은 도구 목록에도 없습니다). 그런데 훅의 SDK 패턴은 “메서드 이름 바로 뒤 괄호”를 찾기 때문에, 키워드 인자로 operation 이름을 넘기는 이 형태는 매칭되지 않습니다. 이 문제는 이슈 #307(2026-09-10 10:33 KST 등록)으로 이미 정확히 보고되어 있고, 확인 시점까지 open 상태였습니다. 우리는 그 재현을 독립적으로 확인한 셈입니다.
로컬에서 임시로 막고 싶다면 MCP 분기에 아래 한 줄을 추가하는 정도로 충분했습니다. 박스에서 이 패치로 19~22번 형태(Pascal·snake·Batch)는 DENY, DescribeSecret·ListSecrets는 ALLOW, 기존 1번·6번 회귀도 그대로였습니다.
BOTO3_OP_PATTERN = re.compile(
r"operation_name\W{0,6}(batch[-_]?)?get[-_]?secret[-_]?value", re.I)
...
if "secretsmanager" in input_str.lower() and BOTO3_OP_PATTERN.search(input_str):
deny()하지만 이것도 "Get" + "SecretValue" 같은 문자열 조립 앞에서는 무력합니다. 훅은 본질적으로 패턴 매칭 가드레일이지 보안 경계가 아닙니다. 정답은 6장의 IAM Deny(aws:ViaAWSMCPService)와 에이전트 전용 역할의 최소 권한이고, 훅은 “실수로 비밀값을 컨텍스트에 끌어오는 일”을 줄이는 1차 필터로 보면 됩니다.
8. 박스 스모크 테스트: 무엇을 돌렸고 얼마나 걸렸나
AWS 계정 없이 할 수 있는 범위로 한정했습니다. 리포 루트의 검증 도구, aws-startup-advisor의 CI 태스크, 원격 MCP 무인증 호출, 그리고 위의 훅 테스트입니다. 환경은 박스의 Python 3.13.5, uv 사용.
| 검사 | 명령 | 결과 | 소요 |
|---|---|---|---|
| 매니페스트·프런트매터 | python3 tools/validate.py |
All validations passed | 0.05초 |
| 플러그인 스킬 동기화 | python3 tools/sync-plugin-skills.py --check |
All plugin skills are in sync | 0.09초 |
| Agent Plugins v1.0.0 스펙 | uv run --with jsonschema --with pyyaml python tools/validate_spec.py |
All checks passed | 0.75초 |
| 도구 단위 테스트 | python3 -m unittest discover -s tools/tests |
6/6 OK | 0.08초 |
| startup-advisor 계약 테스트 | uv run --no-project --with pytest python -m pytest tests -q |
513 passed | 15.5초 |
| 아티팩트 스키마 | scripts/validate-artifacts.py --fixtures |
85개, 오류 0 (baseline 50, info 16) | 즉시 |
| vendored 파일 동일성 | tools/sync-vendored.py --check |
59개 바이트 동일 | 즉시 |
| 스킬 참조 경로 | tools/check-skill-refs.py --check |
1,398개, 누락 0 (baseline 7) | 즉시 |
| 모델 레지스트리 신선도 | tools/model-staleness.py --strict |
fresh and in sync | 즉시 |
| 동의 문구 감사 | scripts/consent-disclosure-audit.py |
OK (6개 파일) | 즉시 |
| 원격 MCP initialize / tools/list | JSON-RPC POST | 도구 8개, 무인증 세션 성공 | 0.53초 / 0.55초 |
| 원격 문서 검색 | search_documentation “Lambda SnapStart supported runtimes” |
지원 런타임(Java 11+, Python 3.12+, .NET 8+) 원문 청크 반환 | 1.69초 |
| 원격 스킬 검색 | 토픽 agent_skills, “secrets manager rotation” |
1순위 creating-secrets-using-best-practices |
1.47초 |
| secret-safety 훅 | 22개 입력 | 의도대로 동작 + 우회 2종 (run_script, 플래그 13+) | 15~26ms/회 |
측정에서 읽히는 점은 두 가지입니다. 첫째, 문서 리포치고 CI가 매우 촘촘합니다. 스킬이 참조하는 파일 경로 1,398개를 전부 검사하고, 플러그인 사본과 canonical 스킬의 트리 동일성, vendored 파일 바이트 동일성까지 봅니다. 사람이 Markdown을 고치다 링크를 깨는 일을 기계적으로 막는 구조입니다. 둘째, 훅 비용은 무시할 만합니다. 호출당 15~26ms라 Bash 호출마다 붙어도 체감이 없습니다. 전체 마크다운 린트(markdownlint-cli2)와 gitleaks, Heroku 소스 리뷰용 Node 테스트는 이번에 돌리지 않았습니다.
9. 대안과 비교
| 선택지 | 강점 | 약점 | 맞는 상황 |
|---|---|---|---|
| Agent Toolkit for AWS | 공식·GA, 관리형 MCP, IAM 조건 키·CloudTrail, 평가된 스킬, 하네스 6종 지원 | MCP 엔드포인트가 us-east-1 기반, AWS 종속, 훅 우회 이슈 open | AWS 중심 팀의 기본값 |
AWS Labs 개별 MCP 서버 (awslabs) |
서비스별 세밀한 도구, 로컬 실행, 기존 사용자 많음 | 공식적으로 후속 리포로 이전 중, 서버마다 설정·버전 관리 | 특정 서비스 전용 도구가 꼭 필요할 때 |
| 로컬 AWS CLI + 에이전트 Bash | 설정 0, 무엇이든 가능 | 사람/에이전트 호출 구분 불가, 감사·통제 약함 | 개인 샌드박스 계정 |
| Terraform/OpenTofu + 범용 에이전트 | 멀티클라우드, plan 리뷰 습관 | AWS 서비스별 함정 지식은 별도 확보 필요 | 이미 IaC가 Terraform인 조직 (단, IAM 스킬은 plan JSON 입력도 지원) |
| 다른 클라우드 공식 MCP (예: Azure MCP Server) | 각 클라우드 네이티브 통합 | AWS 리소스엔 해당 없음 | 멀티클라우드 팀의 병행 구성 |
10. 도입 전 체크리스트와 리스크
| 리스크 | 원인 | 완화책 |
|---|---|---|
| 비밀값이 에이전트 컨텍스트로 유입 | 훅의 run_script·변수 치환·스크립트 파일 우회 | IAM에서 aws:ViaAWSMCPService 조건 Deny, asm-exec 패턴 강제, 로컬 훅 패치 |
| 예전 Deny 정책 무력화 | aws-mcp:* 액션 폐기 |
정책 grep 후 조건 키 방식으로 교체 |
| Bash 경유 호출은 감사에서 사람과 구분 안 됨 | 조건 키는 MCP 경유에만 부착 | 에이전트용 별도 프로필/역할, 규칙 파일로 MCP 우선 강제 |
| 도구 버전 드리프트 | 수동 예시는 @latest |
mcp-proxy-for-aws-cli==1.7.0처럼 고정 |
| 스킬 지식 노후화 | 서비스 변경 속도 | 플러그인 업데이트 주기 관리, 스킬보다 문서 검색을 우선하라는 규칙 유지 |
| 컨텍스트 비용 | 긴 description 인덱스 | 필요한 플러그인만 설치 (core부터) |
| 리전·데이터 경로 | 엔드포인트 호스트가 us-east-1 | 규제 환경은 데이터 경로·로그 위치를 사전 검토 |
11. 상황별 권장
| 상황 | 권장 구성 | 이유 |
|---|---|---|
| 개인·사이드 프로젝트 | aws-core 플러그인만 | 문서·스킬 검색만으로도 할루시네이션이 확 줄어듦 |
| 팀 프로덕션 계정 | aws-core + 에이전트 전용 역할 + MCP 조건 키 Deny + 고정 버전 | 통제는 IAM, 편의는 플러그인 |
| Bedrock 에이전트 개발 | aws-core + aws-agents | AgentCore 라이프사이클별 스킬 |
| 데이터 플랫폼 팀 | aws-data-analytics | S3 Tables·Glue·Athena·MWAA 워크플로 |
| 타 클라우드·OpenAI에서 이전 | aws-startup-advisor | 이전 매핑·비용 추정을 테스트로 고정한 유일한 플러그인 |
| 보안·SRE 조직 | aws-agents-for-devsecops | DevOps Agent·Security Agent 연동 커맨드 |
마무리
이 리포의 가치는 코드가 아니라 “에이전트가 AWS에서 자주 틀리는 것”을 체계적으로 모으고, 그 지식이 깨지지 않게 CI로 지키는 방식에 있습니다. 513개 계약 테스트와 1,398개 참조 경로 검사는 문서 저장소로서는 보기 드문 수준입니다. 실행은 관리형 MCP 서버의 범용 run_script로 단순화하고, 통제는 IAM 조건 키로 넘긴 설계도 합리적입니다. 다만 Claude Code용 secret-safety 훅은 현재 서버의 주 경로를 놓치고 있으니(#307), 도입할 때는 훅을 믿기보다 IAM Deny를 먼저 깔고 훅은 보조로 두는 순서를 지키는 게 좋습니다.