Problem: Prompt engineering — why did I write a 500-word prompt and the AI still doesn't get me? —— Trove problem library

Symptom

Let me start with a scene I can replay from memory: you turn your requirement into a 500-word essay — role, background, requirements, caveats, all arranged — and send it to the AI full of hope.

It replies with a paragraph that "says everything but says nothing".

You push back: "No, that's not what I wanted." It apologizes, retries, and gives you a version that's the same soup with a different spoon. You start questioning everything: did I not explain clearly, or is this AI just useless?

There's an even more common version: you tell the AI "write me an order module", and it actually writes one — using a framework you've never used, dependencies that don't exist in your project, and assumptions you never stated.

You ask why, and it says "based on best practices".

At that moment you want to reach through the screen and shake it: this project is Java 8 + Spring Boot 2, not that "modern stack" you assumed!

Other people live at the opposite extreme: they treat prompts as chat — whatever comes to mind, out it goes.

The result: the same task produces a different output in the morning and the afternoon; change one word, the whole output changes; don't change a word, it still changes.

You can't reproduce it, can't debug it, can't reliably get back that "good result from last time". So you conclude AI is a toy of luck and quit.

And there's a third group: they copied a pile of "universal templates" — "you are a senior expert", "please think step by step" — but the templates fail in their own scenarios.

The template's role is "senior front-end engineer", but your need is "help me see why this SQL is slow"; the template demands "output a Markdown table", but your downstream program needs JSON.

The borrowed template is like a borrowed suit: it doesn't fit, and you don't know where to alter it.

If any of this sounds familiar — prompts getting longer while AI gets more off-target, the same task giving different results every time, copying templates you can't customize, or concluding that "prompt engineering is just mysticism" — this article is for you.

It is not a prompt library. It is the consensus of people who actually treated prompts as engineering, paid for in thousands of useless conversations: a prompt is not a chat message — it's the API contract you write for the AI. Structured, reusable, iterable input is what produces stable, reliable, predictable output.

Cause

First, be clear about why prompts are so hard to write. Four reasons, all pointing at the same thing — vague input inevitably produces probabilistic output.

First, LLMs are probability machines, not search engines. Their training objective is "predict the next token", and output quality directly depends on the clarity and structure of the input prompt.

Give it a vague instruction, and it can only make probabilistic guesses — guessing your business context, guessing your desired format, guessing the constraints you didn't state.

Guess enough, and "hallucinations" and "answers that miss the question" become inevitable. It's not dumb; you gave it too much entropy.

Second, if context isn't in the prompt, the AI has to invent it. Your project's stack, what a file does, what historical behavior a feature must preserve — you have all this in your head, but it's not in the prompt, so the AI guesses from file names, from template experience, from local pages extrapolated to global rules.

It "looks like it works" because it filled in every unstated assumption for you — and your real business rules were exactly in the parts you didn't state.

Third, without evaluation, there is no iteration. With code, you have a thousand ways to verify: compile, test, run and see. With prompts? Most people "write once, use once, forget once" — was it good or bad, and why, is never recorded.

Without evaluation criteria there's no basis for iteration, so prompt skill stays stuck at "lucky guess".

Fourth, treating prompts as "writing" instead of "engineering". One big paragraph, starting from scratch every time, adjustments by feel — that's writing thinking.

Engineering thinking is: decompose the structure (role/task/constraint/example/output), build templates (reusable), version them (comparable), define metrics (evaluable).

Writing thinking makes every prompt a disposable consumable; engineering thinking turns prompts into an accumulating asset. The core of prompt engineering is not "being good at talking" — it's "turning your words into a maintainable system".

Solution

Each experience below follows the same shape: phenomenon → practice → why. None of it is one person's opinion — these are patterns that recur across many independent practices.

Experience 0 (L1 one-sentence conclusion): Prompt = Role + Task + Constraints + Example + Output format

Say all five, and the AI won't have to guess. If you only remember one thing: next time you write a prompt, check whether these five are present — role (whose perspective), task (what to do), constraints (what not to do / boundaries), example (what "correct" looks like), output format (what shape to deliver).

Experiences 1-6 below explain why and how.

Experience 1: Layer it — don't write an essay. Context, task, format

Phenomenon: The most typical failed prompt I've seen is "write me an Express error-handling middleware" — one sentence, nothing else.

The AI can write it, of course, but it will write a "generic version": it doesn't know if your project is JavaScript or TypeScript, whether you have a custom error class, whether you need logging, whether you need tests.

