# Doc-Driven Claude code workflow for large codebase - Here is how Source: https://www.youtube.com/watch?v=MW3t6jP9AOs Recap page: https://rapidrecap.app/video/MW3t6jP9AOs Generated: 2025-10-06T10:32:21.3+00:00 --- ## Quick Overview The video demonstrates a doc-driven workflow for Claude Code agents by establishing a structured `.agent` folder containing documentation files like `CLAUDE.md`, `project_architecture.md`, and task-specific SOPs, which the agent uses to maintain context, generate implementation plans, and ensure consistent project documentation across the team. **Key Points:** - The main outcome is a structured documentation system within a `.agent` folder to support Claude Code agents in maintaining context across large codebases. - The `.agent` folder structure includes specific files: `CLAUDE.md` (general instructions), `project_architecture.md` (system overview), and task-specific SOPs (Standard Operating Procedures). - The agent uses the `/update-doc` command to initialize or update this documentation structure, ensuring it reflects the current state of the codebase. - When planning implementation (e.g., adding Google Auth or a new model integration), the agent first reads the `.agent/README.md` to gain full context. - The documentation structure is designed to be easily scannable, linking related documents (like PRDs and SOPs) to provide clear navigation for engineers and the AI agent. - The presenter showed using the documentation to generate an SOP for integrating a new model (Replicate) and demonstrated the agent successfully reading and updating relevant documentation files based on prompts. ![Screenshot at 00:06: The VS Code terminal shows the agent running commands and outputting context usage statistics, illustrating the agent actively processing information within the development environment.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-00-06.png) **Context:** The video presents a sophisticated workflow for managing complexity in AI agent development, specifically utilizing Claude Code as an agent capable of reading, writing, and executing code. The core concept revolves around 'Context Engineering' and establishing a robust, self-maintaining documentation system within a dedicated `.agent` directory to keep the agent's context fresh and comprehensive, especially when dealing with large or evolving codebases. ## Detailed Analysis The presenter details a doc-driven workflow designed to scale AI agent operations on large codebases, using Claude Code to manage its own documentation. This system relies on a dedicated `.agent` folder containing critical information structured into specific Markdown files: `CLAUDE.md` for general instructions, `project_architecture.md` for system structure, and task-specific SOPs for processes and mistakes. The workflow begins by running `/update-doc init` to perform an initial deep scan and generate this structure. The agent is then instructed to use this documentation (e.g., reading the main `README.md` and related files like `project_architecture.md` and SOPs) before planning any implementation, such as adding Google Auth or integrating a new model like Google's Veo-3-Fast. The presenter demonstrated that when prompted to implement a new feature, the agent first consults the documentation, creates a plan in the `.agent/tasks` folder, and then executes the steps, updating the documentation along the way to maintain accuracy. This ensures the agent always operates with the most up-to-date, relevant context, minimizing errors and improving consistency across all development tasks. ### Context Engineering & Agent Capabilities - Claude Code is used as an agent, not just for coding, handling tasks like memory storage, sending texts, and updating to-dos; Context Engineering optimizes what goes into the conversation history to reduce noise. ### Doc System Structure - The `.agent` folder contains documentation: `CLAUDE.md` (general context), `project_architecture.md` (system structure, database, APIs), `Tasks` (PRDs), and `README.md` (index/navigation hub). ### Documentation Commands - The `/update-doc init` command scans the codebase to create the initial documentation structure; `/update-doc generate SOP integrating replicate model` shows the agent creating specific process documentation. ### System Documentation & Readme - The `README.md` acts as the documentation index, detailing system structure, tasks, SOPs, and providing a quick start guide, which is updated whenever new documentation is created. ### Real-World Example (Text-to-Video) - The presenter demonstrated using the system to build a text-to-video app using Google's Veo-3-Fast model via HTTP API calls, proving the system's ability to handle complex external integrations. ### Continuous Improvement - The agent is instructed to always update `.agent` docs after implementing features and to include relevant documents in the 'Related Doc' section when creating new files to maintain context. ![Screenshot at 00:03: A view of the VS Code environment where the speaker is navigating the project file structure, showing the context setup including the .agent folder.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-00-03.png) ![Screenshot at 00:10: The speaker draws the main concepts on a whiteboard: Context Engineering Optimisation, listing Sub Agent, .agent docs, and Retrieval MCPs as key areas for improvement.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-00-10.png) ![Screenshot at 00:16: A whiteboard diagram illustrating the structure of the Claude code context window, showing elements like System Instruction, System Tools, CLAUDE.md, MCP, User Message, and function calls \(Is\(\), Read\(\), Edit\(\)\).](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-00-16.png) ![Screenshot at 00:34: The terminal shows the output of the /context command, detailing the token usage breakdown across System Prompt, Tools, MCP Tools, Custom Agents, Memory Files, Messages, and Free Space.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-00-34.png) ![Screenshot at 01:15: A flowchart illustrating the agent's reasoning process: User Message triggers a Task, which leads to a Subagent Message \(Summary\), which in turn triggers a Research step on the right side.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-01-15.png) ![Screenshot at 02:27: The speaker highlights the importance of using the /compact command to summarize key actions taken, helping to clean up the conversation history.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-02-27.png) ![Screenshot at 03:33: A decision tree titled 'Is This an Agent Job?' framework used to determine if a task is suitable for agent automation, outlining paths for LLM prompt use, supervision needs, or ideal automation.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-03-33.png) ![Screenshot at 03:49: The presentation shifts to a Hubspot Media partnership slide, showing an advertisement for an 'AI Agents Unleashed: Playbook for 2025 Success' report.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-03-49.png) ![Screenshot at 03:54: A visual representation of the .agent documentation structure, showing how SOP, System, Tasks, and README.md map to specific documentation types \(process/mistakes, structure, PRD, index\).](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-03-54.png) ![Screenshot at 05:53: The agent executes the /update-doc command to create an SOP on integrating the Replicate model, demonstrating the system's ability to generate documentation based on existing code context.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-05-53.png) ![Screenshot at 08:25: A slide summarizing the evolved working documentation structure shared with the team, listing key files within the .agent/docs directory, such as schema and technical spec files.](https://ss.rapidrecap.app/screens/MW3t6jP9AOs/00-08-25.png)