[책 정리] 인프라 구성 · 배포 with 클로드 코드

Chapter 1. AI 시대, 개발자의 인프라

개발자가 인프라를 다뤄야 하는 이유

"만든 사람이 운영한다(You build it, you run it)"
- 개발자는 코드 작성 뿐 아니라 배포, 리소스 관리, 문제 진단 등 운영 영역까지 대응할 수 있어야 한다.

"클라우드 네이티브 전환"
- 다양한 클라우드 환경에서 인프라를 코드로 정의한다.
- 서버 설치 시 버튼을 클릭하여 수동으로 생성하지 않고, 코드 기반으로 인프라와 배포 파이프라인을 자동화한다.
(YAML, Terraform으로 선언 -> Git에 커밋)

"풀스택 개발자의 새로운 의미"
= 백엔드 + 프론트엔드 + 배포 파이프라인 + 인프라

인프라 구축의 출발점

"쿠버네티스"
- 특정 클라우드에 종속되지 않는다.
- 리눅스가 서버 운영의 표준이라면, 쿠버네티스는 클라우드 운영의 표준이다.
- VM, Public Cloud, Container Platform 모두 핵심 개념이 비슷하다. (App 배포, 트래픽 라우팅, 설정 관리, 오토스케일, 모니터링)

"AI"
- CNCF Landscape 보면 수백개의 프로젝트.. 클러스터 운영 시 결정해야 할 요소가 너무 많다.
(모니터링, 로그 수집, 배포 전략, GitOps, Secret 관리, 메시지 큐, 트래픽 관리, ...)
- 도구 평가 / 표준 수립 / 사내 가이드 + 구축 / 배포 / 모니터링 / 장애 대응 / 보안 까지 운영하기 위해선 AI의 도움이 필요하다.
- AI가 현재 상황에 맞는 적합한 도구를 추천해주면, 사람은 어떤걸 쓸지 결정만 하면 된다.
- 설치부터 설정, 검증 과정까지 전부 AI가 맡아 실행해준다. (매니페스트 작성, 트러블 슈팅, 문서화까지 전부)

GitOps에서 GitAIOps로

"기존 GitOps"
- Single Source of Truth. Git 저장소를 단일 공급원으로 삼아 인프라 상태를 선언적으로 관리하겠다.
- 동작 흐름 : 개발자는 파일을 Git에 Push -> GitOps 도구가 Git 감시하다 변경이 생기면 자동 적용
- 장점 : 배포 자동화 / 배포 히스토리 관리 / 롤백 가능 / 동료와 코드 리뷰 / Git 설정 그대로 새로운 환경에 생성 (재현 가능)

"Git+AI+Ops"
- 상태 관리 자동화 + AI 실행 능력
- 사람이 자연어로 지시하면, AI는 YAML 생성, Git Commit. 이후, ArgoCD는 이를 반영.
- 즉, 배포 자동화(ArgoCD)는 그대로 유지하면서 앞단 작업을 AI가 가속화 해준다.
- 이러한 과정에서 히스토리가 점차 쌓이고, 별도 문서 작업을 하지 않아도 작업 과정 자체가 운영 표준이 된다.

책 구성

<개요>
1장. AI 시대에서 개발자에게 필요한 인프라 역량
2장. 실습 환경 구성
---
<인프라 구축>
3장. ArgoCD로 GitOps 도입, GitHub Actions으로 CI 자동화
4장. Prometheus, Grafana, Loki로 Observability(관찰 가능성) 구축
5장. Gateway API와 Argo Rollouts로 무중단 배포 도입
---
<고객 관리>
6장. Cache(Valkey), Secret 관리, Canary 배포 도입
---
<인프라 확장>
7~8장. Multi-Pool Node로 워크로드 분리, App of Apps 패턴으로 여러 앱 관리, Multi-tenancy로 고객 환경 격리,
Kafka로 이벤트 드리븐 아키텍처 도입, Tempo로 분산 트레이싱 구축, CronJob으로 배치 작업 자동화
---
<GitAIOps>
9장. 실습 로그 (Git 코드, 설정, 문서) 분석 후 운영 표준화

** 전체적인 실습 흐름은 다음과 같다.

문제 상황 인식 -> 클로드에게 지시 -> 결과 확인 -> Git 커밋

실습 시나리오 소개

Notifilex 스타트업에서 B2B 알림 SaaS 플랫폼 출시

고객 서비스에서 발생하는 이벤트를 받아 이메일, 문자, 푸시 알림을 발송해줍니다.

저희 API를 호출하기만 하면 됩니다. 이후 복잡한 처리는 저희가 담당합니다.

