Last updated 13 October 2026
How to write a clear Claude Code prompt
The cost of a vague initial request
You open your terminal and type the claude command to start a new session. You give it a quick instruction like fix the header layout and wait for it to work. The agent begins a series of Read and Glob operations to find the relevant files. If your project is large, it might spend several minutes searching through directories that have nothing to do with the header. You watch as your API tokens are consumed by unnecessary Grep searches and file reads. This happens because the agent is guessing where to start based on a high level command that lacks specific boundaries.
When the agent guesses, it often falls back on generic patterns that might not match your specific architectural choices. It might propose an Edit to a CSS file when your project uses a utility-first framework. You eventually have to press Escape to stop the process and provide more detail. This cycle of interruption and correction wastes time and breaks your mental flow. A clear initial prompt acts as a set of rails that keeps the agent on the right path from the first second of the session. It ensures that the first tool the agent picks is the correct one for the job.
Define project standards in the configuration files
Before you enter your first prompt, you should ensure your project has a CLAUDE.md file in the root directory. This file is the primary way to give the agent persistent context about your environment. It should list your build commands, how to run tests, and your preferred coding style. The agent reads this file at the start of every session. If you have a specific way of handling state or a naming convention for components, document it here. This prevents the agent from suggesting code that you would immediately have to reject during a /review command.
You can also use the ~/.claude/CLAUDE.md file for instructions that apply to every project on your computer. This is a good place for your general preferences, such as a preference for functional programming or specific documentation styles. When the agent starts, it combines these global instructions with the local ones in your repo. By setting these expectations in the filesystem, your interactive prompts can stay short. You no longer need to repeat your preferred testing framework in every session because the agent already knows it from the configuration files.
State the specific goal and target files
A clear prompt identifies exactly which part of the codebase needs attention. Instead of asking the agent to add a feature, tell it which directory to look in and which files are involved. You can use the Glob tool implicitly by mentioning a file pattern in your prompt. For example, telling the agent to update the validation logic in the controllers folder gives it a clear starting point. It will use the Read tool on the relevant files immediately rather than searching the entire repository. This narrow focus speeds up the initial analysis and reduces the chance of the agent making irrelevant changes.
Provide the agent with the exact error message or the specific behavior you want to change. If you are fixing a bug, paste the stack trace or the failing test output directly into the prompt. The agent can use this information to pinpoint the source of the problem using the Grep tool more effectively. When you provide concrete data, the agent can form a hypothesis and test it using the Bash tool to run your local scripts. This data driven approach is much more reliable than asking the agent to find the bug on its own without any clues.
Use permission modes to control the workflow
Claude Code has different permission modes that you can cycle through using Shift+Tab. For a complex initial prompt, it is often best to start in plan mode. In this mode, the agent will describe exactly what it intends to do and which tools it will use before it makes any changes. You can read the plan and verify that it understood your prompt correctly. If the plan looks wrong, you can provide feedback or use Escape twice to go back and refine your original request. This prevents the agent from using the Write tool on files you did not want it to touch.
Once you are satisfied with the plan, you can switch to acceptEdits mode. This allows the agent to apply the changes it proposed without asking for permission for every single file. If you are working on a very large task, you might even use bypassPermissions for a short time, though this should be done with caution. You can always check the status of your current permissions by using the /permissions command. Controlling the level of autonomy the agent has at the start of a session ensures that you stay in command of the code changes.
Manage context limits in long sessions
As you interact with the agent, the conversation history and the files it has read fill up the context window. A large context can lead to slower responses or a loss of focus on your original instructions. You should regularly check your current usage with the /cost and /usage commands. If the session has become cluttered with many tool executions and file reads, use the /compact command. This tells the agent to summarize the work done so far and clear the detailed history. This keeps the important facts in memory while freeing up space for new tasks.
If you need to switch to a completely different task within the same project, it is often better to use /clear. This starts a fresh conversation in the same directory without you having to exit and run the claude command again. Starting fresh ensures that the agent is not biased by the logic of the previous task. If you want to go back to a previous state in the current session, you can press Escape twice to see a list of earlier messages. This allows you to rewind the conversation to a point before the agent went off track, which is much more efficient than trying to fix a series of bad edits.
Monitor parallel work streams across multiple tiles
Modern development often involves jumping between different parts of a project or managing multiple repositories at once. If you try to do this in a single terminal session, your prompt history becomes a confusing mix of unrelated tasks. This is where adhdTerminal provides a better way to work. It allows you to run multiple Claude Code sessions side by side as tiles on a wall. Each tile can represent a different sub-task, such as one for backend logic and another for frontend styling. You can give each tile a name and a color to keep your work organized.
Because each tile in adhdTerminal maintains its own separate context and session history, you do not have to worry about one task interfering with another. You can see at a glance whether a specific tile is working, waiting for your input, or finished. This visibility is especially useful when you are running long tasks like a WebSearch or a complex Bash script. You can move between tiles as your focus shifts, ensuring that each prompt you write is specific to the context of that particular tile. This setup prevents the mental fatigue of constantly switching context within a single terminal window.
Leverage custom subagents for specialized tasks
You can define specialized behavior for the agent by creating markdown files in the .claude/agents directory. These subagents can be tailored for specific roles, such as a security auditor or a documentation specialist. In your initial prompt, you can instruct the main agent to use one of these subagents for a part of the task. This modular approach keeps your primary conversation focused on the main logic while the subagent handles the details of its specific domain. You can see a list of available subagents using the /agents command.
Subagents are particularly useful when you have a large codebase and want to restrict the agent's focus. You can define an agent that only has access to certain tools or directories. This reduces the risk of the agent making unexpected changes to sensitive parts of the project. By delegating work to these specialized units, your initial prompt becomes a high level orchestration of different experts. This structure makes the overall process more predictable and easier to debug if the agent makes a mistake in one of the sub-tasks.
Automate verification with hooks and settings
Your prompts will be more effective if you do not have to manually tell the agent to check its work. You can use the /hooks command to see which automated events are configured in your project. By defining hooks in your .claude/settings.json file, you can trigger specific actions like running a linter after every PostToolUse event. This ensures that any code the agent produces via the Edit tool is immediately validated against your project standards. If a hook fails, the agent receives the error message automatically and can attempt to fix it without your intervention.
You can also customize the agent's behavior through the .claude/settings.local.json file. This is the place for your personal overrides that should not be committed to the repository. For example, you might prefer the agent to use the /vim command for editing or have a specific /terminal-setup that differs from your team. These local settings ensure that the agent interacts with your environment in the way you expect. When your environment is properly configured, your prompts can focus entirely on the logic of the task rather than the mechanics of how the agent should operate.
Handling errors and recovering the session
Even with a clear prompt, the agent may occasionally get stuck or make an incorrect edit. If you see the agent repeating the same Bash command or failing to find a file with Glob, use the Escape key to interrupt it. You can then provide a corrective prompt to steer it back in the right direction. If the session has become too corrupted, you can use the /doctor command to check if there are any issues with the installation or the environment. This diagnostic tool helps you identify if the problem is with the agent or with your local setup.
Managing multiple sessions across different projects is easier when you use the global settings at ~/.claude/settings.json. This is also where adhdTerminal helps by letting you resume any session from its tiled interface. If you need to restart your computer, adhdTerminal reopens your tiles in the same place and resumes the same sessions. This persistence means you do not have to re-enter your complex initial prompts or re-establish the context for every task. You can simply pick up where you left off, whether you are using your main computer or checking the progress on the mobile app link.
Questions people ask
How can I see what my previous session cost me?
You can use the /cost command inside any active session to see the current spend for that specific conversation. To see your total usage across all sessions and time periods, use the /usage command. These tools help you monitor your API consumption and identify which prompts are the most expensive.
Is there a way to run a quick command without entering the interactive mode?
Yes, you can use the claude -p command followed by your prompt in quotes. This runs the single prompt and prints the answer directly to your terminal before exiting. This is useful for quick questions or simple file reads where you do not need a full interactive session.
How do I update the agent to the latest version?
You should run the claude update command from your terminal to fetch and install the newest version of the agent. If you are experiencing strange behavior or errors, you can also run claude doctor to verify that your installation is healthy and all dependencies are correctly configured.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.