intent.md 뜻과 작성법: 왜 하는지를 적는 파일

🤔 같은 요청을 고칠 때마다 결과가 달라질 때

에이전트에게 구독 해지 페이지를 만들어 달라고 하면 첫 결과물은 금방 나옵니다. 그런데 보고 나서 "해지 사유도 받아야지", "바로 지우지 말고 한 달은 남겨 둬야 하는데"를 차례로 덧붙이다 보면, 고칠 때마다 앞에서 맞춰 둔 부분이 다시 흐트러집니다. 요구가 대화 곳곳에 흩어져 있어서 에이전트도 무엇이 최종 요구인지 알기 어렵기 때문입니다.

앤트로픽은 2026년 8월 21일 공개한 AI 네이티브 개발 플레이북에서 이 문제를 문서 순서로 풉니다. 만들기 전에 왜 만드는지를 먼저 파일로 남기는 방식이고, 그 첫 문서가 intent.md입니다. 이 편에서는 intent.md를 어떤 도구에서든 쓸 수 있는 원리로 정리합니다. 플레이북 전체 구조와 예시 세 가지는 intent.md 작성법과 SDLC 플레이북 정리에 따로 있습니다.

🔑 intent.md의 정의

intent.md는 코드를 쓰기 전에 무엇을 왜 만들지와 누가 영향을 받는지, 아직 정하지 못한 것을 적어 두는 일감 단위 문서입니다.

SDLC(Software Development Life Cycle)는 기획부터 유지보수까지 소프트웨어가 거치는 단계를 가리키는 말입니다. 앤트로픽 플레이북은 이 단계를 기획, 설계, 구현, 테스트, 배포, 유지보수 여섯 가지로 나누고, 단계마다 다음 단계가 읽을 문서를 하나씩 남기게 합니다. intent.md는 기획 단계의 문서이고, 아이디어를 낸 사람이 자기 말로 에이전트와 대화하며 씁니다.

여행사에 가족 여행을 맡길 때 "부모님 칠순이라 걷는 일정은 적게, 예산은 얼마, 날짜는 아직 미정"이라고 먼저 적어 건네는 방식과 닮았습니다. 어느 항공편을 탈지나 숙소를 어디로 잡을지는 적지 않습니다. 그것은 의뢰를 받은 쪽이 목적을 보고 정할 일입니다.

🧭 AGENTS.md와 intent.md의 차이

둘 다 에이전트가 읽는 마크다운 파일이라 혼동하기 쉬운데, 담는 내용과 수명이 다릅니다. AGENTS.md와 CLAUDE.md가 프로젝트의 늘 같은 규칙이라면, intent.md는 이번 일 하나의 목적입니다.

플레이북은 교훈이 어디로 가는지도 나눠 둡니다. 에이전트가 같은 실수를 두 번 하면 그 교정은 CLAUDE.md에 적으라고 권합니다. 이번 일에만 해당하는 목적과 제약은 intent.md에, 앞으로 모든 일에 통할 규칙은 지침 파일에 둡니다.

📝 intent.md에 들어가는 다섯 항목

플레이북이 제시하는 intent.md는 다섯 항목으로 되어 있습니다.

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

다섯 항목 어디에도 어떻게 만들지가 없습니다. 이 점이 intent.md의 핵심 설계입니다. 기술 선택이 빠져 있어야 다음 단계에서 에이전트가 기존 코드와 규칙을 보고 방법을 고를 수 있고, 나중에 방법이 틀렸을 때도 목적은 그대로 남습니다.

앞의 구독 해지 사례를 다섯 항목으로 옮기면 이렇게 됩니다. 가상의 예시입니다.

맨 위 두 줄이 머리말입니다. 플레이북 예시는 Author: J. Ortiz (claims operations). Status: draft. 형식으로 작성자와 소속, 상태를 적는데, 작성자가 개발자가 아니라 보험금 청구 운영팀 직원입니다. 기술을 모르는 사람이 쓰는 문서라는 뜻입니다.

🔗 intent.md 다음에 이어지는 문서

intent.md는 혼자 쓰이지 않고 다음 단계 문서의 입력이 됩니다. 플레이북에서 승인된 intent.md는 요구사항과 설계 단계를 여는 신호이고, 승인된 spec.md는 구현 계획 단계를 엽니다.

세 문서는 코드와 같은 저장소에 커밋됩니다. 플레이북은 이 커밋의 연속을 감사 기록(audit trail)이라 부르며, 누가 무엇을 요청했고 에이전트가 무엇을 만들었고 누가 승인했는지가 그대로 남는다고 설명합니다. 한 제품이라면 저장소 안의 intent/ 폴더가 가장 단순한 보관 위치라는 안내도 있습니다. plan.md 단계에서 쓰는 플랜 모드는 파일을 고치지 않고 계획만 세우는 클로드 코드의 작업 방식입니다.

🗣️ 빈 파일을 채우지 않고 인터뷰로 쓰는 방법

