Claude Code 그렇게 쓰는 거 아닌데 2026 – 실전 개발자가 먼저 잡아야 할 운영 체크리스트

Posted on by

나도 이런 도구를 보면 처음엔 프롬프트부터 만지고 싶어진다. “이렇게 말하면 더 잘하나?”, “이 문장 넣으면 고수처럼 되나?” 같은 쪽으로 손이 먼저 간다. 그런데 Claude Code 같은 에이전트형 코딩 도구는 프롬프트 한 줄보다 운영판을 먼저 깔아야 한다. 프롬프트는 말이고, 운영판은 일하는 방식이다.

이번 글감의 출발점은 Threads 요약 노트였다. 원문은 웹에서 직접 재확인되지 않았기 때문에, SNS 문장은 사실 근거가 아니라 문제 제기 씨앗으로만 쓴다. 실제 판단은 Anthropic의 Claude Code 공식 문서와 이 볼트의 .claude/agents, .claude/skills, .claude/rules처럼 이미 굴러가는 운영 구조를 기준으로 정리했다. 핵심은 간단하다. Claude Code를 “똑똑한 챗봇”처럼 쓰면 아깝고, “검증 가능한 개발 루프”로 쓰면 훨씬 세다.

빠른 판단: Claude Code를 잘 쓰는 첫 단계는 좋은 프롬프트를 모으는 게 아니라, Claude가 스스로 확인할 테스트·빌드·스크린샷·권한 경계를 먼저 주는 것이다. 이 네 가지가 없으면 도구는 빨라지지만, 검수 부담은 사람에게 그대로 남는다.

왜 프롬프트보다 운영 체크리스트가 먼저인가

Anthropic의 Claude Code best practices 문서는 Claude Code를 일반 챗봇이 아니라 파일을 읽고, 명령을 실행하고, 변경을 만들 수 있는 agentic coding environment로 설명한다. 이 문장 하나만 봐도 사용법이 달라져야 한다. 답변을 잘 받는 문제가 아니라, 변경을 맡길 수 있는 작업 환경을 만드는 문제가 된다.

공식 문서가 가장 강하게 강조하는 부분도 검증이다. Claude가 실행할 수 있는 테스트, 빌드, 린트, 스크린샷 비교 같은 확인 신호를 주면 스스로 결과를 읽고 반복할 수 있다. 반대로 확인할 방법이 없으면 Claude는 “겉보기엔 끝난 것 같다”에서 멈춘다. 그러면 사람은 다시 리뷰어, QA, 릴리즈 매니저를 혼자 다 해야 한다. 도구 샀는데 업무가 다시 내 무릎에 앉는 기분이다.

그래서 Claude Code를 처음 세팅할 때는 “어떤 모델이 제일 좋나”보다 “이 저장소에서 통과해야 할 신호가 무엇인가”를 먼저 써야 한다. 예를 들어 백엔드라면 pytest와 API 계약 테스트, 프론트엔드라면 빌드와 스크린샷, 문서 작업이라면 링크 검사와 금지 표현 검사 같은 식이다. 이 신호가 있어야 Claude가 작업 후 스스로 재시도할 수 있다.

1번 체크: 검증 명령을 먼저 준다

첫 번째 운영 체크는 검증 명령이다. Claude Code에게 “이 버그 고쳐줘”라고 말하기 전에, 고친 뒤 무엇을 실행해야 하는지 알려줘야 한다. 테스트 명령, 빌드 명령, 린트 명령, 로컬 서버 확인 방식이 정리되어 있지 않으면 Claude는 코드 변경을 만들 수는 있어도, 성공 여부를 안정적으로 닫기 어렵다.

실전에서는 CLAUDE.md나 프로젝트 규칙 문서에 검증 명령을 적어두는 편이 좋다. Anthropic의 memory 문서도 프로젝트 CLAUDE.md에는 빌드 명령, 테스트 지침, 프로젝트 관례, 공통 워크플로 같은 팀 단위 기준을 넣으라고 설명한다. 매번 채팅창에 “테스트는 이거야”라고 다시 쓰는 것은 사람에게도 낭비고, 에이전트에게도 불안정한 입력이다.

검증 명령은 길 필요가 없다. 오히려 짧고 확실해야 한다. “프론트 변경 후 npm run build와 핵심 화면 스크린샷 확인”, “API 변경 후 pytest tests/api 실행”, “블로그 글 작성 후 preflight 스크립트 실행”처럼 작업 종류별로 1~2개면 충분하다. 검증이 너무 많으면 Claude가 아무것도 못 끝내고 검사장 안에서 길을 잃는다.

