intent.md 작성법과 사용 예시, 앤트로픽 AI 네이티브 SDLC 플레이북 정리

Claude Code에 말로 시키면 코드가 나온다는 것은 이제 많은 분이 알고 있습니다. 그런데 같은 일을 시켜도 어떤 날은 한 번에 되고 어떤 날은 세 번을 고쳐야 하는 이유는 잘 모릅니다. 이유는 대개 모델이 아니라 시키는 쪽에 있는데, 무엇을 왜 만들지 정리하지 않은 채 "만들어 줘"부터 말하면 고칠 때마다 요구가 조금씩 바뀌어서 결과물도 매번 달라집니다.

앤트로픽이 2026년 8월 21일에 공개한 AI 네이티브 SDLC 플레이북은 이 문제를 문서 순서로 풉니다. SDLC(Software Development Life Cycle), 즉 소프트웨어 개발 수명 주기는 기획부터 유지보수까지 소프트웨어가 거치는 전체 단계를 가리키는 말입니다. 플레이북의 첫 단계에 놓인 파일이 intent.md입니다. 한 줄로 요약하자면 intent.md는 코드를 쓰기 전에 무엇을 왜 만들지 적어 두는 첫 번째 문서입니다. 누가 영향을 받는지와 아직 정하지 못한 것이 무엇인지도 같은 파일에 적습니다.

집을 지을 때 건축주가 설계사에게 먼저 건네는 것이 도면이 아니라 "방은 셋, 예산은 얼마, 남향이면 좋겠다"는 의뢰서이듯, intent.md는 개발자가 아닌 사람이 자기 말로 쓰는 의뢰서입니다. 이름만 보면 예전부터 쓰던 PRD와 비슷해 보이는데, 실제로 무엇이 달라졌는지도 뒤에서 표로 비교합니다. 이 글에서는 플레이북 전체 구조를 짧게 훑은 뒤 intent.md를 만드는 절차와 그대로 가져다 쓸 수 있는 예시 세 가지를 정리했습니다.

AI 네이티브 SDLC 플레이북의 여섯 단계와 문서 사슬

플레이북은 개발 과정을 한 방향으로 흐르는 직선이 아니라 여섯 단계가 도는 고리로 그립니다. 기존 개발이 기획부터 유지보수까지 여섯 단계를 차례로 거치고 문제가 생기면 다음 릴리스에서야 처음으로 돌아갔다면, 에이전트가 구현을 맡는 환경에서는 한 바퀴가 몇 주가 아니라 몇 시간 단위로 돈다는 것이 앤트로픽의 설명입니다.

여섯 단계마다 다음 단계가 읽을 문서를 하나씩 남기는 것이 플레이북의 뼈대입니다.

플레이북은 이 문서 묶음을 감사 기록(audit trail)이라고 부릅니다. 의도와 명세, 계획, 코드 차이, 리뷰 결과가 전부 저장소에 남으니 나중에 왜 이렇게 만들었는지 되짚을 때 메신저 대화를 뒤지지 않아도 됩니다. 아래 그림처럼 구현 단계가 짧아진 만큼 사람의 시간은 요구사항과 리뷰, 릴리스 판단으로 옮겨 갑니다.

intent.md는 정확히 무엇을 적는 파일일까요?

intent.md라는 이름은 CLAUDE.md보다 상대적으로 낯설 수 있습니다. CLAUDE.md가 프로젝트의 규칙을 적어 두는 파일이라면, intent.md는 이번에 하려는 일 하나를 적는 파일입니다. 프로젝트에 CLAUDE.md는 하나지만 intent.md는 일감마다 하나씩 생깁니다.

플레이북이 제시하는 intent.md의 구성은 다섯 항목입니다.

