LangGraph 서버 배포 런북, Claude Code가 헛짚은 여섯 가지
시리즈 Claude Code 워크플로 현재 위치 32 / 32
- git worktree로 AI 세션 여러 개를 동시에 돌리기: 브랜치 충돌과 stash 공유 사고를 피하는 운영 규칙
- AI에게 기억을 심는 법: 메모리 파일로 삽질 교훈을 세션 간에 유지하기
- 스킬로 반복 작업 자동화: 이슈 착수부터 종료까지 한 명령으로 묶은 dev-issue 사례
- 코드 그래프(graft)로 AI의 탐색 비용 줄이기: grep/read 대비 토큰 절감 체감
- AI 코드 리뷰를 규칙으로 고정하기
- 반복되는 Git 워크플로우와 브랜치 정리 자동화
- 같은 요청을 여러 저장소에 반복하는 법: 한 줄 프롬프트 + 기준 문서 하나
- 이슈 하나를 한 줄로 개발 끝내는 법 — 내가 가장 많이 쓰는 Claude Code 스킬들
- 블로그 글을 스무 번 부탁하고 나서, 스킬로 만들었다
- 마라톤 세션이 토큰을 먹는 구조: 로그로 찾고, /compact와 서브에이전트로 줄이기
- 1인 개발자가 클로드코드로 SaaS 11개 만든 기록
- 이슈 하나에 30~60분, 어디서 새고 있었나: skill-creator로 dev-issue 스킬을 만든 과정
- 도면을 AI에게 읽히려다 AI를 뺀 이야기
- 스쿼시 머지 vs 머지 커밋: 1인 개발자의 PR 전략
- "난이도가 높아서 오래 걸리는 거야?" — AIFid 개발 기록으로 따져 본 소요 시간
- 엑셀 간편장부를 웹 ERP로 옮기기 (AICassa)
- Impeccable 스킬 적용한 게시글 상세 화면 구조 개선
- CLAUDE.md로 팀 규칙을 AI에게 가르치는 법
- AI티 나는 디자인 패턴 걷어내기: overused-font 훅 오탐 처리와 접근성 대비 수정
- CI4 브랜드 에러 페이지: 설계서 한 장에서 구현까지
- Claude에 MCP로 디자인 툴 붙이기 — DesignCraft·PhotoCraft 설치부터 명함, 카툰 효과까지
- AI 실수 복구: 메인 체크아웃을 dev 상태로 되돌린 기록
- 870줄 CLAUDE.md를 116줄로 줄인 실전 리팩터링
- AI로 AI 강의안을 만들다 — 실용인문학 5·6강 준비기
- Claude Code 토큰 절감 실전: 3개월 로그 분석과 5단계 전략
- 개발 기록을 재료로 AI가 쓰는 블로그 글 만들기
- Claude Vision으로 영수증·세금계산서 자동 장부 입력 구현
- AI가 만든 실제 실수 4가지 패턴과 교훈
- GitHub 이슈·PR 기반의 월간 작업일지 자동 생성 Claude 스킬 만들기
- Fable 5.2로 스킬 5개 토큰 45% 절감하기
- 12개 SaaS가 함께 쓰는 LangGraph 서버를 설계하며 생긴 일들
- LangGraph 서버 배포 런북, Claude Code가 헛짚은 여섯 가지
시리즈 제품 개발기 현재 위치 24 / 24
- 엑셀 간편장부를 웹 ERP로 옮기기 (AICassa)
- 혼자 쓰는 맛집 앱 Pagus 만들기
- 감으로 잡던 견적을 코드로: CNC 목공과 AILign 개발 이야기
- AIPicto: 도연님의 그림책을 위한 온라인 구독 플랫폼
- PHP 개발자, TypeScript와 R3F로 3D 가구 배치 앱 만들기
- 녹화형 AI 화상면접 솔루션 기획 노트 — AILego
- AIvance 제품 이름은 왜 라틴어일까: Cassa에서 Cella까지
- 1인 개발자가 11개 SaaS를 운영하는 비밀: 공통 골격과 MSA 분할 전략
- "난이도가 높아서 오래 걸리는 거야?" — AIFid 개발 기록으로 따져 본 소요 시간
- 개별로는 통과하는데 전체에서만 죽는다 — AIFid 테스트 스위트가 composer test를 멈춘 날들
- 1인 개발자가 클로드코드로 SaaS 11개 만든 기록
- 도면을 AI에게 읽히려다 AI를 뺀 이야기
- 팬리스 우분투로 DC 모터를 인터넷에서 제어하기
- 저장소 아키텍처를 archify로 그려 README에 링크한 날
- Apache 403 해결과 php spark 로 슈퍼관리자 자동 발급하기
- UX와 보안을 동시에 잡는 그림책 게스트 열람 방안
- 혼자 하는 유지보수, 단가와 한도를 어떻게 정할까
- SEO + GEO 동시 적용: 정적 페이지에서 AI 검색 노출까지 한 방법
- 코어를 건드리지않고 확장하는 CodeIgniter 4 플러그인 구조와 핵심 설계 포인트
- GitHub 이슈·PR 기반의 월간 작업일지 자동 생성 Claude 스킬 만들기
- 경쟁자 4곳 분석으로 도출한 aiVelo MVP 로드맵
- 3일간 75커밋으로 완성한 AI 면접 플랫폼 AISensus 개발기
- 12개 SaaS가 함께 쓰는 LangGraph 서버를 설계하며 생긴 일들
- LangGraph 서버 배포 런북, Claude Code가 헛짚은 여섯 가지
시리즈 설계·아키텍처 현재 위치 17 / 17
- 코어를 건드리지않고 확장하는 CodeIgniter 4 플러그인 구조와 핵심 설계 포인트
- 12개 SaaS가 함께 쓰는 LangGraph 서버를 설계하며 생긴 일들
- 하루 만에 구현한 9가지 블로그 운영 기능과 설계 기준
- iframe 하나로 격리하는 웹 채팅 위젯 설계
- MSA 공통 에러 규약, RFC 9457로 정하기
- 저장소 아키텍처를 archify로 그려 README에 링크한 날
- 멀티테넌트 API에서 company_id를 요청이 아니라 JWT에서 뽑는 이유 — AI 보안 리뷰로 재처리 API 뜯어보기
- 1인 개발자가 11개 SaaS를 운영하는 비밀: 공통 골격과 MSA 분할 전략
- 서비스를 쪼갤까? MSA 선택을 위한 실전 체크리스트
- 26년 차 개발자가 AI 시대에 직접 쥐는 결정 4가지: 제품 범위, 아키텍처, 가격, 보안
- OpenAPI 컴포넌트와 PHP 8 어트리뷰트로 오류 응답 일관성 확보
- CI4에서 얇은 컨트롤러와 서비스 기반 트랜잭션 관리법
- 프론트 로그를 큐로 받는 수집 파이프라인: 즉시 202 → Redis → 워커 → 파일 + DB, 실패 시 dead-letter
- Redis 캐시 TTL 설계와 N+1 방지 실전 가이드
- 직접 JWT 구현 금지! 검증된 라이브러리와 안전 설계
- 중고 OptiPlex 3060 하나로 러너와 홈페이지 서버 통합하기
- LangGraph 서버 배포 런북, Claude Code가 헛짚은 여섯 가지
요약: Aegra 기반 LangGraph 서버를 운영 서버에 올리는 런북을 Claude Code와 쓰면서, 서버 사정을 묻지 않고 문서를 믿거나 가설로 디버깅하다 같은 문서를 여러 번 고쳐 쓰게 됐다. 틀린 지점을 하나씩 짚고,
.env주석 한 글자 때문에 Langfuse 트레이싱이 안 켜진 사건의 진단 과정을 정리했다. 결론은 "AI에게 서버 사실을 먼저 확인시키고, 서버에서 돌려 본 결과만 근거로 삼게 하라"는 것이다.
배경
AIvance 공용 LangGraph 서버(Aegra 0.11.0 기반, 이하 agera)를 운영 서버에 설치하는 작업이었다. 구성은 이렇다.
- agera 컨테이너 2대(2026·2027 포트)를 Apache 로드밸런서 뒤에 둔다.
- Langfuse를 같은 서버에 띄워 트레이싱을 받는다.
- 배포는 GitHub Actions 셀프호스티드 러너가 같은 서버에서 돈다.
- 운영 서버에는 이미 홈페이지와 다른 러너들이 돌고 있다.
Claude Code가 설치 순서를 한 번에 따라가는 런북(docs/deploy-runbook.md)을 쓰고, 나는 서버에서 명령을 실행해 결과를 붙여 주는 식으로 진행했다. 결과적으로 런북은 부분 수정을 거듭하다 전체를 폐기하고 다시 썼고, 사용량도 5시간 한도의 절반 이상이 이 한 가지에 들어갔다.