작업 유형 먼저 줄 검증 신호 사람 검수 포인트
버그 수정 재현 테스트, 관련 단위 테스트 원인 설명이 코드와 맞는지
프론트 수정 빌드, 스크린샷, 콘솔 에러 레이아웃 깨짐과 접근성
문서/블로그 금지 표현 검사, 링크 검사 독자 행동이 닫히는지
리팩터링 기존 테스트 전체 또는 핵심 스모크 변경 범위가 과하지 않은지

2번 체크: 컨텍스트를 아낀다

Claude Code best practices 문서는 컨텍스트 창이 빨리 차고, 컨텍스트가 차면 성능이 떨어질 수 있다고 설명한다. 이건 그냥 토큰 비용 문제가 아니다. 긴 대화 안에서 파일 읽기, 명령 출력, 디버깅 로그가 계속 쌓이면 앞에서 정한 목표와 제약이 희미해질 수 있다. 사람도 회의 3시간 넘어가면 처음 안건이 뭐였는지 흐려진다. AI라고 회의 체력이 무한한 건 아니다.

운영 기준은 단순하다. 탐색은 짧게, 작업은 좁게, 로그는 필요한 만큼만 준다. Claude에게 전체 코드를 무작정 읽히기보다 “이 버그는 결제 콜백과 주문 상태 변경 사이에서 난다”처럼 시작 범위를 좁힌다. 모르면 먼저 조사만 시키고, 바로 수정하지 말라고 한다. 큰 작업에서는 plan 모드나 별도 조사 단계로 나눠서 컨텍스트를 덜 태우는 편이 낫다.

하위 조사 작업은 subagent에 맡기는 것도 한 방법이다. Anthropic 문서는 subagent가 자체 컨텍스트에서 검색, 로그, 파일 내용을 처리하고 요약만 돌려줄 수 있다고 설명한다. 즉 메인 대화에 모든 탐색 로그를 붓지 않아도 된다. 다만 subagent도 권한을 갖는 작업자라서, 읽기 전용 조사인지 파일 수정까지 가능한지 분리해야 한다.

3번 체크: CLAUDE.md를 프로젝트 운영 문서로 쓴다

Claude Code에서 CLAUDE.md는 단순한 팁 저장소가 아니다. 공식 memory 문서에 따르면 프로젝트 CLAUDE.md는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 둘 수 있고, 팀과 공유되는 프로젝트 지침으로 쓸 수 있다. 여기에 빌드·테스트 명령, 코딩 표준, 아키텍처 결정, 자주 쓰는 워크플로를 적는 식이다.

여기서 많이 하는 실수는 CLAUDE.md를 만능 규칙집으로 만드는 것이다. 규칙이 너무 길고 추상적이면 실제 작업에서 잘 지켜지기 어렵다. “좋은 코드를 작성하라”보다 “API 응답 필드는 snake_case 유지”, “결제 코드는 수정 전 plan 작성”, “마이그레이션은 dry-run 먼저”처럼 행동으로 바꿔 써야 한다.

또 하나 중요한 점은 다른 에이전트와의 공존이다. 공식 문서는 저장소가 이미 AGENTS.md를 쓰고 있다면 CLAUDE.md가 이를 import하도록 만들 수 있다고 설명한다. 우리 볼트도 여러 런타임이 .claude/ 구조를 공유한다. 이런 환경에서는 규칙을 여러 파일에 중복 복붙하기보다, 공통 규칙과 Claude 전용 규칙을 나눠야 나중에 덜 꼬인다.

4번 체크: 권한은 기본 보수적으로 둔다

Claude Code 보안 문서는 기본적으로 strict read-only permissions를 사용하고, 파일 편집·테스트 실행·명령 실행 같은 추가 행동에는 명시적 권한이 필요하다고 설명한다. 이것은 귀찮게 하려는 장치가 아니라, 에이전트가 실제 파일과 명령을 만지는 도구이기 때문에 생기는 안전장치다.

실전 개발자는 이 지점에서 두 가지 극단으로 가기 쉽다. 하나는 매번 승인하느라 지쳐서 진행이 느려지는 쪽이고, 다른 하나는 아예 권한을 너무 크게 열어버리는 쪽이다. 둘 다 오래 가기 어렵다. 자주 쓰는 안전 명령은 허용하되, 삭제·배포·인증·결제·데이터베이스 변경은 사람 승인을 유지하는 식으로 계층을 나누는 편이 좋다.