• 문제(Problem): 지금 무엇이 불편하거나 되지 않는지
• 기대 결과(Proposed outcome): 해결되면 무엇이 어떻게 달라지는지
• 영향 범위(Affected users and systems): 누가 쓰고 어떤 시스템이 건드려지는지
• 제약(Constraints): 예산, 기한, 지켜야 할 정책, 쓰지 말아야 할 것
• 열린 질문(Open questions): 아직 정하지 못한 것

다섯 항목 어디에도 "어떻게 만들지"가 없다는 점이 중요합니다. 건축주의 의뢰서에 철근 배치도가 들어가지 않듯, intent.md에는 기술 선택이 들어가지 않습니다. 어떻게 만들지는 다음 단계의 spec.md와 plan.md가 맡고, intent.md는 그 두 문서가 어긋났을 때 돌아와 확인하는 기준이 됩니다.

파일 머리에는 작성자와 상태를 적습니다. 플레이북 예시는 Author: J. Ortiz (claims operations). Status: draft. 형식인데, 작성자가 개발자가 아니라 보험금 청구 운영팀 직원이라는 점이 눈에 띕니다. 아이디어를 낸 사람이 백로그에 티켓을 올리고 몇 주를 기다리는 대신 곧바로 클로드와 대화해 문서를 만들라는 것이 이 단계의 요지입니다.

PRD, TRD와 intent.md의 차이

요구사항을 문서로 먼저 적는 일 자체는 새롭지 않습니다. 기획자가 쓰는 PRD(Product Requirements Document), 즉 제품 요구사항 정의서는 무엇을 만들지를 적고, 개발자가 쓰는 TRD(Technical Requirements Document), 즉 기술 요구사항 정의서는 어떻게 만들지를 적습니다. 두 문서의 세부 형식은 조직마다 다르지만, 직무에 따라 문서를 나누고 사람이 읽는 것을 전제로 한다는 점은 대체로 같습니다.

플레이북의 세 문서를 이 둘에 대응시키면 intent.md는 PRD의 앞부분, spec.md는 PRD의 나머지와 TRD를 합친 것, plan.md는 작업 분해에 가깝습니다. 무엇이 달라졌는지는 아래 표로 볼 수 있습니다.

가장 큰 차이는 읽는 대상입니다. PRD와 TRD는 사람이 읽고 이해한 뒤 머릿속에서 코드로 옮기는 문서라 완결된 형태를 지향하고, 그래서 다 쓰는 데 시간이 오래 걸립니다. intent.md는 클로드가 다음 단계의 입력으로 그대로 읽는 문서라서 짧아도 되고, 모르는 것을 모른다고 적어 두면 클로드가 spec.md를 만들 때 그 질문부터 다룹니다.

두 번째 차이는 문서가 사는 곳입니다. 위키에 있는 PRD는 코드가 바뀌어도 따라 바뀌지 않아서 몇 달 뒤에는 실제와 다른 문서가 되기 쉬운데, 플레이북의 세 문서는 코드와 같은 저장소에서 같은 커밋으로 움직입니다. 건축주의 의뢰서가 설계 변경 때마다 함께 갱신되는 것과 같습니다.

intent.md 작성 절차: 클로드에게 질문을 시키는 방법

intent.md는 빈 파일을 열고 직접 채우는 문서가 아닙니다. 플레이북이 제시하는 절차는 클로드가 묻고 사람이 답하는 인터뷰입니다.

1. 문제를 평소 말투 그대로 클로드에게 설명합니다. 정리되지 않아도 됩니다.
2. 클로드가 범위, 사용자, 제약을 되묻습니다. 모르는 것은 모른다고 답합니다.
3. 대화가 충분해지면 "지금까지 내용을 intent.md 양식으로 써 줘"라고 요청합니다.
4. 클로드가 잘못 이해한 부분을 고칩니다.
5. 저장소의 intent/ 폴더에 커밋합니다.

클로드가 먼저 묻게 하려면 첫 프롬프트에 그 역할을 적어 두는 편이 안정적입니다. 아래는 어떤 주제에든 그대로 쓸 수 있는 형태입니다.

