앤트로픽이 intent.md를 AI 네이티브 개발의 출발점으로 제안했다

CLAUDE.md도 있고 AGENTS.md도 있는데 이번에는 intent.md다. 앤트로픽은 2026년 8월 공개한 AI-Native SDLC 플레이북에서 이 파일을 ‘새 설정 파일’이 아니라, 무엇을 왜 바꾸려는지 먼저 고정하는 버전 관리형 proto-spec으로 제안했다. 핵심은 파일 이름보다 구현 전에 의도와 제약을 남기는 데 있다.

intent.md는 새 자동 설정 파일이 아니다

앤트로픽이 2026년 8월 21일 공개한 The AI-Native SDLC playbook은 개발 과정을 Plan, Design, Build, Test, Deploy, Maintain 여섯 단계로 나누고, 각 단계가 다음 단계가 읽을 수 있는 산출물을 남기는 흐름을 제안한다.

그 출발점이 intent.md다. 공식 설명에서 이 파일은 아이디어를 바로 구현 지시로 바꾸기 전에 무엇을 원하는지, 왜 필요한지, 어떤 제약이 있는지를 사람의 언어로 남기는 짧은 문서다. 제품 책임자가 내용을 검토하고 수정한 뒤 버전 관리에 넣는 흐름이다.

중요한 건 Claude Code가 파일 이름만 보고 자동으로 특별 취급하는 새 기능으로 소개된 것이 아니라는 점이다. CLAUDE.md처럼 세션 시작 때 읽히는 프로젝트 지침과는 역할이 다르다.

앤트로픽은 왜 지금 ‘의도’를 먼저 쓰라고 할까

플레이북의 문제의식은 단순하다. 에이전트가 코드를 빨리 쓰기 시작하면 개발 전체가 같은 속도로 빨라지는 것이 아니라, 기획·검토·테스트·배포 같은 주변 단계가 새로운 병목이 된다는 것이다.

예전에는 구현 자체가 몇 주 걸릴 수 있었기 때문에 요구사항 정리와 승인 과정이 그 속도에 맞춰져 있었다. 그런데 구현이 몇 시간 단위로 짧아지면, 사람이 전달 과정에서 놓친 조건 하나가 오히려 더 큰 재작업을 만든다.

그래서 앤트로픽은 아이디어가 백로그와 회의, 사용자 스토리, 정제 과정을 거치며 원래 뜻에서 멀어지는 문제를 줄이기 위해 처음 제안한 사람이 Claude와 함께 의도를 먼저 정리하고 intent.md로 남기는 방식을 제시한다. 공식 Claude Academy도 이 파일을 “what is wanted, why, and under which constraints”를 담는 proto-spec으로 설명한다.

CLAUDE.md와는 무엇이 다를까

Claude Academy의 CLAUDE.md 설명은 이 파일에 새 팀원이 알아야 할 규칙, 명령, 아키텍처, 자주 반복되는 실수를 넣으라고 한다. 반면 intent.md는 특정 변경의 목적과 범위를 다룬다.

즉 프로젝트 공통 규칙과 개별 변경의 의도를 섞지 않는 것이 포인트다. 이미 AGENTS.md 같은 저장소 지침을 잘 쓰고 있다면 그것을 버릴 이유도 없다. 이번 작업의 목적과 성공 조건이 대화 속에서만 사라지지 않게 별도 산출물로 남기는 쪽에 더 가깝다.

intent.md에는 무엇을 적을까

공식 예시는 문제, 제안하는 결과, 영향을 받는 사용자와 시스템, 제약, 열린 질문을 담는다. 조직이 합의한 템플릿을 쓰도록 권하므로 반드시 똑같은 목차를 강제하는 규격은 아니다.

백엔드 작업에 옮기면 이런 형태가 실용적이다.

# Intent: 주문 생성 재시도 시 중복 주문 방지

## 문제
클라이언트가 응답을 받지 못해 재시도하면
같은 주문이 중복 생성될 수 있다.

## 원하는 결과
같은 사용자가 동일한 요청 식별값으로 재시도해도
주문은 한 건만 생성되어야 한다.
동시 요청도 포함한다.

## 영향을 받는 사용자와 시스템
웹·모바일 클라이언트, 주문 생성 API,
주문 저장소가 영향을 받는다.

## 제약과 제외 범위
기존 인증·권한 정책과 성공 응답 형식을 유지한다.
관련 없는 주문 모듈 전체 리팩터링은 하지 않는다.
새 인프라는 별도 합의 없이 도입하지 않는다.

## 미결정 사항
식별값의 유효기간은 얼마인가?
같은 식별값에 다른 요청 본문이 오면 어떻게 할 것인가?
처리 중 재요청에는 어떤 응답을 줄 것인가?

