4개 파트가 하나의 AI 시스템을 공유하기

date

slug

author

status

tags(최대 3개)

summary

type

thumbnail

TL;DR

5주간 127개 세션 동안 장애 분석, 인프라 구축, 자동화, 비용 분석을 Claude Code와 함께 수행했습니다.

6명의 인프라팀이 하나의 CLAUDE.md 파일과 26개 정책 파일로 AI 에이전트를 공유합니다.

타팀에서 합류한 DE가 첫날 setup.sh 한 번으로, 단 3분 만에 팀 전체의 AI 컨텍스트를 습득했습니다.

장애 쓰레드에 :postmortem: 이모지 하나만 클릭하면 Notion 포스트모템이 자동으로 생성됩니다.

메시지 300개가 달린 Slack 쓰레드도 링크 하나면 30초 만에 핵심만 파악할 수 있습니다.

자유보다는 레일을: 2,000줄의 가이드라인이 만든 가장 빠른 자동화. 잘 설계된 제약은 구속이 아니라 속도입니다. 모호함을 걷어낸 정책 파일들이 Claude Code를 불필요한 고민 없이 목적지까지 실어 나릅니다. (generated by ChatGPT)

1. 도입: 새 팀원이 3분 만에 Claude Code 전문가가 되는 팀

인프라팀 컨벤션에 데이터 정책만 얹어서 바로 활용했습니다.

타팀에서 인프라팀 DE 파트로 합류한 엔지니어가 온보딩 첫날 Slack에 남긴 메시지입니다. 그가 한 일은 딱 두 가지였습니다.


$ git clone https://github.com/******/infra-devops-platform.git
$ cd infra-devops-platform
$ ./.claude/scripts/setup.sh

스크립트를 실행하고 파트(data)만 선택하자, 그는 곧바로 ETL상태, 데이터품질, 배치모니터링 같은 Quick Command를 쓸 수 있었습니다. 별도 교육도, 문서 정독도, 팀원에게 묻는 일도 없이 말입니다.

지난 5주간 저는 Claude Code와 함께 127개 세션을 진행했습니다. 인프라 구축 46건, 자동화 18건, 장애 대응 8건, 비용 분석 5건. 이 모든 작업이 하나의 CLAUDE.md 파일과 26개 정책 파일 위에서 이뤄졌습니다.

핵심은 간단합니다. 팀 전체가 같은 AI 경험을 공유한다는 것입니다.

2. 문제: AI 도구는 있는데, 팀마다 사용법이 달랐다

Claude Code를 처음 도입했을 때 마주한 현실은 이랬습니다.

개인별 활용 수준 격차

A는 복잡한 프롬프트 엔지니어링을 자유자재로 구사했습니다.

B는 기본적인 코드 생성만 사용했습니다.

C는 어떻게 쓰는지 모르겠다며 손을 놓았습니다.

같은 질문, 다른 답

장애 분석해 달라고 입력해도 누구는 상세한 리포트를, 누구는 엉뚱한 답변을 받았습니다.

AI 응답의 품질이 프롬프트 작성 능력에 전적으로 좌우됐습니다.

온보딩 병목

신규 입사자에게 우리 팀의 일하는 방식을 설명하는 데 2주 넘게 걸렸습니다.

장애 대응은 늘 어디서 무엇을 봐야 하는지부터 시작했습니다.

일관된 절차 부재

장애 발생 → 분석 → 포스트모템 → 재발 방지로 이어지는 흐름이 사람마다 달랐습니다.

같은 장애가 또 터지면 처음부터 다시 분석해야 했습니다.

이것이 우리가 풀어야 할 문제였습니다.

3. 해결책: 정책 기반 AI 시스템

우리의 해결책은 CLAUDE.md 2,144줄 + 26개 정책 파일입니다.

3–1. CLAUDE.md 구조


