Decide What App to Build with a Planning Document

1. Continuing from part 3

In part 3, you created the myproject01 project folder and prepared docs/ plus a place for agent.md. This post fills the first design document inside that workspace.

In part 4, you will learn how to write down what you want to build before asking for code. But you will not stare at an empty document and write the whole plan alone. In this tutorial, the default workflow is to shape the app outline together with the agent, then split the result between docs/01-plan.md and agent.md.

Writing the planning document after creating the project folder helps because:

• You can ask AI more precisely.
• You reduce the chance of changing direction in the middle.
• You can organize features, data, and screens together.

2. What this post covers

This post still does not write code. Instead, it covers a step that should happen before coding: writing a planning document. By default, you do not write the full plan alone. You open your AI coding tool in the myproject01 folder, ask the agent to draft the outline with you, and then save the parts you accept into project files.

The basic pattern is:

1. Explain your idea in natural language.
2. Let the agent ask questions and suggest a structured outline.
3. Copy only the useful parts into docs/01-plan.md.
4. Write work-stage notes and do-not-do rules in agent.md.

This is the design pattern we will repeat when adding features later.

A common mistake in vibe coding is asking AI only, "Make an app." Then, when the result is not what you wanted, you feel confused. The problem is often that the goal in your head was never written down.

For example, AI might create a screen where:

• the student list appears, but submission status cannot be changed;
• the colors are too strong and hard to read;
• there is no save button, so everything disappears when the app restarts.

That does not mean AI is bad. It means the request was too broad.

So in this post, we will:

• ask the AI agent to draft the app outline;
• reduce oversized features and choose priorities;
• split the app's work into small features;
• briefly organize the data shape each feature needs;
• write app design into docs/01-plan.md;
• write AI work rules into agent.md.

3. New terms in this post

1. Planning document document: a document that organizes the goal, features, data, and screens before building an app
2. Feature: one task the app performs for the user
3. Input: information the user gives to the app or the program receives for processing
4. Output: the result the program shows or returns after processing
5. Logic: rules that decide how input is processed in order and under conditions
6. Data type: the shape of data, such as text, number, or yes/no
7. Screen: one view the user directly sees and controls

4. First, shape the app outline together with the agent

The starting point of this post is not writing sentences alone in an empty file. Open your AI coding tool from the myproject01 folder you created in part 3, and first tell the agent this.

This project is being developed inside the myproject01 folder.
The goal right now is not to write code, but to shape the outline for the planning document that will go into docs/01-plan.md.

Do not create app.py or any other code file yet.
First, ask questions and organize the app purpose, user, and core features.
Then ask what input the app receives, what output it shows, what thinking order or rule (logic) happens in between, and what data shape is needed, such as a list, table, or yes/no value.
If something is unclear, do not decide it by yourself. Mark it as `Needs clarification: ...`.

This prompt guides the AI away from writing code immediately and toward asking what should be built first.

At this point, agent.md is not a finished rulebook yet. Start using it as a short work stage summary + do-not-do rules memo the agent should read. Put app design in docs/01-plan.md, such as purpose, user, features, input/output/logic, and data shapes. Put only AI work rules and current-stage notes in agent.md. For example, write this in agent.md.

## Current Work Stage

- We are currently writing docs/01-plan.md.
- Do not create Python code files yet.
- First make a numbered question list, and write a design draft only after receiving my answers.
- Organize the app purpose, user, core features, input, output, logic, and data shapes.
- If something is unclear, mark it as `Needs clarification: ...` instead of deciding it silently.

With this in place, whether you continue in the same chat or reopen the agent later, the project keeps a clear rule: this step is for planning. Later, when you ask the agent for help, start by saying, "Please read agent.md first." Then the agent can use these work rules as its baseline.

5. Core idea

The core idea is to turn thoughts in your head into a planning document. A planning document organizes what service or program you want to make, which features it needs, and what data it handles. It is similar to drawing a blueprint before building a house.

Another comparison is a travel plan. Before traveling, you write the destination, date, things to bring, and how to get there. A planning document does the same for an app. It lists what to build, who will use it, and what data it needs.

