In my last article I wrote about using specs to drive agents developing software. The goal is to observe what happens and discuss the implications, good and bad.

For that reason, I chose a supposedly simple specification: the canonical TODO app. This app has a specification documented at todomvc, a project originally designed to compare various MVC JavaScript/TypeScript frameworks. Remarkably detailed for its purpose of evaluating an “MVC” framework for web applications, it outlines very specific requirements. This level of detail itself carries implications we’ll explore further. For this lab, I removed all “web” related elements from the specification, including its insistence on specifying CSS class names and their usage. The stripped-down Markdown version of the specification below.

# TODO app specification

This is a specification for a todo app to create an easy to use and correct todo application.

## Functionality

### Global
The input control should be above any todos and prominent for easier visual attention.

### No Todo State
When there are no todos, focus on [INPUT] control to enter one.

### Entering Todos state
1. The todo is a text with preceding and succeeding whitespace trimmed.
2. Pressing [ENTER] creates todo, appends it to a todo list and clears the input. 

### Marking Todo complete state
1. [CLICKING] the [CHECKBOX] next to a [TODO]
2. Completed TODOs should have a visually distinct style compared to an incomplete one

### Editing a Todo state
1. [DOUBLE CLICKING] an existing [TODO] should load the todo title in the [INPUT] for editing. Any edits subsequently following (1) of Entering todos will proceed using [ENTER] to update the relevant TODO

### Deleting a Todo
1. All Todo items in the list will have a [DELETE] option
2. Selecting that will [DELETE] the TODO item and update the list.

### Persistence
1. The applications provides a storage for todos app

It’s worth noting the deliberate use of certain words in the spec like “easy to use” and “correct”. However, unlike traditional coding this is a very naive and underspecified use of these terms. What even does “ease of use” mean? And what is “correct”? These concepts have significant implications for the agent’s interpretation based on its trained weights.

I intentionally omitted parts of the original spec regarding bulk todo editing and counters to show completed/open todos. This allows us to later add these features to the spec and observe how the agent evolves the code.

Now, for the actual implementation, I initiated a fresh agent session and provided it with my handwritten spec.md file along with the prompt.

Implement @spec.md as a TUI

Here, TUI narrowed down what the nature of the application is: Terminal User Interface, which in turn is a very specific type of application that can be run in a terminal.

Also, let’s pay attention to things that were not specified in the spec.md: no programming languages, tech stacks, frameworks, databases, is it a SaaS product, etc.

It did have, though, some specific words that triggered the implementing agent to pick some choices for all those.

Et voilà, it baked an TUI app, shown below along with an explanation of why it did it this way.

It mapped some parts of the specs directly to the choice of frameworks to use and defaulted the other parts based on the weights of its data. Python as the language of implementation, Textual a framework for building TUIs with mouse support, which is not common in a TUI framework. But it was chosen as the spec had the word SELECT and DOUBLE CLICK, implying the need for mouse support.

The implementation artefacts were quite simple.

├── pyproject.toml
├── README.md
├── spec.md
└── todo_tui
    ├── __init__.py
    ├── __main__.py
    ├── app.py
    ├── app.tcss
    ├── models.py
    └── widgets.py

2 directories, 9 files

Though it missed the tests that it claimed it wrote and ran in the repo, an oversight it claimed to fix after pointing it out.

The app completion summary written to the README.md had the following completed checklist, which I insisted be written in a specific format.

## Feature List

