Prompting Patterns

These are the techniques that work across every kind of task — exploration, debugging, refactoring, code generation. Learn them once, apply them everywhere.

@file and @directory References

Use @ to include files or directories in your prompt without waiting for Claude to search for them. The content is added to context immediately.

Explain the logic in @src/utils/auth.js

What's the structure of @src/components?

Show me the data from @github:repos/owner/repo/issues

The three forms behave differently:

Syntax	What Claude gets	Use when
@src/utils/auth.js	Full file content	You want Claude to read that specific file
@src/components	Directory listing with file info	You want the structure, not the contents
@github:repos/owner/repo/issues	Data from a connected MCP server	You have an MCP server configured

Practical tip: Combine multiple references in a single prompt.

@src/services/order.service.ts depends on @src/models/order.ts —
explain how they interact and whether the null checks are sufficient.

File paths can be relative or absolute. Referencing a file also pulls in any CLAUDE.md files in its directory and parent directories, so project-specific context loads automatically.

Images and Screenshots

Claude can analyze images directly. This is one of the most underused features — a screenshot conveys context that would take a paragraph to describe.

Three ways to add an image:

1. Drag and drop the file into the Claude Code window
2. Paste with Ctrl+V — note: on Mac use Ctrl+V, not Cmd+V
3. Reference by path: analyze this image: /path/to/screenshot.png

High-value use cases:

[paste error screenshot]
What's causing this error?

[paste design mockup]
Implement this component. Match the layout, spacing, and colors as closely as possible.

[paste database diagram]
We're adding a "subscriptions" concept.
How should we modify this schema to support it?

[paste a confusing UI state]
This UI looks wrong. What's likely causing the layout to break?

When Claude references an image (e.g., [Image #1]), you can Ctrl+Click (or Cmd+Click on Mac) the link to open it in your default viewer.

Being Specific Upfront

The most reliable way to get a good result on the first attempt is to include everything Claude needs in the first prompt: what is broken, where to look, and how to verify the fix.

# Vague — works, but you will steer several rounds
fix the authentication bug

# Specific — often correct on first attempt
The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.

The second prompt costs you thirty seconds of thought. It saves five minutes of back-and-forth. At scale — when you are running several Claude sessions — the difference compounds.

What to include when relevant:

• Which file or directory to start in
• The constraint that must not be violated (“no @ts-ignore”, “maintain backward compatibility”)
• How to verify the result (“run npm test”, “the output should be valid JSON”)
• What you have already tried

Giving Claude Something to Verify Against

Claude performs better when it can check its own work. If you can define success as a machine-readable signal, include it.

Implement validateEmail.
Test cases: 'user@example.com' → true, 'invalid' → false, 'user@.com' → false.
Run the tests after implementing.

Refactor this function to remove the nested callbacks.
Run `npm test -- --testPathPattern=utils` after each change and fix any failures.
Do not consider the task done until all tests pass.

This is the core of Verification-First Development. Even a single test case gives Claude a concrete target rather than a subjective judgment.

Unix Pipe Patterns

Claude works as a standard Unix utility. Pipe data in, get structured analysis out.

# Explain a build error
cat build-error.txt | claude -p "explain the root cause concisely"

# Find anomalies in logs
tail -200 app.log | claude -p "flag any anomalies or errors worth investigating"

# Security review of changed files
git diff main --name-only | claude -p "review these changed files for security issues"

# Summarize a diff for a PR description
git diff main | claude -p "write a concise PR description for these changes"

Control the output format when piping into scripts:

# Plain text (default) — for human-readable output
cat data.txt | claude -p "summarize this data" --output-format text

# Full JSON conversation log — for scripts that need metadata
cat code.py | claude -p "analyze for bugs" --output-format json

# Streaming JSON — for real-time monitoring
cat log.txt | claude -p "parse errors" --output-format stream-json

In package.json scripts:

{
  "scripts": {
    "lint:ai": "claude -p 'Check changes vs. main for typos and obvious bugs. Format: filename:line — issue' --output-format text",
    "release-notes": "git log --oneline -20 | claude -p 'Write release notes grouped by Features/Fixes' --output-format text"
  }
}

graph LR A([Data source]) -->|pipe| B([claude -p]) B --> C{output-format} C -->|text| D([Human-readable]) C -->|json| E([Script-parseable]) C -->|stream-json| F([Real-time stream]) style A fill:#1e293b,color:#7dd3fc,stroke:#334155 style B fill:#1e293b,color:#a5b4fc,stroke:#334155 style C fill:#1e293b,color:#fcd34d,stroke:#334155 style D fill:#1e293b,color:#86efac,stroke:#334155 style E fill:#1e293b,color:#86efac,stroke:#334155 style F fill:#1e293b,color:#86efac,stroke:#334155

Extended Thinking

For complex problems — architectural decisions, intricate bugs, tradeoff analysis — Claude can reason more deeply before responding. Extended thinking is enabled by default.

To trigger maximum reasoning depth for a single prompt, include ultrathink anywhere:

ultrathink: design an authentication system that supports SSO, API keys,
and per-tenant permissions. We have 50k users and expect 10x growth.

To toggle thinking on or off for the current session, press Alt+T (Windows/Linux) or Option+T (macOS). To see Claude’s reasoning process, press Ctrl+O for verbose mode — thinking appears as gray italic text.

---

Related: Session Workflows for patterns that span full working sessions — PRs, parallel instances, and rewinding. Creator Workflows for Boris Cherny’s advanced prompting techniques including ultrathink and “grill me”.