Claude Code를 내 개발 파이프라인에 통합하기

들어가며

ChatGPT를 처음 썼을 땐 "물어보는 도구"였다. 답은 잘 해줬지만 내 파일시스템을 건드리거나 내 git에 커밋하진 못했다.

지금 쓰는 Claude Code는 다르다. /deploy v19.48 한 줄로 AWS Lightsail에 배포하고, 텔레그램에서 /dev "히트맵에 필터 추가해"라고 치면 서버가 알아서 코드를 고치고 푸시한다. 어시스턴트가 아니라 실행 레이어다.

이 글은 13개 프로젝트를 혼자 굴리면서 Claude를 어떻게 파이프라인에 통합했는지 — CLAUDE.md, 메모리, 스킬, 원격 에이전트 — 그 구조를 정리한 메모다.

전체 구조: 4겹의 컨텍스트 레이어

Claude Code는 단독으로 똑똑한 게 아니라 네 겹의 컨텍스트 위에서 움직인다.

1. CLAUDE.md — 프로젝트 DNA. 구조·기술스택·금지사항·운영 규칙.
2. Memory — 나와 내 작업 스타일에 대한 장기 기억. 대화 중 자동 주입.
3. Skills — 나만의 슬래시 커맨드 25개. /deploy, /engine-status 등.
4. Hooks — 특정 이벤트 시 자동 실행. settings.json으로 구성.

1. CLAUDE.md — 프로젝트 DNA

CLAUDE.md는 "새 동료에게 주는 온보딩 문서"다. 다만 읽는 게 사람이 아니라 LLM이고, 새 세션마다 Claude가 가장 먼저 읽는다.

Charlie 프로젝트의 CLAUDE.md는 632줄. 길다 싶지만, 운영해보면 짧게 쓴 CLAUDE.md가 가장 큰 낭비다. Claude가 바깥 맥락을 모르는 순간 엉뚱한 코드가 나오고, 수정에 또 시간이 든다.

핵심은 "금지 사항" 섹션이다. 단순 설명이 아니라 "이건 하지 마라"를 명시적으로 박아둔다 — 이벤트 루프 충돌을 부르는 패턴 같은 것. 내가 겪은 버그의 anti-pattern을 규칙으로 굳힌, 검증된 가드레일 모음이다.

원칙 셋: ① 구체적으로 써라("비동기 조심"은 X) ② 한 번 고친 버그는 규칙화 ③ 자주 바뀌는 정보는 빼라.

2. Memory — 장기 기억

CLAUDE.md가 프로젝트 기억이라면, Memory는 나라는 사람에 대한 기억이다. 그리고 대화 중 자동으로 읽고 쓴다.

MEMORY.md가 인덱스이고 각 메모리는 개별 파일. 세션마다 인덱스만 로드하고 필요할 때 개별 파일을 읽어 토큰을 아낀다. 타입은 넷 — user(나), project(프로젝트 요약), feedback(내가 준 피드백), reference(API 키·문서 위치).

효과가 가장 확실한 건 feedback이다.

1Rule: 위험한 명령도 허락 없이 바로 실행.
2Why:  allow:["*"] 설정 상태, 확인 프롬프트로 흐름 끊기는 걸 싫어함.
3How:  파괴적 작업도 맥락상 명확하면 바로 실행.

이 메모리 하나면 매번 "그냥 해"라고 말 안 해도 알아서 움직인다. 한 번의 피드백이 영구 반영되는 것.

저장하면 안 되는 것도 있다 — 코드·경로(ls·grep으로 충분), git 히스토리(git log가 정답), 디버깅 해결책(커밋 메시지에 있음), 오늘 한 일(그건 일기다). 메모리엔 "문서로 봐도 판단이 안 되는 것"만 넣는다.

3. Skills — 나만의 슬래시 커맨드

스킬은 자주 하는 작업을 한 줄로 만든 커맨드다. ~/.claude/skills/에 25개, 세 분류로 나뉜다.

운영 스킬 — Charlie는 24시간 도는 실전이라 운영을 슬래시화했다.

/deploy의 내용은 대단한 마법이 아니라 그냥 내가 매번 하던 순서를 문서화한 것이다. 핵심은 /deploy v19.48 한 줄로 실행까지 된다는 것 — 기억할 필요도, 실수할 구석도 줄어든다.

안전장치 스킬 — 가장 중요한 건 /trading-param-change. 매매 파라미터 변경은 무조건 시뮬레이션 먼저라는 gate다. 실제로 Charlie 운영 중 파라미터 변경 9건 중 7건이 백테스트에서 기각됐다. 감으로 좋아 보이는 변경의 77%가 엔진을 나쁘게 만들었다는 뜻. 이 스킬은 내가 "급하니 시뮬 스킵해"라고 해도 거부한다. 나 자신으로부터 나를 보호하는 장치다.