To write the plan, first divide the app's work into small parts. These small parts are called features. For example, "show the student list" and "save submission status" are different features. Just as a shopping list separates vegetables, meat, and seasoning, an app's work should also be separated into small items.

When writing a feature, attach three questions. The information the user gives is input. The result the app shows is output. The rule in between is logic. In a restaurant example, the order form is input, the food is output, and a rule like "add chili if spicy is selected" is logic.

Finally, decide the data type each feature uses. Data type means what shape the data has and how it is handled. Student name is text, student number is a number, and submission status is yes/no. Writing this down makes your request to AI much clearer.

The app in this series is a small Python program that runs on your computer. First, we will make a simple text-only version in the terminal. Later, we will turn it into a GUI app with a window.

6. Decide which app to build

This series will use one example app and build it step by step: a small app for managing student assignment submission status.

This example can be used directly in a school setting, but the same idea also applies to project participation, club attendance, or personal task tracking. The basic information looks like this.

• App name: Student Assignment Submission Status
• Purpose: check and manage whether students submitted an assignment
• User: a person in charge, such as a teacher or team leader
• Situation: after assigning work, the user wants to quickly see who submitted and who did not

This gives us the big picture, but it is not enough yet. We still need to split the app into concrete tasks.

7. Split what the app must do

Let's split the big goal into small features. A feature is one thing the app does for the user.

Before listing features, ask yourself these questions.

• What does the user enter? → input
• What does the app show? → output
• What rule does the app use to decide? → logic
• Which screen will show this feature? → screen

Using this order makes features easier to organize.

For this app, the features are:

1. Show the student list

   • show student names in a list
   • input: none
   • output: list of student names

2. Receive submission status

   • mark whether each student submitted the assignment
   • input: student name, submission status (yes/no)
   • output: saved submission information

3. Show submission status

   • separate submitted and missing students
   • input: saved submission status data
   • logic: if submission status is "no," put the student in the missing list
   • output: submitted list and missing list

4. Highlight missing students

   • display missing students in red
   • input: missing student list
   • logic: if a student is in the missing list, display the name with a different color
   • output: a visually separated student list

When features are split this way, it becomes clear what each feature receives, how it processes data, and what it outputs. This is the process of clarifying logic.

Because text alone can feel long, let's divide the same idea into two small workflow charts. One shows how the teacher uses the app. The other shows how student submission status is processed inside the app. Separating the flows prevents two questions from getting mixed: "Who uses the app?" and "What data does the app judge?"

First, the teacher's flow.

This chart shows the user's actions. The teacher opens the app, checks the student list, enters or edits submission status, and then reviews the final status.

Next, the data flow inside the app.

This chart shows how the app judges data. It does not mean students directly use this app. It means students' submission states are stored as data, then the app sorts the data and shows the result to the teacher.

8. Connect features to screens

After splitting features, connect them to screens. A screen is what the user directly sees.

For this app, the screens naturally become:

• Student list screen: shows student names
• Submission input screen: lets the user enter submission status
• Submission status screen: shows submitted and missing students separately

In other words, when features are clear, screens follow. If you start from screens without listing features, it is easier to miss something.

9. Organize the data shapes

Now organize what shape the data should have. A data type means the shape in which data is stored and handled.

If this feels difficult, think of organizing items in drawers. You create labeled spaces and put the right kind of item into each space.

A form is another good example. The name field takes text, the number-of-people field takes a number, and the agreement field takes yes/no. Deciding data type means deciding those field shapes inside the app.

This app needs two main kinds of data.

First, student information.

• Name: text (string)
• Class: text or number (for example, "2" or "Class 2")
• Number: number (for example, 1, 2)

In a real app, students may have the same name, so a separate student ID is often used. In this series, we start with student names to keep the explanation simple.

Second, submission information.

• Student name: text (string)
• Assignment name: text (for example, "Performance Task 1" or "Reading Log")
• Submitted: yes/no (boolean)
• Submitted date: date (optional)

With this written down, you can ask AI much more precisely: "How should I save student data?"

