CompCode Academy

Lesson 6 of 6 · Free to read

Mini-project: spec first, then generate

Mini-project: spec first, then generate

Audience: Final-year students and engineers in their first three years
Prerequisites: Lessons 1–5
Time: about 60 minutes
What you will keep: a small command-line tool with tests, built from a spec you wrote, ready for your portfolio
This lesson does not cover: publishing a package.

Why this matters

In the lab you fixed someone else's code. In real work you often start from nothing, and that is where AI tools wander most. The fix is simple and old-fashioned: write down exactly what you want before any code exists. A tight spec turns a long back-and-forth into one or two prompts, and it gives you something to check the result against.

Step 1 · Pick a small tool (5 minutes)

Choose one, or a similar idea of your own that fits in about 100 lines:

  • wordcount: count lines, words and characters in a text file, like wc.
  • toc: print a table of contents from the headings in a Markdown file.
  • dupes: list files in a folder that have identical contents.

Step 2 · Write the spec (20 minutes)

Create SPEC.md. Write at least 12 bullets, each one something a test could check. Cover:

  • Inputs: arguments, flags, file types.
  • Outputs: exact format, ordering.
  • Edge cases: empty file, missing file, very long lines, non-English text.
  • Errors: message and exit code for each failure.

Weak bullet: "Handles errors properly." Testable bullet: "If the file does not exist, print error: file not found: <path> to stderr and exit with code 2."

When you are done, use Critique from lesson 2: "Which three bullets in this spec are ambiguous or untestable? Do not write code." Fix what it finds, if you agree.

Step 3 · Generate from the spec (15 minutes)

In an empty folder, give your AI tool the spec with one Specify prompt:

"Implement the tool described in SPEC.md in Python, using only the standard library. Write one pytest test per bullet in tests/, named after the bullet. Show me the file list first and wait for my OK before writing code."

Asking for the file list first lets you stop a wrong design before it costs you anything.

Step 4 · Make it pass, honestly (15 minutes)

Run the tests yourself. For each failure, decide which is wrong: the code, the test, or the spec. Fix the spec when the spec was unclear, and log every decision in PROMPTS.md.

Stop when:

  • every spec bullet has a test, and all tests pass;
  • you needed three or fewer fix-up prompts after the first generation. If you needed more, note in your log which spec bullet was missing or vague;
  • you can run the tool on a real file and the output matches the spec.

Step 5 · Make it portfolio-ready (5 minutes)

Write a README.md with three short sections: what the tool does, how to run it, and how AI was used, including one thing you rejected and why. Commit SPEC.md, PROMPTS.md, the code and the tests.

That last README section is what makes this a portfolio piece instead of a toy. Anyone can generate a word counter. Showing that you specified it, checked it and pushed back where the AI was wrong is the skill employers are hiring for.

Key points

  • A testable spec makes generation faster and checking possible.
  • Ask for the plan or file list before the code.
  • When a test fails, decide whether the code, the test or the spec is wrong.

New free lessons and course updates. Unsubscribe from any email.