"기술 스택"
- Go 표준 라이브러리로 작성한 API 서버
- scratch 베이스인 컨테이너 이미지
- GKE

"Notifilex에서 나의 역할"
- DevOps 엔지니어. 동료는 클로드 코드.
- 클러스터 구축, 배포 파이프라인 설계, 모니터링, 장애 대응, 인프라 확장 모든 영역을 담당한다

"성장 타임라인"

성장 단계	상황	대응
창업	Notifilex 오픈	GKE에 API 서버 띄우기
첫 고객	배포할 때마다 실수할까봐 겁남	ArgoCD로 GitOps 도입
서비스 장애	서비스 장애가 발생했는데 뭐가 문제인지 모름	Observability 구축
성장 시작	고객이 늘어나면서 서비스가 끊김	무중단 배포 도입
전환기	고객이 늘어나면서 응답 속도와 보안 강화 필요	캐시, 시크릿 관리 및 배포 전략 정비
대형 계약	대형 고객사가 전용 환경을 요청함	인프라를 확장하고 테넌트 분리
대규모 운영	서비스 간 호출이 꼬이고 배치 지연	이벤트 드리븐, 분산 트레이싱, 배치 자동화 도입
돌아보기	지금까지 작업 복기	Git 코드, 설정 파일, 표준 문서 확인 (GitAIOps)

Guide & Guardrails

- 인프라 작업은 정확성이 중요하다. 이를 위한 안전장치로 가이드와 가드레일을 정의한다.
- 가드레일은 클로드 코드가 검증된 경로를 따르도록 안내해준다. (매 단계마다 제대로 가고 있는지 확인 가능하다)

- 책에서 제공하는 가이드 저장소에 3가지 참조 파일이 정의되어 있다.

1. 의사결정 가이드 ( decision-guides )

2. 실행 가드레일 ( prompt-guardrails )

3. 결과 템플릿 ( result-templates )

- 자연어로 질문하면 클로드는 질문 유형에 따라 다른 파일을 참조한다.

1단계 탐색 : ' decision-guides ' 참조해서 추천하고 이유 설명 (ex. 실행 지침, 트러블슈팅, 질문 블록)

-> 2단계 비교 : ' decision-guides ' 내 '비교' 섹션으로 대안 비교 (ex. 작업 도구 비교 및 추천)

-> 3단계 실행 : ' prompt-guardrails ' 지침대로 작업 수행 후 ' result-templates ' 으로 검증 (ex. 작업 후 최종 검토)

1. 의사결정 가이드 ( decision-guides ) 예시

2. 실행 가드레일 ( prompt-guardrails ) 예시

3. 결과 템플릿 ( result-templates ) 예시

[ 가드레일 궁금증에 대한 AI 답변 ]

Q. 가드레일을 보니 AI가 직접 일을 수행하기 보다 가드레일대로 움직이는 거 같은데 맞나요?

A. 어느 정도 맞습니다.

이 책은 Claude Code가 자유롭게 판단하도록 하기보다는, 커리큘럼대로 동일한 결과를 내도록 상세한 가이드와 프롬프트를 제공합니다.

일반적인 AI와 대화하는 경험보다는 잘 정의된 작업 매뉴얼을 수행하는 에이전트에 가까운 느낌을 받게 됩니다.

Q. 그럼 Claude Code를 잘 쓰려면 가드레일 만드는 법을 공부해야 하나요?

A. 맞지만, 책처럼 상세하게 만드는 것이 정답은 아닙니다.

책에서는 교육 목적상 배경 설명, 예상 질문, 핵심 개념, 작업 순서, 다음 단계 까지 모두 정의해 놓았습니다.

하지만 실제 프로젝트에서는 보통 Terraform 사용, Helm 사용, kubectl apply 금지, 테스트 필수 처럼 팀의 원칙과 제약사항만 정의하는 경우가 많습니다.

중요한 것은 AI에게 모든 절차를 알려주는 것이 아니라 AI가 지켜야 할 원칙을 명확히 알려주는 것입니다.

Q. 그럼 Claude Code를 사용하는 목적은 결국 내가 만들어 둔 가드레일대로 반복 작업을 실수 없이 수행하게 하는 건가요?

A. 그것도 중요한 목적 중 하나입니다.

예를 들어 회사에서 새로운 API를 만들 때마다 테스트 작성 문서 수정 Helm 값 변경 Git Commit 을 항상 해야 한다면, 사람이 매번 기억하기는 어렵습니다. 하지만 Claude Code는 가드레일을 통해 항상 같은 절차를 수행할 수 있습니다.