메타 스킬 — /workthrough-v2(작업 후 자동 요약), /systematic-debugging 등 생태계에서 가져온 방법론 스킬. 작업을 끝낼 때마다 요약이 쌓여 프로젝트 타임라인이 저절로 생긴다.

4. Dev Agent — 텔레그램으로 서버에서 Claude 돌리기

Charlie 엔진은 AWS Lightsail에서 돈다. SSH로 들어가 고치는 건 번거로워서, 텔레그램에서 /dev "요청" 치면 서버의 Claude Code가 코드를 고치고 푸시까지 하는 Dev Agent를 만들었다.

구조가 좀 복잡한 건 엔진이 Docker 컨테이너 안에 있어 Claude CLI를 직접 못 부르기 때문이다. docker socket 마운트는 서버 전체 권한 노출이라 위험해서, Redis pub/sub으로 요청을 호스트의 dev_agent에 위임한다.

원격에서 AI가 코드를 푸시한다는 건 위험한 일이라 안전장치 5개를 박았다.

1. pytest 통과해야만 push — 실패 시 커밋·푸시 차단
2. 동시 1세션 제한 — Redis mutex
3. 600초 타임아웃 + 50턴 제한 — 무한 루프 방지
4. chat_id 인가 체크 — 내 개인 챗 외 메시지는 전부 무시
5. 메시지 3500자 truncation — 응답 폭주 방지

덕분에 산책 나가서도 텔레그램으로 버그 수정을 지시한다. 한 번 써보니 없으면 안 될 정도.

5. 경계 — AI가 해서는 안 되는 영역

여기까지 보면 "다 AI한테 맡기면 되겠네" 싶지만 아니다. 이 구조를 짜면서 가장 고민한 건 어디까지 맡기고 어디부터 사람이 하느냐였다.

가장 조심할 건 AI가 그럴듯하게 틀리는 영역이다. Claude는 퀀트 논문을 많이 봐서 파라미터 제안을 그럴싸하게 한다. 문제는 그 제안의 상당수가 실제 백테스트에서 성과를 악화시킨다는 것. 예를 들어 "sell_prob 높으면 더 빨리 익절" 같은 직관적 제안은, sell_prob이 buy_prob의 단순 역수라 새 정보가 0이었다. Claude가 특별히 잘 틀리는 게 아니라 — 내 직관도 틀린다. 그래서 gate가 필요하다.

"AI가 코딩 다 해줄 거다"는 맞으면서 틀리다. 반복 작업·CRUD·보일러플레이트·리팩토링은 맡겨도 된다. 하지만 제품 방향성·데이터 해석·시각 감각·돈이 걸린 파라미터·진정성 있는 글쓰기는 내 판단이 최종권한이다. "AI 맡김 ≠ AI 방임" — 경계 설정이 곧 AI 네이티브 개발자의 핵심 스킬이다.

한 줄 요약: 롤백 비용이 낮으면 맡기고, 높으면 확인.

6. 비용 & 보안 — 솔직하게

비용은 월 $100 내외다(프로젝트 13개 동시 운영, opus 기본 + sonnet 폴백 + prompt caching). 단, subagent나 /ultrareview 같은 병렬 스킬은 한 번에 10~20달러씩 녹으니 남발은 금물.

보안은 솔직히 공격적이다. allow:["*"] + 위험 명령 프롬프트 스킵 + Dev Agent 원격 push 권한 — 이 셋이 합쳐지면 "맥북 셸이 뚫리면 git 저장소까지 조작 가능"이라는 시나리오가 성립한다. 내가 이 trade-off를 받아들인 이유는 ① 1인 개발이라 피해 반경이 나로 한정 ② 매번 확인 프롬프트가 흐름을 깨는 손실이 더 컸음. 단, 누구에게나 맞는 설정은 아니다. 팀 저장소·클라이언트 코드·프로덕션 크레덴셜을 다루면 confirmation prompt를 켜야 한다.

마치며

Claude를 쓰며 배운 가장 큰 교훈은 **"AI를 똑똑하게 만드는 건 AI가 아니라 나"**라는 것이다. CLAUDE.md를 어떻게 설계할지, 메모리에 뭘 남길지, 어디에 gate를 박을지 — 이 결정이 쌓여 파이프라인 성능을 좌우한다. Claude 자체는 알아서 더 똑똑해지지만, 그 똑똑함을 내 프로젝트에 맞게 쓰도록 context engineering 하는 건 여전히 내 몫이다.