당신은 지금 Claude에게 몇 번째 같은 말을 하고 있나
새 세션을 열 때마다 코딩 컨벤션을 설명하고, 폴더 구조를 안내하고, 테스트 방식을 다시 짚어준다. 어제도, 오늘도, 내일도. Claude Code를 쓰는 팀이라면 누구나 겪는 이 반복이 사실은 구조 설계 실패의 증거다. AI를 '프롬프트로 조종하는 도구'로만 쓰는 한, 컨텍스트는 세션마다 증발하고 팀은 매번 처음부터 가르쳐야 한다.
문제의 본질: 확률적 기억 vs. 결정론적 설정
dev.to에 공개된 .claude/ 디렉토리 활용 가이드는 이 문제를 정면으로 다룬다. 핵심 주장은 단순하다. 프롬프트는 확률적이고 일회성이다. 반면 .claude/ 디렉토리는 결정론적으로 동작한다. 세션이 시작될 때마다 자동으로 로드되고, 팀 전체가 버전 컨트롤로 공유하며, 훅(hooks)으로 특정 시점에 확실하게 실행된다.
구조를 보면 이해가 빠르다. 프로젝트 루트의 CLAUDE.md는 빌드 명령어, 코딩 스탠다드, 아키텍처 결정, 흔한 함정까지 200줄 이내로 압축한 팀의 집단 기억이다. .claude/hooks/의 스크립트는 툴 호출 이후나 세션 시작 시점에 결정론적으로 실행된다. .claude/commands/의 슬래시 커맨드는 반복적인 워크플로우를 한 줄 명령으로 줄인다. .claude/agents/의 서브에이전트는 코드 리뷰, 리서치, 로그 분석 같은 역할을 독립된 컨텍스트 윈도우에서 처리한다.
중요한 분기점이 하나 있다. CLAUDE.md는 git에 커밋해서 팀 전체가 공유하고, CLAUDE.local.md와 settings.local.json은 .gitignore로 개인 머신에 남긴다. 팀 규칙과 개인 취향을 레이어로 분리하는 이 구조는 사소해 보이지만, 팀이 커질수록 충돌을 예방하는 핵심 설계 결정이다.
실제 ROI: 25분짜리 아침 루틴을 끊은 방법
이 구조 설계가 실제로 어떤 임팩트를 내는지, 다른 사례가 구체적으로 보여준다. dev.to에 공개된 LLM 에이전트 자동화 사례는 엔지니어가 매일 아침 25~30분을 소모하던 레거시 모니터링 이메일 파싱 작업을 에이전트 하나로 대체한 경험을 기술한다.
환경 자체가 최악이었다. 레플리케이션 지연 알림, 73행짜리 HTML 테이블 형식의 DB 백업 리포트, 하루 20~50건의 인프라 알림 이메일, Confluence에 박혀 있는 배포 현황. 어느 것도 API가 없고, 어느 것도 현대적인 옵저버빌리티 스택에 연결되지 않는다. 누군가 매일 눈으로 읽어야 했다.
저자가 선택한 설계 원칙 세 가지가 흥미롭다. 첫째, 섹션 독립성. 하나의 커넥터가 실패해도 나머지 섹션은 계속 실행되고, 실패한 섹션은 '⚠ connector unavailable'로 명시된다. 부분 리포트가 전체 실패보다 압도적으로 낫다는 판단이다. 둘째, 부재(absence)도 신호. 이메일이 한 건도 없으면 '오늘 알림 없음'을 조용히 넘기지 않고 굵게 경고로 표시한다. 실제로 메일 라우팅 변경으로 백업 리포트가 사라졌을 때 이 장치가 즉시 포착했다. 셋째, 델타 지향. 현재 상태 전체가 아니라 어제와 달라진 것만 보고한다. 주의를 필요한 곳에만 라우팅하는 것이다.
이 사례에서 Python + 정규식 + cron으로 충분하지 않았냐는 질문은 당연하다. 저자의 답변은 솔직하다. 가능하다. 하지만 73행 HTML 테이블의 컬럼 순서가 바뀌거나, AWS 알림 포맷이 달라지거나, 새 데이터 소스가 추가될 때마다 스크립트를 고쳐야 한다. LLM 에이전트는 포맷 변화에 적응하는 대신 결정론적 보장을 포기한다. 트레이드오프다. '오늘 아침 트리아지 요약'처럼 다음 실행이 금방 오는 워크플로우에서는 그 트레이드오프가 수용 가능하다. 자동 복구 트리거처럼 정확성이 절대적인 시스템에서는 아니다.
두 사례가 수렴하는 지점
표면적으로 두 사례는 다른 이야기처럼 보인다. 하나는 개발 환경 설정이고, 하나는 운영 자동화다. 그런데 둘 다 같은 구조적 실패를 해결하고 있다. 반복되는 수동 개입을 구조로 대체하는 것.
Claude Code의 .claude/ 설계는 '이번 세션에서 뭘 해야 하는지'를 매번 설명하는 비용을 없앤다. 에이전트 자동화는 '오늘 아침에 이메일을 열고 표를 읽는' 25분을 없앤다. 두 접근 모두 핵심은 동일하다. 반복 루프를 발견하고, 그것을 구조로 가두고, 사람의 판단이 필요한 부분만 남긴다.
팀 리빌딩 관점에서 이게 의미하는 것
AI-First 워크플로우를 팀에 도입할 때 가장 큰 실수 중 하나는 각자 알아서 프롬프트를 쓰게 두는 것이다. 팀원 10명이 각각 다른 방식으로 Claude를 가르치고 있다면, 그건 AI 도구를 쓰는 게 아니라 10개의 분산된 단기 기억을 관리하는 것이다.
CLAUDE.md를 팀의 첫 번째 AI 온보딩 문서로 만들어라. 신규 입사자가 프로젝트를 클론하면 Claude도 이미 그 프로젝트의 규칙을 알고 있어야 한다. .claude/commands/의 슬래시 커맨드는 팀의 베스트 프랙티스를 코드화하는 방법이다. 한 명이 발견한 효율적인 워크플로우가 팀 전체의 기본값이 되는 구조다.
지금 당장 할 수 있는 것
거창하게 시작할 필요 없다. 내일 아침, 팀에서 가장 자주 반복되는 Claude 프롬프트 세 개를 찾아라. 코딩 스타일 설명, 테스트 방식 안내, 특정 폴더 구조 설명 같은 것들. 그것을 CLAUDE.md에 옮겨라. 그게 전부다. 세션마다 가르치는 일을 한 번의 설계로 대체하는 첫 걸음이다.
그 다음은 팀이 매주 반복하는 수동 작업 하나를 골라라. 포맷이 불규칙하고, API가 없고, 누군가 눈으로 읽어야 하는 것. 그 작업이 에이전트 자동화의 첫 번째 후보다. 설계 원칙은 이미 검증됐다. 섹션을 독립시키고, 부재를 명시적 신호로 다루고, 변화만 보고하는 것.
AI를 도구로 쓰는 팀과 AI가 일하는 환경을 설계하는 팀의 차이는 결국 이 구조 설계의 밀도에서 나온다.