- Prominent input above the list — Status: completed; Notes: docked to the top of the screen with a heavy border so it stays visually distinct from the list below it.
- Focus input whenever no todos exist — Status: completed; Notes: applied on startup and again after the last todo is deleted.
- Trim whitespace on entry — Status: completed; Notes: leading and trailing whitespace is stripped before a todo is created or updated.
- Enter creates a todo, appends it, and clears the input — Status: completed; Notes: a blank submission after trimming is silently ignored.
- Click the checkbox to mark a todo complete — Status: completed; Notes: built on Textual's Checkbox widget and its Changed message.
- Completed todos are visually distinct — Status: completed; Notes: strikethrough text plus a muted color.
- Double-click a todo to load it into the input for editing — Status: completed; Notes: detected via the Click event's chain length reaching 2.
- Enter while editing updates the todo instead of appending a new one — Status: completed; Notes: tracked with an editing_id on the app, cleared after submit.
- Every todo has a delete option — Status: completed; Notes: a small button on each row removes just that row.
- Todos are persisted to storage — Status: completed; Notes: written as JSON to ~/.todo-tui/todos.json on every mutation, loaded on startup.

Lessons learnt

A simple spec is enough for a simple implementation. The less you specify, the more you get in terms of choice of implementation. At the cost of choices that aren’t in your control. Whether that matters is a matter of context and taste. I thought the UI looked ugly but functional. For the next lab, let us add a feature to the spec and evolve the code under consideration.

Agentic AI has collapsed a few layers in the traditional software development process. Particularly the claim is that you can develop a feature of a software just by writing the specification.

Already there are many frameworks written as skill bundles that direct agents how to do that. Read a spec and produce all the artefacts you could expect. A working prototype or complete software with tests and documentation.

But there is a difference between doing this with or without rigour. The looser the specifications the higher the chance of incomplete, buggy or totally irrelevant output. Otherwise SDD is still subject to the “GIGO” principle. “Garbage in Garbage out”.

But what makes a good spec over a bad one? I am going to take some well known popular applications and spec them out and let agents drive the implementations to see the results.

Next Part is here.

Last year, I wrote an article which is almost the “hello world” of customising an agent. Circa 2025, coding agents were limited in context. You needed to constantly tell them everything again in every session. Who am I? Why are we here? That sort of thing. Humour aside, you needed to feed them the same set of instructions, files that you wanted them to ground on. Also, if you were planning a long coding session, a way for them to recollect what they did. I will reproduce that article here verbatim. But note that I no longer use “Pensieve”, the tool I built for this extensively now, but still it is very informative on why it was very useful back then.

Agentic coding is a phenomenal experience. I’ve been working with AI coding agents for a year now, primarily using Claude Code after trying a variety of models. But there’s one well-known problem — they have a ‘context window’ - a limited memory area for what they’re holding in their ‘agentic minds’. Context is nearly everything because it guides them to approach the task from the proper perspective and captures the small details that wire projects together, keeping the process focused and relevant.

What constitutes context? It could be the code already written, high-level architectural ideas, pitfalls to avoid, or observations about the domain the problem is trying to solve. “Code” alone does not capture everything. My earlier approach was to write extensive specs and capture them as docs, which I had to constantly reference when working on a task. It wasn’t scaling, and it wasn’t enough. The agents frequently forgot key details I had decided were essential and wrote docs on, but they weren’t always bringing that knowledge to bear… creating weird spaghetti. Spaghetti that solved the problem at hand but was inconsistent with earlier pieces. I solved most of this by following rigid structures (like templates) for different parts of the codebase, which nearly solved the inconsistency issue, but not entirely.

Depending on the programming stack you use, there’s still information loss about the domain under consideration unless you meticulously document it in the project. The agent wasn’t really “learning”. This is not a meta discussion about what “learning” is and whether they really do. My insight was that they lack “knowledge” - the kind we bring to bear when we learn a codebase and the domain it’s operating in — the little trickles of insights gained that turn into a knowledge repository. What they needed was a way to build this “knowledge” themselves, through working on a project, and to bring it to bear on the problem at hand.

How did I solve this without agents before? The answer was actually so simple. I used structured notes - a scratchpad filled with entries about different aspects of the codebase or domain. For example, I documented data flow, persistence methods, and design choices—things that happen all the time in artisan coding. These notes acted as a personal memory aid, helping me recall critical details quickly and consistently during development.

