Claude Code 모범 사례, 다시 생각하기
참고한 자료
- Rethinking Claude Code Best Practices — Lydia Hallie, Anthropic (AI Engineer, 2026-11-11)
- 앤트로픽 개발자 리디아가 공개한 클로드 코드 최신 사용법 (상위 0.1%) (민둥이 | 쉽게 배우는 AI, 같은 강연의 한국어 정리 영상)
모델이 좋아지면서 지난 1년 동안 Claude Code 설정에 덧붙인 지시와 습관이 이제는 오히려 모델의 발목을 잡는다. 연초의 모범 사례는 사람이 루프 안에서 세션을 조종하고, 명령을 승인하고, 하면 안 되는 일을 막고, 결과를 확인하고, 세션을 직접 시작하는 것이었다. Anthropic Claude Code 팀의 Lydia Hallie는 사람이 루프에서 빠지는 자리마다 모델, 하네스, 환경 중 하나가 그 일을 넘겨받아야 한다고 말한다.
세션이 달라졌다
연초에는 Opus 4.5를 썼다. 그때 모델은 지금보다 일찍 멈췄고, 사람이 계속 바로잡아야 했고, CLAUDE.md에는 IMPORTANT와 느낌표를 붙였다. 자동 모드가 없어서 모든 명령을 손으로 승인하거나 --dangerously-skip-permissions를 썼다.
지금 Anthropic에서는 세션 수십 개를 동시에 몇 시간씩 돌린다. 세션이 스스로 결과를 확인하고, 세션이 다른 세션을 지휘한다. 개발자는 세션 수십 개를 관리하는 사람이 됐다. 10월 Anthropic 블로그 글 기준으로 하루 코드 변경은 5월 약 2,500건에서 9월 3만 건 이상으로 늘었다.
강연 시점에 매일 쓰는 모델은 Opus 5.5다. 그 주에 나온 Fable 5.2는 긴 작업과 코드베이스 이해에 강하고, 특히 자기 결과를 검증하는 데 강하다고 한다.
조종과 승인은 모델과 자동 모드에
먼저 기본값을 지금 것으로 바꾼다. 모델은 Opus 5.5, 권한은 자동 모드다(자동 모드는 8월부터 기본 권한 모드다). Opus 5.5는 의도와 코드베이스를 잘 이해해서 세션 중간에 조종할 일이 적다.
- CLAUDE.md:
IMPORTANT,NEVER!같은 표현은 지금 모델에게 필요 없다. 오히려 엉뚱한 쪽으로 이끌어 도구 호출이 늘고 결과가 나빠진다. Claude가 코드에서 볼 수 없는 것만 남긴다. 예를 들면 코드에서 직접 참조하지는 않지만 어딘가의 레거시 서비스가 아직 쓰는 부분이다. 어떤 스택인지, 어디를 보면 되는지는 지운다. /doctor prompt-audit: 지금 모델 기준으로 CLAUDE.md와 스킬을 훑어 더는 필요 없는 지시를 찾아 준다.- 자동 모드: 프로젝트 안 파일 읽기·편집을 뺀 거의 모든 동작을 별도 분류기가 본다. 테스트 실행이나 의존성 설치처럼 안전한 건 자동으로 허용하고, 확신이 없으면 막는다. 기본으로는 지금 폴더와 저장소만 믿기 때문에, 스테이징 배포용 저장소로 푸시하는 일 같은 건 막히고 사람이 다시 루프로 들어온다.
- 자동 모드에서도 승인을 자주 해야 한다면 설정부터 본다. 믿는 저장소·버킷·도메인, 늘 허용할 일과 절대 하지 말아야 할 일을 일반 영어 문장으로 적으면 그 내용이 분류기에 전달된다.
안전: 거부 규칙, 샌드박스, 클라우드 세션
8월 Anthropic 연구에서 누가 봐도 위험한 명령을 사람은 약 14%만 잡았고, 자동 모드는 89%를 막았다. 사람보다 훨씬 낫지만 10개 중 1개는 그냥 지나간다. 보장이 필요하면 하네스에서 강제해야 한다.
거부 규칙(deny): 도구 호출이 거부 규칙에 걸리면 자동 모드 분류기는 아예 보지도 않는다. Claude가 절대 하지 않게 만드는 가장 확실한 방법이다. 규칙으로 막을지 모델에 맡길지는 “한 번 틀리면 되돌릴 수 있나?“로 정한다. 잘못 쓴 코드는 되돌릴 수 있으니 모델에 맡긴다. 커밋하지 않은 변경을 날리거나 키를 읽어 대화 기록에 남기는 일은 규칙으로 막는다(슬라이드 예: "deny": ["Bash(git reset --hard *)"]). 예를 들어 .env는 자동 모드가 기본으로 읽기를 허용하지만, 거부 규칙에 넣으면 cat 같은 명령으로도 열지 못한다.
하지만 거부 규칙은 도구 호출을 실행할지만 정하고, 실행된 뒤 무엇에 접근하는지는 막지 못한다. npm test 안에서는 의존성 코드나 Claude가 잠깐 짠 스크립트가 돈다. 그중 하나가 악성이면 .env나 SSH 키를 읽어 모르는 서버로 보낼 수 있다. 사람이 승인하고 있었더라도 그냥 테스트라서 허락했을 명령이다.
샌드박스: 명령이 읽을 파일, 쓸 폴더, 접속할 호스트를 운영 체제가 제한하고, 이 제한은 그 명령이 띄운 하위 프로세스에도 적용된다. 샌드박스를 켜면 같은 거부 규칙이 운영 체제 수준으로 넘어가서 의존성이 .env를 열려고 해도 막힌다.
- 기본으로는 여전히 컴퓨터 대부분을 읽을 수 있으니, SSH 키 같은 건 규칙을 더 넣어야 한다.
- 샌드박스는 Claude가 실행하는 셸 명령과 그 하위 프로세스만 감싼다. Claude의 자체 파일 도구, MCP 서버, 훅은 샌드박스 밖에서 돈다.
클라우드 세션: 저장소를 새로 받은 별도 머신에서 돌고, 노트북을 덮어도 계속된다. .env, SSH 키, GitHub 토큰은 git에 올라가 있지 않으니 애초에 없다. API 키가 필요하면 세션이 도중에 키가 없다고 알려 주고, 네트워크 시크릿으로 넣으면 모델에게 보내지 않고 쓴다. 네트워크는 기본으로 패키지 레지스트리와 GitHub 정도만 열려 있어서 다른 호스트는 환경에 직접 추가해야 한다.
클라우드 머신은 버려도 되지만 밖으로 나간 것(푸시한 커밋, 커넥터로 보낸 메시지)은 되돌리지 못한다. 그래서 클라우드에서도 자동 모드와 거부 규칙을 쓰고, 거부 규칙은 저장소에 커밋해 두어 세션과 함께 따라가게 한다. 강제 푸시나 커밋에 섞인 시크릿 같은 걸 이걸로 잡을 수 있다.
검증: 확인 지점, 훅, CI, 리뷰
사람이 모든 변경을 승인하던 때는 이미 다 봤으니 결과를 믿을 수 있었다. 지금은 세션이 몇 시간 동안 백그라운드에서 일하고, 끝난 뒤에 사람이 모든 파일을 읽지도 않는다. 인증을 새 API로 옮기라는 같은 프롬프트로도 어떤 실행은 옛 API를 남기고, 어떤 실행은 새 로그인에만 적용하고, 어떤 실행은 모두를 로그아웃시킨다. 셋 다 그럴듯해 보인다.
그래서 중간중간 확인 지점을 둔다. 테스트, 빌드, 스크린샷처럼 통과·실패로 결과가 나오는 건 무엇이든 된다. 사람은 전체 변경 대신 확인 지점을 리뷰하면 되니 리뷰할 분량이 훨씬 적다. (사람 대신 환경이 실수를 잡게 한다는 생각은 AI가 쓴 코드, 누가 어떻게 믿나에서도 다뤘다.)
- 프롬프트: 가장 쉬운 방법이다. 완료 기준을 말하고, 작업을 나눠 작업마다 테스트를 두게 하고, 사람이 그 자리에 없었으니 실제 출력을 보여 달라고 한다. 하지만 프롬프트만으로는 보장되지 않는다.
- 훅: 반드시 돌아야 하는 건 훅으로 건다. 파일을 고칠 때마다 린터를, 작업을 완료로 표시하려 할 때 바뀐 부분의 테스트(인증 코드를 건드렸으면 인증 테스트)를, 세션을 끝내려 할 때 전체 테스트를 돌린다. 실패하면 다시 고친다.
- 종료 코드: 대부분의 도구는 테스트가 실패하면
1로 끝나는데,1이면 Claude Code는 그 작업을 그냥 완료로 표시한다. 스크립트가2로 끝나야 Claude가 다시 고친다.exit 2 — goes back to fix it / exit 1 — marked as completed
- 세션마다 자기 머신이 있으니 같은 폴더에서 부딪히지 않고, 워크트리를 직접 신경 쓸 일도 줄었다.
- CI: 모든 세션은 결국 PR을 열고, CI는 세션이 어떻게 설정됐든 같은 검사를 돌린다. 강연에서는 이게 가장 중요하다고 했다. CI 자동 수정을 켜면 검사 실패를 Claude가 보고 고친다. 검사가 다 통과하면 GitHub가 병합하게 하는 merge when ready를 켜는 경우도 있지만, 기본값은 아니고 변경의 위험도에 따라 정한다.
- 리뷰: 팀의 모든 PR은 먼저 Claude가 리뷰한다. 코드를 쓴 세션이 아니라 새 컨텍스트의 Claude이고, 찾은 버그마다 별도 에이전트 그룹이 다시 확인한다. 사람 리뷰는 위험도에 따라 나눈다. 문서나 문구 같은 작은 변경은 자동 검사를 통과하면 사람 없이, 일반 제품 변경은 1명, 위험한 변경은 2명이 “필요할 수도 있다”고 했다.
Smaller changes — a typo or a lint fix / Most changes — one person / Riskiest changes — more than one person
세션 시작도 Claude에게
Lydia 본인도 컨텍스트 전환에 약해서 세션을 많이 관리하기 힘들었다고 한다. 그래서 지휘 세션 하나만 둔다.
아직 베타인 Claude Code 프로젝트에서는 할 일을 말하면 지휘 세션이 작업을 나누고, 작업마다 새 세션(스레드)을 띄우고, 돌아온 결과를 챙긴다. 세션 8개와 각각 대화하는 대신 하나와만 대화하면 된다. 지휘 세션은 코드를 직접 쓰지 않으니, 지휘 세션에는 무엇을 할지 정하고 결과를 판단하는 데 강한 Fable을, 스레드에는 실제 일을 잘하는 Opus 5.5를 쓴다. 둘은 따로 설정할 수 있고, 일이 다 안 됐으면 지휘 세션이 다시 돌려보낸다. 컨텍스트 관리도 자동이라 언제 압축하거나 비울지 신경 쓰지 않아도 된다.
Fable — decides and judges / Opus 5.5 — does the work
정리
Steering it → The model / Approving every tool call → Auto mode / Saying no → Deny rules, the environment / Checking it’s done → Tests, hooks, CI / Starting every session → Claude
옛 모범 사례는 사라진 게 아니라 옮겨 갔다. 사람에게는 첫 세션을 시작하고 결과를 리뷰하는 일만 남는다.
해 보려면 평소보다 훨씬 큰 작업 하나를 고르고, CI가 내가 신경 쓰는 걸 실제로 잡는지 확인한다. 그다음 환경(네트워크 접근, 시크릿, 설정 스크립트)을 잠깐 설정하고 클라우드에서 시작한다. 세션이 어디서 막히고 어디서 내가 아직 루프에 있는지 보면, 그게 다음에 Claude에게 넘길 일이다.