First experiments with Claude Code - Writing specs

When vibe coding, detailed specifications are highly advisable. The more freedom given to the model, the more the result can deviate from your needs.

Using a model to help write detailed specifications is an easy way to accomplish this.

This allows you to quickly generate good, detailed specs that you can manually refine. I often use various models with Open Web UI for this.

Now that Claude Code offers agents, and creating an agent is simple, I immediately tried creating agents to automate this process. The results are promising, but not perfect. Claude Code seems focused on writing code and tends to over-deliver. Starting with a simple idea and asking Claude Code to create an agent for brainstorming detailed specifications yields good results, but how good are they?

You must check everything output by a large language model, as it can hallucinate or deviate from your needs. If it generates numerous files with detailed specifications, reviewing them takes considerable time. I want to bring my ideas to life through vibe coding without overcomplicating things. For example, asking for a simple command-line application for interacting with a large language model can result in an overly complex solution.

The Pareto rule often applies: 20% of the code might be what you need, while 80% is generated under the assumption that you need it. To avoid this, start with a simple model and instruct it to generate only a bullet-point list of macro features. The first round might generate too many points, so edit the model’s response, removing unwanted points and adding missing ones. Refine the answer using Open Web UI’s editing capabilities. This quickly gives you a list of essential points.

Then, take each point and ask a more sophisticated model to elaborate and create a list of user story tasks. Continue refining until you have a complete list of requirements.

The key to good results is reading and refining everything the large language model generates to fit your needs.

Proceed iteratively, asking the model not to generate too much at once, keeping everything in scope. This results in a specification list containing only the desired elements for vibe coding.

I’m now replicating this with Claude Agents, starting with an agent that only writes a bullet-point list of specifications. However, Claude Code seems to have a context, prompt, or instruction that leads it to do more than asked.

Figure 1: Claude helping me in drawing specifications

As you can see, I created the agent (1), asked it to brainstorm (2), it activated (3), and started generating content (4). I guided it towards simple file storage (5), and the result seemed good (6). However, it wasn’t as good as expected because it generated too much and needed refinement.

The agent also generated a text-based graphic to illustrate the solution’s structure.

The agent generated by Claude Code (based on a brief description) is very complex. I tried editing it to include only the necessary instructions, hoping for a simpler solution.

Figure 2: My refined brainstormer that contains less instruction and is really specific

The focus of this new agent is specific: I want only a couple of files, one of which is a specification file containing a brief list of specifications (one line per feature) the other is CLAUDE.md. I explicitly tell the agent to write the files after each interaction, so I can review them and refine the results.

When I asked the agent to brainstorm, it generated a list of features, which was good. However, it also created a project structure file with too many details, including API descriptions and other unnecessary information.

However, the agent still doesn’t always follow instructions. It often asks if it should start implementation after the first proposal, which is not desired. Sometimes the result is too detailed, including lengthy instructions and excessive details for each feature.

Most disturbingly, it doesn’t write the files.

Figure 3: Claude agent seems to somewhat ignoring my instructions

It didn’t create the file, even after being instructed to do so. Then I explicitly tells him to create the file. However, the file name wasn’t the one specified in the instructions as you can see on the bottom line of Figure 3.

When corrected (“Your instructions specify that the file should be called specs.md”), it created two files: specs.md and project-structure.md (the latter was not mentioned in the instructions, but I had indicated that project structure was a desired result).

However, the project structure file contained 214 lines, which was too detailed.

Figure 4: Clearly this is too detailed, it contains API description.

It included API descriptions, which were unnecessary at this level I specified that I want only bullet points with features. If I looked at the content of the console, this is the answer of Claude, that is quite good.

Figure 4: Content of the console where Claude Code is running.

However, after I told it to save, it contained 130 lines. What was displayed in the console prompt during the interaction didn’t match what was written to the file and file content was again too detailed.

This was using the Haiku model, nevertheless the interaction with Claude Code was slow, like it is really thinking a lot behind the scene. This suggests that even with this simple assistant, Claude uses its internal mechanisms to be more proactive and generate more than necessary.

In comparison, I copied the same prompt used for the Claude Agent into OpenWebUI, using the Haiku model. I asked the same question and received an almost instantaneous answer.

Figure 4: Results of haiku used directly with API and OpenWebUi.

The result needs refinement, but it’s almost instantaneous and provides a simple bullet-point list of microscopic features and a cloud markdown file containing technical specifications. This shows that the model is capable of generating the desired results and it is Claude Code that its overcokplicating things.

This suggests that Claude Code, even with a specific agent prompt, uses internal structures to make the agent more intelligent, which isn’t always desirable.

This suggests me that Claude Code is really laser focused on writing code and manage complex situation, and it is not suitable for simple tasks like writing one line list of specifications.

Nevertheless, it’s a significant step forward for code generation. I’m still using direct API calls to create specifications and then using Claude Code for vibe coding.

Gian Maria