코딩 전에 쓰는 메모, intent.md란 무엇일까?

※ 초·중등학생도 이해할 수 있도록 쉽게 설명한 글입니다.

1. AI에게 바로 코드를 만들어 달라고 하면 안 될까?

AI는 코드를 아주 빠르게 만들 수 있습니다. 하지만 우리가 원하는 것을 정확히 모르면 엉뚱한 프로그램을 만들 수도 있습니다.

예를 들어 친구에게 이렇게 말한다고 생각해 봅시다.

맛있는 것 만들어 줘.

친구는 김밥을 만들 수도 있고, 라면을 만들 수도 있고, 케이크를 만들 수도 있습니다.

내가 원한 것이 김밥이었다면 처음부터 이렇게 말하는 편이 더 좋습니다.

참치와 단무지가 들어간 김밥을 만들어 줘.
매운 재료는 넣지 말아 줘.

프로그램을 만들 때도 똑같습니다. AI에게 코드를 부탁하기 전에 무엇을 만들고 싶은지 자세히 알려 주어야 합니다.

2. intent.md는 무엇인가?

intent.md는 프로그램을 만들기 전에 작성하는 아이디어 설명서입니다.

여기서 intent는 “의도” 또는 “무엇을 하려는 생각”이라는 뜻입니다.

.md는 Markdown이라는 글쓰기 형식입니다. 메모장처럼 글을 쓸 수 있고, 제목과 목록도 쉽게 만들 수 있습니다.

따라서 intent.md는 쉽게 말해 “이 프로그램을 왜 만들고, 어떤 모습으로 만들고 싶은지 적은 파일”입니다.

3. intent.md에는 무엇을 적을까?

어려운 말을 많이 쓸 필요는 없습니다. 다음 다섯 가지 질문에 답하면 됩니다.

1. 어떤 문제가 있는가?
2. 무엇을 만들고 싶은가?
3. 누가 사용할 것인가?
4. 반드시 지켜야 할 것은 무엇인가?
5. 아직 결정하지 못한 것은 무엇인가?

쉬운 예시

# 학생 검색 기능 만들기
작성자: 민수
상태: 초안
## 어떤 문제가 있나요?
학생이 많아서 원하는 학생을 찾기 어렵습니다.
## 무엇을 만들고 싶나요?
이름이나 학번을 입력하면
학생을 쉽게 찾을 수 있는 검색 기능을 만들고 싶습니다.
## 누가 사용하나요?
선생님과 학교 직원이 사용합니다.
## 꼭 지켜야 할 것은 무엇인가요?
학생의 개인정보가 아무에게나 보이면 안 됩니다.
## 아직 정하지 못한 것은 무엇인가요?
검색 결과를 몇 명까지 보여 줄지 정하지 못했습니다.

이것만 읽어도 어떤 기능을 만들고 싶은지 알 수 있습니다.

4. 왜 글로 적어 두어야 할까?

사람의 말은 시간이 지나면 달라질 수 있습니다.

처음에는 “학생을 쉽게 찾는 기능을 만들자”고 했는데, 나중에는 누군가가 “학생 정보를 모두 보여 주는 기능”으로 잘못 이해할 수도 있습니다.

하지만 처음 생각을 파일에 적어 두면 언제든 다시 확인할 수 있습니다.

즉 intent.md는 처음 생각을 잊지 않게 해 주는 약속 문서입니다.

5. AI가 작성해도 괜찮을까?

AI에게 초안을 작성해 달라고 부탁할 수 있습니다.

예를 들어 이렇게 말할 수 있습니다.

학생 검색 기능을 만들고 싶어.
내가 말한 내용을 정리해서 intent.md 파일로 만들어 줘.

AI는 우리가 말한 내용을 정리해서 intent.md 초안을 만들어 줄 수 있습니다.

하지만 AI가 만든 내용을 그대로 믿고 사용하면 안 됩니다.

AI가 내 생각을 잘못 이해했을 수도 있기 때문입니다.

6. 프로그램을 만드는 6단계

