✏️ Fill this in first — two minutes. It's how a teammate, a mentor, or a judge sees what this project is and whether the document is current.
| Project | [ your project's name ] |
| Team / program | [ FRC 7421 · FTC 23619 · FLL — keep the one that's yours ] |
| Students | [ first names only — no last names, no contact info ] |
| Season | [ e.g. 2026–2027 ] |
| Status | 🟡 Planning · 🔨 Building · ✅ Working · 📦 Season complete — (delete the ones that don't apply) |
| Last updated | [ YYYY-MM-DD ] — (see what changed ↓) |
What this is: A fill-in-the-blanks document that helps you think before you build. You answer the questions, an AI (Claude, ChatGPT, Copilot…) helps fill the gaps, and the finished document becomes the spec it builds from.
The golden rule: An AI can only build what you can clearly describe. A vague plan produces a vague app; a precise plan produces a working one.
This is a LIVING document. It must describe the app as it is right now, not just what you planned at the start. Every time the app changes, this document changes to match. It is the single source of truth: if it's not written here, it's not part of the app.
- Work in your own copy, not the template. If you haven't made one yet,
GIT-BASICS.mdwalks you through it. - Work top to bottom. Each section builds on the last, so go in order — even if you're only doing the six starter sections below.
- Use AI as a thinking partner, not an autopilot. Stuck? Paste the section into your AI and ask: "Help me think through this. Ask me questions until you understand what I want." You draft, the AI attacks it — never the other way round.
THINKING.mdexplains why, and how to find answers that aren't in your head yet. - Mark what you finish. Replace every
[ ... ]placeholder. Leave🟡 TODOwhere you're still deciding. - When the doc is done, build. Jump to the last section, "Hand it to the AI," and use the ready-made prompt.
- Keep it in sync. The AI updates this document for you — check that it actually did.
Seventeen sections is a lot. You don't need them all to start. Fill in these six and you have a real plan you can hand to an AI:
§1 One-line summary · §2 The problem · §3 Goals & non-goals · §5 User stories · §6 The rules · §14 Build plan
What it is, what problem it solves, what it won't be, what it does, how it thinks, and the order you'll build it. The rest can wait — your AI can help you fill those in later. FLL teams and first-time builders: this is your path.
Two levels of detail:
- 🟢 CORE — every project fills these in eventually. If you do all the green sections, you have a thorough plan.
- 🔵 ADVANCED — for bigger projects. (FTC/FRC scouting systems, team websites with logins, anything other people rely on.)
⚠️ One safety rule, read it first: Never put secrets or personal information in this document, an AI chat, or your repo — no passwords, no API keys, no teammates' full names or contact info. Once it's pushed or pasted, treat it as public forever. (The full rules, and what to do if it happens anyway:README.md.)
Why this matters: If you can't say it in one sentence, you don't understand it yet.
Prompt to answer: Fill in this exact sentence —
"We are building a [type of thing] that helps [who] to [do what]."
Example (scouting app):
"We are building a mobile-friendly web app that helps our scouts to record what other teams' robots do during matches, so we can pick good alliance partners."
Your answer:
We are building a [ ... ] that helps [ ... ] to [ ... ].
Why this matters: Software exists to solve a problem. Name the problem first.
Questions to answer:
- What problem or annoyance are we trying to fix right now? (What do people do today, and why is it bad/slow/error-prone?)
- What does success look like? How will we know the app actually helped?
Example (scouting app):
- Problem: Scouts write notes on paper. The notes get lost, the handwriting is messy, and on alliance-selection day we can't quickly compare teams.
- Success: By the end of a competition, we can open the app and instantly see the top 8 robots by average scoring, with no paper involved.
Your answer:
- Problem: [ ... ]
- Success looks like: [ ... ]
Why this matters: This is the most important section. Most student projects fail because they try to do everything. Decide what you are NOT building.
In scope (we WILL build this):
- [ ... ]
- [ ... ]
- [ ... ]
Out of scope (we will NOT build this — at least not now):
- [ ... ]
- [ ... ]
Example (scouting app):
- ✅ In scope: record match data, view team averages, works offline at the venue.
- ❌ Out of scope: user accounts/logins, live syncing between phones, fancy graphs, predicting match winners. (Maybe version 2.)
💡 Tip: When in doubt, put it in "out of scope." You can always add it later. A small app that works beats a big app that doesn't.
🗓️ How long does this app need to live?
- One season — this is the normal answer. Our team rebuilds most apps from scratch each year so new students get to plan their own (see
TEAM.md). - Long-term — only if a mentor has told you this is one of the team's few lasting apps.
This changes what "good" means. A one-season app should be built as small and as simply as it can be — you are not building a foundation for anyone, and time spent making it flexible for a future it won't have is time not spent making it actually work at competition.
Why this matters: You're not building for "everyone." Build for specific people.
| Who they are | What they need from the app | Tech skill level |
|---|---|---|
| [e.g. Scouts in the stands] | [Fast data entry on a phone] | [Low — must be obvious] |
| [ ... ] | [ ... ] | [ ... ] |
| [ ... ] | [ ... ] | [ ... ] |
Why this matters: This is your feature list, written from the user's point of view. The AI will turn each one into a feature.
Format: "As a [user], I want to [do something], so that [benefit]."
Example (scouting app):
- As a scout, I want to tap buttons to count game pieces scored, so that I don't have to type during a fast match.
- As a strategy lead, I want to see each team's average score sorted high-to-low, so that I can build a pick list.
- As a scout, I want the app to save my data even with no internet, so that I don't lose it in a crowded venue.
Your user stories (write 5–15; the most important ones first):
- As a [ ... ], I want to [ ... ], so that [ ... ].
- As a [ ... ], I want to [ ... ], so that [ ... ].
- As a [ ... ], I want to [ ... ], so that [ ... ].
- [ ... ]
- [ ... ]
💡 Sort them. Put a ⭐ next to the 3 you can't live without — build those first.
Why this matters: Rules are the decisions your app makes for you. AI gets these wrong unless you spell them out.
Write rules as "When X happens, the app should do Y." Be picky. Include the weird cases.
Example (scouting app):
- When a scout submits a match, the app should check that a team number and match number were entered, otherwise show an error.
- When two scouts enter data for the same team in the same match, the app should keep both and average them (don't overwrite).
- When a robot's score is left blank, the app should treat it as 0, not as "skip."
- A team's "average" should only count matches where they actually played (ignore no-shows).
Your rules:
- When [ ... ], the app should [ ... ].
- When [ ... ], the app should [ ... ].
- When [ ... ], the app should [ ... ].
- [ ... ]
Edge cases / "what if" list (the situations that break apps):
- What if the user enters [bad/empty/huge] input? → [ ... ]
- What if two people do the same thing at once? → [ ... ]
- What if there's no internet? → [ ... ]
- What if [ ... ]? → [ ... ]
💡 Ask your AI: "Here are my rules. What edge cases am I forgetting? Just list the holes — don't fix them." AI is great at spotting holes in logic, once you've written the logic.
🔍 Struggling to fill this in? That usually means the answers aren't in your head yet — they're out with the people who'll use the app.
THINKING.mdhas the "what if it's empty / huge / doubled / interrupted" sweep that produces most of this list for you.
Why this matters: Almost every app stores information. Listing it now saves huge headaches later.
List the "things" your app keeps track of and what details each one has.
Example (scouting app):
- Match Entry: team number, match number, scout name, points scored (auto), points scored (teleop), did the robot break down? (yes/no), notes
- Team (calculated from entries): team number, average score, number of matches scouted
Your data:
- [Thing 1, e.g. "User"]: [field, field, field ...]
- [Thing 2]: [field, field, field ...]
- [Thing 3]: [field, field, field ...]
Where is the data stored? (pick one to start)
- Just on the device (simplest — good for offline tools)
- A Google Sheet / spreadsheet (easy for teams already using one)
- A shared online database 🔵 (needed only if several people share data live — which one is a mentor decision, and a mentor sets it up; see
TEAM.md) - Something else? Go ahead and explore it — but ask a mentor before you commit to it.
- 🟡 TODO — ask AI to recommend based on my needs
💡 Think you need a shared database? Build on the device first anyway. Keep all saving and loading in one small file (
saveMatch(),getMatches()). When phones really do need to share data, only that file changes. Plenty of apps find they never needed the database at all.Paste this to your AI: "Put all data saving and loading in one separate file, and make those functions
asyncfrom the very start — even though we're only saving on the device for now — so we can swap in a shared database later without rewriting the rest of the app." (Device storage is instant; anything over a network takes a moment. Writing it the "waiting" way from day one costs nothing, saves a painful rewrite, and works the same whichever database we end up approved for.)
Why this matters: Listing the screens/pages is like sketching the app before building it.
List each screen and what's on it. Even a rough description helps the AI a lot.
Example (scouting app):
- Home screen — buttons: "New Match Entry", "View Team Rankings".
- Entry screen — fields for team #, match #, +/- counters for scoring, a "save" button.
- Rankings screen — a table of teams sorted by average score.
Your screens:
- [ ... ] — [what's on it]
- [ ... ] — [what's on it]
- [ ... ] — [what's on it]
How do users move between screens? (the flow)
[e.g. Home → tap "New Entry" → Entry screen → tap Save → back to Home]
🎨 Draw your screens on paper, photograph them, hand that to the AI — it reads sketches fine. Already designed them somewhere else (Claude Design, Figma, a drawing app)? Export an image or PDF, attach it to your chat, and reference it here.
Some design tools can hand off the real design — components, colors, layout — to a coding AI instead of just a picture, which gets the code much closer to what you drew. Check whether yours does.
⚠️ Exporting is a one-person job. If your tool has usage limits or needs a paid plan, have whoever made the design export once and share the file. Ask a mentor before signing up for anything paid.
Why this matters: Pick tools that match your team's skills and that AI knows well.
Not sure? Use these student-friendly defaults and let the AI guide you:
| You want to build... | Good beginner choice | Notes |
|---|---|---|
| A website / web app (works on any phone/laptop) | HTML + CSS + JavaScript | Best default. No build step — the file you edit is the file that runs, so it opens straight from a folder and can go anywhere later. Right choice for most scouting apps. |
| The same, but much bigger 🔵 | React | More power, but it needs a build step, which limits where the app can go. Ask a mentor before choosing it. |
| A phone app you install | A web app first, then wrap it | Real native apps are harder; start with a web app. |
| A robot dashboard / data tool | Python | Pairs well with robot code. Runs on a laptop — simple web hosts can't run Python, so plan on it staying a laptop tool. |
| Quick data crunching | Python or a Google Sheet + scripts |
Our choice:
- Language / framework: [ ... or "🟡 TODO — ask AI"]
- Where it runs: [ phone browser / laptop / installed app / ... ]
- Does it need a build step? [ no — opens straight from a folder / yes — talk to a mentor ]
- Tools we already know: [ ... ]
Hosting — leave this alone until a mentor approves one. Running on your laptop is the normal state; see DEPLOY.md.
- Runs locally for now: ✅ (normal — most projects stay here)
- Host proposed: [ 🟡 not yet ]
- Approved by a mentor: [ ☐ not yet · ✅ on YYYY-MM-DD ]
- Live link: [ ... once it exists ]
💡 Guess first, then ask. Pick something from the table above, then: "I'm thinking [my choice] for [my app], because [my reason]. Our team knows [these tools]. What am I not considering? Is there a simpler option, and what would my choice cost us later?" (Our requirements either way: runs from a folder on a laptop, no build step, not tied to any web host.)
Why this matters: For bigger projects, sketch how the pieces fit together.
Describe (or draw) the main parts and how they talk to each other.
Example (scouting app with online sync):
Phones (web app) → send data → Online database → Rankings page reads from the same database.
Your architecture:
[ ... or paste a simple diagram / "Phone → does X → sends to Y → shows Z" ]
Why this matters: If your app talks to other services, list them.
Examples for FIRST teams: The Blue Alliance API (team & match data), Statbotics (predictions), Google Sheets, FIRST's event API.
Connections we need:
- [Service name] — used for [ ... ] — link to its docs: [ ... ]
- [ ... ]
⚠️ Does one of these need an API key? That's a secret — it never goes in your code, your repo, or an AI chat. Ask a mentor to set it up. (SeeREADME.md.)
Why this matters: "It looks done" is not the same as "it works." Decide the tests up front.
The app is finished when it can pass these checks:
- [e.g. A scout can record a full match in under 30 seconds.]
- [e.g. Rankings show the correct average for a team with 3 entries.]
- [e.g. Data is still there after closing and reopening the app.]
- [ ... ]
- [ ... ]
Things to try to break it (test the edge cases from Section 6):
- [e.g. Submit an empty form — does it warn me?]
- [e.g. Turn off wifi — does it still save?]
💡 Write your checklist first, then ask your AI: "Here are my success criteria and tests. What did I miss? What would you try to break? Don't rewrite my list — tell me what's wrong with it."
⚠️ The order matters here more than anywhere else. If the AI writes this checklist, it's testing what it assumed you wanted — and you'd never find out where its assumptions differ from yours. Finding that gap is the entire job of this section.
Why this matters: How fast, safe, and usable does it need to be?
- Speed: [e.g. A screen should load in under 2 seconds on a phone.]
- Works on: [which phones / browsers / screen sizes?]
- Privacy & safety: [Does it store personal info? Who can see the data?]
- Accessibility: [Big tap targets? Readable in bright sunlight at a venue? Works one-handed?]
- If it crashes: [What should happen? Lose data, or recover it?]
Why this matters: Build in small, working pieces. A working tiny app beats a half-finished big one.
| Step | What we'll have working | Works? | I can explain it? |
|---|---|---|---|
| 1 | [The smallest version that does ONE useful thing — your ⭐ feature] | ⬜ | ⬜ |
| 2 | [Add the next most important feature] | ⬜ | ⬜ |
| 3 | [ ... ] | ⬜ | ⬜ |
| 4 | [ ... ] | ⬜ | ⬜ |
| 5 | [Polish: make it look nice, test edge cases] | ⬜ | ⬜ |
✋ Two boxes, not one — and the second one is the point. A step isn't finished because it runs. It's finished when you could sit down with a teammate, or a judge, and walk them through what that code does and why it's written that way. Can't yet? Ask the AI to explain it differently until you can, then tick the box. Leaving a trail of code you can't explain is how a project stops being yours.
💡 The "minimum first version" is whatever lets a real person do the #1 task. Build that, test it with a teammate, then grow.
🌐 Think you'll need hosting? Start that conversation with a mentor early — around Step 2, not the week before competition. Approval and setup take real time, and discovering late that your app can't be hosted the way you assumed makes for a bad week. Keep building meanwhile; hosting should never block you. See
DEPLOY.md.
Why this matters: Writing down what you don't know yet keeps it from becoming a surprise.
- ❓ Things we haven't decided: [ ... ]
⚠️ What might go wrong: [e.g. "No wifi at the venue" / "Only one person knows the code" / "We run out of time"]- 🛟 Backup plan: [ ... ]
Define any words a new teammate (or the AI) might not know.
- [Term] — [plain-language meaning]
- Auto / Teleop — [the autonomous and driver-controlled periods of a FIRST match]
- Pick list / alliance selection — [ ... ]
- [ ... ]
Why this matters: Every time the app changes, add a line here — newest on top. It lets a teammate, a mentor, a judge, or next year's team see how the app grew and why.
Who writes each entry: whoever made the change. Building with the AI? It writes the entry, you check it. Changed something yourself — a scope call, a dropped feature? You write it.
| Date | What changed | Why | By |
|---|---|---|---|
| [YYYY-MM-DD] | [e.g. Added "robot broke down?" field to Match Entry] | [Scouts needed to flag unreliable robots] | [name / AI] |
| [YYYY-MM-DD] | [e.g. Dropped user logins from scope] | [Too complex for v1; not needed at venue] | [ ... ] |
| [YYYY-MM-DD] | Document created | First version of the plan | [ ... ] |
💡 A change isn't "done" until both the app and this document reflect it. If you only change one, they drift apart and the document stops being trustworthy.
🏁 One last entry, after your final competition. A mentor will ask your team what you learned — which requirements turned out wrong, what you built and never used, what you'd do differently. Write the answers here as the last line, and set the Status at the top to 📦 Season complete. Next year's students won't inherit your code; that entry is what they inherit instead.
A filled-in document is not the same as a plan you understand. Before you build anything, answer these out loud, without reading, to a teammate or a mentor. They're the questions a judge asks anyway.
- Say what you're building in one sentence — without looking at Section 1.
- Name one thing you decided NOT to build, and why. (Nothing comes to mind? Then your scope isn't decided yet — go back to Section 3.)
- Who is the one main user? What do they do today instead, and what's bad about it?
- Pick any rule from Section 6 and explain why it's that way — not what it says, why you chose it.
- What happens when two people do the same thing at once? "We'll deal with that later" means you have a missing requirement, not a small detail.
- What's the first thing you'd cut if you lost a week before competition?
- Point at the part you're least sure about. Everyone has one — not knowing which is the warning sign.
Stuck on any of them? Good — the document just found a hole before you built on top of it. That's the cheapest a hole will ever be. Go fix that section; THINKING.md has ways to dig out answers that aren't in your head yet.
🧑🏫 The best version of this takes ten minutes: hand
DESIGN.mdto a mentor or a teammate who's never read it and let them ask. If they can't tell you what the app does afterwards, the answer belongs in the document — not in your head.
Any time you want to add a feature, drop one, or change a rule mid-build, stop and answer three questions before you touch anything:
- What did I learn that I didn't know before? (If the honest answer is "nothing — it just sounded good," don't do it.)
- Does this still fit Section 3, or is the app quietly growing?
- What comes out to make room? If nothing does, where is the extra time coming from?
Most mid-season ideas should fail this, and that's the point. Your app has one season. Every feature you add is time taken from making the important part actually work at competition — and "we ran out of time" is the single most common way a student project dies.
Passed all three? Then it's a real change: update the section it affects, add a line to the Change Log saying why, and carry on.
Once the green sections are filled in and you can answer the questions above, you're ready to build. Copy the prompt below, paste it into your AI tool, then paste your filled-in document right after it.
💡 Does your AI already have these documents? Some setups (a Claude Project, or a coding tool working inside your repo) can already read
DESIGN.mdandTEAM.md. Then skip the paste and say: "I'm building [project name]. You already have myDESIGN.md— read it, then follow the steps below." Not sure? Paste the whole thing — an extra copy never hurts; a missing one does.
Prompt to start building:
"You are helping a student robotics team build software. Below is our completed software design document. Please do the following, one step at a time:
- First, read the whole thing and ask me about anything that is unclear, contradictory, or missing — especially in the Rules and Edge Cases sections. Don't write code yet.
- Never invent a requirement. If something isn't written in this document, you don't know it — ask me instead of assuming or picking something sensible. If I answer vaguely ("fast", "simple", "handle errors"), keep asking until it's specific enough to test. When there's a real choice to make, show me the options and what each one costs, and let me decide — even when one is obviously better. I'm here to learn to make these calls.
- Then look at Section 9. If we already chose a language or framework, that's my decision — tell me if you'd have chosen differently and why, then go with mine. If it says TODO, propose the simplest option that matches our skills and wait for me to agree. Either way it must run straight from a folder on a laptop with no build step, and must not assume any particular web host or online database — hosting is a separate decision our mentors make later, and our app has to work without one.
- Keep it portable the whole way through: use relative paths (
./file.css, never/file.css), never hardcode a website address, and keep all data saving and loading in one separate file withasyncfunctions. I must always be able to open the app from a plain folder on my laptop and have it work.- Then build 'Step 1' from our Build Plan only — the smallest working version. Explain the code simply, as if teaching a beginner.
- After each step works, ask me to explain back what the code does before we move on. If I can't, explain it a different way and ask again — I have to be able to defend this project to a judge. Then we move to the next step together.
- Keep our design document up to date. Treat it as the single source of truth. Any time we add, change, or remove a feature, rule, screen, data field, or tech choice, update the matching section AND add a dated line to the Change Log (Section 17). At the end of every session, show me the updated document and point out exactly what you changed. Here is our document:"
[paste your filled-in document here]
While building, keep asking the AI to teach, not just type:
- "Explain what this code does, line by line, like I'm new to this."
- "Why did you choose to do it this way?"
- "Here's an error I got: [paste it]. What does it mean and how do I fix it?"
- "How do I test that Step 2 actually works?"
- "Does anything in this code assume where it's hosted? Check for hardcoded addresses and paths starting with
/." - "We just changed [X]. Update the design document and the Change Log to match, and show me what you changed."
🏆 Remember: The goal isn't just a finished app — it's that you can explain how it works. At a FIRST event, judges will ask. The student who planned it with this document will have the answer.
Template made for FRC / FTC / FLL student software projects. Copy it, improve it, and share it with next year's team.