Claude Code로 사이드 프로젝트 자동화하기: 실전에서 겪은 기능 정리 (2026)

블로그(duckpipe)를 Claude Code로 운영하면서 실제로 부딪힌 기능과 패턴을 정리한다. “설치 방법”, “기본 명령어” 같은 소개는 공식 문서가 더 정확하니 생략하고, 사이드 프로젝트를 굴리면서 실제로 도움이 됐던 지점과 조심해야 했던 지점 위주로 쓴다.

1. 권한 모드 — 뭘 자동으로 하고 뭘 물어보게 할지

Claude Code는 작업 성격에 따라 확인을 받을지, 바로 진행할지를 나눌 수 있다. 실제로 운영하면서 자리 잡은 원칙은 이거였다.

• 되돌리기 쉬운 작업(로컬 파일 수정, 로컬 서버 미리보기)은 바로 진행.
• 되돌리기 어렵거나 남에게 보이는 작업(git push, 실제 계정 가입, 결제 정보 입력)은 매번 확인.

예를 들어 AWS 프리 티어 가입 가이드를 쓸 때, 처음엔 “네가 직접 화면 캡처해서 글 써줘”라고 요청했는데 — 실제 계정 생성이나 카드 정보 입력은 도구가 원천적으로 못 하게 막혀 있었다. 결국 계정 가입은 직접 진행하고 단계별 화면만 공유하는 식으로 나눠서 진행했다. 처음엔 번거롭다고 느꼈지만, 결제·개인정보가 얽힌 작업에 확인 절차가 없는 게 오히려 더 큰 리스크라는 걸 감안하면 납득이 가는 구조였다.

2. 백그라운드 작업 — 배포 기다리는 동안 다른 일

Cloudflare Pages 배포는 푸시 후 반영까지 보통 수십 초 걸린다. 이걸 매번 눈으로 지켜보는 대신, 배포 확인을 백그라운드로 넘기고 완료되면 알림받는 식으로 운영했다.

$ git push
# → 백그라운드로 넘어가 배포 완료될 때까지 주기적으로 확인
# → 그 사이 다음 글 작업 진행
# → 배포 확인되면 알림, 그때 라이브 링크 재확인

체감상 가장 크게 시간을 아낀 부분이다. “기다리는 시간”이 “다른 작업하는 시간”으로 바뀐다.

3. 브라우저 자동화로 “만들었다” 말고 “확인했다”

코드를 수정하고 끝내는 게 아니라, 실제 화면을 열어서 라이트·다크 모드, 모바일 반응형, 콘솔 에러 유무까지 확인하는 걸 습관으로 붙였다. 예를 들어 본문 헤딩 디자인을 바꿨을 때 데스크톱·모바일·다크모드 스크린샷을 각각 찍어서 비교했고, 목차(TOC) 기능을 넣었을 때도 좁은 화면에서 목차가 실제로 숨겨지는지, 스크롤할 때 현재 섹션이 정확히 하나만 강조되는지 직접 클릭·스크롤해보고 확인했다.

이 과정에서 배운 것: “코드가 문법적으로 맞다”와 “실제로 의도대로 동작한다”는 다른 문제다. 뒤에서 다룰 디버깅 사례가 정확히 이 지점에서 걸렸다.

4. MCP로 외부 API 연동 — 쿠팡 파트너스 자동화

MCP(Model Context Protocol)는 Claude Code가 외부 도구·서비스와 연결되는 방식이다. 이번 프로젝트에서는 쿠팡 파트너스 Open API를 붙여서 상품 검색과 제휴 링크(딥링크) 생성을 자동화하는 스크립트를 만들었다 — 매번 쿠팡 파트너스 사이트에 들어가서 링크를 수동으로 만드는 대신, 스크립트 한 번 실행으로 처리하는 식이다.

여기서 중요했던 건 API 키를 다루는 방식이었다. 발급받은 액세스 키·시크릿 키를 채팅창에 그대로 붙여넣으려는 시도가 있었는데, 이건 거절당했다 — 대신 .env 파일에 직접 입력하고, 스크립트는 그 값이 존재하는지만 확인하는 식으로 진행했다. 키 값 자체는 한 번도 대화에 노출되지 않았다.

5. 진짜 디버깅 사례: “고쳤다”와 “진짜 고쳐졌다”는 다르다

가장 인상 깊었던 사례를 그대로 옮긴다. 글을 발행하면 카카오톡·슬랙 등에 링크를 공유할 때 뜨는 미리보기 썸네일(OG 이미지)을 자동 생성하는 스크립트가 있는데, 어느 날 실제로 링크를 공유해보니 이렇게 나왔다.

한글이 전부 □D5B9□04AC 같은 깨진 박스로 나오고 있었다. 원인은 이랬다 — 이 이미지는 배포 서버(빌드 컨테이너) 안에서 실시간으로 생성되는데, 그 서버엔 한글 폰트가 설치돼 있지 않았다.

1차 수정은 폰트 파일을 이미지 생성 코드 안에 직접 심어 넣는 방식이었다. 로컬에서 만들어보니 정상적으로 나왔고, 배포하고 나서 파일 크기가 바뀐 것까지 확인하고 “고쳐졌다”고 판단했다. 그런데 실제로 배포된 링크를 다시 열어보니 — 여전히 깨져 있었다. 로컬 환경과 배포 서버 환경(운영체제, 렌더링 엔진 구성)이 달라서, 로컬에서 통했던 방식이 배포 서버에서는 그대로 무시됐던 것이다.

여기서 배운 것: 파일 크기가 바뀌었다고 해서 “제대로 바뀌었다”는 보장은 안 된다. 실제로 배포된 결과물을 다시 열어서 확인해야 한다.

재조사 끝에 대안(텍스트를 이미지가 아니라 벡터 도형으로 미리 변환하는 방식)을 시도했는데, 이번엔 그 변환 라이브러리 자체에 버그가 있어서 특정 글자 하나에서 좌표 계산이 깨지고, 그 뒤 텍스트가 통째로 잘려나가는 문제를 발견했다. 결국 폰트를 직접 그려주는 별도 렌더링 엔진으로 통째로 교체하고 나서야 실제로 해결됐다.

이 사례가 보여주는 건, Claude Code가 “수정했습니다”라고 말하는 것과 실제로 문제가 해결된 것 사이엔 검증이라는 단계가 반드시 있어야 한다는 점이다. 자동화가 작업 속도를 크게 올려주는 건 맞지만, “진짜로 됐는지”를 확인하라고 요구하는 몫은 여전히 사람에게 있다.

정리

기능	실전에서 도움된 점	주의할 점
권한 모드	반복 작업은 빠르게, 위험한 작업은 안전하게	계정 생성·결제처럼 원천 차단되는 영역이 있음(의도된 제약)
백그라운드 작업	배포 기다리는 시간을 다른 작업 시간으로 전환	완료 알림을 실제 확인 없이 “성공”으로 넘겨짚지 않기
브라우저 자동 검증	라이트/다크·반응형 등 실제 화면 기준으로 확인 가능	검증 범위를 도구에 맡기지 말고 무엇을 확인할지 직접 지정
MCP 외부 연동	API 자동화로 반복 수작업 제거	키·시크릿은 채팅에 노출하지 말고 .env로 분리
디버깅	근본 원인까지 파고드는 데 시간 단축	”수정 완료” 보고를 배포 후 재확인 전까진 확정하지 않기