CLAUDE.md 구축 실습

새 Claude 세션을 열 때마다 나는 같은 설명부터 반복했다. “이 프로젝트는 G: 드라이브에 있어서 여기서 npm을 실행하면 안 됩니다.” “지금 NHN KCP 실결제 심사 중입니다.” “가격과 결제 로직은 내 승인 없이 바꾸면 안 됩니다.” AI가 코드를 쓰는 시간보다 프로젝트의 사정을 다시 인수인계하는 시간이 더 아깝게 느껴졌다.

그릿 모먼츠 Task 7의 표면적인 과제는 나에게 맞춘 CLAUDE.md 초안 한 개를 만드는 것이었다. 하지만 관련 책을 읽고 나니 이 파일은 자기소개서도, 긴 만능 프롬프트도 아니었다. 세션이 바뀌어도 일을 이어가고, 위험한 행동을 멈추고, 완료 여부를 같은 기준으로 판단하게 만드는 작은 운영체계에 가까웠다.

이번 과제에서 실제로 만든 것

글로벌·프로젝트 CLAUDE.md, 상태와 결정을 분리한 기억 파일, 시작·검토·배포용 명령을 HeoBrain에 적용했다. 새 세션에서 /작업시작을 실행해 어제의 맥락이 이어지는지도 스트레스 테스트했다.

1. 책에서 가져온 것은 문장이 아니라 구조였다

『팀이 필요하다. 사람 말고.』에서 가장 크게 남은 생각은 지식이 대화 세션이 아니라 파일에 살아야 한다는 것이었다. 프롬프트는 요청할 때마다 다시 입력하지만, 프로토콜은 한 번 만들어 두면 새 세션이 먼저 읽고 같은 순서로 움직인다. 『하네스 엔지니어링 실전 플레이북』도 고성능 모델 하나보다 모델을 둘러싼 역할 분리, 검증 계약, 파일 기반 인계, 낡은 규칙 점검이 프로덕션 품질을 만든다고 설명한다.

나는 이 내용을 세 가지 원칙으로 번역해 HeoBrain에 적용했다.

책의 원칙과 HeoBrain 적용 내용

책에서 얻은 원칙	내가 적용한 방식	해결하려던 문제
대화보다 파일에 남긴다	progress.md, MEMORY.md, decisions.md, FAILURES.md로 정보를 분리했다.	세션이 바뀔 때마다 현재 상태와 과거 결정을 다시 설명하는 문제
생성과 평가를 분리한다	Gen/Eval 분리의 v0로, 구현 세션이 스스로 PASS를 선언하지 않고 별도 세션의 /검토 또는 /code-review가 검사하게 했다.	자기가 만든 결과를 자기가 후하게 채점하는 문제
완료 조건을 먼저 계약한다	타입체크, 시크릿 스캔, C:\TEMP 클론 빌드, 돈 로직 시나리오, 라이브 확인을 게이트로 적었다.	코드만 수정하고 “완료”라고 말하는 문제
규칙도 노후화된다고 본다	PG사·FAQ·명령어·경로를 분기마다 확인하는 신선도 점검을 넣었다.	코드는 정상인데 안내 문구와 운영 지식이 오래되는 문제

좋은 AI를 기다리는 것보다, 지금의 AI가 실수하기 어렵고 일을 이어가기 쉬운 환경을 만드는 편이 내 문제에 더 직접적인 해법이었다.

2. 왜 HeoBrain에는 일반 템플릿이 통하지 않았나

HeoBrain은 오픽·영단어·영문법·AWS 학습 자료를 판매하는 실제 서비스다. Next.js 16, TypeScript, Supabase, PortOne V2와 NHN KCP를 사용하고 있으며, 지금은 실결제 심사를 진행하고 있다. 이 프로젝트에서 AI가 놓치면 안 되는 맥락은 “깔끔한 코드를 작성하라” 같은 추상적인 문장이 아니었다.

