앤트로픽 AI 코딩 플레이북 템플릿 모음: intent부터 review까지

앤트로픽이 2026년 8월 공개한 「The AI-native SDLC playbook」(Claude Academy 무료 강의 14개)을 영상으로 정리하면서 화면에 띄운 템플릿을 그대로 모았다. 예시 주제는 하나로 통일했다. 팝업 매장 대기 손님에게 입장 순서 알림 보내기. 내 프로젝트 주제로 바꿔서 그대로 쓰면 된다.

사이클은 한 줄이 아니라 원이다. 단계가 끝날 때마다 파일을 하나 남기고, 다음 단계는 그 파일을 읽고 시작한다.

단계	남기는 파일	사람이 하는 일
기획	intent.md	AI 인터뷰에 답하고, 파일을 읽고 고친 뒤 승인
설계	spec.md	“걸리는 부분”부터 읽고 판단
계획	plan.md	다른 모델에게 비평을 맡기고 질문 3개
짜기	CLAUDE.md · 스킬	완료 규칙을 미리 깔아둠
리뷰	review.md + 훅	기준은 문서로, 금지는 훅으로
배포	—	내보낼지 결정, 제일 깊은 페이지를 직접 열어봄
유지보수	새 intent.md	어떤 티켓을 고칠지 결정

1. 기획: intent.md

AI가 먼저 질문한다. 누가 쓰는지, 뭐가 불편한지, 어디까지 만들지, 성공하면 뭐가 달라지는지. 답이 끝나면 아래 파일 하나로 남긴다.

# intent: 대기 손님에게 입장 순서 알림 보내기

