TL;DR

• intent.md는 무언가를 만들기 전에 무엇을 왜 원하는지 만드는 사람의 말로 적어 두는 짧은 문서다.
• 문제, 바라는 결과와 완료 확인 방법, 영향 범위, 제약, 범위 밖, 미정 사항을 적고 구현 방법은 적지 않는다.
• 에이전트에게 먼저 인터뷰를 시키고 끝내는 기준을 통과했을 때만 문서로 옮긴다.
• 완성한 문서는 대화를 보지 않은 새 세션에 검토시켜 의도가 문서만으로 전달되는지 확인한다.
• Anthropic의 AI-native SDLC(Software Development Life Cycle) 플레이북 첫 단계 산출물이지만 보고서·자동화·글처럼 만드는 대상과 상관없이 쓸 수 있다.

intent.md - 만들기 전에 의도를 먼저 고정하는 문서

intent.md가 필요한 이유

에이전트와 한참 이야기해 결과물을 받았는데 원하던 것과 조금 어긋나 있을 때가 있다. 다음 세션에서 이어 가려면 무엇을 왜 원했는지 처음부터 다시 설명해야 하는데 원하는 것이 대화 안에만 남아 있으면 새 세션도 다른 사람도 추측으로 채울 수밖에 없다.

intent.md는 무엇을 왜 원하는지 작업 전에 적어 두는 마크다운 문서다. 만드는 사람의 말로 쓰고 어떻게 만들지는 적지 않는다. 사람이 읽을 수 있고 에이전트도 다음 작업의 입력으로 바로 쓸 수 있다.

Anthropic은 AI-native SDLC 플레이북(2026-08-21)에서 intent.md를 개발 주기 첫 단계인 계획(Plan) 단계의 산출물로 두고 다음 단계인 설계가 채택된 intent.md를 읽고 시작하도록 흐름을 짠다.¹

구현이 빨라질수록 느린 쪽은 무엇을 만들지 정하는 일이다.

의도를 파일로 남겨 두면 세션이 바뀌어도 다시 추측할 일이 줄고 설계·계획·결과물을 처음 원한 것과 대조할 수 있다. 플레이북은 소프트웨어 개발을 다루지만 적을 내용은 만드는 대상을 가리지 않아서 보고서, 업무 자동화, 블로그 글, 연구 설계에도 그대로 쓸 수 있다.

신규 입사자 안내 문서 예시

신규 입사자의 첫 주 안내 문서를 만든다고 해 보자. 코드가 한 줄도 없는 작업이지만 intent.md의 칸은 그대로 채워진다.

# Intent: 신규 입사자 첫 주 안내 문서
Author: 김OO · Date: 2026-09-24 · Status: draft
 
## Problem
신규 입사자가 첫 주에 계정 신청, 개발 환경 설정, 정기 회의 일정을
매번 사수에게 묻는다. 사수는 입사자 한 명당 첫 주에 서너 시간을
답변에 쓴다. (추정)
 
## Proposed outcome
입사자가 첫 주에 필요한 절차를 한 문서에서 찾아 스스로 진행한다.
완료 확인: 다음 입사자 두 명의 첫 주 질문을 기록하고,
그중 문서로 해결된 질문의 비율을 센다.
 
## Affected users and systems
신규 입사자, 사수, 팀 위키, 계정 신청 양식.
 
## Constraints
사내 위키에만 게시한다. 비밀번호 발급 절차는 보안 정책상 담당 부서
안내 페이지 링크로만 연결한다.
 
## Out of scope
직무별 기술 교육 자료, 인사 규정 요약.
 
## Open questions
- 부서 공통 절차와 팀 고유 절차를 한 문서에 둘지 (정할 사람: 팀장)

지금 겪는 문제부터 완료를 확인할 방법과 보안 정책 때문에 지켜야 할 조건까지 한 장에 들어 있다. 각 칸에 무엇을 적는지는 아래에서 하나씩 본다.

적는 것과 적지 않는 것

