작업 계획 문서로 만들 앱 정하기

1. 3편에서 이어서 보기

3편에서는 myproject01 프로젝트 폴더를 만들고, 그 안에 docs/ 폴더와 agent.md 자리를 준비했다. 이번 글은 그 작업 공간 안에서 첫 번째 설계 문서를 채우는 단계다.

이번 4편에서는 무엇을 만들지 먼저 글로 정리하는 법을 배운다. 이 과정이 바로 작업 계획 문서 작성이고, 결과물은 docs/01-plan.md에 들어간다.

프로젝트 폴더를 먼저 만든 뒤 작업 계획 문서를 쓰면 좋은 이유는 간단하다.

• AI에게 더 정확하게 요청할 수 있다.
• 만들다 중간에 방향이 흔들리는 일을 줄일 수 있다.
• 기능, 데이터, 화면을 한 번에 정리할 수 있다.

2. 이번 글에서 다루는 것

이 글은 아직 코드를 쓰지 않는다. 대신 앱을 만들기 전에 반드시 거쳐야 하는 단계인 작업 계획 문서 작성을 다룬다.

바이브 코딩에서 가장 흔한 실수는 이런 것이다. AI에게 "앱 만들어 줘"라고만 말하고, 만들어진 결과가 내가 원한 것과 다르면 당황하는 것이다. 왜냐하면 내 머릿속에 있는 목표를 글로 정리한 적이 없기 때문이다.

예를 들어, AI가 이런 화면을 만들어 주었다고 하자.

• 학생 목록은 나오지만 제출 여부를 바꿀 수 없다
• 색깔 표시가 너무 강해서 화면에서 보기 어렵다
• 저장 버튼이 없어서 새로고침하면 내용이 사라진다

이런 문제는 AI가 나빠서가 아니다. 요청이 너무 넓었기 때문이다.

그래서 이번 글에서는 다음을 해본다.

• 이 시리즈에서 만들 앱의 구체적인 모습을 하나로 정한다
• 앱이 해야 할 일을 작은 단위로 쪼개 본다
• 각 기능에 필요한 자료 형태를 간단히 정리해 본다
• docs/01-plan.md 작업 계획 문서 하나를 직접 작성해 본다

3. 이번 글에서 새로 나오는 용어

1. 작업 계획 문서: 앱을 만들기 전에 목표, 기능, 데이터, 화면을 정리한 문서
2. 기능: 사용자를 위해 앱이 수행하는 하나의 일
3. 입력: 사용자가 앱에 넣거나 프로그램이 처리하기 위해 받는 정보
4. 출력: 프로그램이 처리한 뒤 사용자에게 보여 주거나 돌려주는 결과
5. 로직: 입력을 어떤 순서와 조건으로 처리할지 정한 규칙
6. 자료 형태: 데이터가 글자, 숫자, 예/아니오처럼 어떤 모양으로 저장되는지 정한 것
7. 화면: 사용자가 앱에서 직접 보고 조작하는 한 장면

4. 핵심 개념

이번 글의 핵심은 머릿속 생각을 작업 계획 문서로 바꾸는 것이다. 작업 계획 문서는 앱을 만들기 전에 어떤 서비스를 만들 것인지, 어떤 기능이 필요한지, 어떤 데이터를 다룰 것인지를 정리한 문서다. 건축에서 설계 도면을 먼저 그리는 것과 비슷하다.

비유를 하나 더 들어 보자. 여행을 가기 전에 목적지, 날짜, 준비물, 이동 방법을 적어 두면 실제 여행이 덜 흔들린다. 작업 계획 문서도 비슷하다. 앱을 만들기 전에 "무엇을 만들지", "누가 쓸지", "어떤 자료가 필요할지"를 적어 두는 여행 계획표 같은 역할을 한다.

작업 계획 문서를 쓰려면 먼저 앱이 해야 할 일을 작은 단위로 나눠야 한다. 이 작은 일을 기능이라고 한다. 예를 들어 "학생 목록을 보여 준다"와 "제출 여부를 저장한다"는 서로 다른 기능이다. 장보기 목록에서 "채소 사기", "고기 사기", "양념 확인하기"를 따로 적는 것처럼, 앱의 일도 작은 항목으로 나누어 적는다.