인터뷰가 끝난 뒤 나온 파일은 한 번 읽어 보고 두 가지만 확인하면 됩니다. 기대 결과에 내가 말하지 않은 기능이 끼어 있지 않은지, 열린 질문에 내가 정말 모르는 것이 빠지지 않았는지입니다. 클로드가 빈칸을 그럴듯하게 채우는 경우가 있어서, 모르는 것을 모른다고 남겨 두는 일은 사람이 챙겨야 합니다.

플레이북은 이 단계의 측정 기준으로 첫 대화에서 intent.md 커밋까지 걸린 시간을 듭니다. 기존에는 몇 주가 걸리던 일이 몇 시간이면 끝나야 정상이라는 뜻인데, 혼자 쓰는 경우라면 대화 한 번으로 끝납니다.

보편적으로 쓸 수 있는 intent.md 예시 세 가지

플레이북의 예시는 보험사 청구 조회 화면이라 규모가 큽니다. 아래 세 가지는 혼자서도 시작할 수 있는 크기로 줄인 것으로, 반복 업무 자동화, 문의 자동 응답, 웹사이트 기능 추가 순입니다. 항목 이름은 플레이북 원문의 영어를 그대로 두었는데, 한국어로 바꿔 써도 클로드는 똑같이 읽습니다.

예시 1: 매주 월요일 GA4 요약을 메일로 받기

예시 2: 예약 문의 폼에 자동 답장 붙이기

예시 3: 블로그 글 목록에 태그 필터 추가

세 예시 모두 코드가 한 줄도 없고, 대신 열린 질문이 남아 있습니다. 이 질문들은 다음 단계에서 spec.md를 만들 때 클로드가 가장 먼저 다루는 항목이 됩니다.

intent.md 다음에 오는 spec.md와 plan.md

의뢰서를 받은 설계사가 도면을 그리고 시공사가 공정표를 짜듯, intent.md 다음에는 spec.md와 plan.md가 차례로 만들어집니다. 세 파일의 차이는 아래와 같습니다.

spec.md는 intent.md를 첨부하고 아래처럼 요청하면 됩니다. 플레이북의 프롬프트를 개인 규모에 맞게 줄였습니다.

plan.md는 플랜 모드에서 만듭니다. 플랜 모드는 클로드가 파일을 고치지 못하고 읽기와 분석만 하는 상태라, intent.md와 spec.md를 주고 구현 계획을 요청하면 코드 대신 계획이 나옵니다. 플레이북이 권하는 것은 계획을 받은 뒤 무엇이 깨질 수 있는지, 다른 방법은 없는지 되묻는 일인데, 이 질문을 두세 번 하고 나서 승인하면 구현은 대개 한 번에 끝난다고 설명합니다.

plan.md에는 바뀌는 파일 목록, 작업 순서, 위험, 그리고 무엇이 되면 끝난 것으로 보는지를 적습니다. 마지막 항목이 특히 쓸모가 있는데, 예시 1이라면 "월요일 9시에 테스트 메일이 도착하고 숫자가 GA4 화면과 일치한다"처럼 사람이 눈으로 확인할 조건을 미리 적어 두는 것입니다. 구현 도중 계획과 달라지면 코드와 같은 커밋에서 plan.md도 고칩니다.

혼자 쓰는 사람이 플레이북에서 가져갈 부분과 건너뛰어도 되는 부분

플레이북의 뒷부분은 규모가 큰 조직을 위한 내용입니다. 정책 담당자가 스킬로 보안 기준을 강제하고, 훅으로 운영 배포를 막고, CI에서 매일 밤 에이전트 설정을 평가하고, 관리형 설정으로 엔지니어가 바꿀 수 없는 권한을 내려보내는 식입니다. 여러 명이 서브에이전트와 git worktree로 동시에 작업하는 방법도 나옵니다.

