앤트로픽 AI-native SDLC 플레이북 실무 적용: intent부터 review까지 템플릿 도입 가이드

앤트로픽(Anthropic)이 공식 아카데미를 통해 발표한 「The AI-native SDLC playbook」은 인공지능 코딩 에이전트를 단순한 자동완성 도구가 아닌 소프트웨어 개발 생명주기(SDLC) 전반의 협업 주체로 정의한다. 이 플레이북의 핵심은 프롬프트 몇 줄로 코드를 한 번에 뽑아내는 것이 아니라, 각 개발 단계마다 정형화된 마크다운 파일을 생성하고 다음 단계가 그 파일을 읽어 점진적으로 구체화하는 순환형 폐쇄 루프(Closed Loop) 구조에 있다.

국내 실무 빌더인 낭만빌더 김스듴이 정리한 앤트로픽 AI 코딩 플레이북 템플릿 모음에서는 이를 intent.md부터 review.md까지 이어지는 표준 템플릿 세트로 체계화했다. 이 글에서는 Node.js 22.x 및 Claude Code 0.2.x 환경을 기준으로 이 템플릿들을 실제 저장소에 도입하고 파이프라인으로 연결하는 구체적인 절차와 실무 검증 기준을 정리한다.

AI 네이티브 개발 생명주기(SDLC)의 순환 구조와 핵심 산출물

기존 폭포수나 애자일 방식과 달리, AI 네이티브 SDLC에서는 개발자가 직접 코드를 타이핑하기보다 각 단계의 경계 조건을 정의하고 에이전트가 작성한 산출물을 승인하는 역할을 맡는다. 한 단계가 종료되면 반드시 파일이 하나 생성되며, 다음 단계의 에이전트는 해당 파일만을 컨텍스트로 전달받아 작업을 이어간다.

이 흐름은 직선형 파이프라인이 아니라, 운영 단계에서 발생한 에러와 요구사항이 다시 새로운 intent.md로 유입되는 원형 구조를 이룬다.

AI-native SDLC 5단계 적용 절차

실제 프로젝트에 AI 네이티브 개발 주기를 안착시키려면 아래 5단계를 순서대로 거친다.

1. 기획(intent.md) 작성: 대화형 인터뷰를 통해 사용자의 핵심 문제와 시스템 제약, 제외 범위를 확정하고 승인한다.
2. 설계(spec.md) 도출: 사내 규칙과 정책을 연동해 아키텍처를 정의하고, 충돌 지점(우려 사항)을 사전에 격리한다.
3. 계획(plan.md) 수립: Claude Code 플랜 모드에서 수정 대상 파일과 검증 기준을 도출하고 외부 모델로 비평한다.
4. 구현(CLAUDE.md) 통제: 린트, 테스트, 빌드 통과를 완료의 필수 선행 조건으로 지정하고 코드를 작성한다.
5. 리뷰(review.md)와 차단: 4단계 분류 체계로 코드를 점검하고 Git 훅을 통해 미흡한 코드의 머지를 강제 차단한다.

1. 기획 단계: 요구사항 인터뷰와 intent.md 파일 작성

개발 작업을 시작하기 전, 에이전트에게 구현 지시 대신 문제 정의 인터뷰를 요구한다. 에이전트가 "누구를 위한 기능인가", "기존의 어떤 병목을 해결하는가", "제외할 범위(Out of scope)는 무엇인가"를 질문하고, 사용자의 답변을 취합해 프로젝트 루트에 intent.md를 작성한다.

# intent: 대기 고객 대상 순번 알림 발송 시스템

- 상태: 초안 (초안 | 승인 | 반려)
- 출처: 고객 지원 티켓 #204
- 승인자: 프로덕트 매니저 (2026-10-24)

## 해결할 문제
오프라인 팝업 대기열에서 본인 호출 시점을 알 수 없어 매장 앞 혼잡이 가중됨.

## 목표 결과
입장 3팀 전 시점에 카카오 알림톡 또는 SMS로 복귀 안내 메시지가 발송됨.

## 시스템 제약 사항
- 건당 발송 비용이 발생하는 외부 메시징 API 호출은 사전 승인 필요
- 고객 연락처 정보는 서비스 완료 후 24시간 이내 데이터베이스에서 물리 파기
- 현재 운영 중인 프론트엔드 대기 번호표 UI 레이아웃은 수정하지 않음