기능을 적을 때는 세 가지 질문을 함께 붙이면 좋다. 사용자가 넣는 정보는 입력, 앱이 보여 주는 결과는 출력, 그 사이에서 어떤 순서와 조건으로 처리할지를 정한 규칙은 로직이라고 부른다. 식당 주문으로 비유하면, 손님이 주문서에 적는 내용은 입력이고, 주방이 내놓는 음식은 출력이며, "매운맛을 선택하면 고추를 추가한다" 같은 조리 규칙은 로직이다.

마지막으로 각 기능이 다루는 자료 형태를 정한다. 자료 형태는 데이터가 어떤 모양으로 저장되고 다뤄지는지를 뜻한다. 학생 이름은 글자, 번호는 숫자, 제출 여부는 예/아니오처럼 정리해 두면 AI에게도 훨씬 정확히 요청할 수 있다.

이 시리즈에서 만드는 앱은 내 컴퓨터에서 실행되는 작은 Python 프로그램이다. 처음에는 검은 화면(터미널)에서 글자로만 동작하는 간단한 버전을 만들고, 그다음에 창이 뜨는 GUI 버전으로 바꾼다.

5. 어떤 앱을 만들 것인지 정하기

이 시리즈에서는 예시로 하나의 앱을 정하고, 그 앱을 만들어 가는 과정을 기록할 것이다. 1편에서 잠깐 언급했던 것처럼, 학생들의 과제 제출 현황을 관리하는 작은 앱으로 정하겠다.

이 예시는 학교 현장에서 바로 쓸 수 있지만, 팀 프로젝트 참여 현황, 동아리 활동 참석 체크, 개인적인 할 일 관리 등으로 응용할 수도 있다. 앱의 기본 정보를 정리하면 다음과 같다.

• 앱 이름: 학생 과제 제출 현황
• 목적: 학생들의 과제 제출 여부를 쉽게 확인하고 관리한다
• 사용자: 담당자(교사나 팀장 등)
• 상황: 과제를 내준 뒤, 누가 냈고 누가 안 냈는지를 빠르게 확인하고 싶다

이 정도로 정하면 앱의 큰 그림이 보인다. 하지만 아직 부족하다. 이 앱이 구체적으로 어떤 일을 해야 하는지를 더 쪼개야 한다.

6. 앱이 해야 할 일 쪼개기

큰 목표를 작은 기능 단위로 쪼개 보자. 기능은 앱이 사용자를 위해 하는 하나의 일이다.

먼저 기능을 나누기 전에, 아래 질문을 스스로 던져 보면 좋다.

• 사용자는 무엇을 넣을까? → 입력
• 앱은 무엇을 보여 줄까? → 출력
• 앱은 어떤 규칙으로 판단할까? → 로직
• 이 기능은 어떤 화면에서 보일까? → 화면

이 체크 순서로 보면 기능이 훨씬 쉽게 정리된다.

이 앱이 해야 할 기능을 뽑아보면 다음과 같다.

1. 학생 목록 보여 주기

   • 화면에 학생 이름을 목록으로 보여 준다
   • 입력: 없음
   • 출력: 학생 이름 목록

2. 제출 여부 입력받기

   • 각 학생별로 과제를 냈는지 안 냈는지 표시한다
   • 입력: 학생 이름, 제출 여부(예/아니오)
   • 출력: 저장된 제출 정보

3. 제출 현황 보여 주기

   • 전체 학생 중 제출한 사람과 미제출 사람을 나누어 보여 준다
   • 입력: 저장된 제출 여부 데이터
   • 로직: 제출 여부가 "아니오"인 학생은 미제출 목록에 넣는다
   • 출력: 제출한 학생 목록, 미제출 학생 목록

4. 미제출 학생 강조 표시

   • 미제출 학생의 이름을 빨간색으로 표시한다
   • 입력: 미제출 학생 목록
   • 로직: 미제출 목록에 있는 학생은 화면에서 색을 다르게 한다
   • 출력: 색깔이 구분된 학생 목록

이렇게 기능을 쪼개면 각 기능이 무엇을 입력받고, 어떤 규칙으로 처리하고, 무엇을 출력하는지가 명확해진다. 이것이 로직을 규명하는 과정이다.

