계획 전용 CI와 정책 게이트
비용이 많이 드는 AgentCore 실수는 계획(plan)에서 드러납니다: 교체될 메모리(모든 대화 손실), 교체될 게이트웨이(모든 클라이언트의 새 URL), 모든 것을 허용하는 역할. 풀 리퀘스트는 이를 막기에 가장 저렴한 장소이며, 계획(plan)은 확인하기에 적절한 아티팩트입니다 — 실제로 적용될 내용이기 때문입니다.
${CLAUDE_SKILL_DIR}은 스킬 런타임에 의해 이 스킬의 디렉토리로 설정됩니다. 아래 모든 명령어에서 이를 그대로 사용하십시오; 형제 스킬의 스크립트는 ${CLAUDE_SKILL_DIR}/../<skill>/scripts/에 있습니다.
흐름
-
워크플로우 계획하기, 읽기 전용:
python3 ${CLAUDE_SKILL_DIR}/scripts/gen_ci.py <project> --dry-run--tf-root는 계획할 스택의 루트(기본값: AgentCore 리소스에 도달하는 루트),--role-var는 계획 역할을 담은 GitHub 변수명(기본값AWS_PLAN_ROLE_ARN),--region,--terraform. -
보고 루트, Terraform 또는 Terragrunt, 발견된 핀(또는 폴백이 사용된 경우
CI010), 역할 노트(CI011). -
옵션: 워크플로우와 벤더된 검사기 작성(무료); 기존 저장된 계획에 대해 먼저 정책 실행(무료).
AskUserQuestion으로 확인 후 작성. -
게이트를 로컬에서 시도 사용자가 생성한 계획에 대해:
python3 ${CLAUDE_SKILL_DIR}/scripts/policy_check.py agentcore.plan.json--allow-replace <address>는 사람이 검토한 교체에만 사용. -
벤더된 실행기 확인 저장소 루트에서:
python3 ci/agentcore/run.py review ..
CI0xx 계열
| ID | 심각도 | 트리거 |
|---|---|---|
CI001 | 오류 | 계획이 메모리, 게이트웨이, 자격 증명 공급자, 워크로드 ID, Cognito 사용자 풀 또는 DynamoDB 테이블을 삭제 또는 교체함 |
CI002 | 오류 | 계획된 IAM 정책이 * on *을 허용함 |
CI003 | 오류 | authorizer_type = "NONE"으로 계획된 게이트웨이 |
CI004 | 경고 | supported_versions 없이 계획된 게이트웨이 |
CI005 | 정보 | 계획에 변경 사항 없음 |
CI006 | 정보 | 계획이 생성하는 AgentCore 리소스(청구 표면) |
CI010 | 정보 | 저장소에 SHA-고정된 액션 없음; 폴백 핀 사용됨 |
CI011 | 정보 | 계획 작업의 역할은 읽기 전용이어야 함 |
결정 규칙
- CI는 계획하고; 사람이 적용합니다. 워크플로우에는 적용 작업이 없으며, 계획 역할은 쓰기 권한이 없어야 합니다.
- 허가는 주소별로.
--allow-replace는 하나의 리소스를 지정하며, "모두 허용"은 없습니다. - 액션을 SHA로 고정. 저장소의 핀을 재사용; 폴백은 2026-10-05에 첫 번째 사용자의 저장소가 가지고 있던 것으로, 태그로 레이블이 지정됨.
- 벤더링되고, 설치되지 않음.
ci/agentcore/는 순수 Python 3.10+; 플러그인 업데이트는gen_ci.py --force를 다시 실행하고 diff를 검토하는 것을 의미함.
참고 자료
| 질문 | 파일 |
|---|---|
| 워크플로우 단계별; 역할; Terragrunt | plan-only-ci.md |
| 각 정책 규칙, 이유, 검토된 예외를 허용하는 방법 | policy-gates.md |
스크립트
| 명령어 | 기능 | 종료 코드 |
|---|---|---|
scripts/gen_ci.py <project> [--tf-root D] [--role-var V] [--dry-run] [--force] [--json] | 워크플로우 + ci/agentcore/ | 0 작성/계획됨, 1 없음, 2 잘못된 인수 |
scripts/policy_check.py <plan.json> [--allow-replace ADDR ...] [--json] | 저장된 계획에 CI0xx 게이트 | 0 통과, 1 정책 오류, 2 계획 아님 |
완료 체크리스트
- 워크플로우가 쓰기 계획으로 표시되고 작성 전에 확인되었습니다.
- 적용 단계가 없으며, 계획 역할이 읽기 전용으로 설명되었습니다.
-
policy_check.py가 실제 계획에 대해 실행되었거나, 사용자에게 방법이 안내되었습니다. - 벤더된 실행기가 저장소 루트에서 실행되었습니다.