플레이북은 정해진 템플릿을 주지 않는다. 조직이 합의한 템플릿을 쓰도록 하면서 Problem, Proposed outcome, Affected users and systems, Constraints, Open questions 다섯 항목을 담을 수 있다고 제시하고 예시 intent.md 역시 같은 다섯 헤딩을 쓴다.

나는 여기서 완료 확인과 범위 밖을 따로 떼어 일곱 칸으로 쓴다. 플레이북에서도 제안자가 처음 설명할 때 나아진 상태와 범위 밖을 말하고 인터뷰에서는 성공이 어떤 모습인지 묻는다. 그런데 문서에 두 가지를 담을 칸이 없으면 대화에서 나온 답이 다른 칸에 섞이거나 아예 빠지기 쉽다.

필드	적는 내용	점검 질문
Problem	지금 무엇이 안 되고 누가 얼마나 자주 겪는가	이 문제가 없어지면 누가 알아차리는가
Proposed outcome	끝났을 때 달라지는 상태	결과만 읽어도 문제가 줄어드는 게 보이는가
완료 확인	끝났는지 판정하는 관찰 방법	제3자가 같은 방법으로 같은 판정을 내릴 수 있는가
Affected users and systems	쓰는 사람, 영향받는 사람, 건드리는 도구와 데이터	"사용자"라는 말 대신 구체적인 역할로 적었는가
Constraints	반드시 지켜야 하는 조건(기한, 예산, 보안, 기존 도구)	어기면 결과물을 쓸 수 없는 조건만 남았는가
Out of scope	이번에 하지 않는 것	하나 이상 적었는가
Open questions	아직 모르는 것과 정할 사람	추측으로 채운 칸을 여기로 옮겼는가

처음부터 일곱 칸을 다 채우지 않아도 된다

모르는 내용은 Open questions에 적어 두면 된다. 예시에서도 부서 공통 절차와 팀 절차를 한 문서에 둘지는 정하지 못해 팀장이 정할 질문으로 남겼다.

구현 방법은 다음 단계에서 정한다.

어떤 도구나 라이브러리를 쓸지, 파일을 어떻게 나눌지, 어떤 순서로 만들지를 intent.md에서 미리 정해 버리면 설계 단계가 고를 수 있는 선택지가 줄어들고 나중에 문서를 고쳤을 때 목표가 바뀐 건지 방법이 바뀐 건지도 가려내기 어렵다.

인터뷰 중에 방법이 떠오르면 반드시 지켜야 하는 조건인지부터 따진다. 조건이면 Constraints에, 후보일 뿐이면 Open questions에 넣는다. 예시의 "사내 위키에만 게시한다"는 도구를 고른 문장처럼 보여도 지켜야 하는 조건이라서 Constraints에 들어갔다.

아래 양식은 일곱 칸을 문서로 옮길 때 쓴다.

# Intent: <한 줄 이름>
Author: <이름> · Date: YYYY-MM-DD · Status: draft
 
## Problem
 
## Proposed outcome
완료 확인:
 
## Affected users and systems
 
## Constraints
 
## Out of scope
 
## Open questions
- <질문> (정할 사람: )

작성 순서

처음에는 만들고 싶은 일을 평소 말로 설명하기만 하면 되고 빈칸을 찾아 묻고 문서로 옮기는 일은 에이전트가 맡는다.

1. 만들고 싶은 것을 형식 없이 자기 말로 설명한다.
2. 에이전트가 한 번에 하나씩 질문하며 빈 필드를 채운다(프롬프트 1).
3. 끝내는 기준을 점검하고 통과하면 템플릿으로 옮긴다(프롬프트 2).
4. 에이전트가 잘못 이해한 부분을 직접 고친다.
5. 대화를 보지 않은 새 세션에 문서만 주고 검토시킨다(프롬프트 3).
6. 저장하고 Status를 표시한 뒤 다음 단계로 넘긴다.

1·2·4단계는 플레이북의 절차와 같고 3단계의 끝내는 기준과 5단계의 새 세션 검토는 내가 더했다. 5단계는 플레이북이 검증 단계에서 결과를 새 컨텍스트로 판정하는 원칙을 문서 검토에 가져온 것이다. 인터뷰를 진행한 세션은 대화 맥락을 알고 있어서 문서에 빈 곳이 있어도 스스로 메워 읽어 버린다.

