A Better CLAUDE.md Template for SaaS Founders

개요

AI 코딩 에이전트는 단순히 코드 저장소의 명령을 따르는 것을 넘어 제품의 현실을 이해해야 하며, 이를 위해 CLAUDE.md 템플릿은 엔지니어링 규칙뿐만 아니라 제품 맥락을 포함하여 코드 생성 에이전트의 의사결정에 방향을 제시합니다.

주요 내용

- CLAUDE.md의 이중 역할: CLAUDE.md는 코드 저장소의 작동 방식을 설명하는 '엔지니어링 메모리'와 제품이 무엇을 증명하려 하는지를 설명하는 '제품 메모리'의 역할을 모두 수행해야 합니다.
- 기존 CLAUDE.md의 한계: 많은 CLAUDE.md 파일은 주로 pnpm 사용, 테스트 실행, 컴포넌트 위치 등의 엔지니어링 규칙에 집중하지만, 제품의 핵심 가치나 시장 검증에 대한 맥락이 부족하여 잘못된 제품 표면을 구축할 위험이 있습니다.
- 구조화된 CLAUDE.md 템플릿 제안:
1. 제품 현실 (Product Reality): 제품, 대상 고객, 핵심 문제, 현재 단계, 현실적 제약(예: bootstrap SaaS vs. VC-scale startup), 주요 사용자, 경제적 구매자, 현재 대안, 시장 범위를 명확히 정의합니다.
2. 현재 베팅 (Current Bet): 현재 집중하는 좁은 워크플로우 또는 사용 사례, 다음 릴리스에서 증명해야 할 핵심 가설, 최적화할 대상(예: 활성화, 지불 의사) 및 아직 최적화하지 않을 대상(예: 확장, 엔터프라이즈 기능)을 명시합니다.
3. 구축해야 할 것 / 구축하지 말아야 할 것 (Must Build / Must Not Build): 필수적으로 구축해야 할 핵심 기능과 현재 단계에서 피해야 할 기능(예: 팀 관리, 고급 분석)을 구분합니다.
4. 증거 목표 (Evidence Goal): 릴리스를 통해 검증하고자 하는 특정 가설(예: 특정 사용자가 창업자의 도움 없이 가치를 얻을 수 있는지), 주요 성공 신호, 보조 신호, 그리고 방향 전환 또는 중단 트리거를 설정합니다.
5. 엔지니어링 규칙 (Engineering Rules): 스택(프레임워크, 언어, 데이터베이스 등), 중요한 디렉토리 구조, 설치, 타입체크, 린트, 테스트, 빌드 등 구체적인 규칙을 정의합니다. "깨끗한 코드"와 같은 모호한 지침 대신, 실제 의사결정에 영향을 미치는 규칙(예: 간단한 변경은 서버 액션 선호, 기존 UI 컴포넌트 활용)을 포함합니다.
6. 안전 경계 (Safety Boundaries): 프로덕션 데이터베이스 마이그레이션 수정, 파괴적인 데이터베이스 명령 실행, 결제 또는 Stripe 로직 변경, 인증/권한 동작 변경 등 명시적 승인 없이 절대로 해서는 안 되는 작업을 명시합니다.
7. 필수 워크플로우 (Required Workflow): 비정형적인 변경 시, 제품 제약 사항 재확인, 파일 검사, 계획 제안, 위험 및 테스트 식별, 승인된 부분만 구현, 필요한 검사 실행, 변경 사항 요약 등의 단계를 따르도록 합니다.
- CLAUDE.md에 포함하지 말아야 할 내용: 상세한 PRD, 시장 조사 보고서, 경쟁사 테이블, 고객 인용구, 로드맵 전체, 디자인 시스템 토큰, 모든 보안 정책 등은 별도 문서로 관리하여 CLAUDE.md를 간결하게 유지합니다.
- 첫 프롬프트의 중요성: CLAUDE.md 파일을 생성한 후 바로 코드 생성을 시작하기보다, 파일 내용을 읽고 요약하게 하여 목표 고객, 현재 베팅, 안전 경계 등을 확인하고 잠재적 모순이나 누락된 세부 정보를 식별하는 보정 단계를 거치는 것이 효과적입니다.
- CLAUDE.md의 본질: CLAUDE.md는 단순한 코드 지침 파일이 아니라, 고객, 베팅, 증거 목표, 제품 범위, 엔지니어링 규칙, 안전 경계 간의 정렬을 위한 '정렬 파일'입니다.

시사점

잘 설계된 CLAUDE.md 템플릿은 AI 코딩 에이전트가 실질적인 제품 프레임워크 내에서 작동하게 함으로써, 겉보기에는 완성되었으나 실제로는 적은 학습만 제공하는 제품을 구축하는 대신, 실제 시장 가설을 검증하는 데 훨씬 더 유용하게 활용될 수 있습니다.