So you get a middleware that fits nothing, and fixing it takes longer than writing it yourself.

The opposite extreme is just as common: dumping a 500-word essay at once, mixing background, emotions, requirements, history, and caveats into one blob — the AI still goes off-target, because the information is one lump and it can't tell which is constraint, which is background, and which is task.

Practice: Split the prompt into clear layers, one thing per layer: ①Context — project background and stack, the role of the current file, relevant code snippets; tell the AI "what world you work in"; ②Task — what exactly to do, inputs and outputs, constraints;

tell the AI "what you want it to do"; ③Format — code style, comment conventions, testing requirements, output structure; tell the AI "what to deliver".

There's a more complete version called CRISP: Context + Role + Instruction + Specificity + Presentation — role answers "whose perspective", instruction answers "what to do" (single, specific, short, with context), specificity answers "to what degree" (format/length/style), presentation answers "how to deliver" (JSON, Markdown, tables).

Why: AI parses structured input far better than prose. Layering isn't for looks — it's about compressing information loss.

The same requirement with an unstructured prompt can lose close to half its information; structured, the loss drops dramatically: task boundaries become clear, professionalism rises, output becomes controllable.

Every layer you clarify is a guess the AI doesn't have to make; the fewer guesses, the more stable the output.

Remember the principle: give context first, then the concrete task — AI and humans are the same: without background, any task comes back deformed.

Experience 2: Build a template library — manage prompts like code

Phenomenon: Someone who wrote 200+ prompts summarized it into a formula: "role + task + constraints + example + output format".

But the more valuable part isn't the formula — it's what he did next: freezing common scenarios into templates stored in the project's .ai-templates/ directory — new-component.md, refactor-code.md, write-tests.md, debug-error.md, explain-code.md — each with placeholders, ready to fill in.

From then on, writing a prompt wasn't "thinking from zero"; it was "open a template and fill in parameters".

Practice: ①Create templates for high-frequency scenarios — new components, refactoring, writing tests, debugging errors, explaining code: you hit these weekly; build one template each, with role, context, task, requirements, and output format pre-set, leaving only {variable} placeholders;

②From copying templates to customizing them — beginners copying templates is fine, but consciously analyze the structure: why does this template set a role? why is this constraint here?

After analyzing three to five templates you can assemble your own; long-term template-dependence has three side effects: it can't serve individual needs, it never uses the AI's deeper capabilities, and your output becomes homogeneous with everyone else's; ③Manage prompts like code — version control (what changed, why), templating (freeze common scenarios), testing (A/B compare versions, define quantitative metrics);

④Review and update templates daily — ten minutes at night recording today's AI usage: which prompt types worked, which always flipped, update the library.

Why: The biggest waste in prompt writing is "starting from zero every time". A template library turns one-time good prompts into reusable assets — every future use of a template you tuned once saves a round of trial-and-error.

More importantly, templating forces you to think in structure: if you can freeze a prompt into a template, you genuinely understand why it works; if you can't, you're still going by feel. Prompts, like code, are assets, not consumables.

Experience 3: Iterate and evaluate — there is no perfect prompt, only ever-improving prompts

Phenomenon: Most people write prompts once: write, use, rewrite when broken.

People who treat prompts as engineering will tell you something counterintuitive: a perfect prompt rarely appears in one shot — it's tuned. An unsatisfying first output is not a failure; it's data — it tells you what you didn't clarify.

A friend of mine inherited an AI-driven refactor: the first pass, the AI changed the entire button interaction; he said "that's not right", the AI changed it again, still wrong.

Then he turned his feedback into constraints: "button position must match the source project", "this entry must preserve historical behavior" — the AI got it immediately.

"That's not right" is emotion, not a constraint; "X must stay consistent" is a constraint.

Practice: ①Turn feedback into constraints, not emotions — "not right" and "ugly" carry no information; "button position must match the source project", "this field must be kept", "this flow can't be simplified" do; each round, sediment the feedback into explicit constraints for the next round;

②Keep iteration records — a task's prompt went through three versions; what each version output and where it failed — write it down; without records, you're jumping into the same pit repeatedly; ③Evaluate with A/B comparisons — run two prompt versions a few times each and compare output quality;

how to quantify quality?

Define your metrics: format correctness, first-pass success rate, rework count, human-edit volume;

④Set confirmation gates for the AI — for high-risk decisions (auth flows, permission models, data contracts, whether to add new dependencies), require the AI to stop and present 2-3 options for your confirmation, instead of deciding for you; ⑤Require read-first, ask-first, design-first — for complex tasks, the opening prompt is not "start working" but "read the context first, produce a fact list, and don't modify any files until that's done";

