intent.md 작성법, CLAUDE.md와 다른 점과 질문 4가지

intent.md 작성법을 처음 해 보는 사람 기준으로 정리합니다. 하려는 일을 클로드에게 적고, 클로드가 던지는 네 가지 질문에 답한 뒤, 그 내용을 intent.md로 받아 저장소의 intent 폴더에 쌓는 순서입니다. 바로 붙여 쓸 수 있는 요청 문장과 문서 틀도 함께 넣었습니다.

CLAUDE.md와 intent.md는 어떻게 다른가

두 문서는 한 문장으로 나뉩니다.

• CLAUDE.md: AI에게 "이 저장소에서 일하는 법"을 알려 주는 설명서입니다. 코드 스타일, 테스트 명령, 건드리면 안 되는 폴더처럼 저장소 전체에 늘 적용되는 규칙을 적습니다. 클로드 코드는 세션을 시작할 때 이 파일을 자동으로 읽습니다.
• intent.md: "이번에 무엇을 왜 만드는지"를 사람과 AI가 같이 읽는 기획서입니다. 이번 작업의 목적, 범위, 사용자, 조건, 성공 기준을 적습니다.

앞의 것은 저장소 전체의 작업 방식이고, 뒤의 것은 작업 하나의 목적입니다. 그래서 CLAUDE.md는 저장소에 하나를 두고 고쳐 가며 쓰고, intent.md는 작업마다 새로 생깁니다. 작업이 끝난 뒤에도 지우지 않고 남겨 두면 "이 기능을 왜 이렇게 만들었는지"를 나중에 되짚는 기록이 됩니다.

intent.md를 만드는 순서 8단계

준비물

• 클로드 코드(터미널 또는 데스크톱 앱 Code 탭). 파일을 저장소에 바로 저장하게 하려면 폴더를 다룰 수 있는 클로드 코드가 편합니다. 일반 채팅에서 만들었다면 결과를 복사해 직접 파일로 저장합니다.
• 개발 작업을 두는 저장소(프로젝트 폴더).
• 만들고 싶은 일 하나. 새로 떠오른 아이디어여도, 평소 하던 작업이어도 됩니다.

하려는 일을 클로드에게 알리기

1단계. 저장소 폴더에서 클로드 코드를 엽니다

• 위치: 터미널이라면 저장소 폴더로 이동해 claude를 입력합니다. 데스크톱 앱이라면 Code 탭에서 그 폴더를 고릅니다.
• 확인: 입력창에 글을 쓸 수 있습니다.

2단계. 하려는 일을 적습니다

평소 말투로 적어도 됩니다. 클로드가 바로 만들기 시작하지 않고 질문부터 하게 하려면 끝에 한 줄을 붙입니다.

회원들이 서로 글을 남길 수 있는 게시판을 붙이고 싶어. 바로 만들지 말고, 어디까지 만들지, 누가 쓰는지, 지켜야 할 조건은 뭔지, 무엇이 되면 성공인지 하나씩 질문해 줘.

• 확인: 하려는 일이 입력창에 적혀 있습니다.

3단계. 입력한 내용을 보냅니다

• 확인: 클로드가 분석가처럼 질문을 던지기 시작합니다.

클로드의 질문에 답하기

4단계. 클로드의 질문을 읽습니다

• 확인: 아래 네 가지가 들어 있는지 봅니다. 빠진 것이 있으면 "성공 기준도 물어봐 줘"처럼 요청합니다.
• 어디까지 만들지(범위)
• 누가 쓰는지(사용자)
• 지켜야 할 조건은 뭔지(제약)
• 무엇이 되면 성공인지(성공 기준)

5단계. 질문에 답합니다

• 주의: 답을 주고받으며 아이디어가 구체적으로 잡힐 때까지 이어 갑니다. 모르는 것은 "모르겠어, 추천해 줘"라고 답해도 되지만, 추천을 받으면 왜 그게 나은지 한 번 물어봅니다.
• 확인: "이번에 만드는 것"과 "이번에 안 만드는 것"을 내 말로 말할 수 있습니다.

intent.md로 정리하고 보관하기

6단계. 지금까지의 내용을 intent.md로 정리해 달라고 요청합니다

• 순서: 5단계에서 아이디어가 구체적으로 잡힌 다음에 합니다.

지금까지 나눈 내용을 intent.md로 정리해 줘. 왜 만드는지, 범위(만드는 것과 이번에 안 만드는 것), 누가 쓰는지, 지켜야 할 조건, 성공 기준 순서로 써 줘.

• 확인: intent.md 문서 내용이 화면에 나옵니다.

7단계. 만들어진 intent.md를 저장소의 intent 폴더에 둡니다

• 위치: 저장소 맨 위의 intent/ 폴더입니다. 폴더가 없으면 "intent 폴더를 만들고 거기에 저장해 줘"라고 하면 클로드가 만듭니다.
• 이름: 작업마다 한 장씩 쌓이므로 intent/2026-10-21-게시판.md처럼 날짜와 작업 이름을 붙이면 겹치지 않습니다.
• 주의: 파일이 어디에 저장됐는지 모르겠다면 클로드에게 저장 위치를 물어 확인합니다. 저장된 파일은 끝까지 읽고, 내 뜻과 다른 곳은 직접 고칩니다.
• 확인: intent 폴더 안에 파일이 보입니다.

8단계. 새 작업이 생기면 같은 방식으로 문서를 한 장 더 만듭니다

• 확인: intent 폴더에 작업별 문서가 쌓입니다.

다 했는지 확인

• 클로드가 물은 범위, 사용자, 조건, 성공 기준에 답했다
• 아이디어가 구체적으로 잡혔다
• intent.md로 정리해 달라고 요청했다
• 파일이 저장소의 intent 폴더에 있고, 내가 끝까지 읽고 고쳤다

그대로 써도 되는 intent.md 틀

클로드에게 정리를 맡기기 전에 틀을 정해 두면 작업마다 같은 모양으로 쌓입니다. 아래 틀을 CLAUDE.md에 "intent.md는 이 틀로 쓴다"라고 적어 두면 매번 설명하지 않아도 됩니다.

# 작업 이름

## 왜 만드나

## 범위
- 이번에 만드는 것:
- 이번에 안 만드는 것:

## 누가 쓰나

## 지켜야 할 조건

## 성공 기준
- 

성공 기준은 확인할 수 있는 문장으로 씁니다. "편하게 쓸 수 있다"보다 "로그인한 회원이 글을 쓰면 새로 고침 뒤에도 남아 있다"처럼 써야 나중에 클로드가 만든 결과를 이 기준으로 점검할 수 있습니다.