설정 문서에는 민감한 파일을 읽지 못하게 permissions.deny로 .env, secrets, credential 파일 등을 막는 예시도 나온다. 이건 꼭 해둘 만하다. 에이전트가 악의적이라는 뜻이 아니라, 프롬프트 인젝션이나 잘못된 탐색으로 민감 파일이 컨텍스트에 들어오는 일을 줄이기 위한 장치다. 비밀키는 친한 AI에게도 굳이 보여줄 필요 없다. 친하다고 통장 비밀번호 알려주진 않잖아.

권한 항목 기본 운영값 열어도 되는 경우 닫아야 하는 경우
파일 읽기 프로젝트 중심 의존성·문서 확인 필요 .env, secrets, credentials
파일 쓰기 작업 범위 제한 테스트, 문서, 특정 모듈 배포, 인증, 결제, DB
Bash 실행 검증 명령 중심 테스트·빌드·검색 삭제, 강제 reset, 배포
MCP/외부 도구 신뢰한 서버만 공식/사내 승인 도구 출처 불명 서버, 민감 데이터

5번 체크: 훅은 자동화보다 안전망으로 시작한다

Claude Code hooks 문서는 훅을 Claude Code lifecycle의 특정 지점에서 자동 실행되는 shell command, HTTP endpoint, LLM prompt로 설명한다. 이벤트도 다양하다. 세션 시작, 사용자 프롬프트 제출, 도구 호출 전후, 권한 요청, compact 전후 같은 지점에 붙일 수 있다. 듣기만 해도 자동화 욕심이 난다. 여기서 잠깐 멈춰야 한다.

처음부터 훅으로 많은 일을 자동화하면 디버깅이 어려워진다. 훅은 처음에는 안전망으로 쓰는 편이 낫다. 예를 들어 PreToolUse에서 위험 명령을 막거나, PostToolUse에서 테스트 로그를 정리하거나, Stop 시점에 변경 파일 요약을 남기는 식이다. 자동 배포나 외부 알림은 그다음 단계다.

훅은 팀 환경에서 더 중요하다. 보안 문서는 팀 보안 기준으로 managed settings, 승인된 permission configuration 공유, usage monitoring, ConfigChange hooks 같은 운영 방식을 언급한다. 즉 “나 혼자 편하려고 만든 자동화”가 팀 저장소에서는 정책이 될 수 있다. 정책이 되려면 짧고 검증 가능해야 한다.

6번 체크: 한 번에 해결하려 하지 않는다

Claude Code는 큰 작업을 잘게 쪼갤수록 안정적이다. 공식 문서에서도 세션 관리, 컨텍스트 관리, subagent 조사, checkpoints, resume 같은 흐름을 강조한다. 운영 관점에서는 이걸 “큰 일을 작은 계약으로 쪼개기”라고 보면 된다. Claude에게 “전체 리팩터링 해줘”보다 “먼저 영향 파일 목록만 뽑아줘”, “그다음 테스트 추가해줘”, “이제 구현해줘”가 낫다.

특히 초보자가 많이 망하는 지점은 구현과 검토와 배포를 한 프롬프트에 몰아넣는 것이다. 그러면 결과가 빠르게 나와도 사람이 이해하기 어렵다. 변경 파일이 많고 설명이 길고 테스트도 애매하면, 결국 검수 시간이 더 늘어난다. 빠른 자동화가 느린 리뷰를 낳는 순간이다. 이러면 기술이 아니라 마술쇼 뒤처리다.

작업 단위는 “되돌릴 수 있는 크기”로 잡는다. 문서 수정, 테스트 추가, 작은 UI 변경, 한 함수의 버그 수정은 좋다. 인증 흐름, 결제 로직, 데이터 삭제, 운영 배포는 plan과 검수 단계를 분리해야 한다. Claude Code를 잘 쓴다는 것은 모든 걸 맡긴다는 뜻이 아니라, 무엇을 맡기고 무엇을 붙잡을지 정한다는 뜻이다.

7번 체크: 리뷰어를 따로 둔다

Claude Code best practices에는 adversarial review step도 언급된다. 내가 해석하는 실무형 의미는 간단하다. 만든 에이전트와 검수하는 에이전트를 분리하라는 것이다. 같은 흐름에서 “내가 쓴 코드 좋아 보이지?”라고 물으면, 사람도 AI도 관대해지기 쉽다. 리뷰는 성격이 조금 나빠야 한다. 친절하지만 까다로운 성격이면 더 좋다.

리뷰어가 볼 것은 코드 취향이 아니라 위험이다. 요구사항과 다른 변경, 테스트 없는 변경, 너무 넓은 파일 수정, 민감 설정 변경, 실패 시 롤백 어려운 작업을 먼저 본다. 블로그 파이프라인에서도 writer와 reviewer를 나누는 이유가 여기에 있다. 쓰는 쪽은 앞으로 달리고, 검수 쪽은 발목을 잡는다. 좋은 발목잡기는 프로젝트를 살린다.