1. 저장소 문서의 경로를 서버 현실로 착각했다
처음 런북은 저장소 문서에 적힌 /srv/aigraph를 설치 경로로 썼다. 실제 서버에서는 항상 홈 디렉터리 아래에 설치해 왔는데, Claude Code는 이 경로가 맞는지 묻지 않았다. 내가 정정하자 그제야 바꿨다.
문제는 그다음이었다. 워크플로 3개, 백업 스크립트, 크론, composer.json이 모두 /srv/aigraph를 하드코딩하고 있었다. Claude Code는 처음에 심볼릭 링크 하나로 맞추려 했지만, 내가 전부 바꾸라고 해서 경로 문자열을 저장소 전체에서 바꾸는 PR이 됐다. 그 PR은 dev에 먼저 들어온 단일 서버 구성 변경과 충돌해서 rebase까지 해야 했다.
Claude Code도 나중에 이렇게 인정했다. 경로 같은 중요한 값은 문서에 적혀 있어도 먼저 물어봤어야 했다.
2. main에 없는 파일을 런북에 적었다
서버는 main을 내려받는다. 그런데 런북은 내 작업 브랜치에만 있던 infra/systemd/.../after-tailscaled.conf를 복사하라고 안내했다. 서버에는 그 파일이 없으니 실행할 수 없었다.
나는 "너만 작업디렉토리에 가지고 있는 걸 설명서에 떡하니 적어놓고 실행하라고 하니까 하는 소리잖아"라고 짚었다. 고친 방법은 단순했다. 파일을 복사하는 대신 서버에서 printf로 두 줄짜리 파일을 직접 만들게 하고, 런북이 참조하는 모든 파일이 origin/main에 있는지 하나씩 확인했다.
# 이런 식으로 런북이 참조하는 경로가 main 에 실제로 있는지 확인한다(예시)
git ls-tree -r --name-only origin/main | grep -E 'infra/(systemd|tailscale)'
런북 문서 자체도 dev에만 있어서, 서버에서 보려면 dev → main 배포 PR이 필요했다. "문서가 서버에서 보이는가"까지 확인 대상이었다.
3. 자동 보안 리뷰 경고를 판단 없이 크게 전달했다
PR을 올리자 보안 리뷰 플러그인이 경고를 냈다. 그중 두 건을 Claude Code는 HIGH로 전달했다.
- root 크론이 사용자 홈의 스크립트를 실행한다.
- 워크플로가
.env를 사용자 홈에서 읽는다.
그러고는 /etc/aigraph/ 같은 경로로 옮길지, 홈 소유권을 정리할지 나에게 물었다. 나는 화가 났다. .env는 웹 경로 밖에 있고 권한도 600이다. CI4 프로젝트에서 늘 그렇게 써 왔다. 러너 계정이 이미 docker 그룹이라 얻을 것도 없었다. 중요한 설치 경로는 묻지 않고 정하면서, 잘 돌던 구성은 자동 도구 경고 하나로 걸고 넘어진 셈이다.
Claude Code는 "그 지적은 과했다"고 물러섰고 이 건은 접었다. 다만 경고 중 하나는 실제로 유효했다. 백업 덤프가 저장소 폴더 안에 생기는데 .gitignore에 없어서 커밋될 수 있었다. 이건 /backups/를 추가해 고쳤다.
자동 리뷰 도구의 출력은 "후보"이지 "작업 목록"이 아니다. 우리 서버 사정에 비춰 걸러서 전달하게 시켜야 한다.
4. 런북이 설명하지 않고 지시만 했다
런북 2번은 서버에 .env와 langfuse.env를 만들라는 내용이었다. 나는 "그 파일을 만들고 내용을 아래 있는 걸로 복사해 넣으라는 거야? 설명이 없잖아"라고 물었다. 그랬다. 비밀 파일이라 저장소에 없다는 것, 생성값은 openssl rand -hex 24로 만든다는 것, AIGRAPH_SECRET_*는 클라이언트 .env의 aigraph.secret과 같은 값이어야 한다는 것이 문서에 없었다.
비슷한 사고가 두 번 더 있었다.
<러너계정>같은 자리표시자가 남아 있었다. 계정은 이미 정해져 있었다.- "
sudo로 만들면 root 소유 600이 돼서 못 읽는다"는 주의 문장이 헷갈렸다. 나는 이미 그 계정으로 작업 중이고docker그룹에도 넣어 둔 상태였기 때문이다.
여기서 런북을 폐기하고 처음부터 다시 쓰게 했다. 서버 사정(단일 서버, 계정, 모든 포트 127.0.0.1, 홈페이지 공존)을 처음부터 반영한 두 번째 판은 훨씬 나았다.
5. (실수 아님) 서버에서만 컨테이너가 죽었다
런북대로 올리자 agera-1, agera-2가 기동 직후 죽고 재시작을 반복했다. docker exec는 "container is restarting"만 냈다.
Claude Code는 서버에 접근할 수 없으니 추측하지 않고 진단 명령을 줬다. 로그를 받아 보니 컨테이너 안에서 실행 파일을 여는 단계(exec /app/.venv/bin/aegra)에서 operation not permitted가 났다. compose에는 cap_drop: [ALL]과 no-new-privileges가 있었다. 통합테스트 환경에서는 통과했으니, 이 서버의 Docker 설치와 보안 모듈 쪽 차이로 좁혀졌다. 아래 같은 방식으로 제한을 하나씩 켜 보는 명령도 함께 줬다.
# 이미지는 멀쩡한지, 어느 제한에서 같은 오류가 나는지 하나씩 켜 본다
docker run --rm aigraph/agera:latest aegra --help | head -3
docker run --rm --security-opt no-new-privileges:true aigraph/agera:latest aegra --help | head -3
docker run --rm --cap-drop ALL aigraph/agera:latest aegra --help | head -3
이 건은 뻘짓이라기보다 정상적인 디버깅이었다. 선택지는 두 가지였다. no-new-privileges를 compose에서 빼거나, 호스트의 원인 모듈을 찾아 고치는 것이다. 나는 앞쪽(A)을 골랐다. agera는 이미 비루트(10001)에 cap_drop: [ALL]이라 빼도 약해지는 정도가 작다고 판단했다. Langfuse compose에도 같은 옵션이 있어서 같이 뺐다.
6. 트레이싱이 안 켜진다: 가설이 연달아 틀렸다
가장 길게 끌린 건 이 건이다. Langfuse에 키를 발급받아 .env에 OTEL_TARGETS와 키 두 줄을 넣고 agera를 재기동했는데, 로그에는 계속 이 줄이 나왔다.
Observability is disabled (no targets configured).
Claude Code는 서버를 볼 수 없어서 가설을 하나씩 세웠다.
- **
restart가.env를 다시 안 읽는다.** 사실이지만 원인은 아니었다. 11:22에 새로 만든agera-2도 같은disabled를 냈다. - **컨테이너가 읽는 건
agera/.env이고 루트.env와 다른 파일이다.** 내가 받은 재기동 명령의dc에export AIGRAPH_ENV_FILE이 빠져 있었던 건 실제 실수였다. 컨테이너 환경은env_file: ${AIGRAPH_ENV_FILE:-.env}로 읽는데, 명령에는 치환용--env-file만 있었다. 하지만 확인해 보니agera/.env는../.env로 연결된 같은 파일이었다. 가설이 틀렸다.
결정적 단서는 가설이 틀린 뒤에 나왔다. 세 줄이 있어야 하는데 grep -c가 2를 냈다. 마지막으로 이름만 보이게 한 grep 결과에서 원인이 보였다.
# OTEL_TARGETS=(값은 가림)
.env를 agera/.env.example에서 복사해 만들었기 때문에, 파일 맨 아래에 세 줄이 이미 # 주석으로 들어 있었다. 나는 키 두 줄만 주석을 풀고 값을 채웠고, OTEL_TARGETS 줄은 주석인 채로 남아 있었다. 런북 6단계는 "세 줄을 추가한다"고만 적혀 있어서, 새로 붙이라는 건지 기존 줄의 #을 지우라는 건지 알 수 없었다. 나는 "니가 세줄만 복사해서 넣으라면?"이라고 항의했고, Claude Code는 문서 탓이라고 인정했다.

