Updated Sep 2026

GuideAI Tools

Prompting That Works

Modern AI coding agents are brilliant, fast, and brand new to your project every time. A good prompt

Prompt

The text you give to an AI to tell it what you want. Better prompts = better results. It's an art and a science.

"Like giving directions to a taxi driver. Be specific about the destination, or you might end up somewhere weird."

is a good briefing: what you want, why, what "done" looks like, and what to leave alone.

1The Core Principle

Picture a senior contractor on their first morning. Very skilled, zero knowledge of your codebase, your users, or your taste. Vague briefing, vague result. The AI only knows what you tell it and what it can find.

Vague prompt

"Make my code better"

Better how? Faster? Cleaner? More secure? It will guess.

Specific prompt

"Refactor fetchOrders in lib/orders.ts to async/await and add error handling that returns a typed error instead of throwing. Keep the function signature."

Clear goal, clear boundary, clear outcome.

2Give Context, Not Just Instructions

Instructions say what. Context explains why and where, which lets the model make good calls on the hundred small decisions you didn't spell out.

Include:

• What you're building: "A Next.js 16 App Router store for handmade candles"
• Current state: "Products live in a Neon Postgres table, queried with Drizzle"
• What you want: "A shopping cart"
• Why: "Most customers buy on mobile as guests, so guest carts matter most"
• Constraints: "Server Actions, no Redux, no new dependencies without asking"

Good example

I'm building a Next.js 16 (App Router) store with Drizzle and Neon.
I need a shopping cart that persists to the database for logged-in
users and to localStorage for guests, and merges the two when a
guest logs in. Most traffic is mobile guests, so the guest path
matters most. The schema is in @src/db/schema.ts. Use Server
Actions for mutations. Don't add new dependencies without asking.

Stop repeating yourself. Stack, commands, and conventions belong in a project file the agent reads every session (CLAUDE.md

CLAUDE.md

A Markdown file Claude Code reads at the start of every session: project context, commands, conventions, and rules. Put it at `./CLAUDE.md` (shared with the team), `~/.claude/CLAUDE.md` (personal, all projects), or `CLAUDE.local.md` (personal, gitignored). Run `/init` to generate a starter; AGENTS.md is read too.

"Like a welcome packet for a new team member. It tells Claude everything it needs to know about your project."

for Claude Code, which also reads AGENTS.md). Prompting is the per-task part of a bigger skill: context engineering

Context Engineering

Deliberately curating everything the model sees, not just the prompt: instructions files, retrieved docs, tool results, conversation history. Good context engineering keeps the context window small and relevant using CLAUDE.md, skills that load on demand, subagents for side quests, and compaction.

"Like packing a carry-on for a trip. You can't bring the whole closet, so you choose exactly what the journey needs."

, which covers everything the model sees.

3Show Examples

Want output in a specific shape? Show it. Models pick up patterns from examples faster than from descriptions. In a codebase, the best example is usually code you already have.

Format example

Write product descriptions in this format:

Product: Wireless Headphones
Tagline: Sound that moves with you
Description: Premium audio meets all-day comfort...

Now write one for: Running Shoes

Codebase example

Create an API route for orders that follows the same pattern as
@app/api/products/route.ts (validation, error shape, auth check).

Pro tip

Give 2–3 varied examples for tricky formats. With one, the model may copy its quirks; several make the pattern clear.

4Ask for a Plan First

For anything bigger than a one-file change, have the agent read the code and propose a plan before it edits. A wrong plan costs you 30 seconds to fix. Wrong code across 15 files costs an afternoon.

In Claude Code, use plan mode

Plan Mode

A read-only permission mode in Claude Code: Claude can explore the codebase and write up a plan, but can't edit files or run changes until you approve. Enter it by pressing Shift+Tab until the status bar shows plan mode, prefixing a prompt with `/plan`, or starting with `claude --permission-mode plan`.

"Like walking through a house with an architect before renovation. You discuss ideas and make plans without swinging a hammer."

: press Shift+Tab until the status bar shows ⏸ plan mode on, prefix a prompt with /plan, or start the session in it:

Terminal

claude --permission-mode plan

Or just ask (works in any tool)

Before writing any code: read the relevant files, then give me a
step-by-step plan, the files you'll touch, and any questions you
have. Wait for my OK before making changes.

5Set Constraints

Agents are eager. Without fences they'll "helpfully" refactor files you didn't ask about or install a library for a ten-line job. Say what's off-limits, and phrase it positively where you can ("use native HTML validation" beats a list of banned libraries).

"Only change files under app/checkout/"

"Use native HTML5 validation; no new packages"