For example:

"Save student information as name (text), class (text), and number (number). Save submission information as student name (text), assignment name (text), and submitted (yes/no)."

10. Example planning document

Now gather everything into one file: docs/01-plan.md. This is the planning document.

Take a breath. The document below goes into myproject01/docs/01-plan.md. It may look long, but it simply collects what we organized above. You do not need to start this long. A small skeleton is enough.

At first, you can write only this much.

App name: Student Assignment Submission Status
User: teacher

What I want to do:
1. See the student list.
2. Check submission status.
3. See missing students separately.

Data:
- Student name
- Class
- Number
- Submission status

That is the minimum skeleton. The example below is just a more detailed version of the same skeleton.

[Planning Document]

App name: Student Assignment Submission Status
Purpose: easily check and manage whether students submitted assignments
User: person in charge
Situation: after assigning work, quickly see who submitted and who did not

[Feature List]

1. Show student list
   - Input: none
   - Output: list of student names
   - Screen: student list screen

2. Receive submission status
   - Input: student name, submission status (yes/no)
   - Output: saved submission information
   - Screen: submission input screen

3. Show submission status
   - Input: saved submission status data
   - Logic: if submission status is "no," put the student in the missing list
   - Output: submitted student list, missing student list
   - Screen: submission status screen

4. Highlight missing students
   - Input: missing student list
   - Logic: display students in the missing list in red
   - Output: student list with visual distinction
   - Screen: submission status screen

[Data Shapes]

Student information:
- Name: text (string)
- Class: text or number
- Number: number

Submission information:
- Student name: text (string)
- Assignment name: text (string)
- Submitted: yes/no (boolean)
- Submitted date: date (optional)

[Screen Layout]

- Main screen: a table where student list and submission status can be seen together
- Input screen: a screen for entering each student's submission status

[Priority]

- Build first: student list, submission input, submitted/missing lists
- Think later: automatic alerts, AI feedback, statistics graphs

[Exception Cases]

- Do not save if the name is empty
- Ask again if submission status is not selected

With this one document, you can ask AI much more concretely. For example:

"Build a student assignment submission status app based on the planning document. Save student information as name, class, and number. Save submission status as yes/no. On the main screen, show the student list and submission status in a table, and display missing students in red."

11. Build the planning document together with the agent

A planning document is hard to write perfectly from scratch. In this series, the default method is to talk with the AI agent, get a draft, then adjust that draft to your real situation. A prompt is the request you send to AI.

This section is not just an example. It is the first design workbook. If you use the prompts in order, the goal is to shape the app outline with the agent and get a planning document draft for docs/01-plan.md.

The flow is:

1. Write today's work stage and restrictions briefly in agent.md.
2. Use the first prompt to ask the agent for the app outline and a planning document draft.
3. Use the second prompt to reduce scope and set priorities.
4. Pick out the app purpose, user, features, input/output/logic, and data shapes from the AI answer and paste them into docs/01-plan.md.
5. Leave unclear parts as "needs confirmation" and check them again before moving to the first code.

11-1. Prompt for the first draft

I am working in the myproject01 project folder.
Right now I am not writing code. I am shaping the outline for the planning document that will go into docs/01-plan.md.

I am not an IT major, and I want to build a small Python program that runs on my computer.
The purpose is to enter several people's assignment submission status
and see submitted and missing people separately.

Before building the app, I want to write a planning document.
Please create a draft with the following sections.

1. App purpose
2. User and usage situation
3. Core features
4. Input, output, and logic for each feature
5. Needed data shapes
6. What to build first and what to postpone
7. Simple exception cases

If you use developer terms, briefly explain any term when it first appears.
Do not write implementation code yet. Only write a design document draft.
If something is unclear, do not decide it by yourself. Mark it as "needs confirmation".
At the end, also list assumptions and risks I should check.

The expected result is not finished code. AI should organize the app purpose, feature list, input/output, and data shapes as a document. You can move the App purpose, User and usage situation, and Core features parts into the front of docs/01-plan.md.

11-2. Prompt to make the draft smaller