# CLAUDE.md (2,144줄)
├── Quick Commands (키워드 트리거)
│ ├── 세션정리 → Notion 자동 기록
│ ├── 포스트모템 → 장애 보고서 생성
│ ├── 인프라비용기안 → Excel 분석 후 Flex 기안
│ ├── 이미지 프롬프트 → AI 이미지 생성용 프롬프트
│ └── 이벤트긴급 → 즉시 대응 모드
│
├── Credentials Management
│ ├── 1Password CLI 연동
│ └── credentials.json 단일 파일 관리
│
├── API Usage
│ ├── Jira REST API (curl -u 직접 바인딩)
│ ├── Slack API (환경변수 사용 금지!)
│ └── Notion API (Python requests 권장)
│
├── Auto-execution Policy
│ ├── 읽기 작업: 자동 실행
│ └── 쓰기 작업: 승인 필수
│
├── Git Workflow Policy
│ ├── main 직접 push 금지
│ └── Udacity 커밋 컨벤션
│
└── Domain-Specific Policies (@참조)
  └── 26개 정책 파일 연결

3–2. 26개 정책 파일 카테고리

3–3. 수평 + 수직 구조

인프라팀의 구성은 이렇습니다.

DevOps: 2명

DBA: 2명

Security Engineer: 1명

Data Engineer: 1명

이 6명이 하나의 AI 시스템을 공유하는 방식이 바로 수평·수직 구조입니다.

4. 핵심 사례 4가지

사례 1: 장애 대응 자동화 (포스트모템)

Before: 장애가 끝나면 2–3시간에 걸쳐 Slack 메시지를 정리하고, 타임라인을 작성하고, Notion 페이지를 만들었습니다.

After: 장애 쓰레드에 :postmortem: 이모지를 클릭하면 5분 안에 Notion 포스트모템이 자동 생성됩니다.

포스트모템 워크플로우 — 알림에서 문서까지, 자동으로 흐르다

트리거: 장애 쓰레드에 :postmortem: 이모지 클릭

이모지 하나만 누르면 다음이 자동으로 진행됩니다.

Lambda가 Slack 쓰레드 메시지를 수집합니다.

Bedrock Claude가 타임라인을 추출하고 5 Whys 분석을 수행합니다.

Notion API가 포스트모템 페이지를 생성합니다.

완료 알림이 Slack 쓰레드에 답글로 달립니다.

정책 파일(postmortem.md) 핵심 내용:


## 심각도 기준

### 위험 🔴
- 전체 서비스 다운 (메인 페이지 접근 불가)
- 결제/주문 불가 (매출 직접 영향)
- 데이터 손실/유출 발생
- 다운타임 4시간 이상

### 높음 🟠
- 주요 기능 장애 (알림톡, 배송, 정산 등)
- 다수 고객 영향 (10,000건 이상)
- 다운타임 1시간 이상

### 중간 🟡
- 특정 기능 장애 (일부 고객만 영향)
- 우회 방법 존재
- 다운타임 1시간 미만

5 Whys 분석 가이드 (정책에 포함):


1. Why: 알림톡이 발송되지 않았다
   → Infobip API가 403 에러 반환
2. Why: 403 에러가 발생했다
   → HTTP 프로토콜로 요청 시 거부됨
3. Why: HTTP가 거부되었다
   → Infobip이 HTTPS만 허용하도록 정책 변경
4. Why: 정책 변경을 몰랐다
   → 외부 API 변경사항 추적 프로세스 부재
5. Why: 추적 프로세스가 없다
   → 외부 의존성 관리 체계 미비

정책 파일에 이런 가이드를 넣어두면, Claude는 매번 일관된 품질로 5 Whys 분석을 수행합니다. 담당자가 누구든, 경험이 많든 적든 상관없습니다.

사례 2: 장애 → 정책 → 표준화의 선순환 (Datadog 로그 파이프라인)

임팩트: 장애 포스트모템의 액션 아이템이 당일 로그 수집 정책 수립으로, 다시 전사 표준 가이드 배포로 이어졌습니다.

이 사례는 정책이 정책을 낳는다는 우리 시스템의 핵심을 보여줍니다.

시작점: 인포빕 알림톡 장애

