Prompting Best Practices

If CLAUDE.md and skills are your persistent instructions, this chapter is about the prompts you type in the moment. It adapts Anthropic's official prompt-engineering guide to using Claude Code (the CLI).

1. Be clear and direct

Claude responds well to explicit, specific instructions. State the output format and constraints you want, and use numbered lists or bullets when order or completeness matters.

• Don't expect "above and beyond" from a vague prompt — request the level you want, e.g. "go beyond the basics to create a fully-featured implementation."
• Opus 4.8 interprets instructions literally. It does not silently generalize an instruction from one item to another, so state the scope explicitly when you want broad application, e.g. "apply this formatting to every section, not just the first one."

[Less effective]  Create an analytics dashboard
[More effective]  Create an analytics dashboard. Include as many relevant
                  features and interactions as possible. Go beyond the basics
                  to create a fully-featured implementation.

2. Add context (the "why")

Explaining the reason or motivation behind an instruction helps Claude understand your goal and generalize.

[Less effective]  NEVER use ellipses
[More effective]  Your response will be read aloud by a text-to-speech engine,
                  so never use ellipses — the engine can't pronounce them.

Key ways to inject context in Claude Code:

• @ file/directory references: pointing at @src/utils/auth.ts pulls that file (and its directory's CLAUDE.md) into context.
• CLAUDE.md: rules you'd otherwise re-explain every session belong in CLAUDE.md, not in each prompt.
• Specify fully on the first turn: in interactive coding, giving the task, intent, and constraints clearly up front reduces later-turn token usage and increases autonomy and performance. Drip-feeding ambiguous instructions across many turns is less efficient.

3. Use examples (multishot) and XML tags

Examples are the most reliable way to steer output format, tone, and structure (few-shot / multishot). Use 3–5 that mirror your real use case (relevant) and cover edge cases (diverse).

XML tags let Claude parse complex prompts unambiguously when instructions, context, input, and examples are mixed.

<instructions>
Turn the changelog below into user-facing release notes.
</instructions>

<example>
input: "fix: null check in auth"
output: "- Fixed a rare error that could occur during sign-in."
</example>

<changelog>
{{git log here}}
</changelog>

• Use consistent, descriptive tag names, and nest them when content has a hierarchy (<document> inside <documents>).

4. Control format and verbosity

• Say what to do, not what to avoid: instead of "don't use markdown," try "write in smoothly flowing prose paragraphs."
• Use XML format indicators: "write the prose sections inside <prose> tags."
• Match prompt style to output style: reducing markdown in your prompt tends to reduce markdown in the output.
• Opus 4.8 calibrates length to task complexity (shorter on lookups, longer on open-ended analysis). When you need a specific length or style, state it. Positive examples of the desired style work better than negative instructions.
• Newer models may skip summaries after tool calls. If you want visibility, add "after using tools, give a quick summary of what you did."

5. Tune effort and thinking

In Claude Code you control reasoning depth with /effort (low, medium, high, xhigh, max, ultracode).

• Opus 4.8 respects effort strictly. At low/medium it scopes work to what was asked, so if you see shallow reasoning on a hard problem, raise effort to high/xhigh rather than prompting around it.
• If you must stay at low, add targeted guidance: "This task involves multi-step reasoning. Think carefully through it before responding."
• The ultrathink keyword requests deeper reasoning for that turn (it does not change the session effort). think / think hard are not recognized keywords.

6. Action triggering vs. caution

Claude follows instructions precisely, so ask explicitly when you want action.

[Suggests only]  Can you suggest some changes to improve this function?
[Takes action]   Change this function to improve its performance.

• Opus 4.8 tends to favor reasoning over tool calls. To get more tool use, raise effort or state when and how to use the tool.
• To make it more cautious, say: "Don't modify files unless clearly instructed; when intent is ambiguous, default to research and recommendations."
• Dial back CRITICAL/MUST language. Newer models can overtrigger tools/skills, so plain phrasing like "Use this tool when…" is more stable than "CRITICAL: you MUST…".

7. Balance autonomy and safety

Without guidance the model may take hard-to-reverse actions. Tell it to confirm before risky, irreversible, or shared-system operations.

Take local, reversible actions (editing files, running tests) freely, but for
actions that are hard to reverse, affect shared systems, or could be
destructive, ask before proceeding.

Examples that warrant confirmation:
- Destructive: deleting files/branches, dropping DB tables, rm -rf
- Hard to reverse: git push --force, git reset --hard, amending published commits
- Visible to others: pushing code, commenting on PRs/issues, modifying shared infra

Don't bypass safety checks (e.g. --no-verify) or discard unfamiliar files as a shortcut.

This pairs well with Claude Code's Plan mode and permission modes.

8. Curb overengineering and hallucination

• Avoid overengineering: "Only make changes directly requested or clearly necessary. A bug fix doesn't need surrounding cleanup; don't add abstractions, defensive code, or options for hypothetical future needs."
• Prevent hallucination about code:

<investigate_before_answering>
Never speculate about code you have not opened. If the user references a file,
read it before answering. Investigate relevant files before making claims about
the codebase.
</investigate_before_answering>

• Don't fixate on passing tests: "Write a general-purpose solution with standard tools, correct for all valid inputs — not hard-coded workarounds for test cases. If a test is wrong, tell me instead of working around it."

9. Long-horizon and multi-context workflows

Long tasks favor incremental progress plus saved state over doing everything at once. See Context Management and Subagents for the full patterns.

• Use JSON for structured state (tests.json), free text for progress notes (progress.txt), and git for state tracking (logs and checkpoints).
• Context is auto-compacted near the limit, so instructing "don't stop early over token-budget concerns; save progress before the window refreshes" keeps work continuous.
• When continuing in a fresh context window, be prescriptive about how to start: "run pwd, review progress.txt/tests.json/git log, run one integration test, then continue."

Quick remedy checklist

Sources

• Prompting best practices: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
• Effort levels and model config: https://code.claude.com/docs/en/model-config
• Adaptive thinking: https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking
• Claude Code best practices: https://code.claude.com/docs/en/best-practices