다만 Claude Code의 역할이 단순히 반복 작업만 하는 것은 아닙니다.

반복 작업은 가드레일에 맡기고, 새로운 기능 설계 / 에러 원인 분석 / 아키텍처 제안 / 성능 개선 처럼 정답이 없는 문제는 여전히 AI와 대화하며 함께 해결하는 것이 Claude Code의 또 다른 중요한 활용 방식입니다.

가드레일 설계법은 CLAUDE.md에 배운 걸 계속 누적시키는 습관만 있으면 됩니다.
겪은 문제나 결정한 것들을 CLAUDE.md에 그때그때 적어두면 본 실습 저장소처럼 누적된 결과물을 만들 수 있게 됩니다.

앞으로 프로젝트(notiflex-platform) 작업 도중,
1. 문제를 만나면 → 해결 직후 JOURNEY.md 트러블슈팅 이력에 한 줄 추가
2. 도구를 선택하면 → JOURNEY.md 도구 선택 기록에 이유와 함께 추가
3. 각 장 끝날 때 → /update-docs 실행해서 누락 없이 정리
4. 반복되는 워크플로우가 생기면 → 그때 커스텀 스킬로 승격
5. 위험한 명령(삭제 등)이 반복 등장하면 → 그때 settings.json 권한 규칙 추가

Chapter 2. 환경 구성

준비물
1. GCP 계정
2. 클로드 코드 PRO
3. GitHub 저장소

Windows에 클로드 코드 설치

PS C:\Users\RIA> irm https://claude.ai/install.ps1 | iex
Setting up Claude Code...

✔ Claude Code successfully installed!

  Version: 2.1.196

  Location: C:\Users\RIA\.local\bin\claude.exe

  Next: Run claude --help to get started

⚠ Setup notes:
  ● Native installation exists but C:\Users\RIA\.local\bin is not in your PATH. Add it by opening: System Properties → Environment Variables → Edit User PATH → New → Add the path above. Then restart your terminal.

✅ Installation complete!

PS C:\Users\RIA> git clone https://github.com/ria-choi/_Book_GitAIOps.git
Cloning into '_Book_GitAIOps'...
remote: Enumerating objects: 643, done.
remote: Counting objects: 100% (163/163), done.
remote: Compressing objects: 100% (110/110), done.
remote: Total 643 (delta 90), reused 105 (delta 47), pack-reused 480 (from 1)
Receiving objects: 100% (643/643), 234.28 KiB | 675.00 KiB/s, done.
Resolving deltas: 100% (320/320), done.

>> [Windows] claude PATH 환경변수 설정

>> 자동 승인 모드로 claude 실행

- 파일 생성하거나 명령 실행할 때 자동 승인

- 실습할땐 _Book_GitAIOps 경로에서 claude 실행하기 (아래 캡처에서는 잘못 로그인함)

gcloud CLI 설치 / GitHub 저장소 생성 / GKE 클러스터 생성

2.3 gcloud CLI 설정 완료했습니다.

- 계정: ****@gmail.com 로그인 완료 (auth login, auth application-default login)
- 프로젝트: **** (My First Project)
- 존/리전: asia-northeast3-a / asia-northeast3 (서울)
- ADC 쿼터 프로젝트: 설정 완료
- Artifact Registry Docker 인증: asia-northeast3-docker.pkg.dev 설정 완료

# ! gcloud components install kubectl

kubectl 설치 완료했습니다. 다만 PATH에서 Docker Desktop의 kubectl(v1.34.1)이 gcloud가 설치한 버전(1.35.x)보다 먼저 잡혀서, kubectl 명령은 현재 Docker 버전을 사용하고 있어요. GKE 버전 스큐 정책상 1개 마이너 버전 차이는 호환되므로 당장 문제는 없지만, 나중에 GKE 클러스터 버전이 더 올라가면 충돌할 수 있습니다.

Windows에서는 PATH 병합 순서가 시스템(Machine) PATH → 사용자(User) PATH 순으로 고정됩니다. Docker의 kubectl은 시스템 PATH에, gcloud의 kubectl은 사용자 PATH에 있어서 사용자 PATH 순서를 아무리 바꿔도 Docker가 항상 먼저 잡혀요.

PowerShell 프로파일(Microsoft.PowerShell_profile.ps1)에 함수를 추가해서 이제 PowerShell 세션에서 kubectl은 gcloud 버전(v1.35.6)을 사용합니다. 확인해보니 정상적으로 우선순위가 적용됐어요.