외부 API(인포빕)가 HTTP를 HTTPS로 바꾸면서 알림톡 발송이 불안정해졌습니다. 포스트모템에서 나온 액션 아이템 중 하나는 이것이었습니다.

애플리케이션 로그를 Datadog에 표준화된 포맷으로 적재하는 정책 수립

Claude Code와 함께 당일 해결

포스트모템이 끝나자마자 Claude에게 요청했습니다.


나: Datadog에 애플리케이션 로그를 표준화해서 보내는 방법을 정리하고,
PHP/NodeJS/Python 예시 코드까지 포함한 가이드를 만들어줘

Claude는 CLAUDE.md의 기존 정책을 참조하며 다음을 처리했습니다.

로그 포맷 표준 설계: JSON 구조와 필수 필드(service, env, level)를 정의했습니다.

Datadog 인덱스 생성: app-logger 전용 인덱스를 만들고 15일 보관으로 설정했습니다.

언어별 예시 코드: PHP, NodeJS, Python 예시를 작성했습니다.

Notion 가이드 문서: 복사-붙여넣기로 바로 쓸 수 있는 형태로 정리했습니다.

결과물


애플리케이션 → Datadog Agent → Datadog 인덱스
              (UDP 로그)    (@label:LOGGER)

아임웹 Datadog 로그 수집 플로우

언어 무관 (PHP, NodeJS, Python 등)

앱에서 API Key 불필요 (Agent가 처리)

15일 보관, 최우선 인덱싱

핵심 포인트

이 작업이 빠르게 끝난 이유는 다음과 같습니다.

CLAUDE.md에 Datadog API 사용 정책이 이미 있었습니다.

Notion 문서 작성 규칙이 정의되어 있었습니다.

코드 예시 포맷이 표준화되어 있었습니다.

장애 → 포스트모템 → 액션 아이템 → 새 정책 파일 → 다음 작업에 활용. 이것이 정책 기반 시스템의 선순환입니다.

Datadog 로그 수집 가이드 Slack 공유

사례 3: AWS VPN Multi-Account 구축

임팩트: 이틀 만에 AWS 계정 3개의 VPN 연결을 완료했습니다.

VPC 간 연결 문제는 인프라 엔지니어가 가장 자주 겪는 트러블슈팅 중 하나입니다. 체크할 항목이 많고, 하나라도 빠뜨리면 연결이 되지 않습니다.

우리는 이 경험을 정책 파일로 만들었습니다.

정책 파일(vpc-connectivity.md) 핵심 내용:


## Phase 1: 실제 리소스 기준 확인 (최우선)
| 순서 | 항목                     | 확인 방법                |
| --- | ------------------------ | ------------------------ |
| 1   | Source 인스턴스 SG 아웃바운드 | 목적지 CIDR 허용 여부      |
| 2   | Target 리소스 SG 인바운드    | 출발지 CIDR + 포트 허용 여부 |
| 3   | Target 서브넷 라우트 테이블   | 출발지 CIDR → TGW 라우트   |
| 4   | Source 서브넷 라우트 테이블   | 목적지 CIDR → TGW 라우트   |


## 자주 놓치는 항목 (WARNING)

### SG 아웃바운드
CRITICAL: 인바운드만 확인하고 아웃바운드를 빠뜨리는 실수 금지!
목적지 CIDR이 아웃바운드에 허용되어 있는지 반드시 확인!

### 리소스별 서브넷 라우트 테이블
CRITICAL: VPC에 여러 라우트 테이블이 있을 수 있음.
실제 리소스가 있는 서브넷의 라우트 테이블 확인 필수!

이 정책 덕분에 Claude는 VPC 연결 문제가 생기면 자동으로 다음을 수행합니다.

Phase 1 → Phase 2 → Phase 3 순서로 점검합니다.

각 항목의 상태를 표로 정리합니다.

원인과 조치 방법을 제시합니다.

그 결과, 보통 한 달 가까이 걸리던 Multi-Account VPN 구축이 이틀 만에 끝났습니다.

사례 4: 긴 Slack 쓰레드 즉시 파악하기

