| name | deploy-guide |
| description | 워크숍 사전 준비 가이드(packages/guide/site/ 의 index.html + guide-images/)를 S3에 싱크하고 CloudFront 캐시를 무효화해 배포한다. "가이드 배포", "가이드 올려줘", "S3에 싱크", "CloudFront invalidate", "가이드 사이트 업데이트", "캐시 무효화", "가이드 반영" 같은 요청이나, packages/guide/site/ 의 HTML·이미지를 수정한 뒤 라이브에 반영하려는 모든 상황에서 반드시 이 스킬을 사용한다. CDK 전체 스택(deploy/destroy)을 건드리지 않고 콘텐츠만 빠르게 밀어넣는 경량 경로다. 버킷명·배포 ID는 CloudFormation 스택 출력에서 자동 조회하므로 사용자가 ID를 외울 필요가 없다. |
Deploy Guide Skill
워크숍 가이드 사이트를 콘텐츠만 빠르게 라이브에 반영하는 스킬이다.
인프라(S3 버킷 + CloudFront 배포)는 packages/guide 의 CDK 스택이 이미 만들어 두었고,
이 스킬은 그 위에 파일 싱크 + 캐시 무효화만 수행한다.
핵심 전제
- 배포본의 단일 소스(source of truth)는
packages/guide/site/ 이다.
site/index.html — 가이드 본문site/guide-images/ — 가이드에 들어가는 이미지~/Documents/workshop-setup-guide.html 같은 원본 사본은 더 이상 사용하지 않는다.
내용을 바꾸려면 packages/guide/site/ 안에서 직접 편집한다.
- 버킷 이름과 CloudFront 배포 ID는 하드코딩하지 않는다.
WorkshopGuideStack 의
CloudFormation 출력(BucketName, DistributionId, GuideUrl)에서 매번 조회한다.
스택을 재배포해 리소스 이름이 바뀌어도 스킬이 깨지지 않게 하기 위함이다.
언제 이 스킬을 쓰나
packages/guide/site/ 안의 HTML이나 이미지를 수정하고 라이브에 반영하고 싶을 때- "가이드 배포 / 올려줘 / 반영 / 업데이트", "S3 싱크", "CloudFront 무효화" 류의 요청
- 이미지를 추가·교체한 뒤 사이트에 보이게 하고 싶을 때
CDK 리소스 자체(버킷 정책, 배포 설정, 오류 응답 등)를 바꿔야 하는 경우는 이 스킬이 아니라
pnpm --filter @non-tech-ui-poc-workshop/guide deploy 로 스택을 다시 배포해야 한다.
이 스킬은 어디까지나 콘텐츠 갱신용이다.
사용법
대부분의 경우 번들된 스크립트 하나면 끝난다. 레포 어디서든 실행할 수 있다(스크립트가
자기 위치 기준으로 packages/guide/site/ 를 찾는다):
.claude/skills/deploy-guide/scripts/sync-guide.sh
스크립트가 하는 일(순서대로):
WorkshopGuideStack 출력에서 버킷명·배포 ID·URL을 조회packages/guide/site/ → S3 버킷으로 aws s3 sync --delete (정확히 미러링)
- 이미지 등 정적 자산은 길게 캐시(
max-age=86400), HTML은 짧게 캐시(max-age=60)해
본문 변경이 빨리 보이게 한다
- 다운로드 자산(
DOWNLOAD_ASSETS, 현재 guide-images/water-tracker.jpg)은
Content-Disposition: attachment 로 올려, 참여자가 클릭하면 새 탭에서 열리는 대신
바로 파일로 저장되게 한다. 실습용 손그림처럼 "받아서 써야 하는" 이미지가 여기 해당한다.
본문에 보여야 하는 삽화(fig-*.jpg)는 여기 넣지 않는다.
- CloudFront에
/* 무효화를 걸어 엣지 캐시를 비움
- 최종 가이드 URL을 출력
옵션
--dry-run — 실제로 올리지 않고 무엇이 바뀔지만 보여준다. 무엇이 삭제/업로드될지 먼저
확인하고 싶을 때 권장. (--delete 가 걸려 있어, 의도치 않게 S3 파일이 지워지지 않는지
점검하는 용도로 특히 유용하다.)--no-invalidate — S3 싱크만 하고 CloudFront 무효화는 건너뛴다.--stack NAME / --region REGION — 스택 이름이나 리전을 바꿔 실행(기본값:
WorkshopGuideStack / us-east-1).
작업 흐름 가이드
- 사용자가 가이드 내용/이미지를 바꿨다면, 먼저 변경이
packages/guide/site/ 에 반영되어 있는지
확인한다. (다른 곳에서 편집했다면 site/ 로 가져온다.)
- 파괴적 변경(파일 삭제)이 섞여 있거나 사용자가 불안해하면 먼저
--dry-run 으로 보여주고
확인을 받은 뒤 실제 싱크를 실행한다.
- 싱크 후 출력된 URL을 사용자에게 전달하고, 캐시 무효화는 보통 1~3분 걸린다는 점을 알린다.
- 필요하면
curl -sI <URL> 로 200 응답을 확인해 배포가 실제로 반영됐는지 검증한다.
사전 조건
- AWS 자격증명이 설정되어 있어야 한다(
aws sts get-caller-identity 로 확인).
WorkshopGuideStack 이 해당 계정/리전에 이미 배포되어 있어야 한다. 아직 없다면
먼저 pnpm --filter @non-tech-ui-poc-workshop/guide deploy 로 스택을 만든다.
