Why the quality of your prompt is really the quality of your thinking
Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where precision is valued and vagueness is gently corrected. Timothy has arrived with a real problem and a prompt he is rather proud of.
Episode 3: The Craft of the First Prompt
What Timothy Brought In
He arrived with his laptop already open, which Margaret took as a good sign. It meant he had been thinking before he walked through the door.
"I have a real one today," he said, settling into his chair. "Not a toy example. An actual problem from the codebase."
"Good," Margaret said. "Show me what you've written."
He turned the laptop toward her. On the screen was a prompt he had prepared:
"Fix the performance issue in my data processing pipeline."
Margaret read it. Then she looked at him over her glasses with the particular expression she reserved for moments that required patience.
"Timothy," she said. "What is wrong with this prompt?"
He shifted slightly. "I thought it was fairly clear."
"It is not clear at all," she said, not unkindly. "It is the prompt of someone who knows what they want but has not yet done the work of describing it."
The Interrogation
She turned the laptop back toward him and folded her hands.
"Tell me about the pipeline. What does it do?"
"It processes customer transaction records. Reads from a database, applies some business logic, writes results to a reporting table."
"How many records?"
"On small runs, a few thousand. On the monthly batch — around four million."
"And the performance issue. What exactly is happening?"
"The monthly batch is timing out. It used to complete in about forty minutes. Now it's taking over three hours and failing halfway through."
"When did this change?"
Timothy paused. "About three weeks ago."
"What changed three weeks ago?"
Another pause — longer this time. "We added a new validation step. For regulatory compliance."
Margaret looked at him steadily. "And you gave Claude Code the prompt: fix the performance issue in my data processing pipeline."
He had the grace to look slightly embarrassed. "When you say it like that—"
"I say it like that because that is what you wrote." She picked up her pen. "Claude Code is not a mind reader. It does not know about your four million records, your regulatory validation, your three-hour timeout, or the fact that this began three weeks ago. You handed it a problem with no context, no constraints, and no indication of what success looks like. What do you imagine it would produce?"
"Something generic," he admitted.
"Something generic," she confirmed. "Possibly something plausible-sounding but entirely wrong for your specific situation. And you would have to spend an hour discovering that, when five minutes of careful thinking at the start would have prevented it entirely."
The Four Questions
She drew a small grid on her notepad — four boxes.
"Before you write any prompt for a real engineering problem," she said, "you answer four questions. Not in the prompt itself necessarily — but in your own mind first, and then reflected in what you write."
She filled in the boxes as she spoke.
"First — what is the context? What system are we working in, what does it do, what are its constraints? Claude Code needs to understand the world the problem lives in."
"Second — what is the specific problem? Not 'performance issue.' The pipeline processes four million records monthly, recently began timing out after three hours, previously completed in forty minutes, change coincided with addition of a validation step."
"Third — what have you already tried or considered? This is the question most developers skip. If you have already ruled out certain approaches, say so. If you have a theory, share it. You are not asking Claude Code to think from scratch — you are asking it to think alongside you."
Timothy was writing now. Margaret continued.
"Fourth — what does a good solution look like? What are the constraints? Must it complete within a certain time? Must it not change the output format? Are there parts of the codebase it must not touch? Define success before you start, or you will not recognise it when you see it."
She set down her pen. "Now rewrite your prompt."
The Rewrite
Timothy was quiet for several minutes. Margaret drank her tea and did not hurry him. Good thinking could not be rushed, and she had learned long ago that silence was often more productive than assistance.
He turned the laptop toward her.
"I have a data processing pipeline in Python that reads customer transaction records from a PostgreSQL database, applies business logic validation, and writes results to a reporting table. On monthly batch runs of approximately four million records, the pipeline recently began timing out after three hours — it previously completed in forty minutes. The change coincided with the addition of a new regulatory validation step three weeks ago. I suspect the validation logic may be running a database query inside a loop, but I have not confirmed this. The solution must not change the output format or the table schema. Can you help me identify the likely bottleneck and suggest an approach to fix it?"
Margaret read it carefully. All the way through, twice.
"Better," she said. "Much better."
"Just better?"
"Significantly better," she allowed. "You have given it context, a specific problem, a timeline, a hypothesis, and a constraint. Claude Code can now do something genuinely useful with this." She paused. "One addition I would suggest — tell it what you want first. Not at the end."
"What do you mean?"
"You buried the actual request in the last sentence. Lead with the outcome you want, then provide the context. Something like: I need to diagnose and fix a performance regression in a Python data pipeline — then everything else follows. The tool reads from the beginning. Give it direction before you give it detail."
Timothy made the adjustment. The prompt now opened with a clear statement of intent, followed by everything he had already written.
"There," Margaret said. "Now you have a prompt worth sending."
What Changed
"Can I ask something?" Timothy said. "The second prompt is so much longer. Is longer always better?"
"No," Margaret said immediately. "Length is not the virtue. Precision is the virtue. Your second prompt is longer because your first prompt was missing essential information. If your first prompt had been precise and complete, it would have been the right length." She looked at him steadily. "The question to ask is not have I written enough? It is does this contain everything Claude Code needs to help me? Sometimes that is two sentences. Sometimes it is a paragraph. The problem determines the length, not the other way around."
Timothy nodded slowly. "So the prompt is really just... clear thinking written down."
"Exactly that," Margaret said. "That is all it has ever been. The developers who struggle with Claude Code are very often not struggling with the tool — they are struggling with the thinking that should come before the tool. The prompt reveals the quality of your understanding. If your understanding is vague, the prompt will be vague, and the output will be vague."
"And if my understanding is clear—"
"The prompt will be clear, and Claude Code will do remarkable work." She closed her notepad. "This is why I said in our first conversation that the tool amplifies what you bring to it. Nowhere is that more visible than in the prompt."
The Hypothesis Worth Sharing
"You mentioned a hypothesis," Margaret said. "That the validation logic might be running a database query inside a loop. Do you actually believe that?"
"It's the most likely thing," Timothy said. "The validation step checks each transaction against a reference table. If it's doing that one record at a time instead of batching—"
"Then you have an N+1 query problem," Margaret said. "Four million individual database calls instead of a small number of efficient batched queries."
"Which would explain everything."
"It would explain a great deal, yes." She looked at him. "When you have a hypothesis, share it. Not because Claude Code needs your permission to think — but because your hypothesis is information. It tells the tool where to look first, which approaches are worth exploring, and which are likely dead ends. A shared hypothesis is not a constraint. It is a gift."
Timothy looked at the revised prompt on his screen. "I gave it the gift."
"You did." Margaret allowed herself a small smile. "And if your hypothesis is wrong, Claude Code will likely tell you why — which is also useful. You do not lose anything by sharing your thinking. You only gain."
Before He Sent It
"One more thing," Margaret said, just as Timothy was about to hit enter. "Read it aloud."
He looked up. "I beg your pardon?"
"Read the prompt aloud. Before you send it."
He did — slightly self-consciously, but thoroughly. Halfway through, he stopped.
"I said recently twice," he said.
"You did."
"And I never specified which table the results are written to."
"No."
He made both corrections without being asked. Margaret said nothing. She did not need to.
When he sent it, the prompt was clean, precise, and complete. Claude Code's response came back detailed, specific, and directly useful — identifying the likely N+1 pattern, suggesting a batched lookup approach, and flagging two other areas worth investigating.
Timothy read it with the focused expression of someone who understood what they were looking at.
"It knew exactly where to look," he said quietly.
"Because you told it exactly where to look," Margaret said. "That is the partnership. You bring the context and the thinking. It brings the breadth and the speed. Neither is sufficient alone."
She picked up her tea.
"The first prompt is not the beginning of the work, Timothy. It is the end of the thinking. Get the thinking right first, and everything that follows will be better for it."
Outside, London was going about its afternoon. Inside the library, a developer had just learned something that would serve him for the rest of his career — not a trick, not a shortcut, but a discipline.
The discipline of thinking clearly before asking.
Next episode: Margaret and Timothy explore what happens when Claude Code gets it wrong — confidently, convincingly, and completely. How to catch the errors that look like answers.
The Secret Life of Claude Code publishes on tech-reader.blog every other day.
If this series is useful to you, share it with a developer who needs to hear it.
Aaron Rose is a software engineer and technology writer at tech-reader.blog. For explainer videos and podcasts, check out Tech-Reader YouTube channel.
Top comments (4)
Cool! Aaron. I am curious. Have you try vibe coding with claude? Honestly, I am not a fan of vibe coding to much
Hi Benjamin!
I am a vibe coder with Claude! Honestly for me there is a lot of upfront planning and thinking - Sketching out the UI. Thinking about the scope, etc. Yep it's a lot of upfront work. Cheers buddy! ❤🚀
Cool! ok! I see. Have you try loveable? I tried vibe coding once last year. It does make life easier for a developer to do their work :).
Enjoy the weekend as well, man!
I'll check out lovable tonite! thanks Benjamin ❤