고치는 데 필요한 건 한 줄이었다.
# .env.example 에서 따라온 주석을 푼다
sed -i 's/^# *OTEL_TARGETS=/OTEL_TARGETS=/' .env
grep -E '^OTEL_TARGETS=' .env # OTEL_TARGETS=LANGFUSE 인지 확인 (이 줄은 비밀이 아니다)
그다음 agera-1을 --force-recreate로 만들고 healthy를 확인한 뒤 agera-2를 같은 방식으로 만들었다. agera-1 로그에 Attached target 'Langfuse'와 Observability subsystem initialized successfully.가 찍혔다. 런북은 이 흐름에 맞춰 "주석을 푼다"로 고쳤고, .env만 바꿨을 때의 한 대씩 재기동 절차(5-1절)를 새로 추가했다.
7. 서버 클론이 옛 버전이었다
서버 클론이 최신이 아니라서 생긴 혼선이 반복됐다. 서버의 main 클론은 client/** 변경이 있을 때만 git pull된다. 그래서 agera/**나 infra/**만 바뀐 배포는 러너 작업 폴더에서 빌드되고, 서버 클론은 그대로였다.
- 컨테이너가 다시
operation not permitted로 죽는다고 보고했을 때 Claude Code는 서버 클론이 옛 compose일 가능성을 의심해git pull을 시켰다. 다만 이어서 "2는 안뜬다"고 했던agera-2는 로그상/health에 200을 응답하는 정상 상태였고, 실패한 건docker exec타이밍으로 보였다. 이 건은 확정된 원인이 아니다. - Apache는 로드밸런서가
127.0.0.1이 아니라 옛 Tailscale 주소로 연결을 시도하다 타임아웃이 났다.curl은 응답 없이 멈췄고 상태 코드는000이었다. 옛graph설정 파일을sites-available에 복사해 둔 것이 원인으로 지목됐고, 서버 클론을git pull한 뒤 설정을 다시 복사하고reload하자 200이 나왔다. 런북 2단계에 "서버 폴더는client/**일 때만 자동으로 pull된다.agera/**나infra/**만 바뀐 배포 뒤에는 직접 pull하라"는 문장이 들어갔다.
마지막으로 터미널 문제가 있었다. 런북 9번의 for 문을 붙여 넣자 for> 프롬프트에서 멈춘다는 보고가 나왔다. Claude Code는 처음에 curl에 시간 제한이 없어서 멈춘 것처럼 보였다고 추정했다. 결국 해결못함. Ctrl+C로 나올 수 밖에 없었다.
부수 사건: 코드 쪽에서도 있었다
서버 배포만 문제는 아니었다.
- 단위 테스트는 통과했는데 실서버는 전부 401이었다. 테넌트 격리 통합테스트를 실제 Aegra 2대와 Postgres, Redis로 돌리자, Aegra 0.11.0이 인증 핸들러에 헤더 dict를 위치 인자로 넘긴다는 사실이 드러났다. 기존
authenticate(authorization)는 그 dict를 받아서 모든 요청을 거부하고 있었다. 단위 테스트는 헬퍼가 같은 가정으로 호출하고 있어서 잡지 못했다. - 다른 세션이 해결한 충돌에 rebase를 시도했다. CD 워크플로를 고치는 세션에서 PR 충돌 알림을 받은 Claude Code가 현황을 확인하지 않고 워크트리에서
git rebase origin/dev를 돌렸다. 충돌이 났고 바로rebase --abort로 되돌렸다. 알고 보니 PR은 이미 다른 세션이 병합 커밋으로 풀어 머지한 뒤였다.
비용: 같은 문서를 여러 번 쓰는 값
세션 후반에 나는 "런북 하나 가지고 5시간 한도의 50% 이상 잡아먹고 있네"라고 말했다. Claude Code는 원인을 셋으로 정리했다.
- 경로, 구성, 환경이 바뀔 때마다 런북 전체를 다시 읽고 다시 썼다.
- PR 여러 건과 서버 디버깅이 한 세션에 이어졌다. 턴마다 지금까지의 대화를 다시 읽으니 길수록 비싸진다.
- 긴 서버 로그가 컨텍스트에 계속 남았다.
내 반응은 "내가 중간에 런북 다시 쓰라고 했는데도 이러잖아"였다. 재작성 결정은 맞았고, 낭비의 상당 부분은 그 전에 서버 사실을 확인하지 않고 쓴 첫 판에서 나왔다.
배운 점
문서를 쓰기 전에 서버 사실을 묻고 시작하면 대부분 피할 수 있는 일이었다. 앞으로는 이렇게 한다.
- 쓰기 전에 사실 목록을 먼저 받는다. 설치 경로, 실행 계정, 이미 떠 있는 서비스(홈페이지, 다른 러너), Docker 설치 방식, 포트 점유 상황을 Claude Code가 먼저 물어보게 한다. 문서나 코드에 적힌 값은 "기본값"이지 "서버의 현재 상태"가 아니다.
- **런북이 참조하는 파일은
main에서 확인한다.** 서버가 내려받는 브랜치 기준으로 파일 존재를 검증하게 한다. 런북 문서 자체도 서버가 받는 브랜치에 들어가야 보인다. - 서버를 볼 수 없는 AI의 가설은 가설로 취급한다. 가설이 연달아 틀렸고, 답은
grep -c숫자 하나(기대 3, 실제 2)와 이름만 보이는 출력 한 줄에서 나왔다. 값을 가린 진단 명령을 주고 결과를 읽게 하는 방식이 가장 빨랐다. - 복사한 예시 파일의 주석 줄은 "추가"가 아니라 "해제"다. 런북에는 "
#을 지우고 값을 채운다"와 확인용grep -c(기대값 3)를 함께 적는다. - 자동 보안 리뷰 경고는 걸러서 전달하게 한다. 서버 사정에 맞지 않는 경고는 근거와 함께 접고, 실제로 유효한 것(백업 덤프 커밋 가능성)만 고친다.
- 세션을 끊는다. 작업이
dev에 올라가 있으면 새 세션으로 옮겨도 잃는 게 없다. 서버 출력은 오류 줄과 앞뒤 몇 줄만 붙인다.

댓글 0
아직 댓글이 없습니다. 첫 댓글을 남겨 보세요.