INTENT.md란 무엇인가 — AI-Native SDLC의 첫 파일

INTENT.md는 무엇을 담는 파일인가

INTENT.md는 만들고 싶은 것을 아이디어를 낸 사람의 말로 적어 저장소에 커밋하는 마크다운 파일이다. 마크다운은 제목과 목록 정도만 있는 가벼운 서식의 텍스트 파일이고, 확장자가 .md다. 워드나 노션 문서가 아니라 코드와 같은 저장소에 들어간다는 점이 핵심이다.

Anthropic은 2026년 8월 21일 공개한 AI-Native SDLC 플레이북에서 이 파일에 여섯 가지가 들어간다고 적었다. 무엇이 문제인지, 해결되면 어떤 상태가 되는지, 누구와 어떤 시스템이 영향을 받는지, 어떤 제약이 있는지, 아직 안 풀린 질문은 무엇인지, 그리고 작성자와 현재 상태다.

여섯 항목은 형식을 맞추려고 있는 것이 아니다. 다음 단계에서 설계 문서를 만들 때 필요한 재료가 정확히 이것들이다. 제약이 빠지면 못 쓸 설계가 나오고, 미해결 질문이 빠지면 모르는 것을 아는 것처럼 적은 설계가 나온다.

왜 코드보다 의도를 먼저 적으라고 하는가

SDLC는 소프트웨어 개발 생애주기를 뜻한다. 계획하고, 설계하고, 만들고, 테스트하고, 배포하고, 유지보수하는 한 바퀴를 말한다. 기능 하나를 낼 때마다 팀이 도는 이 순환이 SDLC다.

이 여섯 구간 중에서 오래 걸리고 비쌌던 곳은 오랫동안 만드는 구간이었다. 그래서 개발 도구도 채용도 그 구간에 몰렸다. 코딩 에이전트가 실무에 들어오면서 바뀐 것이 이 지점이다. 만드는 시간이 줄어들자 나머지 다섯 구간이 상대적으로 더 크게 보이기 시작했다.

요구사항을 모으는 회의, 문서 담당자를 기다리는 시간, 테스터 순서를 기다리는 며칠, 리뷰가 밀려 있는 PR 대기열은 그대로다. 코드가 빨라져도 기능 하나가 나가는 데 걸리는 시간은 그만큼 줄지 않는다. 병목이 코드에서 프로세스로 옮겨간 것이다.

플레이북의 문제의식이 여기에 있다. 에이전트를 만드는 구간에만 쓰지 말고 앞뒤 구간에도 넣자는 것이고, 그러려면 각 구간이 다음 구간에 넘길 것이 대화가 아니라 파일이어야 한다. INTENT.md가 그 첫 파일이다.

지금 바로 만들어 보는 법

필요한 것은 폴더 하나다. 저장소 최상단에 intent라는 폴더를 만든다. 플레이북은 제품이 하나인 팀이라면 그 제품 저장소 안의 intent 폴더가 가장 단순한 위치라고 적었다.

그다음 에이전트에게 나를 인터뷰하게 시킨다. 여기서 순서가 중요하다. 내가 요구사항을 정리해서 주는 것이 아니라, 에이전트가 계속 물어서 내 머릿속에 있는 것을 꺼내게 하는 쪽이다. 정리해서 주면 정리하면서 이미 빠뜨린 것은 영영 안 나온다.

다크 모드를 넣고 싶다고 하자. 왜 필요한지, 어떤 화면이 걸리는지, 사용자 설정을 어디에 저장할지, 이미지와 로고는 어떻게 할지, 언제까지 필요한지, 무엇을 포기할 수 있는지를 계속 캐묻게 둔다. 더 답할 것이 없을 때까지 간 다음에 파일로 저장하게 한다.