• Google Drive가 마운트된 G: 리포지토리에서는 파일 잠금 문제 때문에 npm 빌드를 실행하지 않는다. 검증용 코드는 C:\TEMP로 복사한다.
• 결제 검증, 환불, 가격, 사업자 정보, 개인정보, 사용자 데이터 삭제, .env 수정은 사람이 결정하는 L4 작업이다.
• 가격이 0원이면 결제창을 띄우지 않고 무료 수령 흐름으로 보내야 한다.
• 같은 payment_id의 중복 처리 차단과 서버의 결제 금액 검증을 완화하면 안 된다.
• push하면 Vercel이 자동 배포되므로, push 자체가 프로덕션 변경에 해당한다.

이런 규칙은 인터넷에서 복사한 CLAUDE.md 템플릿으로는 나올 수 없다. 내가 운영하면서 겪은 제약, 지금 진행 중인 심사, 돈이 움직이는 경계가 들어가야 비로소 “허태웅이라는 엔지니어의 파일”이 된다.

3. 한 파일에 다 넣지 않고 기억을 계층으로 나눴다

첫 초안에서 가장 먼저 발견한 문제는 progress.md와 MEMORY.md가 빠져 있었다는 점이다. CLAUDE.md만 길게 만들면 모든 정보가 한 파일에 섞이고, 오늘의 상태가 내일의 상수처럼 남는다. 그래서 정보의 수명과 역할에 따라 파일을 분리했다.

HeoBrain 기억 계층

파일	담는 내용	실제 예시
글로벌 CLAUDE.md	잘 바뀌지 않는 정체성·목표·공통 원칙	AI를 팀처럼 지휘하는 1인 개발팀, 한국어 소통, 검증 증거 우선
프로젝트 CLAUDE.md	HeoBrain의 기술·도메인·권한·완료 기준	KCP 결제, G: 빌드 제약, L1~L4, 돈 로직 시나리오 5
progress.md	지금 하는 일, 막힌 일, 다음 세션의 첫 행동	Resend 인증, KCP 심사 항목, 900원 실결제 준비
MEMORY.md	최근 결정 요약, 기술 부채, 환경 정보	비회원 구매 도입, 주문 메일 미발송 부채, 레거시 문서
docs/decisions.md	배경·선택지·결정·근거·결과를 남기는 ADR	LangChain 대신 얇은 SDK 직결 선택, 비회원 구매 도입 근거
docs/FAILURES.md	장애의 증상·원인·조치·교훈	latest 의존성 빌드 붕괴, 뉴스레터 가짜 성공, 환불 API 인증 누락

이 구조에서 CLAUDE.md는 모든 지식을 담는 창고가 아니다. 무엇을 먼저 읽고, 어느 파일을 진실의 원천으로 삼고, 어떤 기준으로 행동할지를 알려 주는 입구다. 현재 상태는 progress.md, 오래 남길 결정은 ADR, 실패에서 얻은 교훈은 FAILURES.md에 둔다.

4. AI 초안을 그대로 받지 않고 내가 바꾼 것

이번 과제의 중요한 부분은 AI가 작성한 문서를 저장한 일이 아니라, 내가 운영자로서 틀린 부분을 찾아 경계를 다시 정한 일이었다.