Anthropic은 AI를 이용해 프로그램을 만드는 과정을 6단계로 설명합니다.

어려워 보이지만, 학교에서 과제를 하는 과정과 비슷합니다.

7. 학교 과제로 비유해 보기

프로그램을 만드는 과정을 학교 과제를 하는 과정으로 바꾸어 생각해 보겠습니다.

1단계: Plan — 계획 세우기

과학 시간에 화산 모형을 만든다고 해 봅시다.

먼저 이렇게 생각합니다.

화산이 폭발하는 모습을 보여 주는 모형을 만들자.

이것이 바로 아이디어입니다. 이 아이디어를 자세히 적은 것이 intent.md입니다.

2단계: Design — 모양 정하기

이제 어떤 재료를 사용할지, 화산을 얼마나 크게 만들지, 어떻게 폭발하는 모습을 보여 줄지 정합니다.

프로그램에서는 이 단계에서 화면 모양과 기능을 자세히 정합니다.

3단계: Build — 만들기

정한 계획에 따라 실제로 화산 모형을 만듭니다.

프로그램에서는 AI가 코드를 만들고, 사람이 코드를 확인합니다.

4단계: Test — 시험하기

화산 모형이 정말 폭발하는지 시험합니다.

프로그램에서는 버튼을 눌렀을 때 제대로 작동하는지 확인합니다.

5단계: Deploy — 사용하게 하기

선생님과 친구들에게 모형을 보여 줍니다.

프로그램에서는 다른 사람들이 사용할 수 있도록 공개합니다.

6단계: Maintain — 계속 관리하기

친구들이 사용하다가 문제가 생기면 고칩니다.

프로그램도 사용 중 문제가 생기면 다시 고치고 시험합니다.

8. 6단계는 한 번만 하고 끝나지 않는다

프로그램은 한 번 만들었다고 끝나지 않습니다.

사용하다 보면 새로운 문제가 생길 수 있습니다.

아이디어
  ↓
계획
  ↓
만들기
  ↓
시험하기
  ↓
공개하기
  ↓
사용하기
  ↓
문제 발견
  ↓
새로운 계획

예를 들어 학생 검색 기능을 만들었는데 검색 결과가 너무 느리다는 문제가 생길 수 있습니다.

그러면 이 문제를 다시 새로운 intent.md에 적습니다.

그래서 프로그램 만들기는 계속 반복되는 동그란 과정이라고 생각하면 쉽습니다.

9. intent.md 다음에는 무엇을 만들까?

intent.md는 첫 번째 메모입니다.

그다음에는 더 자세한 문서를 만듭니다.

10. 네 가지 파일을 학교생활로 비유하면

intent.md
= 어떤 과제를 하고 싶은지 적은 아이디어 메모
spec.md
= 과제를 어떻게 만들지 자세히 적은 설명서
plan.md
= 과제를 어떤 순서로 할지 적은 순서표
CLAUDE.md
= 과제를 할 때 지켜야 하는 교실 규칙

각각의 역할이 다르기 때문에 하나의 파일로 모두 대신하지 않습니다.

11. AI가 만든 계획을 바로 실행해도 될까?

가능하면 먼저 계획을 확인하는 것이 좋습니다.

AI가 만든 계획에 잘못된 내용이 있을 수 있기 때문입니다.

예를 들어 AI가 “학생 정보를 모두 공개한다”고 계획했다면 사람은 즉시 잘못된 부분을 고쳐야 합니다.

그래서 중요한 원칙은 다음과 같습니다.

12. AI가 만든 프로그램은 꼭 시험해야 한다

AI가 만든 코드라고 해서 항상 완벽한 것은 아닙니다.

사람이 만든 프로그램도 실수할 수 있고, AI가 만든 프로그램도 실수할 수 있습니다.

그래서 다음과 같이 확인합니다.

• 버튼을 눌렀을 때 제대로 작동하는가?
• 잘못된 값을 입력해도 문제가 없는가?
• 화면이 이상하게 보이지 않는가?
• 기존 기능이 망가지지 않았는가?

코드 만들기
  ↓
