Novice's Thoughts

Specification Grounding

[Source]

[Takeaways]

Overview

The Unstract blog post explained well about the specification grounding technique to build things with LLMs.

idea → specifications → prompt plan → code

Without this technique, if we want to build something with say claude code, I will directly fire up the terminal and ask it to build straight away what I want.

This worked for small projects that require minimal effort but when it came to complex projects, I had to verify and check things manually and ask the agent to update things accordingly.

This specification grounding seems to be useful at it. If I know what I want to do clearly before starting out the coding part, I can just wait for the agent to build it for me, rather than checking and thinking how things are coming up.

The Four-Step Process

1. IDEA

What I want to build? How I am going to build? An idea that I want to build, expressed by me.

If I were to give this work to someone, how will I express? That is documented here.

2. SPEC

Once I tell my idea to someone who is going to build this application, they will surely ask me a lot of questions such as the maximum request timeout, what database I want to use, etc.

This is the specification part. We can use an LLM to do this for us. It will do the role of the person who will ask us these questions.

This process will help us identify and fix our blind spots of what we are going to build.

Once we have confidence, we can ask the same LLM to convert the specifications as a document. In this case a markdown file.

3. PROMPT PLAN

Now that we have our specifications, can we give it to the agent coding tool directly to build the specs? NO.

If we split the work in chunks and give it to the agent coding tool, it will work better.

So we will be using LLM again, to build a PROMPT PLAN. Another document, that gets our specification file and generates a STEP by STEP implementation PLAN.

Ideally, by following these steps and at the end we should get what we have asked in the idea part using the specifications we have mentioned.

Once we have a PROMPT PLAN...We get to build what we have wished.

4. CODE

Now we can fire up claude code, windsurf or the tool of our choice.

They all have something called rules, specific to the tools. Like for example, claude code reads a file called CLAUDE.md, here we can store the information about the files we have created in the above steps.

So that when the tool starts it gets to know what we are intending to do. In this file we can also store our choices for linting, formatting, git related instructions, etc.

In this last step, once we have the rules setup, we can ask the tool to build the idea and bring it to life.

Yes, we won't get the perfect result that we expect. But instead of routinely fighting with the LLM to get the best result, we will get to do better this way.

By following this practice, we will get clarity on what we want and build.

Real-World Examples

Work Project

At work, we tried to implement a JIRA ticket requirement to an existing project using this method.

To our surprise, it worked really well compared to our traditional prompt by prompt approach.

Of course, it took some time to set things up. But it was worth it. Let's see how it goes as this is just a starting point.

Personal Project: Football Tracker

I wanted to try this method more, so I built a hobby project. I don't have much experience in building with LLMs properly—I usually just ask it to build something directly.

Sometimes I do a plan and give it to the model, or brainstorm with it before implementing. Even with that, I had to iterate multiple times to get my desired result.

Previous approach: The Football Times - built with claude code using a normal prompt by prompt flow with a little brainstorming.

New approach: Football Tracker - built using the idea → spec → prompt_plan method.

Compared to my first approach, I didn't spend much time checking upon API errors and all. My focus was inside the prompting folder alone. I set it up correctly and boom. I got my output as expected.

My Workflow

  1. Initial idea draft - Polished with GPT 5.1: Chat link

  2. Created the spec with GPT 5.1: Chat link

  3. Generated the prompt plan with Claude: Chat link

  4. Built with claude code - Created a CLAUDE.md to set up ground rules

Result

Reality Check

But nothing is perfect. We need to constantly experiment and find what works for us. What works for me might not work for you. What works for this project might not work for other projects.

I am still new to all of these things in this rapidly evolving era. Lots to learn! ;)