How to Write Prompts: The Magic Template That Gets AI Right on the First Try
The answer up front: Whether AI can get it right on the first try depends on whether your prompt contains "information" or "wishes." This lesson on AI coding prompts is about how to pack in information—in the previous lesson you organized your idea into a four-part checklist; this lesson turns that checklist into text the AI understands at a glance: a three-element template for writing, a two-round correction rule for when it goes off track, and a place called AGENTS.md / CLAUDE.md to consolidate the rules you repeat every time.
It sounds like a weighty subject, but a complete beginner can get through it in 12 minutes. All four tools (Claude Code, Codex, OpenCode, WorkBuddy) are covered—this lesson teaches the general way to hand information to AI, not any single vendor's proprietary syntax.
Workflow Overview established five disciplines; the previous lesson expanded on the first one, "plan before you act." This lesson continues with the second: how to turn your checklist into a prompt the AI gets right on the first try.
What You'll Be Able to Do After This Lesson
- Use the "location / symptom or goal / completion criteria" three-element template to turn the previous lesson's requirements checklist into a concrete AI coding prompt
- When you have material on hand, stop describing and hand it over directly: reference files with
@, paste screenshots, and paste error messages verbatim into the conversation - Pull it back on track the moment it goes wrong: if correcting the same thing twice still doesn't work, clear the conversation and fold the lessons into a new prompt
- Consolidate the rules you repeat every time (build commands, code conventions, pitfalls) into AGENTS.md / CLAUDE.md so new sessions load them automatically
- Tell real information apart from "magic words": pressure phrases like "think step by step" and "Important!" are explicitly not keywords, according to the official docs
Your Current Struggles
- You write a long prompt, but what the AI delivers is still wrong—and you can't say exactly which sentence it was missing
- Rules like "use Chinese comments" and "don't introduce new libraries" have to be retyped every new session; miss once and things fall apart
- You've heard prompts have "magic words" but don't know which ones actually work and which are superstition, so you add "please be very careful" to every sentence
When to Use This Technique
When you need to:
- Turn the previous lesson's four-part checklist into text the AI actually follows
- Cut one round of rework from everyday tasks like fixing bugs and adding features
- Make every session in the same project automatically carry your rules
And you don't want to:
- Write every prompt from scratch, getting longer and longer with no focus
- Shout "Important!" "Must!" to pressure the AI into obeying
- Keep editing to the fifth revision in the same conversation, still reluctant to start over
🎒 Preparation Before You Start
- Finish reading Plan Before You Act: Turn a One-Sentence Idea into a Requirements Checklist and keep that four-part checklist on hand—this page uses it directly as raw material
- Have installed and used at least one tool: Claude Code, Codex, OpenCode or WorkBuddy
- 12 minutes and a cup of water ☕
Core Idea
A good prompt isn't about eloquence; it's about sufficient information. Claude Code's official best practices put this point first: before starting work, the AI reads your code—it can find the file layout, conventions, and test framework on its own; what it can't find are the things never written into the code—the rules decided in your meetings, the picture in your head, your personal standard for "fixed." Specific prompts work because they supply this missing information.
The official docs also give a criterion for deciding whether to write a sentence—two questions:
- Can it be found by reading the code?
- Will it actually go look for it?
If both answers are "yes," don't write it—writing it dilutes the focus instead. It's the same as packing a suitcase: the fuller it gets, the more easily the truly important things get buried.
The example sentences in the official comparison table from the previous lesson break down neatly into three pieces of information:
| Information the AI lacks | Corresponding part of the example sentence |
|---|---|
| Location: where to look | "Check token refresh in src/auth/" |
| Symptom: what went wrong | "Users report login failure after session timeout" |
| Completion criteria: what "fixed" looks like | "First write a failing test that reproduces the problem, then fix it" |
There's one more easily missed point: a preference between two reasonable approaches is equally unreadable from the code. Whether error messages use popups or inline hints—both are reasonable, and which one the AI picks is pure luck. If you insist on inline, state it up front—the official wording is "if you care which one it picks, say so first."
One sentence to remember this lesson: A prompt is for delivering information, not for making wishes.
Follow Along
(Use the previous lesson's four-part checklist as raw material and complete four steps: it first becomes a fully informative prompt, then becomes a long-term setup you don't have to rewrite every time.)
Step 1: Use the three-element template to turn your checklist into an AI coding prompt
Why: the checklist is written to clarify your own thinking, while the prompt is fed to the AI—the same information, arranged differently, produces completely different first reactions from the AI. The three-element template turns the pattern from the official comparison table into a fill-in-the-blank exercise.
Rearrange the four-part checklist according to this template (the first magic template on this page—copy it and fill it in):
Symptom or goal: <who, under what circumstances, encountering what problem / wanting to build what>
Relevant location: <file, directory, or error message verbatim; if starting from scratch, write "from scratch">
Completion criteria: <what must be true for it to count as done; must be verifiable>
Hard constraints: <no new libraries / keep existing style / single-file delivery...>WorkBuddy Users: paste the filled-in template into the "additional notes" field when creating a task—the official docs likewise recommend stating goals, scope, constraints, and expected output in the task description.
After filling it in, self-check: is every line information the AI cannot get by reading the code? Delete anything it can read (e.g., "the project uses TypeScript").
You should see: a prompt of four lines or fewer. After you send it, the AI's first action is to read the files you named, not to ask back "which bug?"—that's what it looks like when the information is in place.
- Quick check: my "completion criteria" line is verifiable (passes / no longer reproduces / opens), not "done well"
Step 2: If you have the material on hand, hand it over directly instead of describing it
Why: descriptions get distorted; originals don't. The official advice, verbatim, is "if you already have what the AI needs, hand it over instead of describing it"—three sentences of your paraphrased error are worth less than one line of the original.
All four tools have a channel for "handing over"—match it to the type of material:
| Materials | How to hand them over |
|---|---|
| Files | Claude Code: type @ plus the path, and the file's contents go straight into the message; Codex: @ mentions files; OpenCode: on desktop/web, choose Attach file, paste, or drag into the input box; WorkBuddy: @ references files, documents, and rules |
| Screenshots / design mockups | Claude Code: paste them directly into the prompt; WorkBuddy: Ctrl/Cmd + V to paste a screenshot; OpenCode: image attachments (first confirm the model supports image input) |
| Error output | Paste the raw output into the conversation; with Claude Code you can also pipe it in directly |
Claude Code's official piping recipe (no need to open and copy the error log—just ask it in one sentence):
cat error.log | claude -p "这是怎么回事"💡 Handing over materials ≠ skipping the prompt
Even after handing over the originals, you still need to write the three elements from step 1—the originals answer the "where" and the "symptom," while the "definition of done" and "hard constraints" are still known only to you. Only the two combined make a complete prompt.
You should see: the AI references the originals you handed over—it restates file contents and reads out the key lines of the error, rather than guessing from your paraphrase.
- Quick check: at least one part of this prompt is an original I handed over, not my paraphrase
Step 3: Pull it back on the spot when it goes off track; if two rounds of correction fail, clear and rewrite
Why: even the best prompt can't be fire-and-forget. The official advice is to watch the AI's first minute of work and interrupt the moment it goes off track—far cheaper than reworking after it finishes. There's also a pattern to corrections: if correcting the same thing twice still fails, the third attempt almost certainly won't work, because two failed records are already in the conversation, and the AI rereads them every turn.
Course-correction actions come in three tiers, escalating with how far off track it is:
- Interrupt on the spot: in Claude Code, press
Escto stop the current action (keeping what's done), then send a corrective message - Roll back and restart: use
/rewind(or pressEsctwice in an empty input box) to open the rewind menu and roll the code, the conversation, or both back to an earlier prompt - Clear and rewrite: if correcting the same thing fails twice, use
/clearto clear (or start a new session) and fold the lessons from both attempts into one new prompt—in the official words: this is almost always better than a third round of correction
Don't just send "that's wrong" as a corrective message—there's a template for this too (the second magic template on this page):
Stop. What you're doing right now is <what it's doing>; what I want is <the correct direction>.
Don't change the code yet. Confirm your next approach with me in three sentences; start working only after I confirm.Codex officially adds one piece of session discipline: one chat holds one coherent task—don't stuff the whole project into the same session; the thicker the context piles up, the worse the results get.
You should see: most drifts get pulled back in one go; for the one that doesn't, you decisively clear and rewrite, and the new prompt lands in one shot.
- Quick check: recall one experience where I "corrected into a third round"—replay it with the two-round rule: at which step would I clear and rewrite?
Step 4: Distill the rules you repeat every time into the project manual
Why: after writing a few good prompts, you'll notice: "install with pnpm," "run tests with vitest," "don't touch src/legacy/"—these lines have to go into every single prompt. Codex's official best practices put it in these exact words: once a prompting pattern works, the next step is to stop repeating it manually—that's exactly what AGENTS.md exists for. Claude Code's counterpart file is called CLAUDE.md, and OpenCode also reads AGENTS.md. Same mechanism: the file sits in the project and is auto-loaded in every session.
What goes in the manual? Merging the two official checklists gives four categories:
| Category | What to write | Example |
|---|---|---|
| Commands | How to install dependencies, run tests, run a single test, do type checking | pnpm install / pnpm vitest run path/to/file.test.ts |
| Conventions | Which helper to use for error handling, which directories' patterns not to copy | "Use src/lib/errors.ts, don't throw bare strings" |
| Pitfalls | Environment variables, directories that look useless but aren't | "Integration tests need DATABASE_URL" |
| Definition of done | How to verify completion | "After changes, run the corresponding tests; done only when they pass" |
The third magic template on this page—the manual skeleton (works for AGENTS.md / CLAUDE.md):
# Project Manual
## Commands
- Install dependencies: <command>
- Run a single test: <command>
- Type checking: <command>
## Conventions
- <Error handling, naming, directory rules—only what can't be seen from the code>
## Pitfalls
- <Environment variables, easily misjudged directories>
## Definition of Done
- <How to verify completion: what to run, what counts as passing>Two pieces of official advice, more important than the template itself:
- Short and precise beats long and exhaustive. Claude Code's memory guide suggests staying under 200 lines; Codex puts it as "a short, accurate file is more useful than a long one full of vague rules." Start with the basics, and only add new rules after noticing repeated mistakes.
- When the same mistake happens twice, have it reflect and update the manual. This is the concrete action Codex gives officially—the root cause of a mistake is often a missing entry in the manual.
💡 WorkBuddy Users
WorkBuddy's task conversations likewise support @ referencing "files, documents, rules." Save your common rules as a rules document and @ it when creating a task—the effect equals a lightweight manual.
Note a cross-tool difference: OpenCode treats AGENTS.md as authoritative, and only starting from v2.3.1 (2026-11-18) does it fall back to reading CLAUDE.md when there is no AGENTS.md in the directory. When mixing multiple tools, for advanced details on where to put the instruction file and how the hierarchy stacks, see AGENTS.md and CLAUDE.md: Leave a Project Instruction File for AI.
You should see: new sessions no longer need you to retype the rules—ask "how do I run tests in this project," and it cites the commands from the manual.
- Quick check: every entry in the manual passes the core-principle two questions (can't be read from the code / it won't go looking on its own)
Checkpoint ✅
- I can recite the three elements: where, symptom or goal, definition of done—plus one hard constraint
- I've handed over originals: passed files with
@, pasted screenshots, or pasted raw error text, instead of describing them in words - After two failed corrections of the same thing, I cleared and rewrote the prompt instead of sending a third round
- My repeated rules went into AGENTS.md / CLAUDE.md and are auto-loaded in new sessions
- I removed pressure language from my prompts and replaced it with concrete information
Pitfall Reminders
❌ Treating "magic words" as switches
"Think step by step," "be thorough," adding "Important!" to rules or even all caps—the official docs explicitly state these are ordinary prompt text, not keywords; what controls thinking intensity is the effort / reasoning-effort setting, not adjectives. Worse, piling emphasis on rules that keep getting ignored only makes the model over-generalize them. The right move isn't to apply pressure but to write the information concretely; for rules that truly can never have exceptions, use the tool's built-in enforcement mechanisms (permission rules, hooks)—that's the topic of Cost and Safety.
❌ Every prompt carrying the entire household
Codex officially lists "piling long-term rules into the prompt instead of moving them into AGENTS.md" as the number one common mistake. Prompts hold information for this task; the manual holds long-term rules—mixing them has two costs: prompts get longer and longer while the key points get diluted; and once you switch sessions, all the rules are lost.
❌ You want the full version, but you only wrote the minimum requirements
AI tends to interpret your words conservatively, building "the minimal thing that satisfies the literal requirements"—it can't see how big your inner expectations are. If you want a version that fully covers empty states, error messages, and save flows, list the scope in the prompt (the official phrase is be ambitious, followed by the full list of what you want). This was mentioned in the advanced tips of the previous lesson, and this is where it goes on paper.
Advanced Tips (Optional)
Let AI write the manual for you. Both Claude Code and Codex CLIs have /init, which generates a starter manual from the codebase; your job is mainly deletion—cut it down until only the information that can't be read from the code remains. Claude Code also has /doctor to suggest cuts and /context to confirm the file is actually loaded.
From manual to skill. Reusing the same prompt over and over, correcting the same workflow again and again? Codex's official rule of thumb: it's time to package it as a skill. This is the next level of "consolidation"—consider it after your manual has stabilized.
Lesson Summary
✅ You've completed the full chain of AI coding prompts: writing the three elements (location / symptom or goal / done criteria) → passing the originals directly (@ files, pasting screenshots, pasting error messages) → the two-round rule for course correction (interrupt → roll back → clear and rewrite) → consolidating long-term rules (AGENTS.md / CLAUDE.md).
✅ You now know that the standard for a good prompt isn't length—it's that every sentence is information AI can't get from reading the code; run the two questions, and delete everything it could read out.
✅ You can tell information from pressure: magic words aren't a switch, effort levels are; real rules go into the manual or an enforcement mechanism, not "IMPORTANT!".
Key concepts recap:
| Concept | In one sentence | Where to go deeper |
|---|---|---|
| Three elements | Location / symptom or goal / done criteria | Step 1 on this page |
| Pass the originals | @ references, pasting screenshots, pasting raw error messages | Step 2 on this page |
| Two-round rule | Two failed corrections → clear and rewrite | Step 3 on this page |
| Project manual | AGENTS.md / CLAUDE.md, auto-loaded every session | AGENTS.md and CLAUDE.md |
| Magic-word pitfall | Pressure phrases aren't information | Pitfall reminder on this page |
Next Lesson Preview
However well you write the prompt, the code will still throw errors when it runs—and the raw error message is precisely the most valuable material for your next prompt. Next lesson: Error Loop: Feed the Error Message Back Verbatim.
You will learn:
- Why error messages should be fed back "verbatim," and what paraphrasing loses
- How to let AI run the "edit—run—read output—fix again" loop by itself until it passes
- How to change your approach when fixes stall, instead of spinning in a dead end