시험하기
  ↓
문제 발견
  ↓
고치기
  ↓
다시 시험하기

이 과정을 여러 번 반복하면 프로그램의 품질이 좋아집니다.

13. 테스트를 먼저 만들 수도 있다

프로그램에 문제가 생겼을 때는 먼저 그 문제가 다시 나타나는지 확인하는 시험을 만들 수 있습니다.

예를 들어 검색창에 이름을 입력했는데 결과가 나오지 않는 문제가 있다고 해 봅시다.

문제 발견
  ↓
이름을 입력하는 시험 만들기
  ↓
정말 실패하는지 확인하기
  ↓
코드 고치기
  ↓
시험 통과 확인하기

이렇게 하면 문제를 제대로 고쳤는지 쉽게 확인할 수 있습니다.

14. AI가 검토해도 사람의 확인이 필요하다

AI는 코드를 만들 수도 있고, 코드를 읽고 문제를 찾을 수도 있습니다.

하지만 AI가 모든 것을 결정하게 하면 위험할 수 있습니다.

특히 다음과 같은 일은 사람이 확인해야 합니다.

• 정말 필요한 기능인가?
• 사람들이 사용하기 편한가?
• 개인정보가 안전한가?
• 프로그램이 다른 기능을 망가뜨리지 않는가?
• 실제로 공개해도 괜찮은가?

따라서 전체 과정은 다음과 같습니다.

AI가 초안 만들기
  ↓
사람이 확인하기
  ↓
문제 고치기
  ↓
다음 단계로 넘어가기

15. Hooks는 안전장치다

AI가 파일을 수정하거나 명령을 실행할 수 있게 되면 안전장치가 필요할 수 있습니다.

예를 들어 AI가 중요한 파일을 지우려고 할 때 바로 실행하지 못하게 막는 것입니다.

이런 안전장치를 Hooks라고 부릅니다.

Hooks는 다음과 같이 행동할 수 있습니다.

• 허용: 실행해도 됩니다.
• 질문: 사람에게 먼저 물어봅니다.
• 차단: 실행하지 못하게 막습니다.

학교에서 중요한 실험을 하기 전에 선생님에게 허락을 받는 것과 비슷합니다.

16. 프로그램을 공개하기 전에도 확인한다

프로그램을 만들었다고 바로 다른 사람에게 공개하지 않습니다.

먼저 AI와 사람이 함께 확인합니다.

AI가 코드 만들기
  ↓
AI가 시험하기
  ↓
AI가 코드 검토하기
  ↓
사람이 최종 확인하기
  ↓
공개하기

AI는 빠르게 많은 부분을 확인할 수 있고, 사람은 중요한 판단을 할 수 있습니다.

17. 프로그램을 만든 뒤에도 계속 관리한다

프로그램을 공개한 뒤에도 계속 살펴봐야 합니다.

예를 들어 다음과 같은 문제가 생길 수 있습니다.

• 프로그램이 너무 느려짐
• 버튼이 작동하지 않음
• 사용자가 너무 많아짐
• 화면이 깨짐
• 개인정보가 잘못 표시됨

이런 문제가 발견되면 다시 새로운 intent.md를 만들 수 있습니다.

프로그램 사용
  ↓
문제 발견
  ↓
새로운 intent.md 작성
  ↓
새로운 계획
  ↓
수정
  ↓
시험
  ↓
다시 사용

18. 폴더는 어떻게 정리할까?

기능마다 폴더를 하나씩 만들면 정리하기 쉽습니다.

intent/
│
├── 학생검색/
│   ├── intent.md
│   ├── spec.md
│   └── plan.md
│
├── 출석관리/
│   ├── intent.md
│   ├── spec.md
│   └── plan.md
│
└── 성적조회/
    ├── intent.md
    ├── spec.md
    └── plan.md

이렇게 하면 각 기능에 대해 다음 내용을 쉽게 찾을 수 있습니다.

• 왜 만들었는가?
• 무엇을 만들기로 했는가?
• 어떤 순서로 만들었는가?
• 실제 프로그램이 계획과 같은가?

