Claude Code 운영법: CLI, IDE, 데스크톱, 웹을 팀 개발 루틴으로 묶기

요약: Claude Code는 이제 터미널 도구 하나가 아니라 CLI, IDE, 데스크톱 앱, 웹, GitHub Actions, MCP, hooks, sub-agent까지 포함한 개발 운영 도구에 가깝습니다. 문제는 기능이 많아서 팀마다 사용 방식이 흩어지는 것입니다. 이 글은 Claude Code를 팀 루틴으로 묶는 기준을 정리합니다.

핵심 키워드: Claude Code, AI 코딩 에이전트, 개발 자동화, MCP, GitHub Actions AI 리뷰

왜 사용 표준이 필요한가

AI 코딩 도구는 개인이 쓰기 시작할 때 가장 빠르게 퍼집니다. 한 명은 터미널에서 쓰고, 다른 한 명은 VS Code 확장에서 쓰고, 또 다른 사람은 웹 세션에 장기 작업을 맡깁니다. 처음에는 생산성이 올라가는 것처럼 보입니다. 하지만 팀 기준이 없으면 곧 문제가 생깁니다. 변경 내역이 흩어지고, 어떤 명령을 실행했는지 모호하고, 리뷰어가 에이전트의 판단 근거를 확인하기 어렵습니다.

Anthropic 문서 기준으로 Claude Code는 terminal, VS Code, JetBrains, desktop app, web에서 사용할 수 있습니다. 또 GitHub Actions와 GitLab CI/CD, MCP, hooks, skills, sub-agents, scheduled routines 같은 확장 지점도 제공합니다. 이 말은 팀이 “어디에서 무엇을 하게 할지”를 정해야 한다는 뜻입니다. 모든 기능을 켜는 것이 좋은 운영은 아닙니다.

표준의 목적은 통제가 아니라 재현성입니다. 누가 작업하든 같은 종류의 task는 비슷한 방식으로 실행되고, 검증 명령이 남고, 리뷰 기준이 같아야 합니다. 그래야 AI가 만든 코드도 사람이 만든 코드처럼 운영할 수 있습니다.

서피스별 역할을 나누는 기준

터미널 CLI는 가장 강력하지만 위험도도 큽니다. 파일 편집, 명령 실행, 테스트, git 작업까지 한 번에 이어갈 수 있기 때문입니다. 따라서 CLI는 코드베이스 전체 맥락이 필요한 작업에 쓰는 것이 좋습니다. 예를 들어 “auth 모듈 테스트 추가 후 실패 수정”, “lint 오류 전체 정리”, “마이그레이션 스크립트 작성 후 dry-run” 같은 작업입니다.

IDE 확장은 작은 수정과 리뷰에 적합합니다. 개발자가 보고 있는 파일, 선택한 코드, 현재 diff를 바탕으로 빠르게 질문하고 수정할 수 있습니다. UI 컴포넌트 한 파일 수정, 타입 에러 설명, 함수 리팩터링처럼 범위가 좁은 일에 맞습니다. IDE에서 시작한 작업을 무리하게 전체 프로젝트 변경으로 키우지 않는 것이 좋습니다.

데스크톱 앱과 웹은 장기 작업과 병렬 작업에 적합합니다. 로컬 환경에 묶이지 않고 여러 세션을 나눠 돌릴 수 있기 때문입니다. 다만 장기 작업은 중간 checkpoint가 없으면 실패했을 때 복구가 어렵습니다. 따라서 작업을 30분 단위 milestone으로 나누고, 각 milestone마다 결과 파일, 테스트 결과, 남은 blocker를 쓰게 해야 합니다.

팀 CLAUDE.md를 어떻게 써야 하나

Claude Code 문서에서 CLAUDE.md는 프로젝트 루트에 두는 지침 파일입니다. 팀에서는 이 파일을 “AI에게 주는 README”가 아니라 “반복되는 판단을 줄이는 운영 규칙”으로 써야 합니다. 좋은 CLAUDE.md에는 프로젝트 구조, 빌드 명령, 테스트 명령, 브랜치 규칙, 금지 작업, 코드 스타일, 배포 주의사항이 들어갑니다.

예를 들어 Next.js 프로젝트라면 다음 항목이 필요합니다. 서버 컴포넌트에서 자기 API fetch 금지, production build로 확인, 환경변수 추가 시 문서 업데이트, DB 스키마 변경 시 migration과 rollback 같이 작성, UI 변경 시 접근성 확인. 모바일 앱이라면 simulator 실행 방식, Expo SDK 버전, native module 변경 시 빌드 절차, push notification 테스트 계정을 적어야 합니다.

중요한 것은 짧고 구체적이어야 한다는 점입니다. “좋은 코드를 작성하라”는 지침은 쓸모가 없습니다. “수정 후 npm run typecheck와 npm test를 실행하고, 실패 시 실패 로그를 PR 설명에 남긴다”가 쓸모 있습니다. 에이전트는 모호한 원칙보다 실행 가능한 체크리스트에 강합니다.

hooks와 MCP는 언제 써야 하나

