intent.md 작성법: 코딩 전에 목표를 정리하고 저장하는 첫 연습
intent.md는 이번 작업의 문제와 기대 결과, 영향 범위, 제약, 열린 질문을 적는 문서입니다. 예시를 직접 저장하고 확인하는 연습부터 클로드와의 인터뷰, spec.md와 plan.md로 이어지는 방법까지 안내합니다.
목차
- 첫 연습: 태그 필터의 목표를 파일로 저장하기
- AI 네이티브 SDLC 플레이북의 여섯 단계와 문서 사슬
- intent.md는 정확히 무엇을 적는 파일일까요?
- PRD, TRD와 intent.md의 차이
- intent.md 작성 절차: 클로드에게 질문을 시키는 방법
- 보편적으로 쓸 수 있는 intent.md 예시 세 가지
- intent.md 다음에 오는 spec.md와 plan.md
- 혼자 작업할 때 줄일 수 있는 것과 남길 것
- intent.md는 코딩을 모르는 사람도 쓸 수 있나요?
- CLAUDE.md와 intent.md는 어떻게 다른가요?
- intent.md 파일은 어디에 두고 언제 지우나요?
- Sources
- 3줄 요약
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
intent.md는 이번 작업에서 무엇을 왜 바꾸는지를 적는 문서입니다. .md는 마크다운 문서의 확장자로, # 같은 기호로 제목을 표시하지만 일반 텍스트 편집기로도 읽고 쓸 수 있습니다.
앤트로픽의 AI 네이티브 SDLC 플레이북은 2026년 8월 21일 이 문서를 개발 과정의 시작점으로 소개했습니다. SDLC는 기획부터 유지보수까지 소프트웨어를 만드는 과정입니다. intent.md는 새로운 전용 프로그램이나 실행 명령이 아닙니다. 요청이 모호할 때 목표를 함께 확인하는 데 쓰며, 결과가 잘못되는 원인이 항상 요청자에게 있는 것도 아닙니다.
첫 연습: 태그 필터의 목표를 파일로 저장하기
AI 계정과 Git 설치 없이 시작합니다. 윈도우 메모장이나 맥 텍스트 편집기를 열고 아래 내용을 붙입니다. 맥 텍스트 편집기는 포맷 → 일반 텍스트 만들기를 선택합니다. 탐색기나 Finder의 문서 폴더 안에 개인 연습용 폴더 intent-practice를 새로 만들어 사용합니다.
아래 다섯 제목은 순서대로 문제, 기대 결과, 영향 범위, 제약, 열린 질문입니다. 마지막 항목에는 아직 결정하지 않은 내용을 남깁니다.
# Intent: 글 목록에서 AI 글만 고르기
Author: 연습 작성자. Status: draft.
## Problem
여러 주제의 글이 섞여 있어 AI 글만 찾기 어렵다.
## Proposed outcome
AI 태그를 선택하면 해당 글만 보이고, 전체 보기를 누르면 원래 목록으로 돌아간다.
## Affected users and systems
글 목록을 보는 방문자와 기존 글 목록 화면.
## Constraints
기존 글과 태그를 삭제하지 않는다. 로그인과 결제 기능은 추가하지 않는다.
이번에는 목표 문서만 작성하며 실제 코드를 바꾸지 않는다.
## Open questions
여러 태그를 동시에 고르게 할지는 아직 정하지 않았다.새 문서에서 파일 → 저장 또는 다른 이름으로 저장을 선택하고 연습 폴더 안에 intent.md로 저장합니다. 윈도우 메모장은 파일 형식을 모든 파일, 인코딩을 UTF-8로 선택합니다. 맥에서 .txt를 자동으로 붙이는 옵션이 보이면 해제하고 확장자 선택 창에서 .md를 유지합니다. 이미 같은 이름이 있으면 덮어쓰지 말고 새 연습 폴더를 만듭니다.
파일을 닫았다 다시 열어 다음 세 가지를 확인합니다. 더블클릭해 다른 앱이 열리면 텍스트 편집기에서 파일 → 열기로 저장한 파일을 선택합니다. 다섯 항목이 모두 남아 있고, 로그인이나 결제가 목표에 추가되지 않았으며, 여러 태그 선택은 아직 미정으로 적혀 있어야 합니다. 이렇게 확인했다면 목표 문서 만들기를 마친 것입니다. 사이트에 필터가 구현된 것은 아닙니다.
파일명이 intent.md.txt라면 탐색기나 Finder에서 확장자를 표시해 실제 이름을 확인합니다. 서식 정보가 보이거나 글자가 깨지면 일반 텍스트와 UTF-8 형식으로 다시 저장합니다. .md로 끝난다고 특별한 프로그램에서 열어야 하는 것은 아닙니다.
혼자 반복하려면 AI 태그를 마케팅으로 바꿔 intent-marketing.md로 저장합니다. 문제와 기대 결과가 같은 태그를 가리키는지, 기존 글을 보존한다는 제약과 열린 질문은 그대로인지 비교합니다. 목표 변경이 어느 문장에 영향을 주는지 확인하는 연습입니다.
AI 네이티브 SDLC 플레이북의 여섯 단계와 문서 사슬
플레이북은 기획, 설계, 구현, 테스트, 배포, 유지보수를 서로 이어 설명합니다. 핵심은 이전 단계에서 정한 내용을 문서와 변경 기록으로 남겨 다음 작업에서 읽는 것입니다.
| 단계 | 주로 남기는 내용 |
|---|---|
| 기획 | intent.md에 문제와 기대 결과 |
| 설계 | spec.md에 요구사항과 설계 |
| 구현 | plan.md에 변경 순서와 검증 방법, 실제 코드 |
| 테스트 | 실행 결과와 발견한 문제 |
| 배포 | 변경 검토와 릴리스 기록 |
| 유지보수 | 운영 중 발견한 문제와 다음 작업의 목표 |
이는 플레이북의 제안이며 모든 프로젝트가 같은 파일명이나 담당자를 써야 하는 규칙은 아닙니다. 사람과 AI가 같은 기록을 읽는 것이 목적입니다. 파일을 저장했다고 다음 단계가 저절로 시작되지는 않습니다. 자동 연결을 만들려면 별도의 설정과 실행 체계가 필요합니다.
그림은 시간을 실제로 측정한 그래프가 아닙니다. AI를 쓰면 어느 프로젝트나 몇 시간 안에 끝난다는 보장으로 읽지 않습니다.
intent.md는 정확히 무엇을 적는 파일일까요?
intent.md라는 이름은 CLAUDE.md보다 상대적으로 낯설 수 있습니다. CLAUDE.md가 프로젝트의 규칙을 적어 두는 파일이라면, intent.md는 이번에 하려는 일 하나를 적는 파일입니다. CLAUDE.md는 프로젝트 루트와 하위 폴더 등에 여러 개 있을 수 있습니다. intent 문서는 일감마다 구분해 보관할 수 있습니다.
플레이북이 제시하는 intent.md의 구성은 다섯 항목입니다.
- 문제(Problem): 지금 무엇이 불편하거나 되지 않는지
- 기대 결과(Proposed outcome): 해결되면 무엇이 어떻게 달라지는지
- 영향 범위(Affected users and systems): 누가 쓰고 어떤 시스템이 영향을 받는지
- 제약(Constraints): 예산, 기한, 지켜야 할 정책, 쓰지 말아야 할 것
- 열린 질문(Open questions): 아직 정하지 못한 것
첫 문서에서는 문제와 기대 결과부터 분명히 합니다. 아직 고르지 않은 기술을 확정하지 않되, 이미 회사에서 쓰는 시스템이나 반드시 지켜야 할 기술 조건은 제약으로 적어도 됩니다. 예를 들어 “기존 Gmail 계정을 사용한다”는 이미 정해진 환경의 설명일 수 있습니다.
Author는 작성자, Status: draft는 초안 상태라는 뜻입니다. 미정 사항을 확정된 요구사항으로 바꾸지 않는 것이 중요합니다.
PRD, TRD와 intent.md의 차이
PRD는 제품 요구사항 문서, TRD는 기술 요구사항 문서입니다. 형식과 작성자는 조직마다 다릅니다. PRD도 짧게 쓰거나 열린 질문을 남길 수 있고, AI가 읽거나 코드와 함께 관리할 수도 있습니다. 따라서 기존 문서는 사람이 읽고 intent.md만 AI가 읽는다고 구분하면 부정확합니다.
| 문서 | 이 글에서 구분하는 역할 |
|---|---|
| intent.md | 이번 문제와 기대 결과, 제약과 미정 사항 |
| spec.md | 동작 규칙과 필요한 설계, 충돌하는 요구사항 |
| plan.md | 수정할 파일, 작업 순서와 검증 방법 |
기존 PRD나 업무 티켓에 같은 내용이 있다면 새 문서를 중복 작성하기보다 그 문서를 연결하거나 필요한 부분만 요약합니다. 팀이 이미 쓰는 형식을 우선합니다.
intent.md 작성 절차: 클로드에게 질문을 시키는 방법
직접 작성해도 되고 클로드의 질문을 받아 정리해도 됩니다. 클로드를 이미 사용한다면 새 대화에 이번 문제를 설명하고, 모르는 내용은 미정으로 남기도록 요청합니다. 채팅에 나온 문서는 내 컴퓨터에 자동 저장됐다고 가정하지 말고 복사해 저장하거나 파일 생성 결과를 확인합니다.
클로드가 먼저 묻게 하려면 첫 프롬프트에 그 역할을 적어 두는 편이 안정적입니다. 아래는 어떤 주제에든 그대로 쓸 수 있는 형태입니다.
새로 만들고 싶은 것이 있어. 바로 만들지 말고 먼저 인터뷰를 해 줘.
내가 설명하면 범위, 실제로 쓸 사람, 제약, 아직 정하지 못한 것을
한 번에 하나씩 물어봐. 질문이 더 없으면 아래 양식으로 intent.md 초안을 대화에 보여 줘.
모르는 내용은 미정으로 남겨 줘. 코드 수정, 파일 커밋, 외부 발송은 하지 마.
# Intent: (제목)
Author: (이름과 역할). Status: draft.
## Problem
## Proposed outcome
## Affected users and systems
## Constraints
## Open questions
설명 시작: (여기부터 평소 말투로)초안을 읽고 문제와 기대 결과가 맞는지, 말하지 않은 기능이 들어갔는지, 모르는 내용이 열린 질문으로 남았는지 확인합니다. 첫 연습처럼 저장한 파일을 다시 열어 확인한 뒤 다음 단계로 넘어갑니다.
실제 프로젝트에서는 담당자와 합의한 위치에 보관합니다. Git은 파일의 변경 이력을 관리하는 도구이고 커밋은 변경 내용을 이력으로 남기는 동작입니다. 공유 저장소의 intent/ 폴더를 쓴다면 기존 경로와 작성 권한을 확인합니다. Git을 아직 쓰지 않는 분은 먼저 저장한 문서를 담당자에게 전달해 보관 방법을 정할 수 있습니다. 로컬 저장, 커밋, 원격 공유는 같은 동작이 아닙니다.
보편적으로 쓸 수 있는 intent.md 예시 세 가지
플레이북의 예시는 보험사 청구 조회 화면이라 규모가 큽니다. 아래 세 가지는 혼자서도 시작할 수 있는 크기로 줄인 것으로, 반복 업무 자동화, 문의 자동 응답, 웹사이트 기능 추가 순입니다. 항목 이름은 플레이북 원문의 영어를 그대로 두었는데, 한국어 제목으로 바꿔 써도 되며 프로젝트의 기존 양식을 우선합니다.
예시 1: 매주 월요일 GA4 요약을 메일로 받기
GA4는 구글의 웹과 앱 이용 분석 도구입니다. Data API는 프로그램에서 분석 데이터를 조회하는 연결 방식이고, 속성 시간대는 해당 분석 대상에서 날짜를 집계하는 기준 시간대입니다. 아래는 개발 목표의 예시이며 실제 데이터 연결이나 발송을 시작하는 명령은 아닙니다.
# Intent: 주간 GA4 요약 메일 자동 발송
Author: 김OO. Status: draft.
## Problem
매주 월요일 오전에 GA4에 들어가 지난주 세션, 주요 이벤트, 상위 유입 채널을
직접 캡처해 팀 메일로 보내고 있다. 30분이 걸리고 가끔 잊는다.
## Proposed outcome
월요일 오전 9시에 직전 월요일부터 일요일까지와 그 전주를 비교한 요약이
팀 메일로 도착하게 만들고 싶다. 우선 내 테스트 주소로만 확인한다.
비교 기간과 지표 이름, 증감률을 함께 표시한다.
## Affected users and systems
받는 사람은 팀원 4명. GA4 Data API, Gmail 계정, 내 맥 또는 회사 서버.
## Constraints
GA4 편집 권한이 없어 읽기 전용으로만 연결해야 한다.
개인정보가 들어간 측정기준은 쓰지 않는다. 추가 서비스 비용은 0원을 목표로 하되
가능 여부를 확인한다. 팀원 주소로 보내는 것은 테스트 뒤 별도로 정한다.
## Open questions
서버가 없는데 맥을 꺼 두면 어떻게 되는지.
속성 시간대와 집계할 지표를 무엇으로 정할지.
전주 값이 0이거나 데이터가 아직 없을 때 어떻게 표시할지.예시 2: 예약 문의 폼에 자동 답장 붙이기
# Intent: 예약 문의 자동 답장
Author: 박OO. Status: draft.
## Problem
홈페이지 문의 폼으로 예약 문의가 오면 내가 다른 일을 하는 중이라
답장이 반나절씩 늦고, 그 사이 다른 곳으로 예약이 넘어간다.
## Proposed outcome
문의가 들어오면 5분 안에 접수 안내 메일을 보내고 싶다.
우선 가상 문의와 내 테스트 주소로 검증한다.
관리자에게 문의 접수 사실을 알리는 알림도 필요하다.
## Affected users and systems
문의하는 손님과 나. 홈페이지의 구글 폼, Gmail. 관리자 알림 수단은 미정.
## Constraints
손님에게 가는 메일에 가격이나 예약 확정을 자동으로 적지 않는다.
정하지 않은 답변 기한을 약속하지 않는다. 테스트 중에는 손님에게 발송하지 않는다.
개발 지식이 없어서 유지보수를 내가 할 수 있는 수준이어야 한다.
## Open questions
실제 답변 기한과 문의자의 메일 주소 수집 및 이용 안내를 어떻게 정할지.
관리자 알림을 카카오톡으로 보낼 수 있는지와 비용은 얼마인지.예시 3: 블로그 글 목록에 태그 필터 추가
# Intent: 글 목록 태그 필터
Author: 이OO. Status: draft.
## Problem
글이 200편을 넘으면서 방문자가 특정 주제 글만 골라 보기 어렵다.
## Proposed outcome
글 목록 상단에 태그 버튼이 나오고, 누르면 해당 태그 글만 남는다.
주소에 태그가 남아 공유할 수 있다.
## Affected users and systems
방문자 전체. 기존 글 목록 화면과 태그 정보. 실제 코드 파일 위치는 설계 단계에서 확인한다.
## Constraints
기존 글과 태그를 삭제하지 않는다. 로딩 속도를 비교할 조건과 허용 범위는 설계에서 정한다.
태그는 이미 정해 둔 목록 밖의 것을 새로 만들지 않는다.
## Open questions
필터를 건 페이지를 검색엔진에 색인시킬지 말지.세 예시 모두 코드가 한 줄도 없고, 대신 열린 질문이 남아 있습니다. 다음 단계에 문서를 전달할 때 이 질문 중 무엇부터 확인할지 함께 요청합니다.
intent.md 다음에 오는 spec.md와 plan.md
작업 목표가 분명해지면 동작 규칙과 구현 순서를 구체화합니다. 예를 들어 태그 필터라면 해당 글이 없을 때의 표시, 전체 보기 동작, 변경할 파일과 확인 방법을 정합니다. 작은 작업은 한 문서 안에 이 내용을 구분해서 적어도 됩니다.
웹 채팅에서는 저장한 intent 문서를 첨부합니다. 로컬 프로젝트를 읽는 Claude Code에서는 실제 파일 경로를 알려 줍니다. 웹 채팅에 내 컴퓨터 경로만 적었다고 파일 내용까지 전달되는 것은 아닙니다. 다음은 spec.md 초안을 요청하는 예입니다. 플레이북의 프롬프트를 개인 규모에 맞게 줄였습니다.
첨부한 intent.md를 읽고 현재 프로젝트의 요구사항과 설계 명세 초안을 써 줘.
제공된 프로젝트 지침을 지키고, 지킬 수 없는 부분이나 서로 부딪히는 부분은
따로 표시해 줘. 먼저 읽은 intent 문서의 이름 또는 경로와 목표를 요약해 줘.
코드나 지침에 접근할 수 없다면 읽었다고 가정하지 말고 설계에서 확인할 항목으로 남겨 줘.
아직 정하지 않은 사항은 임의로 확정하지 마.
결과는 대화에 보여 주고, 이 단계에서는 코드 수정이나 외부 발송을 하지 마.계획이 필요한 경우 플랜 모드에서 구현 순서와 검증을 요청합니다. Claude Code 터미널에서는 /plan을 요청 앞에 붙이거나 Shift + Tab으로 모드를 바꾸고 상태 표시를 확인합니다. 일반 채팅에서 계획을 써 달라는 요청과 Claude Code의 권한 모드는 구분해야 합니다.
현재 문서는 플랜 모드를 소스 변경 없이 조사하고 계획하는 용도로 설명합니다. 다만 실행 세션의 권한 설정에 따라 명령과 편집 제한의 동작이 달라질 수 있으므로, 어떤 설정에서도 파일을 절대로 바꿀 수 없는 상태라고 생각하면 안 됩니다. 첫 연습을 위해 권한 우회 설정을 켤 필요는 없습니다.
계획에서 바꿀 파일, 순서, 예상 영향, 완료 확인 방법을 읽습니다. 계획을 승인해 구현을 시작하는 동작은 문서 초안을 만드는 것과 다릅니다. 아직 목표만 정리하는 중이라면 계속 계획을 수정합니다. 두세 번 질문하면 반드시 한 번에 구현된다는 보장도 없습니다.
혼자 작업할 때 줄일 수 있는 것과 남길 것
문서 수는 줄일 수 있습니다. 작은 기능이라면 intent.md 안에 요구사항과 작업 순서를 함께 적어도 됩니다. 그러나 혼자라는 이유만으로 테스트와 결과 확인이 불필요해지는 것은 아닙니다.
| 상황 | 확인할 내용 |
|---|---|
| 목표 문서만 작성 | 문서의 다섯 항목과 모순, 저장 상태 확인 |
| 글 목록 필터 변경 | 선택과 해제, 결과가 없는 태그, 기존 목록 보존 확인 |
| 메일 자동화 | 가상 데이터와 테스트 주소, 중복 발송 및 실패 처리 확인 |
| 실제 서비스 변경 | 프로젝트에서 정한 빌드, 테스트와 배포 절차 확인 |
CI는 코드를 변경할 때 자동으로 빌드와 테스트 등을 실행하는 체계입니다. 훅은 정해진 시점에 명령을 실행하는 기능입니다. 이런 도구의 필요성은 팀 인원보다 작업의 영향과 기존 운영 방식에 따라 판단합니다.
CLAUDE.md에 검증 방법을 적을 때는 실제 프로젝트에서 쓰는 명령을 확인합니다. 모든 프로젝트에 npm test가 있는 것은 아닙니다. 실패하면 원인을 읽고 코드, 테스트의 기대값, 실행 환경 중 무엇이 잘못됐는지 판단해야 합니다. 통과시키기 위해 테스트를 무작정 삭제하거나 의미를 바꾸지 않습니다.
## 작업을 끝내기 전에
- 이 프로젝트의 문서와 설정에서 실제 빌드 및 테스트 명령을 확인한다.
- 변경한 동작을 검증하고 실행한 명령, 결과, 확인하지 못한 부분을 기록한다.
- 실패하면 원인과 수정 근거를 남긴다. 관련 없는 기존 변경을 되돌리지 않는다.intent.md는 코딩을 모르는 사람도 쓸 수 있나요?
쓸 수 있고, 플레이북의 예시 작성자도 개발자가 아닌 운영팀 직원입니다. 다섯 항목 어디에도 기술 용어를 요구하는 곳이 없고, 인터뷰 방식이라 클로드가 묻는 질문에 평소 말로 답하면 됩니다. 이미 정해진 시스템이나 필수 조건이 있다면 제약으로 적고, 새로 고를 구현 방법은 설계 단계에서 검토합니다.
CLAUDE.md와 intent.md는 어떻게 다른가요?
CLAUDE.md는 반복해서 참고할 프로젝트 지침이고, intent.md는 특정 작업의 목표입니다. Claude Code는 작업 위치와 접근한 하위 폴더에 따라 관련 CLAUDE.md를 읽습니다. 지침은 문맥으로 전달되는 것이며 그 자체가 모든 동작을 강제하는 보안 설정은 아닙니다.
intent.md는 첨부하거나 경로를 알려 읽도록 요청합니다. 클로드가 모든 파일을 자동으로 읽는 것은 아닙니다. 다른 폴더의 파일을 읽었다면 정확한 경로를 다시 주고 목표와 열린 질문을 요약하게 해서 확인합니다.
intent.md 파일은 어디에 두고 언제 지우나요?
팀에서 정한 저장 위치가 있으면 그곳을 사용합니다. 예를 들어 intent/2026-10-tag-filter.md처럼 작업을 구분할 수 있습니다. 개인 연습은 처음 만든 폴더에 보관해도 됩니다. 더 이상 쓰지 않는 초안이나 완료된 문서는 프로젝트의 보관 규칙에 따라 상태를 표시하거나 정리합니다.
Sources
3줄 요약
-
intent.md는 이번 작업에서 무엇을 왜 바꾸는지와 제약 및 열린 질문을 적는 문서입니다.
-
파일을 저장하고 다시 열어 확인한 뒤 필요한 경우 경로를 알려 AI가 읽도록 요청하며, 파일 이름만으로 다음 단계가 자동 실행되지는 않습니다.
-
spec.md와 plan.md는 요구사항과 구현 순서를 구체화하는 문서이며 작업 규모에 맞게 합칠 수 있어도 필요한 검증까지 생략하는 뜻은 아닙니다.
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
intent.md를 저장한 뒤 기대할 수 있는 상태는 무엇인가요?
이 글이 도움이 되었나요?
도구에 상관없이 통하는 에이전트 원리와 설계 규칙을 정리했습니다
- 1AI 에이전트(AI Agent) 뜻과 챗봇, 워크플로의 차이
- 2에이전트 루프와 도구 호출(Tool Calling) 원리
- 3AGENTS.md와 CLAUDE.md(에이전트 지침 파일) 뜻과 작성법
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.