19. 하나의 기능에는 하나의 계획을 둔다

학생 검색 기능과 출석 관리 기능은 서로 다른 기능입니다.

따라서 각각 따로 관리하는 것이 좋습니다.

학생검색/
├── intent.md
├── spec.md
└── plan.md
출석관리/
├── intent.md
├── spec.md
└── plan.md

한 폴더 안에 너무 많은 기능을 넣으면 어떤 계획이 어떤 코드와 연결되는지 헷갈릴 수 있습니다.

20. Git은 무엇일까?

Git은 파일의 변경 내용을 기록해 주는 도구입니다.

숙제 파일을 매번 새 이름으로 저장한다고 생각해 봅시다.

과학과제_1차.docx
과학과제_2차.docx
과학과제_최종.docx
과학과제_진짜최종.docx

Git을 사용하면 누가 언제 무엇을 바꾸었는지 더 편하게 확인할 수 있습니다.

그래서 intent.md를 Git에 저장하면 처음 아이디어가 어떻게 바뀌었는지도 볼 수 있습니다.

21. PR은 무엇일까?

PR은 다른 사람에게 “제가 이렇게 바꿨는데 확인해 주세요”라고 부탁하는 과정입니다.

조별 과제를 제출하기 전에 친구에게 먼저 보여 주고 틀린 부분이 없는지 확인해 달라고 하는 것과 비슷합니다.

프로그램에서는 다음과 같이 사용할 수 있습니다.

• intent.md를 만들고 확인받기
• spec.md를 만들고 확인받기
• 코드를 만들고 시험하기
• PR을 만들어 다른 사람이 검토하기
• 문제가 없으면 프로그램에 반영하기

22. AI와 사람은 어떤 일을 나누어 할까?

23. AI-Native SDLC를 아주 쉽게 말하면

AI-Native SDLC라는 어려운 말은 사실 다음 뜻입니다.

24. 가장 중요한 세 가지

첫째, 코드를 바로 만들지 않는다

먼저 무엇을 만들고 싶은지 적습니다.

둘째, AI가 만든 내용을 확인한다

AI는 똑똑하지만 항상 정답을 말하는 것은 아닙니다. 사람이 내용을 확인해야 합니다.

셋째, 만든 뒤에도 계속 시험한다

프로그램은 사용하면서 문제가 발견될 수 있습니다. 문제가 생기면 다시 계획을 세우고 고칩니다.

25. 한 문장으로 정리하면

26. 전체 과정 한눈에 보기

아이디어가 생김
  ↓
intent.md에 생각을 적음
  ↓
사람이 내용 확인
  ↓
spec.md에 자세한 기능을 적음
  ↓
plan.md에 만드는 순서를 적음
  ↓
AI가 코드 작성
  ↓
테스트하고 문제 고치기
  ↓
AI와 사람이 코드 검토
  ↓
프로그램 공개
  ↓
사용 중 문제 발견
  ↓
새로운 intent.md 작성

27. 마무리

AI는 프로그램을 빠르게 만들어 주는 좋은 도구입니다.

하지만 AI에게 아무 설명 없이 “프로그램 만들어 줘”라고 하면 내가 원하는 것과 다른 결과가 나올 수 있습니다.

그래서 먼저 생각을 정리하고, 그 내용을 intent.md에 적습니다.

그다음 자세한 설명과 만드는 순서를 정하고, AI와 함께 코드를 만듭니다.

마지막으로 반드시 시험하고, 사람이 확인한 뒤 사용합니다.

이것이 AI를 이용해 프로그램을 안전하고 똑똑하게 만드는 방법입니다.

※ 이 글은 Anthropic과 Claude Academy에서 설명하는 AI-Native SDLC 개념을 초·중등학생도 이해할 수 있도록 쉬운 말과 학교 과제 비유로 다시 설명한 글입니다.

#intentmd #AI개발 #AI코딩 #Claude #ClaudeCode #프로그램만들기 #소프트웨어개발 #코딩공부 #개발공부 #AI공부