make it prove it has read the context before it touches code.

Why: Prompt quality isn't written; it's iterated. No evaluation, no iteration; no iteration, no progress — this applies to prompts exactly as it applies to code.

Turning feedback into constraints is the key step from "human-chatbot dialogue" to "human-AI collaboration": emotional feedback only makes the AI guess; structural constraints calibrate it.

Confirmation gates turn the AI from "executor" into "investigator" — it proves understanding first, then acts, preventing it from making business decisions for you in critical positions.

Experience 4: Decompose complex tasks — design first, foundation first, one piece at a time

Phenomenon: Many people, on their first complex task with AI, compress the requirement into one sentence: "help me refactor this project". That sentence starts a conversation, but rarely a reliable engineering collaboration.

The AI's biggest problem isn't writing code — it's starting to write too fast: guessing business meaning from file names, changing interfaces from template experience, judging global rules from local pages, ending with something that "looks like it runs, but the key contracts have changed".

In a large refactor, if you let the AI move all pages at once, you'll find mid-way that request protocols are inconsistent, permission checks are inconsistent, data structures are inconsistent, routing rules are inconsistent — full rework.

Practice: ①Write the design document before the code — require the AI to first produce a refactor design doc: what to keep, what to migrate, which rules defer to the API docs, what parts of the reference implementation are reusable, the risk list, the phased plan;

no business code changes until the design is approved; ②Foundation before business — request wrapping, auth state, permission/navigation, pagination protocols, common components: land the infrastructure first, then use one low-risk module as the pilot, and only after it runs do you scale the migration;

③One module at a time, aligned on three lines — visual interaction toward the new project, business fields toward the source project, data contracts toward the API docs; missing any one line fails; when conflicts appear, make the AI stop and explain rather than choose for itself;

④Difference review matters more than "I'm done" — after each batch, require the AI to review against the source project: list fields, operation flows, permission checks, detail views, item by item; review first, don't change code, just report differences;

⑤Use chain-of-thought for complex reasoning — ask the AI to think step by step: "analyze step by step, write the steps first, then the answer"; one example with reasoning beats ten dry results.

Why: Complex tasks always fail in "do it all at once" mode and succeed in "batch it, verify each batch" mode.

AI's speed is an advantage — but only if you draw the boundaries: the design doc is a boundary, the foundation is a boundary, three-line alignment is a boundary, difference review is a boundary.

AI refactoring without boundaries turns speed into a risk amplifier; with boundaries, it becomes a real leverage.

Chain-of-thought exploits the model's "reason first, then answer" capability — if you demand the reasoning, you can see where it went wrong instead of just seeing the wrong conclusion.

Experience 5: Know the prompt's limits — it decides "how to think", not "what it can do"

Phenomenon: Someone used a pure prompt to ask the AI to "check today's weather in Beijing", and the AI replied "sorry, I can't query real-time data".

That's not a badly written prompt — it's a capability boundary: prompts can only access the model's internal knowledge, not real-time data.

There's a sneakier boundary: you ask the AI to write code, it does — using dependencies you've never seen and APIs it never verified, because its "knowledge" ends at some cutoff date and it may not know the new versions of libraries.

No prompt, however perfect, crosses these boundaries.

Practice: ①Separate "how to think" from "what it can do" — prompts decide how the AI thinks (role, approach, style); tools/Skills decide what it can do (check weather, publish posts, drive a browser, call APIs); when you need real-time data, external operations, or proprietary interfaces, don't just write a prompt — give it tools;

②Remember the priority: prompts before fine-tuning — if a prompt can solve it, don't jump to fine-tuning: writing prompts is cheap, explainable, and iterable; if a prompt can't even reach basic requirements, fine-tuning has a low chance of success either;

conversely, once the prompt passes the bar, fine-tuning can push further; ③AI-generated code must be reviewed — AI writes fast, but its understanding of "your system" is always local; critical logic, security boundaries, and performance details need human review;

boilerplate and repetitive logic can go to the AI; ④Don't treat AI as the final answer — it's a "second brain", not an "outsourced brain": architecture decisions, edge conditions, and business constraints are always human responsibility.

Why: Every tool has a capability boundary; prompts are no exception. Knowing the boundary matters more than knowing the tricks — effort inside the boundary is leverage; effort outside it is waste.

The right relationship between prompts and tools is complementary: prompts say what you want; tools fill in what's possible.

