Claude Code한테 시키기 전에, intent.md부터 써야 하는 이유
Claude Code한테 곧바로 기능 구현을 시켜도 될까요?
답부터 드리면, 코드를 시키기 전에 의도부터 짧은 문서로 붙잡아 두는 게 먼저예요. 그래야 나중에 방향이 흔들리지 않는다는 얘기가 강의에 나와요.
코드보다 의도를 먼저 문서로 남겨야 방향이 안 흔들려요.
이 이야기는 Capture as intent.md — Anthropic Academy 라는 강의에 나오는 내용이에요. The AI-Native SDLC Playbook 이라는 14개짜리 시리즈 중 두 번째 강의고, 전체 개발 단계 중 첫 단계인 “Stage 1: Plan”에 속해요. 길이는 24분이에요.
무엇이 다른가 — 전통 방식과 AI 네이티브 방식
전통적인 방식은 아이디어 하나가 백로그에 올라갔다가 사용자 스토리로 바뀌고, 스토리 포인트가 매겨지고, 개선 회의를 몇 차례 거친 뒤에야 누군가 실제로 손을 대는 구조예요. 강의는 이 과정에서 단계를 넘길 때마다 소유권이 바뀌면서 원래 의도가 조금씩 변형된다고 짚어요. 그래서 처음 낸 아이디어와 실제로 만들어진 것이 다른 경우가 생겨요.
- 전통 방식: 아이디어 → 백로그 → 사용자 스토리 → 스토리 포인트 → 개선 회의 → 실행
- AI 네이티브 방식: 아이디어 제안자가 Claude와 함께 마크다운으로 intent.md를 바로 작성 → 다음 단계에서 그대로 이어받음
intent.md를 쓰는 다섯 단계
강의가 제시하는 절차는 다섯 단계로 나뉘어요. 코드를 짜기 전에 대화부터 시작한다는 점이 핵심이에요.
- 문제를 자연어로 설명한다 — 아이디어를 낸 사람이 Claude에게 지금 겪는 문제를 그대로 이야기해요.
- Claude와 함께 브레인스토밍한다 — 아이디어가 구체화될 때까지 되묻고 답해요.
- 조직의 템플릿으로 intent.md를 만든다 — Claude에게 팀이 쓰던 양식대로 정리해 달라고 요청해요.
- 제안자가 검토하고 오해를 고친다.
- 공유 저장소에 intent.md를 커밋한다.
이 다섯 단계는 강의 페이지에 순서대로 나와 있어요.
intent.md 안에는 무엇이 들어가나
강의가 밝힌 항목은 다섯 개예요. 문제, 예상 결과, 영향받는 사용자와 시스템, 제약사항, 아직 정하지 못한 질문이 그것이고, 순서도 이대로예요.
# intent.md
## 문제
(무엇이 왜 불편한가)
## 예상 결과
(이게 되면 무엇이 달라지는가)
## 영향받는 사용자 / 시스템
(누가 쓰고, 어디에 연결되는가)
## 제약사항
(예산, 일정, 기술적 한계)
## 아직 정하지 못한 질문
(결정이 필요한 것들)사용자 스토리처럼 잘게 쪼개지 않고, 통째로 한 문서에 담아 두는 게 핵심이에요.
이 방식이 됐는지 어떻게 확인하나 — 지표 두 가지
강의는 성공 여부를 판단할 두 가지 지표를 제시해요.
- 선행 지표: 첫 대화부터 intent.md 커밋까지 걸리는 시간
- 후행 지표: 제품 소유자가 그 intent.md를 그대로 승인하는 비율 (생존율)
두 지표 모두 강의 개요에 나와 있는 내용이에요. 짧을수록, 높을수록 좋다는 뜻이죠.
오늘 바로 써먹는 법
팀에 조직 템플릿이 없다면, Claude Code 새 대화창에서 이렇게 시작해 보세요. “이 문제를 intent.md 형식으로 정리해 줘. 문제, 예상 결과, 영향받는 사용자, 제약사항, 아직 정하지 못한 질문 다섯 항목으로 나눠서” 라고 요청하면 돼요.
Claude가 되물어 오는 질문에는 짧게라도 답을 채워 넣어요. 빈칸으로 넘어가면 나중에 코드가 엉뚱한 방향으로 갈 수 있어요. 다 채운 다음엔 저장소에 커밋해서 팀이 같이 볼 수 있게 해 두면 됩니다.
확인해 둘 것 — 한계와 안 맞는 경우
검토해 줄 사람이 없으면 intent.md도 무거운 절차예요.
이 절차는 제품 소유자나 동료처럼 검토해 줄 사람이 있을 때 의미가 있어요. 혼자 만드는 사이드 프로젝트나 간단한 버그 수정이라면 intent.md까지 쓰는 건 오히려 일을 늘리는 셈이에요.
출처