Last updated 13 October 2026
Run Claude Code with a specific system prompt
Initial context prevents repetitive instructions
You might find that the Claude CLI starts every session with a blank slate. It does not know your coding style or your project requirements unless you tell it every time you open a new window. This leads to a repetitive cycle of typing out the same rules for every new task. You want the agent to act as a senior developer who already knows your specific tech stack and naming conventions. Without a way to pass initial instructions, you spend too much time on manual setup.
A lack of persistent context is a common friction point for developers. You need a way to pass system level instructions that stay active across different sessions. If you do not provide this context, the agent might suggest libraries you do not use or write code that violates your project linting rules. The goal is to make the agent a part of your workflow by giving it a permanent memory of how you work. This is done by using specific files that the agent reads every time it starts up.
Project instructions live in the CLAUDE.md file
The CLAUDE.md file is the primary tool for defining your project system prompt. You place this file in the root directory of your git repository. When you run the claude command, the agent looks for this file before it begins the interactive session. It reads the instructions inside and treats them as the foundation for all its actions. This is where you should define the core architecture of your application and the specific libraries you prefer to use for testing or state management.
You can use standard markdown in CLAUDE.md to organize your instructions. Use headers to separate sections like build commands, test patterns, and code style. For example, you can tell the agent to always use the Edit tool instead of the Write tool when modifying existing files. You can also specify that it should use the Glob tool to find files before it tries to read them. This gives the agent a clear roadmap for how to interact with your specific codebase without you having to repeat yourself.
Hierarchical files provide granular control
Claude Code supports a hierarchy of CLAUDE.md files that allows for granular control over different parts of your repo. If your project has a complex structure, you can place a CLAUDE.md file in any subdirectory. The instructions in a subdirectory apply specifically to the files and tasks within that part of the tree. This is very useful when a single repository contains different environments like a React frontend and a Go backend that require different coding standards.
The agent combines the instructions from the root CLAUDE.md with those found in the subdirectory where it is currently working. This means you do not have to repeat general project rules in every folder. You can keep the high level architecture in the root and put specific API guidelines or styling rules in the relevant subfolders. This hierarchical approach keeps your instruction files clean and focused on the immediate context of the agent while maintaining global project standards.
Global instructions apply to every project
Some instructions are universal to every project you work on. You might have a specific way you like to communicate or a preferred terminal setup that never changes. Instead of adding these to every single repository, you can use a global configuration file. This file is located at ~/.claude/CLAUDE.md on your system. The agent reads this global file every time you start a session, regardless of which project folder you are in or which repository you have open.
The global CLAUDE.md file is the perfect place to define your personal developer identity and general preferences. You might instruct the agent to always be brief or to never use certain tools unless you specifically ask for them. If you have a specific way you want the agent to handle error messages or logs, this is the place to document it. By using the global file, you ensure a consistent experience across all your development tasks without cluttering your project-specific documentation with personal preferences.
Subagents offer specialized roles and personas
If you need to switch between different roles or sets of instructions frequently, you can use custom subagents. These are defined by creating markdown files in the .claude/agents directory. Each file serves as a specialized system prompt for a particular task or persona. You might have one agent specifically for refactoring legacy code and another for writing technical documentation. These subagents allow you to change the behavior of the CLI without editing your main CLAUDE.md files.
You can invoke these subagents within a session using the /agents command. This command lists the available subagents and lets you select the one you need for your current task. Each subagent can have its own unique instructions and tool preferences. This is a powerful way to manage complex workflows where the agent needs to adopt different personalities. It keeps the main conversation context focused while providing the flexibility to bring in specialized help when a specific technical challenge arises.
Settings files manage technical boundaries and permissions
The settings.json file provides another layer of control over how the agent behaves at a system level. While CLAUDE.md is for architectural instructions, settings.json is for technical configuration and permissions. You can find this file in the .claude directory of your project or in your home directory at ~/.claude/settings.json. This file allows you to set the default permission mode for the agent, which dictates how much it can do without your explicit approval.
Inside settings.json, you can define specific permissions for each tool the agent uses under the permissions key. For instance, you might want to allow the Read and Glob tools to run without asking but require a manual prompt before the Bash or Edit tools execute. You can choose between modes like default, acceptEdits, plan, and bypassPermissions. By configuring these settings once, you ensure the agent operates within your safety comfort zone every time you start a new task in your terminal.
Visual organization helps manage multiple contexts
Managing multiple projects with different system prompts can become difficult when using a standard terminal. This is where adhdTerminal provides a better way to work. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. The app lets you run many Claude Code sessions side by side as tiles on a wall. This visual layout helps you keep track of different projects that each have their own unique CLAUDE.md instructions.
Each tile in adhdTerminal has its own color, number, and name. It shows you the last exchanges of the conversation and the current status of the agent. You can see if a tile is working, waiting for you, or idle at a glance. Because tiles reopen in the same place after a restart and resume the same session, you do not lose your place or your context. This setup is ideal for developers who need to jump between backend and frontend tasks while keeping their project-specific instructions organized and visible.
Single prompts respect your existing configuration
You can use the claude -p flag to run a single prompt with specific instructions from your shell. This is useful for one-off tasks where you do not want to enter a full interactive session. Even in this mode, the agent still respects the CLAUDE.md files in your current directory. This means your project-specific system prompt is still active and the agent will follow your architectural rules even for a single-use command that prints an answer and exits.
If you need to pass additional instructions that are not in your permanent files, you can include them directly in the prompt string. This is common for automation scripts or when you are testing a new instruction before adding it to your CLAUDE.md file. The claude -p command is a flexible tool that allows you to leverage your existing system prompts while providing the ability to extend them for a single execution. This keeps your automated tasks as consistent as your manual ones.
Session management keeps instructions effective
Maintaining a clean context is vital for the agent to follow your system prompt effectively. Over time, a long conversation can fill the context window and cause the agent to lose track of the initial instructions in your CLAUDE.md file. You can use the /compact command to address this. It summarizes the session so far and frees up space in the context window. This ensures the most important parts of your conversation and your system prompt remain at the forefront of the agent memory.
If you want to start a completely fresh conversation without losing your project context, use the /clear command. This resets the session in the same folder and forces the agent to re-read your CLAUDE.md files from the disk. This is the best way to apply changes you have made to your system prompt files. It ensures that the agent is not influenced by previous mistakes or irrelevant context from earlier in the session, allowing it to focus purely on your updated instructions.
Questions people ask
Do I need to restart the CLI to apply changes to CLAUDE.md?
You do not need to exit the terminal to update your instructions. After you save changes to your CLAUDE.md file, use the /clear command inside your active session. This action resets the conversation and forces the agent to re-read the project instructions from the disk.
Can I use different system prompts for different tasks in the same folder?
Yes, you can create multiple specialized personas by adding markdown files to the .claude/agents directory. Use the /agents command to list and select these subagents during your session. This allows you to switch between a code refactorer and a documentation writer without modifying your main project files.
How can I confirm which instructions the agent is currently using?
You can use the /status command to see information about your current session context. While it does not print the entire instruction file, it confirms that the agent is operating within your project. You can also ask the agent directly to summarize its current instructions to verify it has read your CLAUDE.md file correctly.
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.