Blog

Good Prompting

I don't know that much about good writing, but Paul Graham wrote something recently that has been stuck in my head. He says writing that sounds right helps you find ideas that are right. When he rereads a draft, he is asking if anything catches, or if anything feels wrong.

I think this is also true when working with agents.

Maybe good prompting is not getting the first prompt right; it is drilling down until the prompt is right. The first prompt starts the work, the questions shape it, and the review is where you find out what the prompt should have said.

You cannot know what you don't know before building the thing. Creation is discovery, so the important work is often after the agent produces something. You review the artifact and ask questions until it makes sense.

I'm saying artifact on purpose. Agents don't only produce code. They produce PRs, tests, plans, comments, migrations, config, and docs. The output is a thing with concepts inside it.

I don't think you need to understand every line. That's not the goal. The goal is to understand every concept the artifact asks you to trust.

In practice, good prompting looks a lot like working with teammates, colleagues, or fellow builders. You don't throw something over the wall and accept whatever comes back. You ask questions. You review the plan. You ask why something exists. You ask whether something already does this. You leave comments where the next person would get confused.

Sometimes the best prompt is: don't code yet. Read the artifact, tell me what already exists, ask the questions that would change your approach, and give me a small plan I can review.

Not a giant spec. Not an RFP nobody can keep in their head. Just enough of a plan that we can see the concepts before they turn into code.

A common problem with coding agents is that they code too soon. Sometimes asking questions to clarify is the best work.

Creating with agents is not one prompt. It is the collective prompts and iterations that happen while you are building. The review comments are prompts. The clarifying questions are prompts. The comments you leave for the next reader are prompts too.

The questions are boring:

Anything you can't answer clearly is the part that still doesn't make sense.

The second one matters a lot.

If React already has the concept, don't invent a new one. If the browser already has the concept, don't invent a new one. If the codebase already has the concept, don't invent a new one with a slightly different name.

Agents are good at making new things. Too good. They will happily add another helper, another wrapper, another config flag, another abstraction. Sometimes that's right. But a lot of the time the better answer is: no, this already exists.

This is where I think anxiety comes from. Not from complexity by itself, because some systems are just complex. The anxiety comes from depending on concepts you haven't made clear yet.

A large codebase can feel calm if the concepts make sense. A small change can feel dangerous if you don't know why it exists.

When something catches in review, I try to leave the artifact better than I found it. Ideally the thing explains itself with a better name, a smaller function, a less clever shape, or by deleting the extra concept entirely.

But sometimes you can't phrase it differently. Sometimes the concept is real and the code is already the simplest version of it. Then leave a comment.

Not a comment that says what the next line does. A comment that explains the thing you had to work to understand.

That comment is an artifact too. It's a little transfer of understanding from your brain into the system.

Every unanswered why leaves residue. Some of it lives in the artifact. Some of it lives in your brain.

So maybe good prompting is the review loop: ask why, ask what already does this, ask how, and then make the answer visible.

Not every line needs to be memorized. But every concept needs to be owned.

Good writing leaves fewer things catching in the reader's mind.

Good agent work should do the same.