## 제외 범위 (Out of scope)
- 고객 임의 순번 미루기 기능
- 사전 예약 및 시간 지정 방문 결제

작성된 파일은 사람이 직접 읽고 "제외 범위"와 "제약 사항"이 누락되지 않았는지 확인한 후 상단의 상태를 승인으로 변경한다.

2. 설계 단계: intent를 기반으로 spec.md 프롬프트 실행

승인된 intent.md를 바탕으로 엔지니어링 세부 사항을 결정하는 spec.md를 생성한다. 이때 가장 중요한 점은 AI에게 "판단이 모호하거나 규칙이 충돌하는 지점"을 숨기지 말고 드러내도록 지시하는 것이다.

루트에 위치한 intent.md를 정독하고, 현재 코드베이스 구조에 맞춘 엔지니어링 설계를 작성해 줘.

- 프로젝트 내부 보안 정책 및 데이터 처리 가이드라인 스킬을 준수할 것.
- 데이터 생성, 수정, 삭제(TTL) 수명주기를 데이터베이스 스키마 관점에서 기술할 것.
- 규칙끼리 상충되어 단일 방식으로 해결할 수 없는 병목이나 우려 지점은 '검토 필요 사항'에 별도로 명시할 것.
- 산출물은 spec.md 파일로 저장할 것.

생성된 spec.md의 본문 중 다른 부분보다 '검토 필요 사항(Worrisome points)' 섹션을 먼저 읽어야 한다. 예를 들어 "연락처 자동 삭제 배치 작업 실패 시 재시도 전략 부재"와 같은 지점을 사전에 파악하여 설계 단계에서 사람이 개입해 의사결정을 내린다.

3. 계획 단계: Claude Code 플랜 모드와 plan.md 수립

설계가 확정되어도 에이전트에게 바로 소스 코드를 수정하게 해서는 안 된다. Claude Code의 읽기 전용 모드인 플랜 모드(Shift + Tab 키 입력)로 진입한 후 변경 계획서를 작성하도록 명령한다.

# plan: 대기 고객 알림 및 개인정보 파기 파이프라인

## 수정 및 생성 대상 파일
- `src/services/notification.ts` (신규): 메시지 발송 추상화 인터페이스
- `src/controllers/queue.controller.ts`: 3팀 전 도달 이벤트 트리거 연결
- `src/jobs/cleanup.job.ts` (신규): 24시간 경과 개인정보 물리 삭제 스케줄러
- `tests/services/notification.test.ts` (신규): 멱등성 및 중복 발송 방지 검증

## 세부 실행 순서
1. 발송 로직의 mock 모드를 먼저 구현하여 테스트 통과를 확인한다.
2. 큐 상태 전이 이벤트 훅에 알림 발송 트리거를 연결한다.
3. 데이터 만료 스케줄러를 cron 태스크로 등록한다.

## 위험 요소 및 완화 방안
- 동일 고객 대상 메시지 중복 발송 위험: Redis 키 기반 분산 락(TTL 60초) 적용

계획이 나오면 해당 계획을 수립한 동일한 AI에게 "이 계획이 적절하냐"고 물어서는 안 된다. 이는 스스로 쓴 답안지를 자가 채점하는 것과 같으므로, 다른 모델 엔진이나 서브에이전트에게 계획서를 전달해 비판적 결함을 찾도록 교차 검증을 진행한다.

4. 구현 단계: CLAUDE.md 완료 규칙 고정

실제 코딩 단계에 들어가기 전, 프로젝트 루트의 CLAUDE.md 파일에 "어떤 조건을 만족해야 작업을 완료했다고 보고할 수 있는지"를 하드코딩해 둔다.

# CLAUDE.md — 작업 완료 검증 규칙

## 작업 종료 전 필수 점검 항목
모든 코드 수정 후 아래 명령을 차례대로 수행하고, 에러가 0건이어야 한다.

1. 정적 검사: `npm run lint`
2. 단위 및 통합 테스트: `npm test`
3. 프로덕션 빌드: `npm run build`

## 금지 사항
- 테스트 실패를 해결하기 위해 기존 테스트 단언문(assert)을 임의로 삭제하거나 기준을 완화하지 않는다.
- UI 변경 작업이 포함된 경우, 변경 전후의 렌더링 스크린샷 증빙을 제시한다.