hooks는 자동 검증에 적합합니다. 예를 들어 파일 수정 후 formatter 실행, commit 전 typecheck, 특정 디렉터리 변경 시 테스트 실행 같은 일을 붙일 수 있습니다. 단, hooks에 너무 무거운 명령을 넣으면 작업 속도가 급격히 느려집니다. 기본 원칙은 빠른 검증은 hook, 긴 검증은 명시적 command입니다. 5초 안에 끝나는 것은 hook 후보이고, 1분 이상 걸리는 것은 별도 task로 두는 편이 낫습니다.

MCP는 외부 도구 연결에 적합합니다. 디자인 문서, Jira, Slack, Google Drive, 사내 DB 같은 맥락을 Claude Code가 읽게 할 수 있습니다. 하지만 MCP는 권한 위험도 함께 가져옵니다. 읽기 전용부터 시작하고, 쓰기 권한은 사용 사례가 검증된 뒤에 열어야 합니다. 특히 이슈 상태 변경, 메시지 전송, 배포 트리거 같은 외부 write는 사람 승인 흐름을 두는 것이 안전합니다.

팀에 처음 도입한다면 hooks보다 CLAUDE.md가 먼저입니다. 그 다음 반복되는 검증을 hooks로 옮기고, 마지막에 MCP를 붙이세요. 많은 팀이 반대로 합니다. 도구 연결부터 늘리면 에이전트가 똑똑해진 것처럼 보이지만, 기준이 없으면 더 빠르게 잘못된 작업을 합니다.

GitHub Actions와 코드 리뷰 자동화

Claude Code는 CI와 연결해 코드 리뷰나 이슈 triage에 쓸 수 있습니다. 실무에서는 자동 리뷰를 “최종 판단자”로 두면 안 됩니다. 대신 사람이 놓치기 쉬운 반복 항목을 맡기는 것이 좋습니다. 예를 들어 누락된 테스트, 위험한 환경변수 사용, breaking change 가능성, 문서 업데이트 누락, 보안 키 노출 후보를 점검하게 할 수 있습니다.

좋은 자동 리뷰 코멘트는 짧고 재현 가능해야 합니다. “이 코드는 개선이 필요합니다”는 나쁜 코멘트입니다. “app/community/[id]/page.tsx에서 headers()를 사용하므로 generateStaticParams와 함께 쓰면 static/dynamic 충돌 가능성이 있습니다. production build로 확인하세요”는 좋은 코멘트입니다. 파일, 근거, 확인 방법이 있어야 합니다.

또 자동 리뷰는 noise budget을 관리해야 합니다. 에이전트가 PR마다 20개 코멘트를 달면 팀은 곧 무시합니다. 처음에는 critical issue만 코멘트하게 하고, style suggestion은 별도 summary에 묶는 편이 낫습니다. 리뷰 자동화의 목표는 사람 리뷰를 대체하는 것이 아니라, 사람이 중요한 설계 판단에 시간을 쓰게 만드는 것입니다.

작은 팀용 운영 루틴

작은 팀은 복잡한 플랫폼보다 단순한 루틴이 이깁니다. 추천 구조는 이렇습니다. 첫째, 모든 프로젝트 루트에 CLAUDE.md를 둡니다. 둘째, task template을 만듭니다. 목표, 범위, 금지 작업, 검증 명령, 완료 산출물을 적습니다. 셋째, 장기 작업은 별도 브랜치와 세션 이름을 붙입니다. 넷째, PR 설명에 “AI가 수행한 작업, 실행한 명령, 실패한 명령, 사람이 확인해야 할 부분”을 남깁니다.

다섯째, 주 1회 실패 사례를 정리합니다. 에이전트가 잘못 수정한 이유가 지침 부족인지, 테스트 부족인지, task 범위 과다인지 구분합니다. 지침 부족이면 CLAUDE.md를 고치고, 테스트 부족이면 테스트를 추가하고, 범위 과다면 task를 쪼갭니다. 이 회고가 없으면 같은 실수가 반복됩니다.

도입 초기에는 에이전트가 만든 코드를 merge하는 속도보다, 팀이 검증 루틴을 몸에 익히는 속도가 중요합니다. 빠른 merge보다 안전한 반복이 먼저입니다.

실행 체크리스트

• 프로젝트 루트에 최신 CLAUDE.md가 있는가?
• 빌드, 테스트, 타입체크, lint 명령이 문서에 적혀 있는가?
• CLI, IDE, 웹/데스크톱의 사용 목적을 팀에서 합의했는가?
• 장기 작업은 milestone과 checkpoint를 남기게 했는가?
• hooks에는 5초 내외의 빠른 검증만 넣었는가?
• MCP 연결은 읽기 전용부터 시작했는가?
• 외부 write 작업은 사람 승인 뒤에만 실행되는가?
• PR 설명에 AI 작업 로그와 검증 결과를 남기는가?
• 자동 리뷰 코멘트의 noise를 제한하는가?
• 실패 사례를 CLAUDE.md나 팀 문서에 반영하는가?

출처는 Anthropic의 Claude Code 공식 문서입니다. 결론은 간단합니다. Claude Code를 잘 쓰는 팀은 “어떤 모델이 더 똑똑한가”보다 “어떤 작업을 어떤 표면에서, 어떤 검증으로 끝낼 것인가”를 먼저 정합니다. 사용 표준이 있으면 AI 코딩은 개인 생산성 도구를 넘어 팀 운영 시스템이 됩니다.