/
Simple Spec Driven Development

Simple Spec Driven Development

Learn how basic spec prompts help humans and AI’s collaborate to write better code, faster

 

Prerequisites

A coding agent that can run prompts.
A feature you are going to implement. The feature should be something that would normally take 1-3 days to complete by hand. You should have some available context like a Jira issue and/or Figma designs.

Overview

This training will teach you how to use spec-driven development to write code. We will:

  1. Create a hand-written spec file

  2. Run the spec prompt on it

  3. Review the spec, answer its questions, make suggestions

  4. Once we are satisfied with the result, we will start a new context and run the spec-check prompt

  5. Once satisfied with the spec-check and the implementation, we will instruct the AI to start implementing the spec in a phased approach

  6. At each phase, we will check things out and make sure it looks right

 

Create a spec file

  1. Create a folder for your specs. Example: /spec.

  2. Create a spec file with the number of your ticket and a brief description. Example: /spec/221-my-basic-feature.md

  3. Handwrite a spec file with as much detail as you can about what the feature is and how you might accomplish it

    For https://bitovi.atlassian.com/browse/FOO-221 I'm build the allow editing button of https://www.figma.com/design/yRyWXdNtJ8KwS1GVqRBL1O/branch/KxgPt0v1fI8ZxJYxR9Wnfe/User-onboarding-designs?node-id=246-10957&t=VNwbTaCK9jG0XAhV-0 It allows editing, by setting the `process_status` to "editing" (LOOKUP) We will need to make an `allowEditing` in packages/fe/src/api/fetchApplicationRecords.ts that will do a PATCH to application records with `process_status=updating` We will need the application mock handler ( packages/fe/src/api/mocks/handlers/applications.ts ) to set `process_status` to `updating`. When the process_status is updating the application details page will need to change to the read-only version.

The hand written spec file should detail the technical changes that need to be made. How would you implement this? What things need to be considered?

Tips:

  • Make sure you have Atlassian and/or Figma’s MCP servers configured and started.

  • Add the paths to files or folders where things will need to change.

  • Don’t worry too much about formatting. The AI will clean it up. Chain-of-thought is ok, but make sure the thoughts are clear.

  • If you have other prompts the implementation should be aware of (example: generators), add the paths to those prompts.

  • Copilot instructions can help. It's good to have it in place.

 

Run the spec prompt

  1. Add https://github.com/bitovi/ai-enablement-prompts/blob/main/writing-code/specs/spec.prompt.md to .github/prompts/spec.prompt.md

  2. Create a new context.

  3. Make sure you have your spec file open and focused in VSCode

  4. Type /spec in your agent and hit enter

image-20251204-224245.png

This will generate your spec.

 

Review and Improve the Spec

Depending on the complexity, the generated spec might be between 100s to over 1000 lines long. There might be a lot to review and big changes to make.

To review it and improve it, we suggest the following pattern:

  1. Do a quick review / spot check. Scan the spec, does it look right? Did it get concepts right?

    1. If you see anything large, tell the agent what it got wrong and have it update the spec accordingly.

  2. Scroll to the bottom and look at the questions. Answer all of the questions inline. After completing the questions, tell the prompt:

    I have answered your questions. Please review my questions and incorporate into the spec. If you have additional questions, please include them in a `## Questions` section at the bottom of the page.

  3. Once questions have been answered, now do a thorough, top-to-bottom review. When the spec gets things wrong, prompt the AI to make improvements.

  4. Once the prompt feels right, go to the next step.

Agent checks the spec

Before implementing, it’s useful to have the AI do one additional review.

  1. Add https://github.com/bitovi/ai-enablement-prompts/blob/main/writing-code/specs/spec-check.prompt.md to /.github/prompts/spec-check.md

  2. Start a new context

  3. Make sure to open your spec.

  4. Run /spec-check.md

 

If the agent reports or finds serious problems with the spec, address them as we did in the “Review and Improve the Spec” section. If large changes are needed, you might want to run /spec-check multiple times.

Once you and the AI are happy with the spec, it’s time to implement it.

Implement the spec

Tell the AI to start implementing the spec. Here’s a prompt that will make it run with todos:

Please implement this spec. Create a todo list for each phase and/or step of the implementation plan. After each step, pause and let me check the results before continuing. At the end please verify everything works by re-running the build, tests and linting.