## 완료 조건
동시 중복 요청에서도 주문이 한 건만 저장되어야 한다.
응답 유실 뒤 재시도해도 중복 생성되지 않아야 한다.
기존 주문 생성 테스트도 통과해야 한다.

여기서 눈여겨볼 부분은 구현 기술을 너무 빨리 고르지 않는다는 점이다. “Redis 락을 붙인다”보다 “어떤 상황에서도 중복 주문이 생기지 않아야 한다”를 먼저 고정하면, DB 제약이나 멱등성 키 같은 다른 설계를 비교할 여지가 남는다.

문서를 쓴 뒤 바로 코딩으로 가는 흐름도 아니다

앤트로픽의 공식 흐름에서는 작성자가 Claude와 intent.md를 만들고, 제품 책임자가 잘못 이해된 부분을 고친다. 승인된 의도는 요구사항과 설계 문서로 발전하고, 엔지니어는 그 문서를 바탕으로 Plan Mode에서 plan.md를 만든다.

Requirements and design 단계에서는 충돌하는 정책과 해결되지 않은 우려를 드러내도록 하고, Plan Mode에서는 변경 파일과 테스트까지 계획에 넣는다.

제가 보기에는 문서 개수보다 이 연결이 더 중요하다. 주문 API 예시라면 설계로 넘어가면서 ‘동시 요청’이나 ‘기존 인증 유지’가 슬쩍 빠지지 않았는지 확인할 수 있어야 한다.

Jira나 기존 이슈를 없애라는 뜻도 아니다

플레이북은 기존 업무 시스템과 마크다운 산출물이 함께 존재할 수 있다고 명시한다. 대신 어느 쪽이 최종 기준인지 정하거나 최소한 양쪽을 연결해야 한다고 설명한다.

Jira가 이미 요구사항의 기준이라면 intent.md는 작업용 복사본이 될 수 있다. 반대로 저장소의 마크다운을 기준으로 삼고 Jira가 커밋을 가리키게 할 수도 있다. 가장 피해야 할 형태는 둘 다 최신이라고 믿는데 내용은 서로 다른 상태다.

정말 효과가 있는지는 따로 봐야 한다

intent.md의 취지는 합리적이지만, 파일 하나를 추가하면 생산성이 몇 배 오른다고 검증된 것은 아니다. 공식 플레이북은 도입 효과를 측정하기 위한 지표를 제안하지만, intent.md 하나만 떼어 통제 실험으로 생산성 향상을 증명한 자료는 아니다.

그래서 적용한다면 코드 생성 시간이 아니라 구현이 시작된 뒤 요구사항을 다시 고치는 횟수를 보는 편이 낫다. Claude Academy도 intent.md에서 spec.md까지 걸린 시간과, 첫 plan.md 이후 발생한 요구사항 재작업을 측정 지표로 제안한다.

문서를 만들었는데 아무도 검토하지 않는다면 오히려 관리할 파일만 하나 늘어난다. 작은 오탈자 수정이나 범위가 완전히 명확한 변경까지 매번 intent.md → spec.md → plan.md를 강제하는 것도 과할 수 있다.

테스트를 대신하는 문서도 아니다

“중복 주문이 없어야 한다”는 문장은 목표이고, 실제 동시 요청 테스트가 통과했다는 것은 증거다. 둘은 역할이 다르다.

앤트로픽도 feedback loop 단계에서 에이전트가 빌드·테스트·스크린샷 같은 방법으로 자신의 작업을 검증하도록 강조한다. 의도는 문서로 고정하되, 실제로 지켜졌는지는 테스트와 리뷰로 확인해야 한다.

그래서

intent.md를 새 유행 파일로 보고 모든 저장소 루트에 하나씩 만들 필요는 없어 보인다. 대신 요구사항 해석에 따라 구현이 크게 달라지는 기능 하나를 골라, 왜 필요한지·무엇을 바꾸면 안 되는지·아직 결정되지 않은 것이 무엇인지부터 짧게 남겨 보는 쪽이 낫다.

이미 이슈와 PRD가 그 역할을 잘하고 있다면 파일 이름을 바꾸는 데 큰 의미는 없다. 반대로 중요한 조건이 Slack이나 대화창 속에만 남아 있었다면, 버전 관리되는 짧은 intent.md는 꽤 실용적인 출발점이 될 수 있다.

결국 앤트로픽이 제안한 변화는 “AI에게 더 긴 프롬프트를 써라”보다는 “AI가 빨라진 만큼 사람의 의사결정도 추적 가능한 산출물로 남겨라”에 가깝다. 파일보다 중요한 것은 그 의도가 설계, 구현, 테스트까지 끝까지 이어지는지다.

자료: Anthropic/Claude 공식 AI-Native SDLC playbook 및 Claude Academy. 브랜드 SVG는 Simple Icons 공개 저장소의 Anthropic·Claude 항목을 로컬에 저장해 사용했다.