Last updated 13 October 2026
Writing a brief for a complex feature
The Context Saturation Problem in Large Features
When you start a complex feature, the agent begins with a clean state. It uses the Read tool to look at your entry points and the Glob tool to understand your file structure. As you provide more details, the context window fills with file contents and previous conversation turns. If the feature brief is not structured correctly, the agent will eventually lose track of the original architectural requirements. This leads to a situation where the agent suggests changes that conflict with earlier decisions or fails to account for the secondary effects of a specific modification.
To avoid this, you must monitor how much of the context window you are consuming. You can run the /usage command to see the current token count and the /cost command to see the financial impact of the session. If the conversation becomes too long, the agent might start making mistakes or ignoring parts of your brief. This is why a well-structured brief is not just about clarity for the developer, but also about managing the technical limits of the Claude Code session. You should aim to keep the initial instructions concise and rely on the file system to provide persistent context through the duration of the feature development.
Hierarchical Instructions with CLAUDE.md Files
The most effective way to ensure the agent follows your architectural rules is to use CLAUDE.md files. A CLAUDE.md file in the root of your project acts as the primary source of truth. You should define your build commands, test runners, and general coding style there. However, for a complex feature, you should also create a CLAUDE.md file in the specific subdirectory where the feature lives. This localized file should contain the technical brief, the expected data structures, and the specific patterns that the agent must use for this part of the project. Claude Code reads these files automatically and prioritizes the instructions in the current directory tree.
When you start a session with the claude command, the agent looks for these files to understand the environment. If you update the brief mid-session, the agent will pick up the changes the next time it reads the directory. This is much more reliable than pasting a long brief into the chat prompt, as the chat history is subject to being summarized or removed when you use the /compact command. By keeping your brief in a markdown file within the repository, you ensure that the agent always has access to the core requirements without wasting space in the conversation history.
Scaling with Subagents and Custom Commands
For features that span multiple domains, such as a concurrent change to the database schema and the frontend API, you should use subagents. You can define a subagent by creating a markdown file in the .claude/agents directory. This file should describe the specific persona and the tools that the subagent is allowed to use. When you run the /agents command, you can see the available agents and delegate specific parts of the brief to them. This keeps the main session focused on the high-level orchestration while the subagent handles the granular details of a specific module.
You can also create custom slash commands by placing markdown files in .claude/commands. For example, if your feature requires a specific validation step that is not covered by your standard test suite, you can define a command that explains how to perform that validation. This allows you to quickly trigger complex logic without re-explaining it to the agent every time. These tools help maintain a clean context by moving repetitive or complex instructions out of the main chat flow and into structured configuration files that the agent can access on demand.
Controlling the Workflow with Permission Modes
Managing a complex brief requires careful control over what the agent can modify. By default, the agent will ask for permission before using tools like Edit or Write. For a large feature, you should use the plan mode. You can cycle through modes using Shift+Tab inside the session. In plan mode, the agent will describe the steps it intends to take and show you the logic it plans to implement without actually modifying any files. This is the best time to verify if the agent has correctly understood your brief before any code is written.
Once you are satisfied with the plan, you can switch to the acceptEdits mode to let the agent apply the changes. If you find that the agent is making too many small errors, you can go back to the default mode to review every tool call individually. You can also configure specific tool permissions in the .claude/settings.json file. For instance, you might want to allow the Read and Glob tools to run without intervention while requiring manual approval for any Bash command. This granular control ensures that the agent stays within the boundaries of your brief even during long-running tasks.
Monitoring Multi-Part Features via adhdTerminal
When a feature is particularly large, it is often more efficient to break it into several concurrent sessions. Running multiple claude sessions in a standard terminal can be chaotic as you lose track of which session is doing what. This is where adhdTerminal becomes a useful tool for the workflow. It allows you to run many Claude Code sessions side by side as tiles on a single wall. Each tile shows the last few exchanges of the conversation and a status indicator that tells you if the agent is currently working, waiting for your input, or has finished the task.
Using adhdTerminal, you can have one tile dedicated to the backend implementation while another tile focuses on the frontend components. Because the app preserves the state of each tile, you can restart your computer and find all your sessions exactly where you left them, already resumed and ready to continue. If you are away from your desk, the free iPhone app mirrors this wall, allowing you to check the progress of a long-running Task or provide a quick answer to a prompt. This visibility is essential when managing a complex brief that requires multiple parallel streams of work.
Using Hooks to Enforce Technical Standards
To ensure that the agent does not drift from your technical brief, you can use hook events defined in the .claude/settings.json file. For example, you can use the PostToolUse hook to run a linter or a type checker every time the agent finishes using the Edit tool. If the linter fails, the agent will see the output and can immediately correct the mistake. This creates a self-correcting feedback loop that keeps the code aligned with your standards without you having to manually intervene every time.
Other hooks like SessionStart and UserPromptSubmit can be used to inject specific reminders or to log the progress of the feature. If you want the agent to always check a specific documentation file before starting a task, you can use a hook to remind it of that requirement. These hooks provide a way to automate the oversight of the agent, ensuring that the constraints of your brief are enforced at the level of the execution environment rather than relying solely on the agent memory.
Managing Long Conversations with Compact and Clear
As the implementation of a complex feature progresses, the session history will grow. This can lead to confusion and increased latency. You should use the /compact command periodically. This command summarizes the session so far, preserving the key decisions and the current state of the project while freeing up space in the context window. It is particularly useful after a long debugging session or after completing a significant sub-task of the brief. The PreCompact hook can even be used to automate some of this cleanup before the summarization happens.
If the session becomes so cluttered that the agent is no longer performing well, do not be afraid to use the /clear command. This will wipe the conversation history but keep the agent in the same project folder. Since your architectural brief is stored in CLAUDE.md and your settings are in .claude/settings.json, the agent will quickly regain its bearings. You can then use the /resume command to pick up from a previous point if necessary, or simply start a new prompt to continue the next phase of the feature implementation.
Backtracking and History Management
Errors are inevitable during the development of a complex feature. If the agent makes a mistake that is hard to fix by simply providing more instructions, you can use the Escape key twice. This opens a list of earlier messages, allowing you to go back to a point before the error occurred. This is much more efficient than trying to debug a hallucination or a failed architectural choice. It effectively rewinds the state of the session, giving you a second chance to phrase your instructions or provide better context.
You can also use Ctrl+R in the terminal to search through your own shell history if you need to find a specific command or prompt you used earlier. If the agent is stuck in a loop or taking too long on a Task, a single press of the Escape key will interrupt the current operation. This allows you to regain control immediately and adjust the brief or the current task. Managing the history of the session is just as important as writing the initial brief, as it allows you to steer the agent back on track when the complexity of the feature begins to cause friction.
Finalizing and Validating the Feature Implementation
The final stage of a complex feature brief is validation. You should instruct the agent to use the /review command to look over the changes it has made. The agent will analyze the diffs and compare them against the requirements you set out in your CLAUDE.md files. This often catches edge cases or missing documentation that might have been overlooked during the implementation phase. You can also use the Bash tool to run the full test suite and the Read tool to verify that the final code structure matches the initial architectural plan.
Once the feature is complete and validated, you can use the /export command to save the session history for future reference. This is helpful for post-mortems or for refining your brief-writing process for the next feature. By following this structured approach, using persistent files for instructions, specialized subagents for task delegation, and hooks for automated oversight, you can successfully guide Claude Code through even the most complex architectural changes without losing the necessary context.
Questions people ask
What should I do if the agent starts ignoring the instructions in my CLAUDE.md file?
You should use the /compact command to refresh the context window and ensure the agent is not overwhelmed by recent chat history. If that fails, use the Read tool to explicitly ask the agent to re-read the CLAUDE.md file and summarize its understanding of the instructions. This forces the agent to prioritize those persistent constraints over the immediate conversation flow.
Can I use multiple subagents for a single feature brief?
Yes, you can define different subagents in the .claude/agents folder for specific tasks like testing, frontend, or database work. You can then use the /agents command to switch between them or delegate tasks to them within the main session. This helps keep the context for each task isolated and manageable.
How do I handle a brief that requires changes across multiple repositories?
The best way is to use the /add-dir command to include other repositories in the current session context. You can also manage separate Claude Code sessions for each repository and use adhdTerminal to view them side by side. This allows you to coordinate changes across projects while keeping each session focused on its respective file system.
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.