에이전트가 "테스트 통과"를 보고하더라도 모의 객체(mock) 설정으로 인해 실제 테스트 코드가 건너뛰어졌는지(skipped) 반드시 실행 로그를 확인해야 한다. 상세한 코드 리뷰 수칙은 AI 생성 코드 리뷰 가이드를 참고한다.

5. 리뷰 단계: review.md 기준과 Git 훅을 통한 차단

코드가 작성된 후에는 review.md에 정의된 4단계 심각도 기준에 따라 검토를 진행한다. 말로만 작성된 가이드라인은 대화가 길어지면 무시되므로, Git 훅을 결합해 머지를 원천 차단한다.

# review.md — 머지 심각도 분류 기준

## 차단 대상 [BLOCK]
- SQL Injection, 민감정보 하드코딩 등 보안 취약점
- intent.md 및 plan.md에 명시되지 않은 임의의 아키텍처 변경
- 테스트 커버리지 하락 또는 기존 테스트 스위트 주석 처리

## 권고 대상 [WARN]
- 함수 및 변수 네이밍 컨벤션 미준수 (PR당 최대 5개로 제한)
- 불필요한 주석 및 디버깅 로그 잔재

이러한 차단 규칙을 강제하기 위해 .husky 또는 로컬 .git/hooks/pre-commit 스크립트를 구성한다. 자세한 훅 구성 기법은 Claude Code 훅 설정 가이드에서 확인할 수 있다.

#!/bin/sh
# .git/hooks/pre-commit
echo "=== [AI-SDLC] Pre-commit 품질 검사 시작 ==="
npm run lint || { echo "[ERROR] 린트 검사 실패"; exit 1; }
npm test || { echo "[ERROR] 테스트 실패 코드는 커밋할 수 없습니다"; exit 1; }

사람이 직접 통제해야 하는 3대 검증 지점과 운영 실패 방지책

AI 에이전트의 자율성이 높아질수록 인간 엔지니어의 통제 지점은 더욱 명확해져야 한다. 앤트로픽 가이드와 현장 사례가 공통적으로 경고하는 핵심 판단 영역은 다음 세 가지다.

첫째, 무엇을 만들고 무엇을 거절할지 결정하는 의사결정권이다. 에이전트는 들어온 요구사항을 거절하지 않고 어떻게든 구현하려는 경향이 있다. 복잡도를 높이는 불필요한 기능 요청을 intent.md의 "제외 범위"로 밀어 넣는 작업은 도메인 책임자만이 수행할 수 있다.

둘째, 프로덕션 배포 전 파괴적 변경의 승인권이다. 데이터베이스 테이블 칼럼 삭제, 권한 체계 재구성, 외부 결제 웹훅 라우트 변경 등 롤백 비용이 극단적으로 큰 작업은 에이전트가 배포 파이프라인을 트리거할 수 없도록 CI 환경에서 수동 승인(Manual approval gate)을 걸어두어야 한다.

셋째, 배포 후 '가장 깊은 경로의 상세 페이지' 직접 검증이다. 단순 헬스체크(/healthz)나 메인 페이지는 캐시된 응답이나 단순 렌더링으로 인해 정상 상태를 반환하기 쉽다. 실제 데이터베이스 트랜잭션과 복잡한 상태 처리가 일어나는 가장 깊은 페이지를 사람이 직접 브라우저로 열어보고 검증을 완료해야 운영 장애를 방지할 수 있다.

도입 전 확인해야 할 프로젝트 구성 체크리스트

AI 네이티브 SDLC 템플릿을 저장소에 올바르게 안착시키기 위해 단계별 점검 사항을 확인한다.

• intent.md에 문제 정의, 정량적 성공 지표, 제외 범위가 명확히 기술되었는가?
• 설계 프롬프트에서 사내 보안 가이드라인 스킬을 호출하고 있는가?
• plan.md가 플랜 모드에서 생성되었으며 파일 변경 단위가 세분화되었는가?
• CLAUDE.md의 완료 선행 조건으로 린트, 테스트, 빌드가 등록되었는가?
• 커밋 및 푸시 단계에서 규칙 위반을 감지하는 Git 훅 스크립트가 실행 권한을 가지고 있는가?

위 요소들이 유기적으로 결합될 때 비로소 에이전트의 환각으로 인한 기술 부채를 방어하고, 일관된 품질 기준을 유지하며 빠른 프로덕트 딜리버리를 달성할 수 있다.