If the AI draft is too broad, ask again like this.

Good. But the first version has too many features.
Please keep only the features that are necessary for the first version.

Use these rules:
- Make the first version small enough to draft in one day.
- Move login, alerts, and statistics graphs to later features.
- Make input, output, and logic shorter and clearer.
- Add one sentence about privacy or sensitive data precautions.
- Do not write code examples yet.

The expected result is a smaller planning document. From that result, copy Build first, Think later, and Exception cases into the back of docs/01-plan.md. Designing in a vibe-coding way does not mean trusting AI's answer as-is. It means reducing, checking, and rewriting the answer for your real purpose.

12. Tips for writing the planning document

First, do not try to make it perfect at the beginning. Write a rough feature list first, then fill in details gradually.

Second, make each feature do one thing. "Show the student list, receive submission status, and show the result" is too large. Split it into "show student list," "receive submission status," and "show status."

Third, clearly write input and output. If you write what each feature receives and produces, AI can understand the data flow more easily later.

Fourth, write data shapes even roughly. Name is text, number is a number, and submitted is yes/no. That much is enough for the beginning.

Fifth, separate what to build first from what to think about later. Trying to build everything at once makes the project heavy. If you separate the first version and later features, AI can work step by step.

Sixth, write simple exception cases. For example, do not save an empty name, or ask again if submission status is not selected.

13. Development environment rule to add to agent.md before the first code

Now docs/01-plan.md has the outline of the app. In the next post, we will use it to create the first Python file.

So at this point, add one rule to agent.md: Python work must happen inside the uv virtual environment. In this series, we use uv as the default Python execution tool instead of starting with python -m venv or direct pip commands. You can understand uv run ... as the command that runs something inside the project environment without manually turning the environment on and off.

Add this to agent.md.

## Development Environment

- This project manages the Python virtual environment with uv (astral-sh/uv).
- All Python code and package installation must run inside the virtual environment (.venv).
- Do not use the system-wide Python directly.

### Check uv installation
- First check whether uv is installed with `uv --version`.
- If it is not installed, install it from https://github.com/astral-sh/uv.

### Create the virtual environment
- Run `uv venv` from the project root (myproject01/).
- Success means the `.venv` folder is created.

### Install packages
- Install external packages such as PySide6 with `uv add PySide6`.
- Process requirements.txt with `uv add -r requirements.txt`.

### Run code
- Run Python scripts with `uv run python script.py`.
- This automatically runs the script inside the virtual environment.

This clause is not about writing code immediately. It is a work rule AI must follow from the next post onward. With this in place, AI should avoid installing packages into the system-wide Python and should work from the project's .venv instead.

14. If you use another AI coding tool

This series explains the workflow using opencode. If you use another AI coding tool, only the command changes.

Tool	Command	Note
opencode	opencode	default for this series
Claude Code	claude	requires an Anthropic account
Gemini CLI	gemini	requires a Google account
Antigravity	open the desktop app	GUI instead of terminal
Codex CLI	codex	requires an OpenAI account

The flow is the same.

1. Run the tool in the project folder.
2. Ask it to read agent.md and the documents inside docs/.
3. Make a natural-language request.
4. Check the result and ask again.

15. What we will do next

You are done for today if...

After this post, docs/01-plan.md should roughly contain the app name, purpose, user, core features, input, output, logic, data shapes, and Needs clarification: ... items. And agent.md should keep the work rules saying that this was the planning step and that the next Python work must follow the uv rule. The sentences do not have to be perfect. The important thing is that "what to build" is no longer blank.

In the next post, we will use the planning document and the uv rule in agent.md to build the first feature as a very small Python CLI version.

Since part 4 decided "what to build" and "Python work happens inside uv," part 5 will create the first running program. We will not jump to a windowed app yet. First, we will check the input-processing-output flow in the terminal.

The next post will:

• ask AI to read docs/01-plan.md;
• create the first Python file named app.py;
• enter student name and submission status;
• print submitted and missing lists in the terminal.

At that point, the app will no longer be only an idea inside a document. It will become the first program you can actually run.