참고로 이 방식은 새 PowerShell 세션에만 적용되고, cmd.exe나 Git Bash 등 다른 터미널에서는 여전히 Docker의 kubectl(v1.34.1)이 잡힙니다.

Notiflex App 빌드 및 배포 / GitHub 커밋 / update-docs 스킬 생성

** 문서 오류 확인 후 트러블슈팅 내역 업데이트

_Book_GitAIOps/prompt-guardrails/ch2/2.2-install-check.md at main · sysnet4admin/_Book_GitAIOps

(수정 전)

>> Windows에서 %USERPROFILE% 문법은 동작하지 않음

(수정 후)

# Git Bash 설치된 Windows 에서 settings.json 설정
# 3가지 command 모두 가능

1)
{
  "autoUpdatesChannel": "latest",
  "skipDangerousModePermissionPrompt": true,
  "statusLine": {
    "type": "command",
    "command": "/bin/bash ~/.claude/statusline-command.sh",
    "padding": 0
  }
}

2)
{
  "autoUpdatesChannel": "latest",
  "skipDangerousModePermissionPrompt": true,
  "statusLine": {
    "type": "command",
    "command": "/bin/bash $USERPROFILE/.claude/statusline-command.sh",
    "padding": 0
  }
}

3)
{
  "autoUpdatesChannel": "latest",
  "skipDangerousModePermissionPrompt": true,
  "statusLine": {
    "type": "command",
    "command": "bash $USERPROFILE/.claude/statusline-command.sh",
    "padding": 0
  }
}

/bin/bash 추가 설명

/bin/bash와 bash 방식의 차이는?

둘 다 Bash를 실행하는 명령이다. 차이는 Bash 실행 파일 경로를 지정하는 방식이다.

1. /bin/bash

/bin/bash ~/.claude/statusline-command.sh

Bash 실행 파일의 위치를 직접 지정한다.
macOS, Linux에서는 /bin/bash가 기본적으로 존재하므로 가장 일반적인 방식이다.

2. bash

bash ~/.claude/statusline-command.sh

bash를 PATH에서 찾아 실행한다.
Windows에서는 PATH 설정에 따라 Git Bash, WSL bash 등 여러 bash 중 하나가 실행된다.

Windows에서는 왜 /bin/bash도 동작하는가?

 
Windows에는 /bin/bash라는 실제 파일이 존재하지 않는다.

Git for Windows(Git Bash)는 MSYS 환경을 통해 리눅스 호환 파일 시스템 뷰를 제공하며,
이 환경 안에서 /bin/bash는 실제 Windows 경로가 아니라 MSYS가 제공하는 가상 파일 시스템 상의 경로이다.

'AI' 카테고리의 다른 글

[책 정리] 인프라 구성 · 배포 with 클로드 코드 - (4) (0)	2026.07.25
[책 정리] 인프라 구성 · 배포 with 클로드 코드 - (3) (0)	2026.07.18
[책 정리] 인프라 구성 · 배포 with 클로드 코드 - (2) (0)	2026.07.07

Interlude님의 블로그

[책 정리] 인프라 구성 · 배포 with 클로드 코드 - (1)

Chapter 1. AI 시대, 개발자의 인프라

개발자가 인프라를 다뤄야 하는 이유

인프라 구축의 출발점

GitOps에서 GitAIOps로

책 구성

실습 시나리오 소개

Guide & Guardrails

Chapter 2. 환경 구성

Windows에 클로드 코드 설치

gcloud CLI 설치 / GitHub 저장소 생성 / GKE 클러스터 생성

Notiflex App 빌드 및 배포 / GitHub 커밋 / update-docs 스킬 생성

/bin/bash와 bash 방식의 차이는?

Windows에서는 왜 /bin/bash도 동작하는가?

'AI' 카테고리의 다른 글

티스토리툴바

[책 정리] 인프라 구성 · 배포 with 클로드 코드 - (1)

Chapter 1. AI 시대, 개발자의 인프라

개발자가 인프라를 다뤄야 하는 이유

인프라 구축의 출발점

GitOps에서 GitAIOps로

책 구성

실습 시나리오 소개

Guide & Guardrails

Chapter 2. 환경 구성

Windows에 클로드 코드 설치

gcloud CLI 설치 / GitHub 저장소 생성 / GKE 클러스터 생성

Notiflex App 빌드 및 배포 / GitHub 커밋 / update-docs 스킬 생성

/bin/bash와 bash 방식의 차이는?

Windows에서는 왜 /bin/bash도 동작하는가?

'AI' 카테고리의 다른 글

관련글

티스토리툴바