Your First Claude Code Prompt

1. The most common first-prompt mistake

New users open Claude Code, stare at the prompt, and type something like: “Refactor this project to follow best practices.” Then they wait. Then they read an impossibly broad set of changes touching files they have never heard of. Then they undo everything and wonder what went wrong.

The mistake is not the ambition — it is the lack of shared context. Claude Code did not know what “best practices” meant to you, which parts of the codebase were stable and which were actively changing, or what you were actually trying to achieve. It made reasonable assumptions about all of those things, and they did not match yours.

The fix is simple: start with exploration, not implementation. Your first prompt should never ask Claude Code to change anything. It should ask Claude Code to learn something and report back. This gives you two things: you find out what Claude Code understands about your codebase, and you create shared context for every subsequent prompt in the session.

A good first prompt on a new codebase looks like:

Explore this codebase and give me a high-level map: main modules, how they connect, 
the data flow from the user's perspective, and anything that looks unusual or technical-debt-y.

This takes 30–60 seconds, produces a response you can actually evaluate, and gives Claude Code the context it needs to execute targeted tasks accurately for the rest of the session.

2. How to give context efficiently

After exploration, subsequent prompts should be specific about three things: what to change, where to change it, and why. The “why” is often skipped, but it is frequently the most important — it tells Claude Code what constraints to respect and what trade-offs to accept.

Compare these two prompts for the same task:

Weak: “Add error handling to the API client.”

Strong: “Add error handling to the API client in src/api/client.ts. We use a centralized error logger at src/utils/logger.ts — route all errors through that. Network failures should be retried up to 3 times with exponential backoff. Do not throw to the caller; instead return a Result type with success/error variants.”

The strong version tells Claude Code exactly what file to touch, which existing patterns to follow, what behavior to implement, and what constraints the caller interface must satisfy. Claude Code can satisfy all of those constraints. The weak version forces it to guess all of them — and one wrong guess means the code is wrong even if it looks plausible.

You do not need to write an essay for every prompt. For small, well-scoped tasks — “rename this function to match the convention in this file” — a short prompt is fine. Length and specificity should scale with the scope and risk of the task.

3. Approval mode and the safety tradeoff

Every action Claude Code takes can require your explicit approval or can proceed automatically. Understanding this tradeoff before your first task will save you from unpleasant surprises.

Manual approval mode is the default. Claude Code shows you what it is about to do — which file it is about to write, which command it is about to run — and waits for you to press Enter. This feels slow at first. It is not: it is you learning what Claude Code does, which makes you dramatically better at prompting it and catching problems before they propagate.

Auto-accept mode (activated with claude --yes or by typing --yes at the Claude Code prompt) skips those approval steps. Claude Code acts immediately on its plan. This is appropriate when you are repeating a workflow you have already reviewed, or when working on a throwaway branch where speed matters more than caution.

A hybrid strategy that many experienced users settle on: auto-accept file reads and directory listings, but manually approve writes and bash commands. This removes the friction from the observation phase while keeping you in control of the action phase.

4. Three productive first tasks

Three categories of tasks work especially well as first interactions with a codebase in Claude Code, regardless of the project type.

Codebase mapping: Ask Claude Code to explain the architecture, trace the execution path for a key feature, or find where a specific concept is implemented. These tasks are safe (read-only), produce immediately valuable output, and build shared context for subsequent tasks. “Walk me through what happens when a user logs in, starting from the HTTP request and ending at the session cookie” is a classic example.

Bug investigation: Give Claude Code a failing test or error message and ask it to find the cause — but not fix it yet. Separating investigation from implementation lets you validate the diagnosis before committing to a fix. “The payment webhook test in tests/webhooks.test.ts is failing with a 422 error. Find out why, explain the root cause, and outline what a fix would look like — but don’t change any files yet.”

Targeted mechanical changes: Refactors, renames, migration of a config format, updating all usages of a deprecated API — changes where the pattern is clear and repetitive, the success criterion is obvious, and verification is easy. “The project uses var in several files in the utils/ directory. Convert all of them to const or let as appropriate and run the tests to confirm nothing broke.”

5. Iterative prompting: the conversation is the tool

Claude Code is not a one-shot tool. The most effective use of it is a genuine back-and-forth, where each exchange refines the output toward exactly what you need.

After Claude Code responds, resist the urge to immediately accept or reject. Instead, probe: “Why did you choose this approach over X?” or “What would break if we removed this constraint?” These follow-up questions surface assumptions you can agree or disagree with before they get baked into code.

When the output is close but not quite right, be precise about what is wrong: “Everything looks good except the error retry logic — it should use exponential backoff starting at 1 second, not a fixed 500ms delay. Fix only that part.” This preserves what is correct while targeting the specific issue, rather than triggering a full regeneration that might change things that were already right.

If you reach a point where the conversation has drifted from the original goal, it is often faster to type /clear and start fresh with a better-informed prompt than to try to steer back. A clean context with a precise prompt nearly always outperforms a long conversation trying to undo earlier wrong turns.

cd ~/projects/your-repo
claude

Explore this codebase. Give me: the main purpose of the project, the top-level directory structure and what each folder contains, the primary data flow, and anything that stands out as technical debt or unusual design decisions.

Your description of the auth module is slightly off — the JWT is validated in middleware/auth.ts, not in the controller. Given that correction, what would be the safest place to add rate limiting?

Find all places where we're catching errors but not logging them. List the file, line number, and what the caught error is for each case.

In src/utils/logger.ts, add a logError(error: Error, context?: Record<string, unknown>) function that writes to stderr using the existing format. Do not change any call sites — just add the new function.