1.   빠진 기억 계층을 복구했다. 첫 초안에 없던 progress.md와 MEMORY.md를 추가하고, 상세 결정과 실패 로그까지 연결했다.
2.   스택을 유행 목록이 아니라 의사결정으로 바꿨다. 후보를 나열하고 끝내지 말고 프로젝트 규모와 디버깅 비용의 trade-off를 설명한 뒤 추천 하나를 고르게 했다. AI 서비스 기본 방향은 두꺼운 LangChain 추상화보다 Vercel AI SDK와 Claude Agent SDK의 직접 연결로 정했다.
3.   TypeScript 프로젝트의 네이밍을 바로잡았다. 함수 이름을 Python식 snake_case가 아니라 기존 코드와 같은 camelCase로 확정했다.
4.   자율성보다 승인선을 먼저 그었다. L3는 계획을 먼저 보고하고 승인 후 착수, L4는 결제·환불·가격·개인정보·프로덕션 DB·.env처럼 사람이 반드시 결정하도록 바꿨다.
5.    생성과 검토를 나누는 v0를 시작했다. 구현한 세션은 자기 코드를 통과 판정하지 못한다. 결제·인증·DB처럼 위험한 변경은 별도 세션의 독립 검토와 실제 시나리오 검증을 모두 거치게 했다. 전용 평가 에이전트와 고정 루브릭은 다음 단계다.
6.   도구의 실제 제약도 확인했다. 새로 만든 슬래시 명령은 작성 중인 세션이 아니라 새 세션부터 인식된다는 점을 스트레스 테스트 과정에서 확인했다.

여기서 배운 역할 분담은 분명했다. AI는 초안을 빠르게 만들고 누락 가능성을 넓게 탐색한다. 나는 실제 코드베이스와 사업 맥락에 비춰 사실을 확인하고, 무엇을 자동화하면 안 되는지 결정한다. 1인 개발팀에서 사람의 핵심 업무는 타이핑이 아니라 설계·검증·운영 판단이었다.

5. 새 세션 스트레스 테스트: 한마디로 어제 일을 이어갈 수 있나

파일을 만든 뒤에는 같은 세션에서 “잘 됐다”고 평가하지 않았다. 새 세션을 열고 /작업시작만 입력했다. 이 명령은 progress.md → MEMORY.md → decisions.md → FAILURES.md → 최근 커밋 순서로 읽고, 이어서 할 일·사람의 액션이 필요한 막힘·오늘의 제안을 구분해 보고하도록 설계했다.

스트레스 테스트 전후 비교

확인 항목	파일이 없을 때	/작업시작 실행 후
현재 작업	내가 KCP 심사와 실결제 준비를 다시 설명해야 한다.	Task 7 마무리와 900원 실결제·비회원 결제 준비를 이어서 제시했다.
막힌 일	AI가 할 일과 내가 처리할 일이 한 목록에 섞인다.	Resend 인증과 KCP 심사 항목을 ‘사장님 액션 대기’로 분리했다.
최근 맥락	지난 작업의 변경 흐름을 내가 요약해야 한다.	최근 5개 커밋과 라이브 확인 상태를 먼저 요약했다.
권한 경계	push나 결제 변경을 바로 시도할 위험이 있다.	push는 자동 배포이므로 내 실행 항목으로 남기고, AI는 다음 작업을 제안하는 데서 멈췄다.

회고 — 이 파일이 없었으면?

AI는 “무엇을 도와드릴까요?”로 시작했을 것이고, 나는 G: 드라이브에서 npm이 안 된다는 것과 KCP 심사 중이라는 맥락을 또 설명했을 것이다. 실제로는 /작업시작 한마디에 Resend 미설정, 심사 대기, 다음 실결제 준비가 이어졌다. 특히 막힌 일이 내 액션 대기 항목으로 분리되면서 AI가 할 일과 내가 할 일이 바로 구분됐다. 프롬프트를 다듬는 것보다 프로토콜 파일이 세션 사이의 기억을 잇는 효과가 더 컸다.

물론 한 번의 테스트가 이 하네스의 안전성을 증명하는 것은 아니다. 다만 목표였던 “새 세션에서 맥락을 이어받고, 사람과 AI의 다음 행동을 구분하는가”에는 성공했다. 이것은 막연한 생산성 수치보다 내가 직접 확인한 변화다.

6. 현재는 v1이다: 적어 둔 규칙과 강제 장치는 다르다

현재 구현을 다섯 계층의 완성형이라고 부르면 과장이다. 지식·기억 계층은 파일로 갖췄고, 역할·방어 규칙도 문서에 넣었지만, 실제 전용 에이전트와 자동 차단 장치는 아직 일부만 존재한다. CLAUDE.md에 “하지 말라”고 쓰는 것은 행동 지침이지 물리적인 보안 장치가 아니다.