- 상태: 초안            <!-- 초안 | 승인 | 반려 -->
- 작성: 운영 담당 (문의 티켓 #128)
- 출처: 고객 문의        <!-- 아이디어 | 티켓 | 장애 알림 -->
- 승인: —               <!-- 승인한 사람 + 날짜 -->

## 문제
팝업 매장에서 줄 선 손님이 자기 차례가 언제인지 몰라서 자리를 못 떠요.
직원이 이름을 크게 불러야 하고, 놓친 손님은 처음부터 다시 줄을 서요.

## 원하는 결과
차례가 세 팀 앞으로 다가오면 손님 휴대폰으로 알림이 가요.
손님은 근처에서 기다리다가 알림을 받고 돌아오면 돼요.

## 영향받는 사람
- 손님: 대기 등록할 때 연락처를 남긴 사람
- 매장 직원: 호출 버튼을 누르는 사람

## 제약
- 문자 비용이 드는 방식은 승인 없이 쓰지 않는다
- 연락처는 입장 후 24시간 안에 지운다
- 지금 쓰는 대기 화면 구성은 바꾸지 않는다

## 범위 밖
- 예약 기능
- 손님이 순서를 미루는 기능

## 잘 됐는지 아는 법
- 호출 후 3분 안에 오는 손님 비율이 지금보다 높아진다
- 호출을 놓쳐서 다시 줄 서는 경우가 한 달 동안 줄어든다

## 아직 모르는 것
- 문자 대신 카카오 알림톡으로 보내도 되나?
- 세 팀 앞이 적당한가, 매장마다 다르게 해야 하나?

판단: 사람이 이 파일을 읽고 고친 다음에야 다음 단계로 넘어간다. AI가 잘못 알아들은 건 여기서 잡아야 뒤에서 덜 고생한다.

2. 설계: intent → spec 프롬프트

intent가 왜 만드는지라면, spec은 무엇을 만드는지다.

첨부한 intent.md를 읽고, 지금 코드베이스에 넣기 위한 요구사항과 설계 문서를 써줘.

- 우리 회사 규칙(디자인 가이드, 보안 정책, 화면 기준)이 담긴 스킬을 적용해서
  그 규칙에 맞는 설계가 되게 해줘.
- 결과는 spec.md 하나로 정리해서, 개발팀에 바로 넘길 수 있는 수준으로 써줘.
- 걱정되는 부분은 숨기지 말고 따로 적어줘.
  특히 규칙끼리 부딪혀서 둘 다 지킬 수 없는 곳이 있으면 꼭 표시해줘.

spec.md에 들어갈 것:

1. 화면과 동작: 사용자가 보는 것, 누르면 일어나는 일
2. 데이터: 새로 저장하는 것, 지우는 것, 얼마나 보관하는지
3. 지켜야 할 규칙: 어떤 스킬·정책을 적용했는지
4. 걱정되는 부분: 사람이 판단해야 할 곳 (← 여기부터 읽는다)
5. intent의 “아직 모르는 것”에 대한 답, 또는 다음으로 넘긴 이유

판단: 마지막 줄이 핵심이다. 말하지 않으면 AI는 애매한 걸 알아서 정해버린다. 걸리는 걸 따로 적게 하면 사람이 판단할 지점이 보인다.

3. 계획: plan.md

설계가 끝나도 바로 코딩하지 않는다. 클로드 코드의 플랜 모드(코드는 읽기만 하고 아무것도 안 바꾸는 모드)에서 계획부터 쓰게 한다.

# plan: 대기 손님 입장 알림 (intent 2026-10-12 승인본 기준)

## 바뀌는 파일
- `app/queue/notify.ts` (새 파일) — 알림 보내는 함수
- `app/api/queue/call/route.ts` — 호출 버튼 누를 때 알림 연결
- `tests/queue/notify.test.ts` (새 파일)

## 작업 순서
1. 알림 함수를 만든다. 실제 발송 대신 기록만 남기는 모드부터.
2. 호출 버튼에 연결한다. 세 팀 앞 손님을 찾아서 알림.
3. 입장 후 24시간 지난 연락처를 지우는 작업을 붙인다.

## 위험한 부분
- 같은 손님에게 알림이 두 번 갈 수 있다 → 보낸 기록을 남기고 한 번만 보낸다
- 연락처 삭제가 실패해도 아무도 모를 수 있다 → 실패하면 에러 기록에 남긴다

## 다 됐다는 증명
- `notify.test.ts`: 세 팀 앞에서만 보내는지, 두 번 안 보내는지
- 실제 매장 하나에서 기록 모드로 하루 돌려서 보낸 횟수 확인

계획을 받으면 그냥 넘기지 말고 묻는다.

• 이거 바꾸면 뭐가 망가질 수 있어?
• 제일 위험한 단계는 어디야?
• 안 고른 다른 방법은 뭐였어? 왜 안 골랐어?

함정: 계획을 짠 AI한테 그 계획의 검토까지 시키는 것. 자기가 쓴 답안지를 자기가 채점하면 늘 괜찮다고 나온다. 비평은 다른 회사 모델에게 맡긴다. oh-my-claudecode, oh-my-hermes 같은 오픈소스 하네스에 인터뷰 → 계획 → 비평 흐름이 들어 있다.

4. 짜기: CLAUDE.md 완료 규칙 · 스킬 · 동시에 여러 개

앤트로픽이 짜기 전에 챙기라는 세 가지.

1. CLAUDE.md — 프로젝트 폴더의 설명서. 테스트 돌리는 법, 자주 하는 실수를 적어두면 AI가 작업마다 먼저 읽는다.
2. 스킬 — 보안 점검 순서, 디자인 규칙처럼 반복되는 일을 문서로 묶어두면 AI가 비슷한 일에 꺼내 쓴다. 규칙이 바뀌면 스킬 하나만 고친다.
3. 동시에 여러 개 — 작업마다 AI를 따로 띄우고, 사람은 지휘하는 쪽으로 간다.

CLAUDE.md에 넣는 완료 규칙:

# CLAUDE.md — 완료 규칙

## 다 됐다고 말하기 전에
아래 세 가지를 직접 돌리고, 전부 통과해야만 "완료"라고 보고한다.

1. 테스트: `npm test`
2. 린트: `npm run lint`
3. 빌드: `npm run build`

하나라도 실패하면 고치고 다시 돌린다.
실패한 채로 "거의 다 됐어요"라고 보고하지 않는다.

## 테스트를 고치지 말 것
테스트가 실패하면 코드를 고친다.
테스트를 지우거나 기준을 낮춰서 통과시키지 않는다.

## 화면이 있는 작업이면
바뀐 화면을 캡처해서 같이 보여준다.

함정: 테스트가 “통과”라고 떴는데 사실 하나도 안 돌았던 적이 있다. 통합 테스트가 특정 데이터베이스에 연결됐을 때만 돌게 돼 있어서, 평소엔 건너뛰고 결과만 통과로 찍혔다. 통과했냐보다 그 테스트가 진짜 실행됐냐를 먼저 본다.

테스트는 아래층부터 채운다. ① 함수 하나 ② 버튼·입력창 같은 화면 조각 ③ 사용자가 처음부터 끝까지 써보는 흐름.

5. 평가: 모델을 바꿔도 안 망가지게

AI한테 맡겨서 잘 끝났던 실제 작업 20~50개를 모아 시험지로 만들고, 모델이나 규칙을 바꿀 때마다 자동으로 돌린다. 잘 되던 게 조용히 망가지는 걸 바로 알 수 있다.

솔직히 나는 아직 이건 안 하고 있다. 지금 제일 먼저 해야겠다고 생각하는 부분이다.

6. 리뷰: review.md + 훅

# review.md — 리뷰 기준

## 꼭 잡을 것 (발견하면 머지 막음)
- 버그: 의도와 다르게 동작하는 코드
- 보안: 비밀번호·키가 코드에 들어감, 로그인 없이 접근 가능
- 규칙 위반: plan.md에 없는 범위를 바꿈, 회사 정책 어김

## 따로 묶을 것 (머지는 막지 않음)
- 이름, 줄바꿈, 주석 같은 사소한 것
- 한 PR에 다섯 개까지만 적고 나머지는 생략

## 보지 말 것
- 자동으로 만들어진 파일 (`generated/`, 잠금 파일)
- 이번 PR에서 안 바뀐 줄

## 적는 방식
발견한 것마다 앞에 붙인다: [버그] [보안] [규칙] [사소]
근거가 되는 줄 번호를 같이 적는다.

처음엔 짧게 시작하고, 사람이 리뷰에서 반복해서 지적한 걸 하나씩 추가한다.

함정: 규칙을 문서로만 적어두면 안 지켜진다. 브랜치 규칙을 문서에만 써뒀더니 규칙을 건너뛴 PR이 10건 연속 들어왔고, 그사이 중간 검증용 브랜치가 통째로 사라졌다. 지켜야 하는 건 훅(AI가 특정 행동을 하려는 순간 막는 장치)이나 CI로 자동으로 떨어뜨린다. 부탁하지 않고 막는다.

7. 배포: 내보내기 전과 후

• 전: 빌드가 깨지면 AI가 로그를 읽고 원인을 고치는 PR을 올린다. 데이터베이스에서 테이블이나 칸을 지우는 변경은 배포를 멈추게 해둔다.
• 후: AI가 에러 기록을 보고 갑자기 터지는 게 있는지 확인한다. 터지면 되돌리고 원인을 고친다. 되돌리는 방법은 미리 연습해둔다. 급할 때 처음 해보면 안 된다.

함정: 블로그 상세 페이지가 전부 에러를 냈는데, 목록 페이지가 멀쩡해서 배포 확인을 통과한 적이 있다. 배포 확인은 제일 잘 되는 페이지가 아니라 제일 깊은 페이지로 한다.

8. 유지보수: 사이클 닫기

에러가 반복되거나 사용자가 자꾸 막히는 곳을 AI가 주기적으로 읽고, 고칠 만한 걸 찾으면 새 intent를 쓴다. 그게 다시 첫 단계 기획으로 들어간다.

내가 돌리는 방식:

1. 매일 오전 9시, AI가 에러 기록과 사용자 행동 데이터를 읽는다.
2. 고칠 만한 걸 노션 칸반 보드의 “할 일”에 티켓으로 올린다.
3. AI가 알아서 고치지는 않는다. 어떤 걸 고칠지는 사람이 정한다.
4. 사람이 티켓을 “진행 중”으로 옮겨야 그때 AI가 작업을 시작한다.

사람이 꼭 판단하는 곳 세 군데

1. 어떤 걸 만들고 고칠지 정한다.
2. 실제 서비스에 내보낼지 정한다.
3. 내보낸 다음 제일 깊은 페이지를 직접 열어본다.

전부 한 번에 할 필요는 없다. 계획부터 먼저 쓰게 하는 것 하나만 해도 확 달라진다.

출처

• 앤트로픽 「The AI-native SDLC playbook」 (2026-08-21) — https://claude.com/blog/the-ai-native-sdlc-playbook
• Claude Academy 무료 강의 14개 — https://academy.claude.com/courses/ai-native-sdlc-playbook
• 구성 참고: Eric Tech 「Claude Code: The Complete AI-Native SDLC Guide」 — https://www.youtube.com/watch?v=6CaQ9ZFuuKI