Claude Code나 Cursor처럼 파일을 직접 만들 수 있는 도구를 쓰고 있다면 대화 끝에 저장까지 시키면 되고, 웹 채팅을 쓴다면 결과를 복사해 파일로 붙여 넣으면 된다. 파일 이름은 기능을 알아볼 수 있게 짓는다. intent/dark-mode.md처럼 짓거나, 날짜를 앞에 붙여 정렬되게 해도 된다.

지금부터 내가 만들려는 기능에 대해 질문해 줘.
한 번에 하나씩, 내가 더 답할 게 없다고 말할 때까지 물어봐.

물어볼 것: 이 기능이 필요한 이유, 지금 무엇이 불편한지,
영향받는 사용자와 화면, 연결된 다른 시스템, 예산·기한·기술 제약,
내가 아직 결정하지 못한 것.

내가 "됐다"고 하면 대화를 정리해서 intent/<기능이름>.md 로 저장해 줘.
형식: 문제 / 목표 상태 / 영향 범위 / 제약 / 미해결 질문 / 작성자와 상태

# 다크 모드

## 문제
야간에 앱을 쓰는 사용자가 화면이 밝아 눈이 부시다는 문의를 최근 3개월간 반복해서 보냈다.

## 목표 상태
사용자가 설정에서 밝은 화면과 어두운 화면을 고를 수 있고, 기기의 시스템 설정을 따라가는 선택지도 있다.

## 영향 범위
앱 전체 화면. 설정 화면에 항목 하나 추가. 로고와 일러스트는 밝은 배경 전제로 만들어져 있어 다시 봐야 한다.

## 제약
다음 분기 정기 배포 안에 들어가야 한다. 디자인 시스템 색상 토큰을 새로 만들 여력은 없고 기존 토큰 재사용 범위에서 해결한다.

## 미해결 질문
사용자 선택을 기기에만 저장할지 계정에 저장해 기기 간 동기화할지 정하지 못했다.
이메일 템플릿까지 대응할지 범위에서 뺄지 정하지 못했다.

## 작성자와 상태
작성 신승호 · 2026-09-05 · 검토 대기

원작자가 다시 읽는 단계를 빼면 안 된다

에이전트가 파일을 만들어 준 시점이 끝이 아니다. 플레이북은 아이디어를 낸 사람이 그 결과를 다시 읽고 고친 뒤에 커밋하라고 적었다. 이 단계가 이 방식 전체에서 가장 쉽게 생략되는 곳이고, 생략했을 때 손해가 가장 큰 곳이다.

이유는 뒤에 오는 구조에 있다. 이 파일은 다음 단계에서 설계 문서가 되고, 설계 문서는 그다음에 작업 계획이 되고, 계획은 코드가 된다. 각 단계는 앞 단계의 파일만 읽는다. 그러니 첫 파일에 잘못 적힌 문장 하나는 조용히 세 단계를 지나 코드까지 간다.

실제로 자주 어긋나는 자리가 정해져 있다. 에이전트는 대화에서 내가 지나가듯 말한 것을 확정된 요구로 적어 두는 경향이 있고, 반대로 내가 당연하게 여겨 말하지 않은 제약은 아예 없는 것으로 적는다. 읽을 때 이 두 가지를 먼저 본다.

고칠 때는 문장을 다듬기보다 사실 관계를 본다. 내가 정하지 않은 것이 정해진 것처럼 적혀 있으면 미해결 질문으로 내리고, 범위 밖이라고 생각한 것이 영향 범위에 들어와 있으면 뺀다. 검토가 끝나면 커밋하고, 플레이북은 그 승인 자체를 문서를 병합했거나 리뷰를 닫은 기록으로 남기라고 적었다.

원작자는 개발자가 아니어도 된다

플레이북에서 이 파일을 쓰는 사람을 원작자라고 부른다. 조직 안에서 아이디어를 가진 사람 누구나 원작자가 될 수 있다는 것이 이 용어의 요지다.

