Comment-driven development

Kiro launched. Cursor added specs. Every AI IDE is now selling spec-driven development as if it were a new discovery — and all of them, conveniently, are selling you the tool to manage those specs.

That’s not cynicism. It’s just worth noticing. The frameworks that received the most marketing attention — BDD, TDD, spec-driven development — all had products attached to them. RSpec. Cucumber. SpecFlow. Now Kiro. The workflow is real. The hype is subsidized.

Meanwhile, the simplest version of the same idea has been sitting in every programming textbook since the 1970s. You probably learned it in your first CS class. You just never heard it called a framework.

What they taught you before you could code

Before you wrote any actual code, you wrote comments. Not documentation — pseudo-code. You sketched the logic in plain English, inside the file, where the code was going to live:

// get the user's input
// validate that it's a number
// if it's negative, return an error
// otherwise add it to the running total
// update the display

Then you’d fill in the real code underneath each comment, one step at a time. The comments weren’t a spec file. They were scaffolding — a way to think through the problem before committing to syntax.

Nobody named this. It was just how you learned to program.

Why agents make it valuable again

The problem with a spec file — the markdown document that spec-driven development asks you to maintain — is that it’s not where the work happens. It’s a separate artifact the agent has to retrieve, reconcile with the current code, and keep synchronized. That synchronization breaks down. Specs drift. The code moves; the document doesn’t.

Comments don’t drift the same way. They live inside the file, next to the code they describe. When an agent is about to implement a function, the context it needs is sitting right above where it’s about to type.

This is why passive, embedded context consistently outperforms active retrieval — AGENTS.md hitting 100% pass rates where skills stalled at 53% being a clean example. The agent doesn’t have to go find the context. The context is already in the document it’s reading.

Comments give you that. For free. In the file. Where the code lives.

Before the code exists

The original use is still the best one. Before writing a function, before building a component, write the comments that describe what it should do:

# fetch the latest 20 posts from the database
# filter out any posts marked as drafts
# for each post, resolve the author's display name from the user table
# return as a list of PostSummary objects

Hand that to an agent. It now has a scoped, precise description of exactly one task — expressed in the terms of your codebase, positioned exactly where the implementation goes. No spec file to reference. No prompt to write from scratch. The intent is already there.

This is narrower than a BDD scenario and faster to write than a task spec. It takes a minute. It works.

After the code exists

The less obvious application is annotation. Once code is written — especially code that’s grown complex, or old, or written by someone else — comments that explain why give an agent the same thing they give a human developer: understanding without having to reconstruct intent from behavior.

// This runs on every render, not just on mount. The dependency array
// intentionally includes `userId` because we need to re-fetch when
// the user switches accounts. Do not memoize the fetch call here —
// the cache in useUserData already handles deduplication.
useEffect(() => {
  fetchUserProfile(userId);
}, [userId]);

A human reading that comment doesn’t have to reverse-engineer the design decision. Neither does an agent being asked to modify the component. The context is embedded in the code itself.

This is the most underused pattern in AI-assisted development. Developers spend hours writing specs and crafting prompts to give agents context about their systems. Those same minutes spent adding intent comments to existing code create permanent context — for agents, for teammates, for yourself six months from now.

The distant file problem

Spec-driven development works. But its architecture has a structural flaw: the spec is always somewhere else. A file you have to remember to update. A document that gets stale the moment the code moves faster than the documentation.

Comments solve the location problem by making context local. There’s no sync to maintain between the spec and the implementation because the comment is the implementation’s neighbor. They can’t get out of sync because they live in the same file.

The tradeoff is scope. A spec file documents the whole system. Comments document one function at a time. The answer isn’t to pick one — it’s to use each for what it does well. Specs for system-level intent. Comments for implementation-level context.

They’re not competing. The comment-annotated codebase and the living spec work together better than either does alone.

Call it what it is

Comment-driven development isn’t a new methodology. There’s no conference talk, no product, no IDE plugin to install. You already know how to write a comment. You were taught to do exactly this before you were trusted to write code without training wheels.

What’s new is that agents made the pattern exceptionally valuable again. A collaborator that reads your file top to bottom, takes its cues from what it finds, and executes against that context is exactly the kind of reader that comments were always written for.

Write the comments first. Fill in the code. Leave the comments when you’re done. Go back to old code and add them there too.

That’s it. That’s the whole framework.