Doc-Driven Claude code workflow for large codebase - Here is how

Key Concepts

• Context Engineering: Optimizing the conversation history thread for large language models (LLMs) like Claude to include only relevant and necessary information, guiding the agent's next actions.
• Token Context Limit: The maximum number of tokens an LLM can process in a single conversation. Claude has a default limit of 200,000 tokens.
• Sub-agents: A feature allowing delegation of specific tasks to isolated agents with their own conversation threads, reducing token consumption in the main thread.
• Documentation System: A structured approach to create summarized snapshots of a codebase, providing agents with pre-digested, relevant information instead of requiring deep, real-time research.
• PRD (Product Requirements Document): Implementation plans generated by Claude for new features, stored as documentation.
• SOP (Standard Operating Procedure): Documented step-by-step processes or solutions to common agent mistakes, used for consistent execution and learning.
• .agent folder: A dedicated folder within a project to store all relevant documentation for the Claude agent.
• update doc command: A custom command used to initialize the documentation structure or update existing documentation based on new features or corrected mistakes.
• plan mode: A Claude feature used to generate detailed implementation plans before starting a coding task.
• compact command: A command to proactively clean up conversation threads after an agent completes isolated tasks, reducing context size.

---

Optimizing Claude's Performance Through Context Engineering

The video addresses the challenge of maintaining Claude's efficiency as a codebase grows in complexity, focusing on context engineering to prevent frustration and performance degradation. Context engineering involves optimizing the conversation history thread for Claude or CodeX agents, ensuring only relevant and necessary information guides the agent's actions.

Understanding and Optimizing the Context Window

Claude has a default 200,000 token context limit. The /contacts command in Claude provides a breakdown of token consumption across different categories. The overall context consists of several components:

• System Prompt, Assistant Tools: These are generally fixed and come with the agent.
• Agent-specific Tools (MCPs/Custom Agents): These can consume significant tokens even if unused. Removing unnecessary MCPs can immediately free up context. For example, removing unused MCPs can yield a 2% additional context token window.
• Memory File (cloud.md): This file can grow very large in complex projects, leaving little room for actual messages.
• Actual Message: This includes the user's message and the agent's tool call actions. The key is to ensure information in the history is relevant and noise is minimized.

Leveraging Sub-agents for Context Reduction

One effective method to reduce context is using sub-agents. When an agent is prompted for a complex task (e.g., "help me add a Google OAuth"), a significant portion of its actions might involve research (e.g., figuring out the implementation plan) rather than direct coding. These research steps consume many tokens in the main conversation thread.

• Process: Sub-agents allow delegating research-related token consumption to an isolated conversation thread. The sub-agent performs the research and returns only a summary to the main conversation thread.
• Benefit: This ensures only absolutely necessary information and tokens are included in the main context, significantly reducing noise.
• Actionable Insight: Before implementing a big feature, explicitly instruct Claude to "use task or sub-agent to do the research first" to trigger this behavior. The speaker also proactively uses the compact command after isolated tasks to clean up the conversation thread.

Building a Comprehensive Documentation System

The speaker emphasizes setting up a robust documentation system for the codebase, which is crucial as Claude is increasingly used for day-to-day operations beyond just coding. This system creates a summarized snapshot of the codebase, allowing the agent to quickly access relevant information without extensive real-time research.

Purpose and Benefits

• Reduced Noise: Less irrelevant information in the context window.
• Ensured Relevance: All critical information is explicitly fed into the context, rather than hoping the agent pulls it together.
• Scalability: Designed to remain useful as the codebase grows.

Speaker's Documentation Structure

The speaker typically uses a .agent folder containing the following sub-folders and files:

1. task folder: Stores PRDs (Product Requirements Documents). Before implementing any feature, the speaker uses plan mode to generate an implementation plan, which is then saved here. These serve as references for similar future implementations.
2. system folder: Contains overarching project information like project structure, database schema, APIs, or critical/complex parts of the codebase. This helps the agent gain an overall understanding and can grow significantly.
3. SOPs (Standard Operating Procedures) folder: Logs standard processes for specific tasks or common mistakes made by the agent. After an agent completes a task, it's asked to generate an SOP for that process (e.g., "adding a new database table," "integrating a new Replicate model").
4. readme file: Acts as an index for all documentation files, guiding the agent on when to read which document to get a quick overview.