글로만 보면 길어 보일 수 있으니, 같은 내용을 두 개의 작은 워크플로우 차트로 나누어 보자. 하나는 교사가 앱을 쓰는 흐름이고, 다른 하나는 학생 제출 상태가 앱 안에서 처리되는 흐름이다. 두 흐름을 나누면 “누가 앱을 쓰는가”와 “앱이 어떤 자료를 판단하는가”가 덜 섞인다.

먼저 교사 입장에서 보는 흐름이다.

이 차트는 사용자의 행동 순서를 보여 준다. 교사는 앱을 열고, 학생 목록을 확인하고, 제출 여부를 입력하거나 수정한 뒤, 마지막으로 제출 현황을 확인한다.

다음은 학생 제출 상태가 앱 안에서 처리되는 흐름이다.

이 차트는 앱이 판단하는 자료의 흐름을 보여 준다. 학생이 직접 이 앱을 조작한다는 뜻이 아니라, 학생들의 제출 상태가 앱 안에 자료로 저장되고, 앱은 그 자료를 기준으로 제출/미제출을 나누어 교사에게 보여 준다는 뜻이다.

7. 이 기능이 화면과 어떻게 연결되는가

기능을 나눴다면, 이제 화면으로 옮겨 보자. 화면은 사용자가 직접 보는 부분이다.

이 앱이라면 화면도 자연스럽게 나눠진다.

• 학생 목록 화면: 학생 이름을 보여 주는 화면
• 제출 입력 화면: 제출 여부를 적는 화면
• 제출 현황 화면: 제출한 학생과 미제출 학생을 나누어 보여 주는 화면

즉, 기능을 먼저 나누면 화면도 따라 나온다. 반대로 말하면, 화면부터 무작정 만들면 빠뜨리는 기능이 생기기 쉽다.

8. 필요한 자료 형태 정리하기

이제 각 기능에서 다루는 데이터가 어떤 모양인지 정리해 보자. 자료 형태는 데이터가 어떤 모양으로 저장되고 다뤄지는지를 뜻한다.

이 부분은 어렵게 느껴질 수 있으니, 서랍에 물건을 정리한다고 생각하면 쉽다. 이름표가 붙은 칸을 만들고, 그 안에 맞는 자료를 넣는 것이다.

또는 신청서 양식을 떠올려도 좋다. 이름 칸에는 글자를 쓰고, 인원 수 칸에는 숫자를 쓰고, 동의 여부 칸에는 예/아니오를 표시한다. 자료 형태를 정한다는 것은 앱 안에서도 이런 칸의 성격을 미리 정해 두는 일이다.

이 앱에서 필요한 데이터는 크게 두 가지이다.

첫째, 학생 정보이다.

• 이름: 글자(문자열)
• 반: 글자 또는 숫자(예: "2" 또는 "2반")
• 번호: 숫자(예: 1번, 2번)

여기서 하나 덧붙이면 좋다. 실제 앱에서는 학생 이름이 겹칠 수 있으므로, 별도의 학생 ID를 쓰기도 한다. 하지만 이 시리즈에서는 이해를 쉽게 하기 위해 먼저 학생 이름 중심으로 설명한다.

둘째, 제출 정보이다.

• 학생 이름: 글자(문자열)
• 과제 이름: 글자(예: "수행평가 1", "독서록")
• 제출 여부: 예/아니오(불리언)
• 제출 날짜: 날짜(선택 사항)

이렇게 적어 두면, 나중에 AI에게 "학생 데이터를 어떻게 저장할까요?"라고 물을 때, 내가 원하는 자료 형태를 정확히 말할 수 있다.

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

"학생 정보는 이름(글자), 반(글자), 번호(숫자)로 저장하고, 제출 정보는 학생 이름(글자), 과제 이름(글자), 제출 여부(예/아니오)로 저장해 주세요."

9. 작업 계획 문서 예시

지금까지 정리한 내용을 docs/01-plan.md 파일 하나로 모아 보자. 이것이 작업 계획 문서이다.