그래서 검토는 문서만 받은 새 세션에서 한다.

프롬프트 1 · 인터뷰

문서를 쓰기 전에 아래 프롬프트를 먼저 보내고 이어서 만들고 싶은 일을 평소 말로 설명하면 된다.

지금부터 내가 만들고 싶은 것을 설명할게. 바로 만들거나 해결책을 제안하지 말고,
intent.md를 쓰기 위한 인터뷰를 진행해 줘.
 
진행 규칙
- 질문은 한 번에 하나만 한다.
- 내 답을 한 줄로 되짚은 뒤 다음 질문으로 넘어간다. 내가 틀렸다고 하면 고쳐서 다시 되짚는다.
- 아래 일곱 항목을 채울 때까지 질문한다.
  문제 / 바라는 결과 / 완료 확인 방법 / 영향받는 사람과 도구 / 제약 / 범위 밖 / 미정 사항
- "빠르게", "편하게", "잘"처럼 확인할 수 없는 답이 나오면 관찰할 수 있는 기준으로 바꿔 달라고 되묻는다.
- 내가 도구·기술·구조 같은 해결 방법을 말하면 반드시 지켜야 할 조건인지, 후보일 뿐인지 묻는다.
  조건이면 제약에, 후보면 미정 사항에 기록한다.
- 내가 모른다고 하면 추측해서 채우지 않는다. 미정 사항으로 기록하고 누가 정할지만 묻는다.
- 사실과 내 추정이 섞여 있으면 구분해서 기록한다.
- 질문마다 앞에 [채움 3/7]처럼 지금까지 채운 항목 수를 표시한다.
 
먼저 내 설명을 기다려 줘.

프롬프트 2 · 인터뷰 끝내기와 문서화

질문할 거리가 떨어졌다는 이유로 인터뷰를 끝내지 않는다. 최근 두세 개의 질문에서 새 정보가 나오지 않으면 아래 프롬프트를 보낸다. 에이전트가 끝내는 기준 여섯 가지를 표로 점검해 통과하지 못한 칸만 다시 묻고 모두 통과하면 템플릿으로 옮긴다.

인터뷰를 끝내기 전에 아래 기준을 항목별로 점검하고 통과/미통과와 근거를 표로 보여 줘.
 
1. 일곱 항목에 구체적인 문장이 하나 이상씩 있다.
2. 완료 확인이 관찰로 판정 가능하다.
3. 범위 밖이 하나 이상 있다.
4. 바라는 결과가 이루어지면 적어 둔 문제가 줄어든다.
5. 구현 방법이 본문에 섞여 있지 않다.
6. 미정 사항마다 정할 사람이나 시점이 있다.
 
미통과 항목이 있으면 그 항목을 채우는 데 필요한 질문만 이어서 해 줘.
모두 통과하면 아래 템플릿으로 intent.md를 작성해 줘.
- 내 표현을 최대한 살린다.
- 인터뷰에서 나오지 않은 내용은 추가하지 않는다.
- 추정으로 적은 문장 끝에는 (추정)을 붙인다.
 
# Intent: <한 줄 이름>
Author: <이름> · Date: <오늘 날짜> · Status: draft
## Problem
## Proposed outcome
완료 확인:
## Affected users and systems
## Constraints
## Out of scope
## Open questions

완료 확인은 예시의 "다음 입사자 두 명의 질문 중 문서로 해결된 비율"처럼 누가 확인해도 같은 판정이 나와야 통과다.

표가 모두 통과로 나와도 아래 신호가 보이면 더 묻는다.

• 바라는 결과가 "개선한다", "자동화한다"처럼 동사로만 적혀 있다.
• 영향받는 사람이 "사용자", "팀"처럼 역할 없이 적혀 있다.
• 제약 칸이 비어 있다. 제약이 정말 없는 일은 드물다. 대부분은 아직 묻지 않은 것이다.

