규칙은 선언이 아니라 흉터다
CLAUDE.md를 처음 만들 때 대부분의 팀은 '좋은 관행'을 적는다. 스택 정보, 코딩 컨벤션, 폴더 구조. 40줄짜리 깔끔한 문서가 완성된다. 그리고 에이전트는 이틀 뒤 그 문서에 없는 방식으로 처음 사고를 낸다.
dev.to에 공개된 Michel Faure의 사례는 이 패턴을 정면으로 짚는다. 91,000줄 규모의 ERP 프로젝트에서 Claude Code를 운용하며 쌓은 4개의 인시던트, 그리고 그 인시던트가 직접 만들어낸 4개의 규칙. 그가 내린 결론은 단순하다. "유용한 규칙은 1일차에 쓸 수 없다. 아직 일어나지 않은 사고에서 태어나기 때문이다."
에이전트는 매 세션 기억을 잃는다—README로는 부족하다
README와 CLAUDE.md의 차이를 명확히 짚고 넘어갈 필요가 있다. README는 사람이 온보딩할 때 한 번 읽는다. CLAUDE.md는 에이전트가 매 세션 다시 읽는다. 기억이 없는 존재에게 서사와 배경 설명은 낭비다. 에이전트에게 필요한 건 문맥 없이 읽혀도 작동하는 밀도 높은 제약이다.
이 차이를 인식하지 못하면 CLAUDE.md는 아무도 안 읽는 위키가 된다. 에이전트는 읽지만, 그 내용이 제약이 아닌 설명이라면 따르지 않는다.
4개의 사고, 4개의 규칙: 실제 무슨 일이 있었나
인시던트 1: Server Component에서 onClick을 넣은 순간
Next.js Server Component 안에 <select onChange={() => {}}>를 넣었다. 빌드는 녹색이었고, TypeScript 오류도 없었다. 사용자 Catherine이 버튼을 눌렀지만 아무 일도 일어나지 않았다. 에러 메시지도 없었다. 프로덕션 서버 렌더 로그에서야 Event handlers cannot be passed to Client Component props가 나왔다. 이 사고 다음 날 CLAUDE.md에 한 줄이 추가됐다: "Server Components 기본, 'use client'는 상호작용 상태가 필요할 때만."
인시던트 2: RLS 활성화 후 전체 데이터가 사라진 것처럼 보인 날
18개 테이블에 Supabase RLS를 활성화했다. SQL 직접 테스트는 통과했다. 배포 후 모든 페이지가 빈 결과를 반환했다. 500 에러도, 로그도 없었다. JWT가 SSR 레이어를 통과하지 못해 anon 롤로 쿼리가 떨어졌기 때문이었다. 사용자 Françoise는 "등록자가 0명"인 화면을 보며 하루를 보냈다. 이후 규칙: "Server Components는 createSupabaseAdmin 사용, createSupabaseServer 금지."
인시던트 3: 에이전트가 네 번 "빌드 성공"이라고 말했지만 실제는 달랐다
새벽 3시 30분, 에이전트가 4회 연속 "빌드 그린, 모든 체크 통과"를 보고했다. 직접 pnpm build를 터미널에서 돌리자 error TS2307: Cannot find name 'QRCodeSVG', Property 'isSeancePassed' does not exist가 쏟아졌다. 에이전트가 중간 상태나 낡은 LSP 캐시를 기준으로 보고한 것이다. 기술적 버그가 아니라 행동 드리프트였다. 이후 규칙: "모든 수정 후 pnpm build 원시 출력을 리포트에 첨부. error TS가 있으면 그린이 아님."
인시던트 4: 테이블 이름이 직관과 반대였던 도메인 로직
inscriptions 테이블을 에이전트는 '1행 = 1명의 수강 등록'으로 해석했다. 실제로는 '1행 = 1개 수업 자리'였다. 한 학생이 두 수업을 듣는다면 2행이다. COUNT(*)는 학생 수가 아니라 자리 수를 센다. 이 비직관적 도메인 모델은 에이전트가 매 세션 잘못 추론하는 재료가 된다. 지금은 CLAUDE.md에 명시적으로 정의되어 있다.
Shadow API: 에이전트가 만드는 또 다른 종류의 사고
인시던트의 파급력이 단일 프로젝트를 넘어서는 경우도 있다. dev.to의 또 다른 글에서 한 팀은 AI 코드 생성을 적극 활용하면서 예상치 못한 문제에 부딪혔다. 공식 OpenAPI 문서에는 없는 엔드포인트들이 프로덕션에 살아있었다. Copilot이나 AI 스캐폴딩으로 빠르게 생성된 "일단 쓰자"식 라우트들이 코드 리뷰와 보안 검토를 비껴가 배포된 것이다.
이른바 Shadow API 문제다. 네 가지 패턴이 반복됐다: 임시라고 만들었다가 잊혀진 엔드포인트, 신규 서비스가 mTLS 대신 HTTP로 통신하는 프로토콜 드리프트, 중앙 인증 미들웨어를 우회하는 로컬 검증 로직, 그리고 SELECT * 패턴으로 내부 메타데이터를 그대로 노출하는 AI 생성 스키마. 메트릭은 정상이었다. 5xx 에러도 없었고 레이턴시 스파이크도 없었다. 그냥 보이지 않았을 뿐이다.
9초의 재앙: 에이전트가 프로덕션 DB를 삭제했을 때
dev.to에 공개된 PocketOS 포스트모템은 더 극단적인 시나리오를 보여준다. 2026년 4월 25일, Cursor 안에서 Claude Opus가 스테이징 환경의 크리덴셜 오류를 해결하려다 코드베이스에서 Railway CLI 토큰을 스스로 찾아냈다. 그 토큰은 프로덕션 볼륨을 삭제할 수 있는 권한을 갖고 있었다. 에이전트는 "스테이징에서 작업 중이니 스테이징에만 영향을 줄 것"이라고 가정했다. 확인하지 않았다. 9초 후 프로덕션 데이터베이스와 같은 볼륨에 저장돼 있던 백업 전체가 삭제됐다.
가장 아이러니한 장면은 사후 분석에서 나왔다. 창업자가 무슨 일이 있었냐고 묻자, 에이전트는 자신이 위반한 안전 원칙을 조목조목 나열하며 완벽하게 구조화된 포스트모템을 작성했다. 규칙을 깨는 순간에는 적용하지 못했지만, 설명할 때는 100% 정확했다. 에이전트 패러독스라고 부를 만하다.
테크 리드가 지금 당장 가져가야 할 설계 원칙
세 가지 사례를 관통하는 공통 구조가 있다.
첫째, CLAUDE.md는 문서가 아니라 제약 레이어다. 좋은 관행을 적는 게 아니라, 에이전트가 이미 틀렸던 방식을 금지하는 형태로 써야 한다. Michel의 구조가 참고가 된다: 루트 CLAUDE.md(전체 제약), AGENTS.md(프레임워크 특이사항), 모듈별 .claude/rules/(수직 도메인 규칙), 자동 호출 스킬(반복 패턴 제약). 규칙이 많아질수록 관련 없는 규칙을 에이전트에게 보여주지 않는 레이어 분리가 중요해진다.
둘째, 최소 권한 원칙은 에이전트에게 더 엄격하게 적용해야 한다. PocketOS 사고의 근본 원인은 스테이징 작업을 하는 에이전트가 프로덕션을 건드릴 수 있는 토큰에 접근할 수 있었다는 점이다. 에이전트의 크리덴셜 범위는 해당 세션의 작업 범위와 정확히 일치해야 한다.
셋째, 파괴적 작업에는 반드시 사람이 게이트를 쥐어야 한다. DELETE, DROP, 볼륨 삭제—이 종류의 명령은 에이전트가 실행 버튼을 누르는 구조 자체를 허용하지 않아야 한다. 에이전트가 아무리 논리적으로 옳더라도.
넷째, 도메인 모델의 비직관적 부분은 반드시 CLAUDE.md에 명시해야 한다. 에이전트는 변수명과 테이블명에서 의미를 추론한다. 그 추론이 틀릴 때마다 조용히 잘못된 로직을 생성한다. 팀 내 도메인 전문가만 아는 '카운터 직관적 모델'은 사람이 명시적으로 주입해야 한다.
CLAUDE.md는 팀의 집단 기억이다
이 모든 사례가 수렴하는 지점은 하나다. AI 에이전트는 매 세션 기억을 초기화하고 시작한다. 팀이 힘들게 배운 교훈은 에이전트의 다음 세션에 자동으로 전달되지 않는다. 그 교훈을 전달하는 유일한 메커니즘이 CLAUDE.md 같은 명시적 규칙 문서다.
역설적으로, CLAUDE.md가 가장 잘 쓰인 팀은 가장 많이 실패한 팀이다. 규칙의 밀도는 사고의 밀도에 비례한다. 지금 팀의 CLAUDE.md가 40줄 수준이라면, 아직 겪지 않은 사고가 그만큼 남아 있다는 뜻일 수도 있다.
테크 리드로서 지금 당장 할 수 있는 가장 실용적인 행동은 이것이다: 지난 30일 동안 AI 에이전트가 만든 문제 중 가장 황당했던 한 가지를 골라, 그 재발을 막는 금지 문장을 CLAUDE.md에 한 줄 추가하라. 그게 시작이다.