AI와 함께한 CI/CD 구축기
시작하며
지난 글에서 GitHub Actions CI/CD 아키텍처의 전체 구조를 소개했다.
사실 이 모든 걸 혼자 만든 건 아니다.
Claude Code를 적극 활용했다.
처음엔 단순한 코드 생성기로 썼지만,
이 도구를 "학습하는 파트너"로 활용하는 방법을 터득하게 됐다.
이 글에서는 그 과정을 솔직하게 공유하려 한다.
배경
솔직히 말하면, 나는 CI/CD에 대한 지식은 전무했다.
GitHub Actions? Docker 빌드? ECS 배포? 들어는 봤지만 직접 구축해본 적은 없었다.
그런데 갑자기 "CI/CD 좀 만들어줘"라는 요청이 들어왔다.
막막했다. 구글링을 해봐도:
- 공식 문서는 너무 방대해서 학습에 시간이 너무 오래걸리고
- 블로그 글들은 각자 환경이 달라서 그대로 적용이 안 되고
- 에러가 나면 뭐가 잘못된 건지 감도 안 잡히고
- 물어볼 사람도 마땅치 않고...
그래서 이번에 Claude Code를 적극 활용 해보기로 했다.
나만의 작업 프레임워크 구축
Claude Code에는 Memory라는 기능이 있다..claude/ 디렉토리에 CLAUDE.md 파일을 두면 AI가 그 내용을 기억하고 적용한다.
나는 이걸 적극 활용했다.
1. 프로젝트 유형별 가이드 문서화
Java, Vue.js, Angular, Lambda... 각각 배포 방식이 다르다. 처음에는 매번 설명해야 했다.
"이건 Java 프로젝트야. Maven 빌드하고, Docker 이미지 만들어서 ECS에 배포해야 해."
하지만 같은 설명을 반복하는 건 비효율적이다. 그래서 프로젝트 유형별 가이드 문서를 만들었다.
.claude/
├── GITHUB_ACTIONS_가이드.md # 공통 규칙
├── JAVA_배포_가이드.md # Java 프로젝트용
├── VUE_배포_가이드.md # Vue.js 프로젝트용
├── ANGULAR_배포_가이드.md # Angular 프로젝트용
├── LAMBDA_배포_가이드.md # Lambda 함수용
└── 트러블슈팅_가이드.md # 자주 발생하는 오류와 해결법이제 새 프로젝트에서 Claude Code를 열면,
AI가 자동으로 해당 프로젝트 유형에 맞는 가이드를 참조한다.
2. 실수를 규칙으로 바꾸기
가장 효과적이었던 건 실수를 문서화하는 것이었다.
예를 들어, 처음에 워크플로우를 작성할 때 이런 실수를 했다:
# 잘못된 예: 삼항연산자 사용
cluster_name: ${{ github.event.inputs.environment == 'prd' && 'CLUSTER-PRD' || 'CLUSTER-DEV' }}이 방식은 환경이 3개, 4개로 늘어나면 읽기 어려워진다. 더 나은 방법이 있었다:
# 올바른 예: setup job + case 문
jobs:
setup:
steps:
- name: Set configuration
run: |
case "$ENV" in
"dev") echo "cluster_name=CLUSTER-DEV" >> $GITHUB_OUTPUT ;;
"prd") echo "cluster_name=CLUSTER-PRD" >> $GITHUB_OUTPUT ;;
"stg") echo "cluster_name=CLUSTER-STG" >> $GITHUB_OUTPUT ;;
esac이런 교훈을 가이드 문서에 추가했다:
## 절대 하지 말 것
- ❌ 삼항연산자로 환경 분기 (가독성 저하)
- ❌ 리소스명 추측 (반드시 설정 파일에서 확인)
- ❌ Dockerfile 내용 수정 (위치 이동만 허용)
## 반드시 할 것
- ✅ setup job + case 문 패턴 사용
- ✅ 환경별 설정 파일에서 정확한 리소스명 확인
- ✅ permissions 섹션 포함이제 Claude Code는 같은 실수를 반복하지 않는다.
내가 한 번 실수하고 문서화하면, AI는 그걸 기억하고 다음번에 올바른 방식을 제안한다.
재사용 워크플로우 구축
반복 작업을 줄이기 위해 재사용 워크플로우를 만들었다.
Java, Vue.js, Angular, Lambda... 프로젝트 유형마다 배포 방식은 비슷한데, 매번 처음부터 워크플로우를 작성하는 건 비효율적이었다.
그래서 프로젝트 유형별로 공통 워크플로우를 만들고, 각 프로젝트에서는 환경별 설정값만 넘겨주면 되도록 구조화했다.
실제 작업 흐름
Step 1: 로컬에 체크아웃
먼저 작업할 리포지토리를 로컬에 체크아웃한다. Claude Code는 로컬 파일 시스템에서 작업하기 때문이다.
git clone {repo-url}
cd {project-name}Step 2: 프로젝트 분석
체크아웃한 프로젝트 경로에서 Super Claude /sc:analyze 명령어로 분석을 요청한다.
> /sc:analyze그러면 Claude Code가:
pom.xml,package.json등을 확인해서 기술 스택 파악- 기존 Docker 설정이 있는지 확인
- Memory에 설정해둔 프로젝트 유형별 가이드 문서 참조
- 적합한 재사용 워크플로우 추천
Step 3: deploy.yml 생성
분석이 끝나면 워크플로우 생성을 요청한다.
> deploy.yml 만들어줘이 한 마디면 된다. Memory에 설정해둔 가이드 덕분에 Claude Code는 알아서:
- 리소스 정의 파일에서 ECS Cluster, Service, ECR 이름 확인
- 환경별(dev, prd, stg 등) 설정값 매핑
- setup job + case 문 패턴으로 워크플로우 구조화
- 재사용 워크플로우 파라미터 정확히 매칭
- Dockerfile 위치 확인 및 표준 경로로 이동
이 모든 걸 수행한다. 재사용 워크플로우를 호출하는 구조라서, 정해진 양식에 AWS 리소스명만 채우면 되는 형태로 생성된다.
name: Deploy Application
permissions:
id-token: write
contents: read
packages: read
actions: read
on:
push:
branches: [develop]
workflow_dispatch:
inputs:
environment:
description: '배포 환경'
type: choice
options: [dev, prd, stg]
jobs:
setup:
runs-on: ubuntu-latest
outputs:
cluster_name: ${{ steps.config.outputs.cluster_name }}
# ... 기타 outputs
steps:
- name: Set configuration
id: config
run: |
ENV="${{ github.event.inputs.environment || 'dev' }}"
case "$ENV" in
"dev")
echo "cluster_name=..." >> $GITHUB_OUTPUT
;;
# ... 환경별 설정
esac
deploy:
needs: setup
uses: {org}/common-ci-cd/.github/workflows/{type}.yml@main
with:
environment: ${{ github.event.inputs.environment || 'dev' }}
cluster_name: ${{ needs.setup.outputs.cluster_name }}
# ... 파라미터들
secrets: inherit핵심은 uses: 라인이다. 여기서 미리 만들어둔 재사용 워크플로우를 호출한다.{type} 부분에 프로젝트 유형(java, vue, angular, lambda 등)에 맞는 워크플로우를 지정하면,
빌드부터 배포까지 전체 파이프라인이 실행된다.
Step 4: 배포 및 모니터링
워크플로우가 준비되면 배포를 요청한다.
> 배포해줘그러면 Claude Code가 알아서:
- feature 브랜치에서 dev 환경으로 워크플로우 실행
- 실시간 모니터링으로 배포 상태 추적
gh workflow run deploy.yml --ref feature/workflow -f environment=dev
gh run watch $(gh run list --workflow=deploy.yml --limit=1 --json databaseId --jq '.[0].databaseId')Step 5: AWS 리소스 확인
배포가 완료되면 리소스 상태 확인을 요청한다.
> 리소스 상태 확인해줘Memory에 AWS SSO 설정을 해뒀기 때문에, Claude Code가 알아서:
- SSO 토큰 만료 여부 체크
- 만료됐으면 자동 재로그인
- ECS 서비스 상태 확인
# SSO 토큰 체크 후 리소스 상태 확인
aws ecs describe-services --cluster {cluster} --services {service}Step 6: 배포 오류 디버깅
배포가 항상 성공하는 건 아니다. 오류가 나면 GitHub Actions 실행 링크를 확인하고, 그 링크만 Claude Code에게 전달한다.
> https://github.com/{org}/{repo}/actions/runs/123456789 이거 왜 실패했어?그러면 Claude Code가 알아서:
- 링크를 파싱해서
gh명령어 생성 - 실패한 job의 로그 조회
- 오류 원인 분석 및 해결책 제안
gh run view 123456789 --log-failed대부분의 디버깅은 이 과정으로 해결됐다.
효과
CI/CD에 대한 지식이 거의 없었지만, Claude Code와 함께 작업하면서 하나씩 알아갔다.
실수할 때마다 Memory에 규칙을 추가했고, 그 규칙들이 쌓이면서 작업 시간이 눈에 띄게 단축됐다.
처음엔 하나의 프로젝트에 CI/CD를 적용하는 데 하루 종일 걸렸지만, 나중엔 30분이면 충분했다.
배운 것들
1. AI는 도구가 아니라 파트너다
처음에는 "코드 생성해줘"라는 식으로 사용했다. 하지만 진짜 효과를 본 건 "같이 규칙을 만들어가는" 방식이었다.
- 내가 실수하면 → 규칙으로 문서화
- AI가 그 규칙을 기억하고 → 다음번에 적용
- 시간이 지나면서 → 나만의 프레임워크 완성
2. 문서화가 핵심이다
Memory에 쌓인 문서들이 진짜 자산이다. 이 문서들 덕분에:
- 새 프로젝트에서도 일관된 품질 유지
- 휴가 다녀와도 컨텍스트 유지
- 다른 팀원에게 인수인계도 쉬워짐
3. 반복 작업은 자동화해야 한다
AWS SSO 체크, 리포지토리 설정, 파라미터 확인... 반복되는 작업은 스크립트로 만들었다.
AI가 이 스크립트들을 알아서 활용하도록 설정해두니, 내 개입 없이도 작업이 진행된다.
다음에 시도해볼 것
작업을 마치고 나서 알게 된 게 있다. Memory에 무작정 문서를 넣는 건 능사가 아니라는 것.
- context 점유: CLAUDE.md는 세션 시작할 때 전부 읽힘. 파일이 클수록 실제 작업에 쓸 수 있는 context가 줄어든다.
- 처리 시간 증가: 문서가 많을수록 Claude Code가 분석하는 시간도 길어진다.
- 권장 크기: CLAUDE.md는 100-200줄 정도가 적정하다고 한다.
Claude Code는 이 문제를 해결할 수 있는 기능들을 제공한다:
- Skills:
.claude/skills/폴더에 분리해두면 필요할 때만 로드됨 - Hooks: 특정 시점에 자동 실행되는 쉘 명령어. "should-do"가 아닌 "must-do" 규칙
- Slash Commands:
/compact,/clear,/context등으로 context 관리
다음 프로젝트에서는 Memory를 더 효율적으로 구성해봐야겠다.
마무리
CI/CD에 대한 지식이 거의 없던 상태에서 시작했다.
하지만 Claude Code와 함께 작업하면서 하나씩 알아갔고, 실수할 때마다 규칙으로 문서화했다.
결국 중요한 건 규칙을 만드는 과정이었다.
AI는 그 규칙을 빠르게 적용해줄 뿐, 규칙 자체는 내가 만들어야 했다.
"deploy.yml 만들어줘"라는 한 마디가 통하는 건, 그 뒤에 쌓아둔 가이드 문서들이 있기 때문이다.