버그를 겪은 고객이 원작자일 수 있다. 기능 아이디어가 있는 기획자도, 반복되는 수작업을 없애고 싶은 운영 담당자도 원작자다. 지금까지 이런 요청은 티켓 한 줄로 접수돼 누군가 다시 물어보고 정리해야 했는데, 그 정리를 에이전트가 대신하니 겪은 사람이 겪은 말로 그대로 남길 수 있다.

그렇다고 전부 그대로 개발로 가는 것은 아니다. 모인 파일들은 제품 책임자가 훑고 우선순위를 정한다. 폴더에 쌓인 마크다운 파일 목록 자체가 백로그가 되고, 팀에 따라 이 목록을 Notion이나 Linear 같은 도구로 옮겨 관리하기도 한다. 분류와 우선순위 초안은 에이전트에게 먼저 시키고 사람이 확정하는 방식도 쓸 수 있다.

INTENT.md 다음에 오는 것 — 아티팩트 체인

이 파일은 혼자 있지 않다. 플레이북은 단계마다 남는 산출물을 이어 붙인 사슬을 제시하고, INTENT.md가 그 사슬의 첫 고리다.

의도가 커밋되면 그것을 재료로 요구사항과 설계를 담은 spec.md를 만든다. 플레이북은 이 단계에 쓸 지시문 예시를 함께 제시했다. 첨부한 intent.md를 읽고 요구사항과 설계 문서를 만들되, 쓸 수 있는 스킬을 적용해 브랜드 가이드라인과 보안 정책, UX 기준에 맞추라는 내용이다.

설계가 정해지면 엔지니어가 의도와 설계를 함께 넣어 작업 계획인 plan.md를 만든다. 어떤 파일을 고칠지, 어떤 순서로 할지, 무엇이 위험한지, 완료를 무엇으로 확인할지가 여기 들어간다. 계획이 좋은지 판단하는 기준 하나는 이 문서만 받은 사람이 앞의 두 문서를 안 보고도 작업할 수 있는가다.

이 기준이 까다로워 보이지만 이유가 있다. 여섯 구간을 에이전트 하나가 처음부터 끝까지 담당하지 않기 때문이다. 단계마다 다른 대화, 다른 에이전트, 다른 서브에이전트가 붙고 그들은 앞선 대화를 모른다. 넘길 것이 대화가 아니라 파일이어야 한다는 말이 여기서 실질적인 요구가 된다.

우리 팀에 넣을 때 먼저 정할 것

폴더 하나로 시작할 수 있지만, 팀에 정착시키려면 몇 가지를 미리 정해 두는 편이 낫다. 파일을 어디에 둘지, 이름을 어떻게 지을지, 누가 검토하고 무엇으로 승인 표시를 할지다. 자주 바꾸면 사람도 에이전트도 매번 다른 규칙을 만나 이득이 사라진다.

규칙을 문서로만 두지 않고 실행되게 만들 수도 있다. 의도가 병합되면 설계 문서 생성을 걸어 두는 식으로 훅을 쓰거나, 우리 팀이 쓰는 문서 형식을 스킬로 만들어 두면 매번 지시문을 다시 쓰지 않아도 된다. 플레이북이 거버넌스를 코드로 두라고 말하는 부분이 이것이다.

이미 돌아가는 방식이 있다면 통째로 갈아엎을 이유는 없다. 각 팀은 이미 자기 방식의 계획 문서와 리뷰 절차를 갖고 있고, 이 플레이북도 하나의 방식일 뿐이다. 겹치는 부분은 이름만 맞추고, 지금 비어 있는 자리 하나부터 채우는 편이 정착에 유리하다.

가장 작게 시작하는 방법은 이번 주에 나갈 기능 하나를 골라 intent 폴더에 파일 하나를 만들어 보는 것이다. 그 파일만으로 다음 사람이 설계를 시작할 수 있는지 보면, 이 방식이 우리 팀에 필요한지 아닌지가 한 번에 드러난다.