아파트 단지를 짓는 시공사와 원룸 하나를 고치는 사람이 같은 서류를 다 갖출 필요가 없듯, 혼자 쓰는 사람은 그중 일부만 가져가면 됩니다.

이 표에서 혼자 쓰는 사람에게 남는 것은 결국 두 가지입니다. 시작하기 전에 intent.md를 쓰는 습관과, 구현 전에 플랜 모드로 계획을 한 번 보는 습관입니다. 플레이북이 여섯 단계에 걸쳐 만든 장치의 대부분은 사람 여럿이 같은 기준을 지키게 하려는 것이고, 혼자라면 그 기준은 내 머릿속에 있으니 문서 하나로 충분합니다.

CLAUDE.md에 넣을 검증 명령은 플레이북 예시를 줄이면 이 정도입니다.

에이전트가 자기 작업을 스스로 확인하고 나서 보고하게 만드는 것이 이 세 줄의 목적입니다. 플레이북은 이것을 피드백 루프를 준다고 표현하는데, 사람이 결과를 열어 보기 전에 클로드가 먼저 한 바퀴 돌려 보게 하는 장치라고 보면 됩니다.

intent.md는 코딩을 모르는 사람도 쓸 수 있나요?

쓸 수 있고, 플레이북의 예시 작성자도 개발자가 아닌 운영팀 직원입니다. 다섯 항목 어디에도 기술 용어를 요구하는 곳이 없고, 인터뷰 방식이라 클로드가 묻는 질문에 평소 말로 답하면 됩니다. 오히려 기술을 아는 사람이 "어떻게"를 intent.md에 미리 적어 넣는 쪽이 플레이북이 말리는 방향입니다.

CLAUDE.md와 intent.md는 어떻게 다른가요?

CLAUDE.md는 프로젝트 전체에 늘 적용되는 규칙이고, intent.md는 이번 일감 하나의 목표입니다. CLAUDE.md는 세션이 시작될 때마다 자동으로 읽히지만 intent.md는 사람이 첨부하거나 경로를 알려 줘야 읽습니다. 플레이북은 클로드가 같은 실수를 두 번 하면 그 교정을 CLAUDE.md에 적으라고 권하는데, 이런 교훈은 intent.md가 아니라 CLAUDE.md로 갑니다.

intent.md 파일은 어디에 두고 언제 지우나요?

플레이북은 저장소 안의 intent/ 폴더처럼 버전 관리되는 곳에 두라고 권합니다. 지우지 않고 상태 표시를 초안에서 승인이나 종료로 바꿔 두는 방식인데, 나중에 왜 이 기능을 만들었는지 확인할 때 이 파일이 가장 짧은 답이 되기 때문입니다. 혼자 쓴다면 프로젝트 루트에 intent/2026-09-weekly-ga4-mail.md처럼 날짜를 붙여 쌓아 두는 정도면 됩니다.

3줄 요약:

• intent.md는 앤트로픽 AI 네이티브 SDLC 플레이북의 첫 단계 문서로, 코드를 쓰기 전에 문제와 기대 결과, 영향 범위와 제약, 열린 질문 다섯 항목을 적습니다.
• 빈 파일을 직접 채우는 대신 클로드에게 범위와 사용자, 제약을 되묻게 한 뒤 양식으로 정리시켜 저장소의 intent 폴더에 커밋하고, 이어서 spec.md와 plan.md가 이 파일을 읽고 만들어집니다.
• 팀 규모에서 필요한 정책 담당자 승인이나 훅, CI 평가는 혼자 쓸 때 건너뛰어도 되고 intent.md 작성과 플랜 모드 검토 두 가지만 남기면 됩니다.

Sources:

• Claude.com: The AI-native SDLC playbook (2026-08-21)
• Claude Code Docs: Plan mode
• Claude Code Docs: Manage Claude's memory (CLAUDE.md)
• Claude Code Docs: Hooks
• Claude Code Docs: Skills