intent.md는 빈 양식을 열고 혼자 채우는 문서가 아닙니다. 플레이북이 권하는 방식은 에이전트가 묻고 사람이 답하는 인터뷰입니다. 사람은 평소 말투로 문제를 설명하고, 에이전트는 범위와 사용자, 제약을 되묻고, 대화가 충분해지면 양식으로 정리합니다.

첫 요청에 역할을 적어 두면 에이전트가 바로 만들기 시작하지 않고 먼저 묻습니다.

정리된 파일은 사람이 한 번 읽고 고칩니다. 플레이북도 제품 담당자가 에이전트가 쓴 intent.md를 검토하고 고친 뒤에 커밋한다고 적고 있습니다. 이때 볼 곳은 두 군데입니다. 기대 결과에 내가 말하지 않은 기능이 끼어들지 않았는지, 열린 질문에 내가 정말 모르는 것이 빠지지 않았는지입니다. 에이전트는 빈칸을 그럴듯한 답으로 채우는 경향이 있어서 모른다고 남겨 둘 곳을 챙기는 일은 사람 몫입니다.

플레이북은 이 단계가 잘 돌아가는지 보는 지표로 첫 대화에서 intent.md 커밋까지 걸린 시간을 듭니다. 몇 주 걸리던 일이 몇 시간으로 줄어야 정상이라는 설명입니다.

⚠️ intent.md를 쓸 때 자주 하는 실수

• 해결책을 적습니다: "버튼을 추가한다", "이 라이브러리를 쓴다"는 방법입니다. 기대 결과에는 버튼을 누른 뒤 무엇이 달라지는지를 적습니다
• 열린 질문을 비워 둡니다: 모르는 것을 적지 않으면 에이전트가 짐작으로 채우고, 그 짐작이 spec.md와 코드로 이어집니다
• 확인할 수 없는 기대 결과를 적습니다: "편하게 만든다"보다 "3분 안에 확인 메일이 간다"처럼 끝났는지 눈으로 확인할 수 있는 조건이 다음 단계에서 쓸모가 있습니다
• 지침 파일에 섞어 넣습니다: 이번 일의 목적을 AGENTS.md나 CLAUDE.md에 적으면 다른 일을 할 때도 매번 읽혀 엉뚱한 제약으로 작동합니다

❓ 자주 묻는 질문

에이전트가 intent.md를 자동으로 읽나요?

2026년 9월 28일 기준으로 intent.md라는 이름을 자동으로 찾아 읽는다고 안내한 도구 문서는 확인하지 못했습니다. 지침 파일과 달리 사람이 첨부하거나 "intent/unsubscribe.md를 읽고 spec.md를 써 줘"처럼 경로를 알려 줘야 합니다. 그래서 파일 이름보다 저장소 안 일정한 폴더에 모아 두는 습관이 더 중요합니다.

PRD와 intent.md는 무엇이 다른가요?

PRD(제품 요구사항 정의서)는 사람이 읽고 합의하는 완결된 문서를 지향하고, intent.md는 다음 단계의 에이전트가 입력으로 읽는 짧은 문서입니다. intent.md는 열린 질문을 남겨 두는 것이 정상이고, 위키가 아니라 코드와 같은 저장소에서 같은 커밋으로 움직입니다.

혼자 쓰는 작은 작업에도 intent.md가 필요한가요?

한 번 요청하고 끝나는 작업이라면 필요하지 않습니다. 결과물을 여러 번 고칠 것 같거나 며칠에 걸쳐 이어 갈 작업이라면 다섯 항목을 몇 줄로라도 적어 두는 편이 요구가 흩어지는 일을 줄여 줍니다. 팀 규모에서 필요한 승인 절차는 혼자 쓸 때 건너뛰어도 됩니다.

일이 끝나면 intent.md는 지우나요?

지우지 않고 상태 표시만 바꿔 둡니다. 나중에 왜 이 기능을 만들었는지 확인할 때 가장 짧은 답이 이 파일에 있기 때문입니다. 플레이북은 운영 중 문제가 생기면 그 진단을 새 intent.md로 써서 다시 첫 단계로 돌린다고 설명합니다.

📋 3줄 요약

1. intent.md는 앤트로픽이 2026년 8월 21일 공개한 AI 네이티브 개발 플레이북의 첫 단계 문서로 코드를 쓰기 전에 무엇을 왜 만들지를 일감마다 하나씩 적습니다.

2. 항목은 문제와 기대 결과, 영향 범위와 제약, 열린 질문 다섯 가지이고 어떻게 만들지는 넣지 않으며 기술 선택은 다음 단계의 spec.md와 plan.md가 맡습니다.

3. AGENTS.md가 프로젝트 전체에 늘 적용되는 규칙이라면 intent.md는 이번 일감 하나의 목적이어서 자동으로 읽히지 않고 사람이 첨부하거나 경로를 알려 줘야 합니다.

📚 참고 자료

• 앤트로픽, The AI-native SDLC playbook (2026-08-21): https://claude.com/blog/the-ai-native-sdlc-playbook
• 클로드 코드 문서, How Claude remembers your project: https://code.claude.com/docs/en/memory