질문이 열다섯 개를 넘어가는데도 빈칸이 많이 남는다면 범위가 너무 크다는 신호이니 인터뷰를 멈추고 intent를 둘 이상으로 나눈다.

프롬프트 3 · 새 세션에서 검토

작성한 intent.md를 대화를 보지 않은 새 세션에 주고 문서만 읽게 한다.

첨부한 intent.md만 읽고 검토해 줘. 이 문서를 만든 대화는 볼 수 없다고 가정한다.
 
1. 이 문서가 원하는 것을 한 문장으로 요약해 줘.
2. 두 가지 이상으로 읽힐 수 있는 문장을 찾아 줘.
3. 끝났는지 판정할 수 없는 결과가 있으면 알려 줘.
4. 원하는 상태 대신 구현 방법을 적은 문장이 있으면 알려 줘.
5. 이 문서만 보고 설계를 시작한다면 가장 먼저 물어볼 질문 세 개를 적어 줘.
 
문서는 고치지 말고 목록만 줘.

새 세션의 1번 요약이 내가 생각한 의도와 다르면 문서만으로는 아직 뜻이 전달되지 않는다. 5번에서 나온 질문은 대부분 Open questions에 이미 있어야 하고 새로 나온 질문은 문서에 보탠다.

작성 후 돌아볼 질문

플레이북은 Plan 단계의 성과를 git 기록에서 읽는 지표로 잰다. 아래 표의 왼쪽은 플레이북의 지표이고 오른쪽은 혼자 작업할 때 쓰려고 내가 바꿔 본 질문이다.

플레이북 지표	혼자 쓸 때의 점검 질문
첫 대화부터 intent.md 커밋까지 걸린 시간	인터뷰가 한 번에 끝나지 않는다면 문제가 아직 흐리거나 범위가 크다
채택률(설계 단계로 넘어간 intent의 비율)	써 둔 intent 중 실제로 착수한 것은 몇 개인가
설계를 시작한 뒤 intent가 바뀐 횟수	만드는 도중 intent를 고쳤는가. 고쳤다면 어느 필드였는가

가장 쓸모 있는 지표는 설계를 시작한 뒤 intent가 바뀐 횟수다. 만들다가 Constraints나 Out of scope를 자꾸 고친다면 인터뷰에서 약하게 물은 칸이니 다음 인터뷰에서는 두 칸을 먼저, 더 오래 묻는다.

다음 단계로 넘기기

채운 intent.md는 다음 작업의 입력이 된다. 팀이나 조직이라면 요구사항·설계 문서(spec.md)를 만들고 이어서 작업 계획(plan.md)을 세운다. 혼자 하는 작업이라면 intent.md를 계획 단계에 바로 넣으면 되고 코딩 에이전트에 파일을 바꾸지 않고 계획만 세우는 plan mode가 있다면 거기에 넣는다.

첨부한 intent.md를 기준으로 작업 계획을 세워 줘. 아직 아무것도 만들거나 바꾸지 마.
- 계획에는 바꿀 것, 작업 순서, 완료를 확인할 방법을 넣는다.
- intent.md의 Constraints나 Out of scope를 어기는 단계가 있으면 표시한다.
- Open questions 중 계획 전에 답이 필요한 것은 먼저 물어본다.

만드는 도중 목표가 바뀌면 결과물보다 intent.md를 먼저 고친다. 결과물만 고치면 문서와 결과물이 어긋나서 나중에 무엇을 왜 바꿨는지 추적할 수 없다.

파일 관리

intent.md는 작업 한 건에 파일 하나를 둔다. 여러 요청을 한 파일에 이어 쓰지 않는다. 플레이북은 intent를 파일 단위로 채택하거나 닫고 채택 여부를 병합(merge)으로 기록한다. 설계 단계에서는 같은 건의 spec.md를 intent.md 옆에 커밋해 무엇을 요청했고 무엇을 정했는지를 파일 쌍으로 남기고 운영 중에 새 문제가 발견되면 그때마다 새 intent.md를 쓴다.

