Claude Code 환경 구축 & 워크플로우

어떤 프로젝트인가

Claude Code를 도구로 한 번 써보는 것과, 매일 기대고 일하는 환경으로 만드는 것 사이에는 꽤 큰 간격이 있습니다. 이 프로젝트는 그 간격을 메우는 작업입니다. Mac에서의 안정적인 설치 가이드부터, 프로젝트별 에이전트 라우팅, 멀티에이전트 검증 워크플로까지 운영 노하우를 체계화했습니다.

이 사이트의 블로그에 가이드 문서로도 정리되어 있습니다.

초보자용 설치 가이드

처음 설치할 때 가장 많이 막히는 지점은 코드가 아니라 환경 변수입니다. 셸 설정 파일(~/.zprofile)에 어떤 값이 왜 들어가는지, 잘못 들어갔을 때 어떤 증상이 나는지 트러블슈팅 시나리오별로 문서화했습니다. 터미널 명령어를 복사해 붙일 때의 보안 주의점도 함께 다뤘습니다.

CLAUDE.md와 커스텀 스킬

프로젝트마다 CLAUDE.md에 규칙을 박고, 작업 유형별 커스텀 스킬로 에이전트를 라우팅합니다. 이 사이트의 경우 블로그 작성, 기능 개발, 코드 리뷰, 배포 등 18개 스킬 파일이 각자의 체크리스트를 들고 있어서, "블로그 글 써줘"와 "보안 뉴스 써줘"가 서로 다른 규칙으로 동작합니다.

글쓰기 톤 가이드도 스킬로 분리했습니다. AI 특유의 과장 어휘와 상투적 전환구를 금지어로 박아두면, 생성되는 글의 톤이 일관되게 유지됩니다.

작성과 검증의 분리

가장 효과가 컸던 패턴은 멀티에이전트 워크플로입니다. 구현하는 에이전트와 검증하는 에이전트를 분리하고, 같은 컨텍스트에서 자기 작업을 자기가 승인하지 못하게 했습니다. 계획 단계에서는 계획을 반박하는 비평 패스를 따로 돌립니다. 이 구조로 "그럴듯하지만 틀린" 결과물이 코드가 되기 전에 걸러지는 비율이 눈에 띄게 올라갔습니다.

훅 기반 가드레일도 운영 중입니다. dev 서버가 켜진 상태의 빌드 차단, 시크릿 패턴 차단처럼, 사람이 매번 기억하기 어려운 규칙을 도구 실행 전 단계에서 기계적으로 막습니다.

배운 점

AI 코딩 도구의 생산성은 모델 성능보다 환경 설계에서 갈렸습니다. 같은 모델이라도 규칙과 검증 구조가 있는 프로젝트에서는 결과물이 안정적이었고, 없는 프로젝트에서는 매번 품질이 출렁였습니다. 도구를 잘 쓰는 법의 절반은 도구가 실수하기 어려운 환경을 만드는 일이었습니다.