팀에서는 이 단계를 PR 리뷰나 CI와 연결할 수 있다. Claude Code의 non-interactive mode는 CI, pre-commit hooks, 자동화 워크플로에 붙일 수 있다. 다만 여기서도 첫 용도는 “자동 승인”이 아니라 “자동 점검”이어야 한다. 기계가 먼저 보고, 사람이 최종 판단하는 구조가 가장 오래 간다.

바로 적용할 운영 체크리스트

아래 표는 Claude Code를 새 프로젝트에 붙이기 전에 내가 먼저 채울 기준이다. 다 채울 필요는 없지만, 첫 4개가 비어 있다면 아직 “운영”이 아니라 “시도”에 가깝다.

순서 체크 항목 완료 기준
1 검증 명령 테스트·빌드·린트 중 최소 1개가 Claude가 실행 가능
2 프로젝트 지침 CLAUDE.md에 빌드/테스트/금지 작업이 적혀 있음
3 민감 파일 차단 .env, secrets, credentials 읽기 제한
4 작업 단위 큰 작업을 조사→계획→구현→검수로 분리
5 권한 계층 안전 명령과 위험 명령이 분리됨
6 훅 위험 명령 차단 또는 변경 요약부터 시작
7 리뷰 루프 작성자와 리뷰어 역할 분리
8 컨텍스트 관리 긴 로그를 다 붓지 않고 요약·subagent 활용

내 기준 결론

Claude Code를 “프롬프트 잘 먹는 코딩 챗봇”으로 쓰면 금방 한계가 온다. 반대로 테스트, 권한, 컨텍스트, 프로젝트 지침, 리뷰 루프를 먼저 잡으면 실제 개발 워크플로의 일부가 된다. 차이는 도구의 지능이 아니라 운영자의 세팅에서 나온다.

그래서 이 글의 제목처럼 “그렇게 쓰는 거 아닌데”라고 말하고 싶어지는 지점은 프롬프트가 아니다. 검증 없이 맡기고, 권한을 한 번에 열고, 컨텍스트를 계속 태우고, 리뷰 없이 결과를 믿는 방식이다. Claude Code는 혼자 천재처럼 날아가는 도구라기보다, 좋은 작업장을 만들어주면 빠르게 움직이는 동료에 가깝다. 작업장 바닥부터 치우자. 그래야 동료도 안 넘어진다.

관련 글

FAQ

Q. Claude Code를 처음 쓰면 제일 먼저 뭘 해야 하나?

프롬프트 템플릿을 모으기 전에 프로젝트의 검증 명령을 정리하는 게 먼저다. 테스트, 빌드, 린트, 스크린샷 확인 중 하나라도 Claude가 실행하고 결과를 읽을 수 있어야 한다. 그래야 결과가 “그럴듯한 코드”에서 “검증된 변경”으로 바뀐다.

Q. CLAUDE.md에는 무엇을 적어야 하나?

빌드 명령, 테스트 명령, 코딩 표준, 자주 하는 워크플로, 건드리면 안 되는 파일, 승인 필요한 작업을 적는 것이 좋다. 추상적인 원칙보다 실제 행동 기준이 낫다. 예를 들어 “좋은 코드 작성”보다 “결제 로직 수정 전 plan 작성, 테스트 추가 없으면 구현 금지”가 훨씬 쓸모 있다.

Q. 권한을 자동으로 열어두면 더 빠르지 않나?

빠를 수는 있지만 위험도 같이 커진다. 안전한 반복 명령은 허용하되, 삭제·배포·인증·결제·DB 변경은 승인 필요로 남기는 편이 좋다. 특히 팀 저장소에서는 개인 편의보다 감사 가능성과 복구 가능성이 더 중요하다.

Q. 훅은 언제부터 쓰면 좋나?

처음부터 복잡한 자동화를 붙이기보다 위험 명령 차단, 변경 파일 요약, 테스트 실행 같은 안전망부터 시작하는 편이 좋다. 훅이 많아질수록 문제 발생 시 원인 추적이 어려워질 수 있으므로, 작은 훅을 하나씩 추가하고 로그를 확인하는 방식이 안정적이다.

공식 출처

이 글은 Claude Code를 특정 방식으로 강제하는 문서가 아니라, 실전 개발 환경에서 실패 비용을 줄이기 위한 운영 체크리스트다. 도구 버전과 조직 정책에 따라 auto mode, sandbox, plugins, hooks 사용 가능 여부가 다를 수 있으니 실제 환경의 /help, /permissions, 공식 문서를 함께 확인해야 한다.