And "AI output must be human-reviewed" is the least glamorous but most life-saving rule in all AI-coding experience: no matter how high the AI's accuracy, on the critical path its error rate is a cost you can't afford.

Experience 6: The human is the final owner — AI does the scaffolding, you do the architecture

Phenomenon: Someone who used Copilot, Cursor, Codex, Claude Code and more, generating over 500,000 lines of code cumulatively, summarized a counterintuitive conclusion: what truly improved efficiency wasn't the tools — it was a reusable workflow. His workflow: AI generates the skeleton → human writes core logic and edge conditions → AI adds unit tests → AI reviews the code → human does the final confirmation.

His biggest pitfall was letting the AI write entire features from zero — the code ran, but was hard to maintain, and debugging took longer than writing it by hand.

Practice: ①Divide labor explicitly — AI handles boilerplate, repetitive logic, test generation, PR descriptions; humans handle architecture, edge conditions, performance, security; ②Don't let the AI write whole features from zero — from zero means the AI made every architecture decision for you, and it knows nothing about your business;

the right posture is "skeleton to AI, flesh by hand"; ③Critical paths must be human-reviewed — treat AI-generated code like intern code: worth reusing, but must be reviewed; the cost of debugging a production bug is always higher than the extra five minutes spent reviewing code;

④Treat the AI as a collaborator, not a generator — make it read first, ask first, design first, then change in batches with verification; the more context it has, the closer the output comes to what you want;

⑤Sediment workflows, not just prompts — morning planning, feature development, code review, evening retro: embed AI into fixed points of the process instead of using it on a whim.

Why: Tools amplify human ability; they don't replace human judgment. AI writes code ten times faster, but "what is good code" judgment is still human.

Handing architecture and boundaries to the AI is like handing the wheel to someone who has never driven this road — it may go fast, but one wrong turn costs more in rework than the time saved.

A well-divided team is efficient; human-AI collaboration is the same: each does what it's good at — that's leverage; letting the AI do the parts you're not comfortable with is gambling.

How to start using this (checklist, L1 execution layer)

1. Today: turn your most common scenario (e.g., "write tests" or "explain code") into a template in the project's .ai-templates/; use it next time; when it fails, fix the template, not the body text;
2. This week: before every prompt, check the five pieces — role, task, constraints, example, output format — and fill in whatever is missing; for complex tasks, always split into "read context first → confirm the plan → do it in batches → review each batch";
3. Every feedback: change "that's not right" into "X must stay consistent"; put the new constraint into the next prompt instead of correcting verbally;
4. After every task: write one line of evaluation — what prompt was used, output quality score, how to improve next time; after 10 records, you'll see your prompt-skill curve;
5. Long term: manage prompts like code — templates into version control, versions compared, effects measured; AI-generated code always reviewed, critical logic always human-written.

How to adapt this to your scenario (L3 deep-dive layer)

• Personal daily (writing/learning/research): use a template library for your common prompts — one writing template, one summarization template, one translation template; make "please analyze step by step" muscle memory; when output disappoints, fix the prompt before fixing your temper.
• Developers (AI-assisted coding): the three-piece set — layered structure + template library + review discipline; complex refactors must follow design-first, confirmation gates, batch verification; treat AI output as intern code, and write critical paths by hand.
• Teams (multiple people using AI): put prompt templates in the repo, shared by the team; new hires start with the template library instead of fumbling from zero; run periodic prompt-sharing sessions to turn personal experience into team assets.
• API integration (prompts shipped in products): output format must be strictly enforced (JSON-Schema level); use A/B tests across versions; define quantitative metrics (format correctness, first-pass success rate); version and roll back like code.
• Students / beginners: copying templates is fine, but analyze one template a week — "why is it written this way"; in three months you'll find yourself assembling your own; remember: prompts are a skill, not a talent — they come from practice and retro, not inspiration.
• If you're stuck in "the AI never listens": start with the smallest loop — today, write one prompt with all five pieces; tomorrow, build one template; this week, record one evaluation line per task. Prompt engineering is not mysticism; it's a craft — and craft comes from repetition, not a single epiphany.

(Final words) After years of writing prompts, my deepest lesson is: five hundred words of prose lose to five lines of structure. AI does not need your literary talent; it needs your engineering discipline — role, task, constraints, examples, output format.

Get the five parts right and it beats any rhetoric.

Keep your frequent prompts in a template library, version them like code, and your output quality will stabilise to a point that surprises even you. And always remember the last rule: AI writes the boilerplate, you own the architecture.

When the output is wrong, fix your input first — do not blame the model.