"Keep the public API of lib/auth.ts unchanged"

"Don't touch the database schema; propose changes instead"

6Define "Done" (Verification Criteria)

The biggest upgrade to your prompts: tell the agent how to check its own work. Agents that can run a test, a type-check, or a build will loop until it passes. Agents without a finish line stop when the code merely looks right.

Prompt with a finish line

Add rate limiting to POST /api/contact (5 requests per minute per IP).

Done means:
- a test in tests/contact.test.ts proves the 6th request gets a 429
- npx tsc --noEmit passes
- npm run build passes
Run those yourself and show me the output before you say you're done.

No tests yet? Ask for them first: "Write a failing test that reproduces this bug, then fix it." For AI features inside your app, the same idea scales up into evals.

7Iterate & Refine

First result not perfect? Normal. Prompting is a conversation. Build in small, checkable steps:

Start: "Build a contact form component"

Refine: "Add validation for email and phone fields"

Polish: "Disable the submit button while sending"

Fix: "The email check rejects .co.uk addresses"

Know when to reset. If you've corrected the same mistake twice, the conversation is polluted with bad attempts. Start fresh with /clear and a better prompt that includes what you learned. In Claude Code, Esc Esc opens rewind so you can back up to an earlier point.

8Claude Code Specifics

Use @ mentions for file context

Type @ and a path to pull a file into the conversation.

"Update @src/db/schema.ts to add a createdAt column to the users table"

Slash commands worth knowing

/initGenerate a starter CLAUDE.md

/clearStart a fresh conversation

/compactSummarize to free up context

/contextSee how full the context window is

/planPlan before editing

/memoryEdit CLAUDE.md files

Compaction

Summarizing a long conversation so it takes up less of the context window while keeping the important parts. Claude Code compacts automatically as the window fills, or on demand with `/compact`, and you can steer it: `/compact keep the test output`. `/context` shows how full your window is.

"Like condensing a 40-page meeting transcript into a one-page brief so the next meeting can start with the essentials."

and a watchful eye on the context window

Context Window

The amount of text an AI can 'see' at once, measured in tokens: your instructions, the conversation, files it read, and tool results. Current Claude models (Opus 5.5, Sonnet 5, Fable 5.1) offer 1M-token windows and Haiku 4.5 has 200K, but even huge windows work best when kept focused.

"Like short-term memory. The bigger the window, the more the AI can remember from your conversation."

matter on long sessions. More in Claude Code Tips.

Turn repeat prompts into skills

Typing the same instructions every week? Save them as a skill in .claude/skills/<name>/SKILL.md and run it with /<name>. See Skills Ecosystem.

9Common Pitfalls

Being too vague

"Fix the bug" without context leaves the AI guessing.

Fix: Describe current behavior, expected behavior, and how to reproduce it. Paste the exact error.

No context about your stack

You get Pages Router code in an App Router project, or npm commands when you use pnpm.

Fix: Put your stack in CLAUDE.md / AGENTS.md: "Next.js 16 App Router, Drizzle, Tailwind v4, pnpm".

No finish line

The agent says "done" and the build is broken.

Fix: Give verification criteria and ask it to run them.

Giant one-shot requests

"Build my whole SaaS" produces a lot of code and a lot of bugs.

Fix: Plan first, then build in slices you can test.

Accepting code you don't understand

Unreviewed code becomes bugs you can't fix, and it can include made-up APIs.

Fix: Ask "walk me through this change" and check anything that looks like a hallucination against the docs.

Worried about hallucinations

Hallucination

When an AI confidently makes up information that isn't true. A known limitation — always verify important facts.

"Like a very confident friend who sometimes makes up stories. Trust but verify."

? Asking the agent to cite the file or doc it's relying on makes them much easier to catch.

10A Template to Steal

Prompt template

Goal: <what you want, in one sentence>
Why: <who it's for / what problem it solves>
Context: <relevant files with @paths, current behavior, errors>
Constraints: <what not to touch, libraries to use or avoid>
Done when: <tests / type-check / build / manual check to run>
Process: read first, propose a plan, wait for my OK, then build.

Put persistent context in CLAUDE.md, not every prompt

Describe current state AND desired state

Show an example of the shape you want

Ask for a plan on anything multi-file

Say what's off-limits

Give a verifiable finish line

Iterate in small slices; reset when polluted

Review and understand before you ship

Pasting logs or code into a chat? Run it through the Prompt Scrubber first to strip secrets.

Level up from prompts to context

A great prompt only covers one task. Context engineering sets up the project so every prompt starts from a better place.

Context Engineering Claude Code Tips