상황: 회의 중인데 갑자기 메시지 200개가 달린 에러 알람 쓰레드에서 멘션이 옵니다. 또는 휴가에서 복귀해 복잡한 논의가 오간 쓰레드를 봐야 합니다. 의사결정은 필요한데, 스크롤하며 읽을 시간이 없습니다.

해결: Slack 링크를 복사해 Claude Code에 붙여넣으면 끝입니다.


나: [Slack 쓰레드 링크] 아주 쉽게 일목요연하게 요약해줘

Claude가 자동으로 처리합니다.

Slack API로 쓰레드 전체 메시지를 수집합니다.

시간순으로 핵심 논의를 정리합니다.

결론과 미결 사항을 분리합니다.

내가 해야 할 액션 아이템을 추출합니다.

실제 경험

메시지 300개가 넘는 장애 쓰레드에 갑자기 호출당한 적이 있습니다. 스크롤하며 읽으면 30분은 걸릴 분량이었습니다. 저는 링크와 함께 지금 상황을 정리해 달라고 던졌고, 30초 뒤 이런 답을 받았습니다.

장애 시작: 14:32 KST

원인: Redis 커넥션 풀 고갈

현재 상태: 임시 조치 완료, 모니터링 중

내가 해야 할 것: 영구 조치 검토 (max_connections 증설 vs 커넥션 풀 로직 수정)

쓰레드 전체를 읽지 않고도, 이 정보만으로 바로 의사결정에 참여할 수 있었습니다.

왜 가능한가?

CLAUDE.md에 Slack API 호출 정책이 이미 정의되어 있기 때문입니다.


## Slack API 사용 정책
- Python requests 라이브러리 우선 사용
- Bearer 토큰 직접 바인딩 (환경변수 사용 금지)
- 쓰레드 메시지 수집: conversations.replies API
- 결과는 /tmp/에 JSON 저장 후 파싱

정책이 없었다면 매번 Slack API를 어떻게 호출할지부터 고민해야 했을 겁니다. 정책이 있으니 Claude는 묻지 않고 바로 실행합니다.

5. 온보딩 시스템: 3분 온보딩의 비밀

신규 입사자가 3분 만에 팀의 AI 시스템을 쓸 수 있는 비밀은 setup.sh 스크립트에 있습니다.

빠른 시작 (3분)


# 1. 레포 클론
git clone https://github.com/******/infra-devops-platform.git
cd infra-devops-platform

# 2. 설정 스크립트 실행
./.claude/scripts/setup.sh

# 3. 옵션 선택
# - 저장 방식: iCloud 연동(권장) 또는 로컬 파일만
# - 파트 선택: infra(기본), db, data, security

스크립트가 하는 일은 이렇습니다.

iCloud 디렉토리 심볼릭 링크를 생성합니다.

팀 공통 CLAUDE.md를 연결합니다.

선택한 파트의 정책 파일을 로드합니다.

credentials.json 템플릿을 생성합니다.

파트별 Quick Commands

파트를 바꾸고 싶다면 이렇게 합니다.


./.claude/scripts/setup.sh part db # DB 파트로 변경
./.claude/scripts/setup.sh status  # 현재 상태 확인

설정 완료 후 상태


새 팀원이 setup.sh 실행 후:

~/CLAUDE.md                    → 본인 iCloud의 CLAUDE.md
~/claude-policies/             → 본인 iCloud의 정책 파일들
.claude/CLAUDE.md              → Git에서 clone한 팀 공유 설정
.claude/policies/              → Git에서 clone한 팀 공유 정책
.claude/parts/{part}/          → Git에서 clone한 파트별 설정
.claude.local/credentials.json → 본인이 직접 입력한 토큰
.claude.local/personal.md      → 본인 Slack ID, Notion ID 등
.claude.local/CLAUDE.md.part   → 선택한 파트의 CLAUDE.md 심볼릭 링크

민감정보는 어떻게 공유하나요?

핵심: Git에 올라가는 파일에는 민감정보가 없습니다.