잠깐 쉬어 가자. 아래 문서는 myproject01/docs/01-plan.md에 들어갈 내용이다. 길어 보이지만, 사실 방금까지 정리한 내용을 한 번에 모아 놓은 것뿐이다. 처음부터 이렇게 길게 쓰지 않아도 된다. 일단 뼈대만 먼저 만들면 된다.

처음에는 아래 정도만 적어도 출발할 수 있다.

앱 이름: 학생 과제 제출 현황
사용자: 교사

하고 싶은 일:
1. 학생 목록을 본다.
2. 제출 여부를 체크한다.
3. 미제출 학생을 따로 본다.

자료:
- 학생 이름
- 반
- 번호
- 제출 여부

이 정도가 최소 뼈대다. 아래 예시는 이 뼈대를 조금 더 자세히 펼친 버전이라고 보면 된다.

[작업 계획 문서]

앱 이름: 학생 과제 제출 현황
목적: 학생들의 과제 제출 여부를 쉽게 확인하고 관리한다
사용자: 담당자
상황: 과제를 내준 뒤, 누가 냈고 누가 안 냈는지를 빠르게 확인하고 싶다

[기능 목록]

1. 학생 목록 보여 주기
   - 입력: 없음
   - 출력: 학생 이름 목록
   - 화면: 학생 목록 화면

2. 제출 여부 입력받기
   - 입력: 학생 이름, 제출 여부(예/아니오)
   - 출력: 저장된 제출 정보
   - 화면: 제출 입력 화면

3. 제출 현황 보여 주기
   - 입력: 저장된 제출 여부 데이터
   - 로직: 제출 여부가 "아니오"인 학생은 미제출 목록에 넣는다
   - 출력: 제출한 학생 목록, 미제출 학생 목록
   - 화면: 제출 현황 화면

4. 미제출 학생 강조 표시
   - 입력: 미제출 학생 목록
   - 로직: 미제출 목록에 있는 학생은 화면에서 빨간색으로 표시한다
   - 출력: 색깔이 구분된 학생 목록
   - 화면: 제출 현황 화면

[자료 형태]

학생 정보:
- 이름: 글자(문자열)
- 반: 글자 또는 숫자
- 번호: 숫자

제출 정보:
- 학생 이름: 글자(문자열)
- 과제 이름: 글자(문자열)
- 제출 여부: 예/아니오(불리언)
- 제출 날짜: 날짜(선택 사항)

[화면 구성]

- 메인 화면: 학생 목록과 제출 현황을 한눈에 볼 수 있는 표
- 입력 화면: 학생별 제출 여부를 입력하는 화면

[우선순위]

- 먼저 만들 것: 학생 목록, 제출 여부 입력, 제출/미제출 목록
- 나중에 생각할 것: 자동 알림, AI 피드백, 통계 그래프

[예외 상황]

- 이름이 비어 있으면 저장하지 않는다
- 제출 여부를 선택하지 않으면 다시 확인하게 한다

이 문서 하나만 있어도 AI에게 훨씬 구체적으로 요청할 수 있다. 예를 들어 이렇게 말할 수 있다.

"작업 계획 문서에 따라 학생 과제 제출 현황 앱을 만들어 주세요. 학생 정보는 이름, 반, 번호로 저장하고, 제출 여부는 예/아니오로 저장해 주세요. 메인 화면에서는 전체 학생 목록과 제출 현황을 표로 보여 주고, 미제출 학생은 빨간색으로 표시해 주세요."

10. 바이브하게 작업 계획 문서 만들기

작업 계획 문서는 혼자 처음부터 완벽하게 쓰려고 하면 어렵다. 이럴 때 AI와 대화하면서 초안을 만들고, 그 초안을 내 상황에 맞게 고치는 방식으로 진행하면 좋다. 여기서 프롬프트는 AI에게 보내는 요청문을 뜻한다.

이 섹션은 단순한 예시가 아니라 첫 번째 설계 워크북이다. 아래 프롬프트를 순서대로 사용하면 docs/01-plan.md에 넣을 작업 계획 문서 초안을 얻는 것이 목표다.

진행 흐름은 이렇다.