현재 하네스와 다음 단계

계층	현재 v1	다음 단계
지식	글로벌·프로젝트 CLAUDE.md, ADR	규칙이 길어지면 경로별 파일로 분리
기억	progress.md, MEMORY.md, FAILURES.md	장애가 반복되면 교훈을 자동 검사 또는 금지 규칙으로 승격
역할	단일 구현 세션과 별도 검토 세션으로 Gen/Eval 분리의 v0 시작	.claude/agents/에 code-reviewer·qa 역할 추가
방어	타입체크·시크릿 스캔·클론 빌드·돈 로직 시나리오	pre-commit 훅으로 시크릿과 타입 오류를 자동 차단
자율	/헬스체크 수동 실행, L4는 사람 승인	일일 헬스체크와 PG 결제 대사 크론, 이상 등급별 알림

여기서 자율화의 목표는 AI에게 무조건 많은 권한을 주는 것이 아니다. 정상일 때는 조용히 점검하고, 실패하면 기록에서 재개하며, 돈과 개인정보가 걸린 경계에서는 반드시 사람을 호출하는 구조가 목표다. 또한 분기마다 끝난 심사 상태, 죽은 명령어, 바뀐 PG사와 안내 문구를 걷어 내야 이 파일이 살아 있는 운영 문서로 남는다.

7. 이번 과제의 결론

처음에는 CLAUDE.md를 “AI에게 나를 설명하는 파일” 정도로 생각했다. 과제를 끝낸 뒤에는 정의가 달라졌다. 이 파일은 내가 반복해서 내리는 판단을 프로젝트가 기억하게 만드는 운영 계약의 입구다.

1인 개발팀은 AI 창을 여러 개 띄우는 것으로 완성되지 않는다. 누가 만들고 누가 검토하는지, 어떤 상태를 어디에 남기는지, 무엇을 통과해야 완료인지, 어느 순간 사람이 결정권을 가져오는지가 분명해야 한다. 이번 Task 7에서 만든 것은 그 구조의 v1이다.

프롬프트는 한 번의 답을 바꾸지만, 프로토콜은 다음 세션의 출발점을 바꾼다.

다음 과제는 더 긴 지침을 쓰는 일이 아니다. 역할 에이전트를 실제로 분리하고, 중요한 규칙을 훅과 테스트로 강제하며, 실패할 때마다 교훈을 구조에 누적하는 일이다. 그렇게 해야 AI를 “잘 쓰는 사람”을 넘어, AI가 일할 수 있는 팀을 설계하는 엔지니어에 가까워질 수 있다.

읽고 적용한 자료

• Team Grit, 『팀이 필요하다. 사람 말고.』 — 프로토콜과 프롬프트, 다섯 계층, progress.md, Gen/Val 분리(PDF pp.13~32, 37~40)
• Team Grit, 『하네스 엔지니어링 실전 플레이북』 — Generator/Evaluator 분리, 검증 계약, 파일 기반 인계, 신선도 감사(PDF pp.10~14, 22~24, 39~46, 72~80)
• 『Claude Code로 1인 개발팀 만들기』 — 글로벌·프로젝트 CLAUDE.md, 역할·권한·검증·실패의 규칙화(PDF pp.21~23, 43~55, 97~124, 147~162)
• 『링크드인 온보딩 가이드』 — 실제 경험 하나를 훅·상황·시도·깨달음·질문으로 정리하는 글쓰기 구조(PDF pp.38~42)

이 글은 책의 일반론을 요약한 글이 아니라, 2026년 7월 HeoBrain 프로젝트에 Task 7을 직접 적용하고 새 세션에서 검증한 경험을 바탕으로 작성했다. 책 속 사례 수치는 보편적 성과로 일반화하지 않고, 내 프로젝트에서 확인한 결과만 서술했다.