CLAUDE.md에 Slack 채널 ID나 API 엔드포인트가 언급되더라도, 실제 토큰은 .claude.local/credentials.json에만 존재합니다. 이 파일은 .gitignore에 포함되어 절대 커밋되지 않습니다.

외부에 공유할 때도 마찬가지입니다. 이 블로그에 인용한 모든 코드 예시에서 토큰, 채널 ID, 사용자 ID는 플레이스홀더(xoxb-XXX, C0XXXXXXXXX)로 치환했습니다.

6. 팀 전체 확장: 정책 파일 기여 = 팀 지식 축적

파트별 활용 현황

정책 파일 기여 사이클


문제 발생 → 해결 → 패턴화 → 정책 파일 작성 → PR → 팀 공유

예를 들면 이렇게 흘러갑니다.

VPC 연결 문제가 발생합니다.

여러 번의 삽질 끝에 해결합니다.

SG 아웃바운드를 자주 놓친다는 패턴을 발견합니다.

vpc-connectivity.md 정책 파일을 작성합니다.

PR 후, 팀 전체가 같은 실수를 반복하지 않게 됩니다.

프롬프트 철학

우리 팀이 공유하는 프롬프트 철학이 있습니다. 이름하여 몽둥이를 들어 긴장시키기입니다.

너 때문에 회사가 망할 수 있어.

너 때문에 천만 원 손실 봤어.

네 대답을 천 명의 임직원이 보고 있어.

물론 과장된 표현입니다. 하지만 핵심은 컨텍스트의 중요성을 AI에게 각인시키는 것입니다. AI가 이건 중요한 작업이라고 인식하면, 더 신중하고 정확한 응답을 내놓습니다.

7. 결론: 시작하는 팀을 위한 조언

핵심 교훈 3가지

1. 컨텍스트가 핵심이다

AI에게 팀의 방식을 알려줘야 합니다. 어떤 API를 어떻게 호출하는지, 어떤 규칙을 지켜야 하는지, 결과를 어떤 형식으로 원하는지. 이것을 CLAUDE.md에 명시하면 AI는 팀의 일원처럼 일합니다.

2. 정책 파일 = 재사용 가능한 지식

한 번 작성한 정책 파일은 무한히 재사용됩니다. VPC 연결 문제, 장애 분석, 포스트모템. 한 사람이 해결한 문제의 패턴을 정책으로 만들면, 팀 전체가 그 지식을 공유합니다.

3. 수평 + 수직 구조의 조합

팀 공통 설정(수평)과 파트별 맞춤 설정(수직)을 조합하세요. 모든 것을 한 파일에 넣으면 관리가 어렵고, 완전히 분리하면 일관성을 잃습니다.

시작 가이드

Day 1: CLAUDE.md에 기본 컨벤션을 작성합니다.

API 호출 방식 (Jira, Slack, Notion)

코드 스타일

커밋 메시지 규칙

~ Day 3: 반복 작업 3개를 정책 파일로 만듭니다.

가장 자주 하는 작업부터

실수하기 쉬운 작업부터

온보딩 때 설명하기 어려운 작업부터

~ Day 7: 팀 전체에 공유하고 기여 문화를 만듭니다.

Git 레포에 .claude/ 디렉토리 추가

setup.sh 스크립트 작성

정책 파일 PR 문화 정착

마무리

CLAUDE.md 2,144줄. 26개 정책 파일. 6명의 인프라팀. 숫자만 보면 복잡해 보이지만, 핵심은 단순합니다.

팀의 지식을 AI가 이해할 수 있는 형태로 정리하고, 모든 팀원이 같은 AI 경험을 공유하게 하라.

타팀에서 온 DE가 첫날 3분 만에 Databricks Job을 분석할 수 있었던 건, 기본 인프라 정책 위에 데이터 파트 정책을 얹었기 때문입니다. 그리고 그가 앞으로 발견할 패턴은 다음 팀원을 위한 정책이 될 것입니다.

이것이 우리가 AI 에이전트를 길들인 방법입니다.