1. 첫 프롬프트로 작업 계획 문서 초안을 받는다.
2. 두 번째 프롬프트로 기능을 줄이고 우선순위를 정한다.
3. AI 답변 중 앱 목적, 사용자, 기능, 입력·출력·로직, 자료 형태를 골라 docs/01-plan.md에 붙인다.
4. 애매한 부분은 "확인 필요"로 남겨 두고 다음 장에서 구조 설계로 넘긴다.

10-1. 처음 초안을 부탁하는 프롬프트

나는 IT 분야 비전공자이고, 내 컴퓨터에서 실행되는 작은 Python 프로그램을 만들고 싶습니다.
앱의 목적은 여러 사람의 과제 제출 여부를 입력하고,
제출한 사람과 미제출한 사람을 나누어 보는 것입니다.

이 앱을 만들기 전에 작업 계획 문서를 작성하려고 합니다.
다음 항목으로 나누어 초안을 만들어 주세요.

1. 앱의 목적
2. 사용자와 사용 상황
3. 핵심 기능
4. 각 기능의 입력, 출력, 로직
5. 필요한 자료 형태
6. 먼저 만들 것과 나중에 만들 것
7. 간단한 예외 상황

전문 개발자 용어를 쓰더라도, 처음 나오는 용어는 짧게 설명해 주세요.
아직 구현 코드는 만들지 말고, 설계 문서 초안만 작성해 주세요.
마지막에는 내가 더 확인해야 할 가정과 위험 요소도 적어 주세요.

예상 결과는 완성된 코드가 아니다. AI가 앱의 목적, 기능 목록, 입력과 출력, 자료 형태를 문서 형태로 정리해 주는 것이 정상이다. 이 결과에서 앱의 목적, 사용자와 사용 상황, 핵심 기능 부분은 그대로 docs/01-plan.md의 앞부분으로 옮길 수 있다.

10-2. 초안을 더 구체적으로 고치는 프롬프트

AI가 만든 초안이 너무 넓거나 막연하면 이렇게 다시 요청한다.

좋습니다. 그런데 처음 버전은 너무 기능이 많습니다.
첫 번째 버전에서 꼭 필요한 기능만 남겨 주세요.

기준은 다음과 같습니다.
- 하루 안에 초안을 만들 수 있을 정도로 작게 나눈다.
- 로그인, 알림, 통계 그래프는 나중 기능으로 보낸다.
- 입력, 출력, 로직을 더 짧고 분명하게 쓴다.
- 개인정보나 민감한 자료를 다룰 때 주의할 점을 한 줄로 적는다.
- 아직 코드 예시는 만들지 않는다.

예상 결과는 기능 범위가 줄어든 작업 계획 문서다. 이 결과에서 먼저 만들 것, 나중에 생각할 것, 예외 상황을 골라 docs/01-plan.md의 뒷부분에 붙인다. 바이브하게 설계한다는 것은 AI가 준 답을 그대로 믿는 것이 아니라, 내 목적에 맞게 작게 줄이고 다시 정리하는 과정이다.

11. 작업 계획 문서를 작성할 때의 팁

작업 계획 문서를 작성할 때 유용한 몇 가지 팁을 정리한다.

첫째, 처음부터 완벽하게 적으려 하지 않는다. 대략적인 기능 목록만 먼저 적고, 세부 사항은 점점 채워 나간다.

둘째, 하나의 기능은 하나의 일만 하도록 쪼갠다. 예를 들어 "학생 목록을 보여 주고 제출 여부를 입력받고 현황을 보여 준다"는 너무 크다. 이것을 "학생 목록 보여 주기", "제출 여부 입력받기", "현황 보여 주기"로 나눈다.

셋째, 입력과 출력을 명확히 적는다. 기능이 무엇을 받아서 무엇을 만드는지를 적어 두면, 나중에 AI가 코드를 만들 때도 데이터 흐름이 명확해진다.

넷째, 자료 형태를 간단히라도 적는다. 이름은 글자, 번호는 숫자, 제출 여부는 예/아니오처럼 간단히 적어도 충분하다.

다섯째, 먼저 만들 기능과 나중에 만들 기능을 나눈다. 모든 기능을 한 번에 만들려고 하면 부담이 커진다. "먼저 만들 것"과 "나중에 생각할 것"을 구분하면 AI에게도 단계적으로 요청하기 쉽다.

