Claude Code는 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하고, 개발 도구와 연동하는 agentic coding tool입니다. 공식 문서는 Terminal CLI, VS Code, Desktop app, Web, JetBrains 환경을 지원한다고 설명합니다. 개발팀 입장에서는 “좋은 코딩 챗봇”이 아니라, 권한과 워크플로우를 설계해야 하는 개발 자동화 도구로 봐야 합니다.
이 글은 Claude Code 도입, MCP, hooks, sub-agents, coding agent 운영을 검색하는 팀을 위한 실무 체크리스트입니다. 이미 개인 개발자가 쓰는 단계라면 다음 고민은 팀 표준화입니다. 어떤 명령을 허용할지, 어떤 문서를 읽게 할지, 어떤 작업은 승인 없이 못 하게 할지 정해야 합니다.
Claude Code는 터미널에서 claude로 시작할 수 있고, VS Code나 JetBrains에서도 쓸 수 있습니다. 설치 자체는 어렵지 않습니다. 하지만 팀 도입의 핵심은 실행 경계입니다. 에이전트가 파일을 수정하고 명령을 실행할 수 있기 때문에, 어떤 repository에서 어떤 권한으로 동작하는지 먼저 정해야 합니다.
개인 실험에서는 “알아서 고쳐줘”가 편합니다. 팀 환경에서는 위험합니다. production config, migration script, secret 파일, 배포 명령은 별도 승인 대상이어야 합니다. 반대로 테스트 생성, lint 수정, 문서 업데이트, 타입 오류 수정 같은 작업은 자동화 효과가 큽니다.
처음 도입할 때는 write 권한을 모든 repo에 열지 말고, 내부 도구나 테스트 repo에서 시작하는 편이 안전합니다. 성공 사례와 실패 사례를 모은 뒤 핵심 제품 repo로 넓히는 순서가 좋습니다.
Claude Code 문서에서 중요한 기능 중 하나는 CLAUDE.md입니다. 프로젝트 루트에 두는 markdown 파일로, 세션 시작 시 코딩 표준, 아키텍처 결정, 선호 라이브러리, 리뷰 체크리스트를 전달할 수 있습니다.
이 파일은 길게 쓰는 것보다 정확하게 쓰는 것이 중요합니다. 예를 들어 “좋은 코드를 작성해라”는 도움이 되지 않습니다. 대신 “API route에서는 직접 DB client를 만들지 말고 lib/db.ts의 factory를 사용한다”, “React component는 server component를 기본값으로 하고 client directive는 필요한 경우에만 쓴다”처럼 판단 기준을 적어야 합니다.
팀 표준은 자주 바뀝니다. 그래서 CLAUDE.md도 living document로 관리해야 합니다. PR 리뷰에서 반복되는 지적이 있다면 문서에 반영하세요. 에이전트가 같은 실수를 반복한다면 prompt를 더 세게 쓰는 것보다 작업 계약을 더 구체화하는 편이 낫습니다.
Claude Code는 Model Context Protocol(MCP)을 통해 외부 데이터 소스와 연결할 수 있습니다. Google Drive, Jira, Slack, 사내 도구처럼 개발자가 매일 보는 맥락을 에이전트가 읽을 수 있게 됩니다. 잘 쓰면 엄청난 생산성 향상이지만, 잘못 열면 데이터 노출 위험이 큽니다.
MCP 도입의 기본 원칙은 최소 권한입니다. 모든 문서를 읽게 하지 말고, 특정 프로젝트 폴더나 특정 ticket scope부터 시작합니다. write action은 더 조심해야 합니다. Jira ticket 업데이트, Slack 전송, 배포 트리거 같은 외부 변경은 human approval을 기본값으로 두는 편이 안전합니다.
또한 MCP server별 로그를 남겨야 합니다. 누가, 어떤 세션에서, 어떤 리소스를 읽었는지 확인할 수 있어야 합니다. AI 도구가 사람 대신 접근했더라도 감사 관점에서는 동일하게 취급해야 합니다.
Claude Code의 hooks는 에이전트 action 전후에 shell command를 실행할 수 있는 기능입니다. 예를 들어 파일 수정 후 formatter를 돌리거나, commit 전 lint를 실행하거나, 특정 파일 변경 시 경고를 띄울 수 있습니다.
좋은 hook은 개발자를 귀찮게 하지 않고 품질을 지킵니다. 예를 들어 TypeScript 프로젝트에서는 수정 후 npm run typecheck를 돌리고 실패하면 에이전트가 즉시 고치도록 할 수 있습니다. Python 프로젝트에서는 ruff와 unit test를 기본 gate로 둘 수 있습니다.
하지만 hook도 과하면 느려집니다. 모든 수정마다 전체 e2e test를 돌리면 에이전트 작업 속도가 크게 떨어집니다. 변경 범위에 맞춰 lightweight gate와 heavy gate를 나누는 것이 좋습니다. 작은 수정에는 formatter와 typecheck, 큰 변경에는 full test와 build를 붙이는 식입니다.
Claude Code는 여러 agent를 병렬로 실행하거나, background agents로 긴 작업을 맡길 수 있습니다. 이 기능은 대형 refactor, 테스트 보강, 문서 정리처럼 분리 가능한 작업에 유용합니다.
문제는 merge입니다. 여러 agent가 같은 파일을 동시에 고치면 충돌이 생깁니다. 따라서 병렬 작업을 시킬 때는 파일 범위와 책임을 명확히 나눠야 합니다. 예를 들어 한 agent는 API layer, 다른 agent는 UI component, 다른 agent는 test만 맡도록 분리합니다.
또한 lead agent나 사람이 최종 통합 책임을 가져야 합니다. 병렬 에이전트의 결과를 그대로 합치는 것은 위험합니다. 각 sub-agent 결과는 diff, test result, 남은 이슈를 포함해야 하고, 마지막에 하나의 통합 검토를 거쳐야 합니다.
AI 코딩 도구 도입은 감으로 평가하기 쉽습니다. “빠른 것 같다”, “편한 것 같다”는 충분하지 않습니다. 최소한 다음 지표를 보는 것이 좋습니다.
이 지표가 있어야 도입 범위를 넓힐지, 특정 작업만 유지할지 판단할 수 있습니다. 생산성 도구는 느낌이 아니라 병목 제거로 증명해야 합니다.
Claude Code는 개인 생산성 도구로도 좋지만, 팀에 들어오는 순간 운영 시스템이 됩니다. CLI 설치보다 중요한 것은 권한, 문서, 연결, hook, 평가 기준입니다.
실행 체크리스트는 다음과 같습니다.
CLAUDE.md에 아키텍처 규칙과 금지 패턴을 구체적으로 씁니다.참고 자료는 Claude Code 공식 overview 문서입니다. 핵심 키워드는 Claude Code, MCP, CLAUDE.md, hooks, sub-agents, agentic coding tool입니다.