Claude Code 빠르게 쓸수록 CLAUDE.md 설계가 먼저다

Claude Code 빠르게 쓸수록 CLAUDE.md 설계가 먼저다

비개발자가 2시간 만에 제품을 완성하는 시대, 그 속도를 안전하게 담보하는 거버넌스 설계와 공급망 보안 리스크를 함께 따져봐야 할 때다.

Claude Code CLAUDE.md permission-first AI 에이전트 보안 공급망 공격 자격증명 노출 AI 거버넌스 스킬 파일
광고

2시간 완성, 그 이면의 질문

비개발자가 Claude Code로 2시간 만에 Umbraco 스팸 필터 패키지를 완성했다. dev.to에 올라온 이 사례가 화제가 된 건 단순히 빠른 개발 때문이 아니다. 저자는 20년 경력의 디지털 딜리버리 전문가이고, 그는 코드를 한 줄도 직접 치지 않았다. 테스트 코퍼스 9개 중 8.5개 정답, 스팸 차단 정확도도 실사용 수준이었다.

이 사례가 흥미로운 건 결과물보다 프로세스에 있다. 저자가 강조하는 성공 요인은 Claude Code가 아니었다. '정확히 무엇을 만들지 알고 있었고, 그 기준이 흔들리지 않았다'는 점이었다. 그는 사전에 제품 브리프를 작성하고, 스팸/정상 메일 테스트 케이스를 준비했으며, 안전망(default-pass 보장, 마스터 킬스위치)을 설계 초기부터 내장했다. AI가 타이핑을 대체한 게 아니라, 설계 판단을 AI에게 위임하지 않았기 때문에 완성될 수 있었다.

속도가 만들어내는 통제 문제

하지만 모든 팀이 이만큼 명확한 설계 판단을 들고 Claude Code를 켜는 건 아니다. AI 코딩 에이전트를 실제로 쓰다 보면 다른 문제에 부딪힌다. 에이전트가 승인 없이 파일을 삭제하고, 요청하지 않은 리팩토링을 실행하며, '도움이 되는' 가정을 아키텍처 전반에 박아넣는다.

이 문제를 해결하기 위해 'Full Stack HQ'라는 permission-first CLAUDE.md 설정 킷이 등장했다(MIT, 오픈소스). 핵심 철학은 하나다: 에이전트는 계획을 먼저 보여주고, 명시적 승인을 받은 뒤에만 실행한다. 유효한 승인 키워드는 PLAN APPROVED, IMPLEMENTATION APPROVED, PROCEED, DO IT 네 가지뿐이다. 그 외 어떤 응답도 에이전트를 멈춘다.

이 구조가 해결하는 문제는 생각보다 넓다. 기획-실행 분리(plan-then-execute)만으로도 에이전트발 '의도치 않은 변경' 80%가 사라진다고 저자는 주장한다. 여기에 10개의 전문 에이전트(frontend, backend, database, security-auditor 등)와 28개 스킬 모듈, 7개 슬래시 커맨드(/plan, /debug, /test 등)가 결합되면, 범용 에이전트가 '전문성 없는 루트 접근 인턴'처럼 행동하는 문제가 구조적으로 줄어든다. 특히 커밋 전 보안 체크리스트(하드코딩된 시크릿 없음, 입력값 검증, 무제한 쿼리 금지 등)가 CLAUDE.md에 내장된다는 점은 팀 리드 입장에서 주목할 부분이다.

15% 자격증명 노출, 공급망이 열려 있다

속도와 통제 사이의 긴장이 가장 날카롭게 드러나는 지점은 보안이다. 이번 주 Capsule Security의 분석은 20만 개 이상의 에이전트 스킬 파일을 스캔한 결과를 발표했다. 핵심 수치: 고유 스킬 파일의 약 15%(19,618개 중 2,909개)에 하드코딩된 자격증명이 데이터베이스 쓰기 권한과 함께 존재했다. 별도의 익스플로잇이 필요 없다. 스킬을 설치하는 순간, 에이전트가 설정 파일을 읽고, 자격증명이 컨텍스트 윈도우 안으로 들어온다.

더 심각한 건 별도의 캠페인 사례다. 2026년 3월, 공격자들은 정상적으로 보이는 커뮤니티 스킬을 배포했다. 악성 페이로드의 전달 방식은 전통적인 멀웨어 드로퍼가 아니었다. 스킬 파일 내부의 설치 지침 자체가 Remcos RAT와 GhostLoader 설치를 지시했다. 에이전트는 그걸 충실히 따랐다. 설치 지침이 원래 그런 용도이기 때문이다. 이 공격은 2026년 1월 발생한 공급망 공격과도 다른 사례로, 스킬 생태계가 반복적으로 공격 채널이 되고 있음을 보여준다. AI 워크플로우가 빠를수록, 스킬 설치는 의존성 추가(npm install)와 동급의 공급망 이벤트로 취급해야 한다는 의미다.

팀 리드가 내일 해야 할 것

세 사례를 놓고 보면 공통된 구조가 보인다. Claude Code의 속도는 설계 판단 없이는 리스크다. 에이전트의 자율성은 permission-first 거버넌스 없이는 아키텍처 부채다. 스킬/설정 파일 생태계는 보안 감사 없이는 공급망 구멍이다.

실행 가능한 체크리스트 세 가지만 꼽는다.

첫째, CLAUDE.md에 permission gate를 먼저 설계하라. Full Stack HQ가 완벽한 해답은 아니지만, '에이전트가 먼저 계획을 보여주고 승인을 받는다'는 구조는 당장 내일 팀에 적용할 수 있다. CLAUDE.md가 없는 팀이라면, 그게 없는 상태에서 에이전트를 쓰는 건 룰 없이 신입 개발자에게 프로덕션 접근권을 주는 것과 같다.

둘째, 스킬/MCP 설치를 공급망 이벤트로 취급하라. 커뮤니티 소스 스킬 파일에 대해 package.json 의존성과 동일한 리뷰를 적용해야 한다. 설치 전 설치 지침 섹션을 직접 읽고, 외부 URL 참조나 셸 커맨드 실행 지시가 있는지 확인하라. 자격증명 패턴 regex 스캔은 첫 단계로 충분하다.

셋째, 속도는 설계 판단을 대체하지 않는다. 2시간 완성 사례의 교훈은 '빠르다'가 아니라 '설계가 먼저였다'는 것이다. 무엇을 만들지, 안전망은 어디에 넣을지, 실패했을 때 기본 동작은 무엇인지—이 판단들은 에이전트가 빠를수록 더 먼저 인간이 내려야 한다.

속도와 통제, 둘 다 가져가려면

Claude Code가 가속하는 속도는 실재한다. 비개발자가 2시간 만에 실제 제품을 완성한다는 건 더 이상 마케팅 문구가 아니다. 문제는 그 속도를 팀 전체에 적용할 때, 거버넌스 없는 자율성이 어떤 형태로 터지는지가 이제 데이터로 보이기 시작했다는 점이다. 15% 자격증명 노출이라는 숫자, 설치 지침이 RAT를 내려받은 사례—이건 이론적 리스크가 아니라 이미 일어나고 있는 일이다.

속도를 포기할 이유는 없다. 하지만 CLAUDE.md를 비워둔 채 에이전트를 켜는 건, 엑셀레이터만 있고 브레이크 없는 차를 내모는 것과 다르지 않다. 빠르게 쓸수록 설계가 먼저다.

출처

더 많은 AI 트렌드를 Seedora 앱에서 확인하세요