여섯째, 아주 간단한 예외 상황을 적는다. 예를 들어 이름이 비어 있으면 저장하지 않는다거나, 제출 여부를 선택하지 않으면 다시 확인하게 한다는 정도면 충분하다.

12. 첫 코드를 만들기 전에 agent.md에 적어둘 개발 환경

이제 docs/01-plan.md에 만들 앱의 윤곽이 생겼다. 다음 글에서는 이 내용을 바탕으로 첫 Python 파일을 만들기 시작한다.

그래서 여기서 한 가지 원칙을 agent.md에 미리 적어 둔다. 바로 Python은 uv 가상환경 안에서만 다룬다는 원칙이다.

아래 내용을 agent.md에 추가한다.

## 개발 환경

- 이 프로젝트는 uv(astral-sh/uv)로 Python 가상환경을 관리합니다.
- 모든 Python 코드와 패키지 설치는 가상환경(.venv) 내에서 실행합니다.
- 시스템 전역 Python을 직접 사용하지 않습니다.

### uv 설치 확인
- `uv --version`으로 uv가 설치되어 있는지 먼저 확인합니다.
- 설치되어 있지 않다면 https://github.com/astral-sh/uv 에서 설치합니다.

### 가상환경 생성
- 프로젝트 루트(myproject01/)에서 `uv venv`를 실행합니다.
- `.venv` 폴더가 생성되면 성공입니다.

### 패키지 설치
- PySide6 같은 외부 패키지는 `uv add PySide6`으로 설치합니다.
- requirements.txt는 `uv add -r requirements.txt`로 처리합니다.

### 코드 실행
- Python 스크립트는 `uv run python script.py`로 실행합니다.
- 이렇게 하면 가상환경을 자동으로 활성화한 채 실행됩니다.

이 조항은 지금 당장 코드를 만들기 위한 내용이라기보다, 다음 글부터 AI가 Python 작업을 시작할 때 지켜야 할 작업 규칙이다. 이렇게 해 두면 AI가 시스템 전역 Python에 아무 패키지나 설치하지 않고, 프로젝트 안의 .venv를 기준으로 작업하게 된다.

13. 다른 AI 코딩 도구를 쓴다면

이 시리즈는 opencode를 기준으로 설명한다. 다른 AI 코딩 도구를 쓴다면 명령어만 바꾸면 된다.

도구	실행 명령	비고
opencode	opencode	이 시리즈의 기본
Claude Code	claude	Anthropic 계정 필요
Gemini CLI	gemini	Google 계정 필요
Antigravity	데스크톱 앱 실행	터미널 대신 GUI
Codex CLI	codex	OpenAI 계정 필요

도구가 달라도 다음 흐름은 같다.

1. 프로젝트 폴더에서 도구를 실행한다.
2. agent.md와 docs/ 안의 문서를 읽게 한다.
3. 자연어로 요청한다.
4. 결과를 확인하고 다시 요청한다.

14. 다음 글에서 할 일

오늘 여기까지 했으면 성공

이번 글을 끝내고 나면 docs/01-plan.md 안에 앱 이름, 목적, 사용자, 핵심 기능, 입력, 출력, 로직, 자료 형태가 대략 적혀 있어야 한다. 문장이 완벽하지 않아도 된다. 중요한 것은 "무엇을 만들지"가 빈칸으로 남아 있지 않은 것이다.

다음 글에서는 작업 계획 문서와 agent.md의 uv 원칙을 바탕으로 아주 작은 Python CLI 버전의 첫 기능을 만들어 본다.

4편에서 "무엇을 만들지"와 "Python 작업은 uv 안에서 한다"는 원칙을 정했다면, 5편에서는 이 원칙을 지키며 첫 기능을 실행해 본다. 아직 창이 뜨는 앱까지 가지 않고, 터미널에서 입력·처리·출력 흐름을 먼저 확인할 것이다.

다음 글의 목표는 다음과 같다.

• docs/01-plan.md를 AI에게 읽게 하기
• app.py라는 첫 Python 파일 만들기
• 학생 이름과 제출 여부를 입력받기
• 제출/미제출 목록을 터미널에 출력하기

여기까지 하면 앱은 더 이상 문서 속 생각이 아니라, 실제로 실행되는 첫 프로그램이 된다.