보관 장소도 플레이북에 나온다. 제품이 하나면 제품 저장소 안의 intent/ 폴더가 가장 단순하고 intent가 여러 저장소에 걸치면 별도 저장소를, 모노레포라면 디렉터리 하나를 쓴다.

Status는 draft에서 시작해 착수하기로 하면 accepted, 끝나면 done, 하지 않기로 하면 closed로 바꾼다. 파일은 지우지 않는다. 플레이북이 채택과 반려 결정 자체를 기록으로 남기듯 버려진 intent도 나중에 같은 아이디어가 다시 나왔을 때 참고가 된다.

파일 이름 규칙은 플레이북에 없다. 나는 변경 한 건마다 폴더를 하나 만들어 intent.md, spec.md, plan.md를 두는데 이렇게 하면 파일 이름을 고정해도 건끼리 부딪히지 않고 한 건의 문서가 한곳에 모인다.

intent/
  2026-09-24-onboarding-guide/
    intent.md     Status: accepted
    spec.md       설계 단계에서 추가
    plan.md       계획 단계에서 추가
  2026-09-30-meeting-notes-bot/
    intent.md     Status: closed (하지 않기로 함)
  2026-10-02-weekly-report/
    intent.md     Status: draft

작업이 작다면 intent/2026-09-24-onboarding-guide.md처럼 파일 하나로 시작했다가 spec.md가 생길 때 폴더로 옮겨도 된다.

ADR과의 관계

intent.md를 처음 보면 ADR(Architecture Decision Record)과 비슷해 보인다. 둘 다 짧은 마크다운 파일로 버전 관리하고 Status가 있으며 채택하지 않은 것도 지우지 않는다. 대화나 사람 머릿속에 있던 맥락을 파일로 꺼내 다음 사람과 에이전트가 읽게 한다는 점도 같다. 플레이북은 ADR을 언급하지 않으니 둘을 잇는 건 내 해석이다.

차이는 쓰는 시점이다. intent.md는 무엇을 할지 정하기 전에 쓰고 ADR은 방법을 정한 뒤에 쓴다.

	intent.md	ADR
쓰는 시점	무엇을 할지 정하기 전	방법을 정한 뒤
담는 것	문제, 바라는 결과, 제약, 범위 밖, 미정 사항	맥락, 결정, 결과(얻는 것과 감수할 것), 검토한 대안
구현 방법	적지 않는다	선택한 방법이 핵심이다
한 건의 단위	작업 한 건	중요한 결정 하나
쓰는 사람	아이디어를 낸 사람(비개발자 포함)	주로 개발팀
바뀔 때	문서를 고친다	새 ADR로 대체한다(AWS 방식)

신규 입사자 예시로 보면 흐름이 드러난다. intent.md의 Open questions에는 "부서 공통 절차와 팀 절차를 한 문서에 둘지"가 남아 있었는데 설계하면서 팀장이 한 문서에 합치기로 정했다면 합치기로 한 결정이 결정 기록의 후보가 된다. 소프트웨어였다면 ADR로 남겼을 결정이다. 결정 기록은 intent의 미정 사항이 풀릴 때 생기고 ADR의 맥락(Context) 항목을 쓸 때는 intent의 Problem과 Constraints를 그대로 가져올 수 있다.

그래서 목표가 바뀌면 intent.md를 고치고 결정이 바뀌면 새 ADR을 쓴다.

Connections

• 하네스 엔지니어링은 모델 바깥의 실행 환경을 설계하는 일이다 — intent.md는 하네스의 지시 층을 작업 하나 단위로 파일에 고정한 형태다.
• Architecture Decision Record (ADR) — ADR은 내린 결정과 이유를 남기고 intent.md는 결정 전의 의도를 남긴다.
• Agent Skills - AI 에이전트에게 전문성을 부여하는 방법 — 반복해서 쓰는 인터뷰 프롬프트와 템플릿은 skill로 묶어 재사용할 수 있다.

Related MOCs

• [[MOCs - Harness Engineering]]

출처

1. Anthropic (2026-08-21). The AI-Native SDLC Playbook ↩︎