But what do I mean by structured notes? You need to distinguish between free-form writing and structured writing. Free-form writing about a problem solved in a project would be like a couple of paragraphs explaining what was solved. But depending upon how good you are at keeping all relevant details, the free-form approach becomes lossy and inconsistent. So I follow a system where I design a template for each type of learning that I have. For instance, a “problem solved” template might capture the problem, the root cause, and what was learned. Or a “design principles” template might have fields for the principle itself (limited to 150 characters), the rationale behind it, and what anti-pattern it prevents. The template forces me to list the relevant details. And I design little templates to use for other things, like “patterns discovered” or “workarounds learned”. These are, by necessity, brief and distinct from project-level documentation. Having a structure enhances consistency and makes the gathered knowledge really valuable.

Now, how do I make the agents follow such a system? Define templates, and use them whenever the context dictates, preferably in a seamless way… like when I think and jot them down.

Enter Pensieve, a scratchpad for AI agents to use - a command-line interface (CLI) tool that agents can use to define templates and record notes in them and recall them as needed. Agents are very good at using CLI-based tools, and they automatically discovered how to use them with a little prompting. The agents designed templates in collaboration with me for each project I was working on and started filling them in as we tackled tasks together. And slowly, as we started new sessions, the agent started recollecting past learnings, informing the task at hand and making it more guided and precise than before. You no longer needed to yell the same information over and over.

But why exactly is this better than using CLAUDE.md or docs in the repo? It is because they are unstructured, and the agents follow those instructions in an inconsistent manner. The more you have in this memory, the less likely the agent is going to find it and use it. Also, without specifying limits, the agents generated verbose, pointless documentation which they themselves did not follow. By forcing the agents to create structured notes with well-defined fields and LIMITING the length of them as needed, more disciplined knowledge capture happened.

Besides templates, Pensieve also encourages agents to link entries with each other. Nothing is lost forever — a note can be “augmented,” “superseded,” or “deprecated” by another note. In most cases, this is sufficient, and the agent is encouraged to follow these links when inspecting a note. This allows the agent to crawl through memory AS NEEDED for the task at hand, digging deeper and deeper into memory, building a “graph of sorts” in its agentic mind.

I no longer have the repo for the same open. Instead, I plan to share a spec of the tool, which should be sufficient for any agent to design one.

Large Language Models (LLMs) have unleashed a Cambrian explosion of software. Over the decades, coding was partly considered elitist, despite efforts to make it accessible to more people. Many people became coders without calling themselves that. Writers and script writers were never afforded the title, despite, for all intents and purposes, they were indeed “coding”.

Still, there was a class of software considered inaccessible to them. You needed an elaborate ritual of Software Engineering professions—from Product designers, analysts, managers, developers, and QA—to build these classes of software. Cloud apps, mobile apps, SaaS products.

The gate that prevented them had nothing to do with the complexity of the problem that they were trying to solve in a domain. The complexity of the business, be it payment processing workflows, scheduling apps, delivery apps with their own niche problems, was something product builders were able to dissect and find elegant solutions. But the translation of their solutions into software was blocked by something much more insipid.

It was the sheer amount of accidental complexity Software Architects and engineers had created over the decades. These abstractions were just endless indirections that tackled particular problems sometimes meaningful, many times not so. It still forced those looking to translate their solutions to software to deal with them.

What are React Hooks and why do you need them? What is pydantic for? What is a REST API and why do I need it?

These are worthwhile questions, but the answers and the rabbit holes of knowledge required to master them bore both deep insights and rote knowledge that needs translation and execution. The latter of which LLMs offer to solve. They can never really solve the former except to rehash pre-discovered wisdom.

How do we deal with this new world? Is it an all-or-nothing approach to go for? Is a new development approach on offer? Has a new type of coder emerged? We will set out to find out here.