The update doc Command

The speaker frequently uses a custom update doc command. This command includes instructions for the agent on how to:

• Initialize the documentation structure.
• Update documentation after implementing features or correcting mistakes.
• Create new documentation files with specific rules. This ensures continuous maintenance and updating of the documentation system.

Real-world Example: Simon from AI Builder Club

Simon from AI Builder Club showcased his team's documentation system for their Lexi codebase.

• Design: The documentation is human-readable but primarily designed for LLMs.
• Content: It covers migrations, data storage, helper classes, updaters, utilities, etc., split into well-documented sections.
• Generation Workflow: Initial versions were generated by Claude. They use a workflow where:
  1. Claude is prompted to review a class and upgrade its inline documentation.
  2. A separate prompt is used to generate more detailed class documentation from the inline docs, outputting it into the larger documentation system.
• Benefit: This workflow makes the entire documentation process easier to manage by exposing all relevant information.

Practical Demonstration of the Documentation System

The speaker demonstrates setting up and using the system:

1. Initial Setup:
   • Create a cloud.md file with a "docs" section explaining the desired doc structure and rules (e.g., always update .agent folder docs after features, read readme first for context).
   • Create a doc_cloud_folder_commands_update_doc.md file containing a simple prompt that tells the agent about the doc structure, initialization, update procedures, and rules for new doc files.
   • Run /update doc initialize. This command scans the project, sets up the .agent folder, creates a project_architecture.md as the first doc, and generates a readme.md listing all docs.
2. Building a Text-to-Image App:
   • Prompt Claude to build a text-to-image app using a Replicate model, using plan mode.
   • After planning, prompt Claude to "save implementation plan in a .agent/task folder and start implementation."
3. Generating an SOP for Integration:
   • If the model integration fails (a common experience), prompt Claude with /update doc generate SOP integrating replicate model.
   • This creates an replicate_model_integration_SOP.md document detailing step-by-step integration, directory structure, and related documentation.
   • The readme.md is also updated to include this new SOP.
4. Leveraging Documentation for New Tasks:
   • Clear the conversation context.
   • Prompt Claude to add text-to-video capability using a different model, explicitly instructing it to "read .agent doc first for context" and use plan mode.
   • Claude reads the existing documentation (including the newly generated SOP) to get the full picture.
   • The implementation plan is saved, and Claude successfully implements the feature in one shot without errors.

Data and Research Findings

The video mentions a research report titled "AI agents unleashed: a pragmatic report." This report explores how people are using Claude for various day-to-day operational tasks (emails, system automation, journaling) beyond just coding. It dives into real-world examples, interviewing hundreds of people from top startups and enterprises across marketing, sales, and operations, highlighting common pitfalls and challenges. The report proposes a framework for identifying tasks and use cases that can drive significant business value.

---

Conclusion

Effectively managing Claude's context window is paramount for its performance and usability, especially with complex codebases. This can be achieved through a multi-faceted approach:

1. Basic Context Engineering: Proactively removing unused tools and being mindful of the cloud.md file size.
2. Strategic Use of Sub-agents: Delegating research and isolated tasks to separate threads to keep the main conversation focused and lean.
3. Robust Documentation System: Implementing a structured system (like the .agent folder with task, system, SOPs, and readme files) allows Claude to access pre-digested, relevant information, significantly reducing the need for extensive real-time context searching. Custom commands like update doc facilitate continuous maintenance and evolution of this documentation.

By adopting these strategies, users can achieve more consistent and reliable performance from Claude, enabling it to handle increasingly complex tasks with higher confidence and fewer errors. The "AI agents unleashed" report further underscores the growing utility of LLM agents in diverse operational roles, making context management even more critical for productionizing these applications.