By admin on
Article Type
tutorial
Video url
https://www.youtube.com/watch?v=MW3t6jP9AOs

Tutorial: .agent folder is making claude code 10x better...

What You'll Learn

  • Viewers will learn how to optimize Claude Code's performance using context engineering techniques.
  • Viewers will understand how to set up and leverage a comprehensive documentation system for their codebase.
  • Viewers will gain strategies for reducing token consumption and improving agent accuracy.
  • Viewers will be able to apply sub-agent and documentation strategies in their own projects.
  • Viewers will be able to manage larger and more complex codebases with Claude Code more effectively.

In this tutorial, we will explore advanced strategies for optimizing Claude Code's performance through context engineering. This article details how to leverage the .agent folder structure to significantly enhance your AI agent's capabilities. We will cover methods to reduce token consumption, improve agent accuracy, and effectively manage larger codebases. You will learn to implement a comprehensive documentation system and apply sub-agent strategies to streamline your development process.

Step 1: Context Engineering Optimization

Context Engineering Optimization

Context engineering optimizes the information in a conversation history thread to guide an agent's next actions. Claude Code has a 200,000 token context limit.

  1. Run /contexts in Claude Code to view a breakdown of token consumption.

To optimize context:

  • Identify and remove any unnecessary MCPS (Multi-Context-Prompts) from the agent if they are consuming tokens.
  • Ensure that all information in the conversation history is relevant and reduces noise.
  • Utilize sub-agents to reduce context by delegating research to an isolated conversation thread. This returns only a summary of the research to the main conversation thread.
    • Before implementing a large feature, add a small text prompt to use a task or sub-agent for research first.
  • Use the compact command proactively to clean up the conversation thread after an agent completes a set of isolated tasks.
  • Set up a documentation system for your codebase.
    • Create a .agent folder to contain relevant information.
      • Task Folder: Store PRDs (Product Requirements Documents). When plan mode is used to generate an implementation plan, save it to the task folder.
      • System Folder: Store project structure, database schema, APIs, and critical or complex code parts.
      • SOPs (Standard Operating Procedures): Log standard processes or mistakes the agent makes. After the agent performs a task, ask it to generate an SOP for that specific process.
      • Readme File: This acts as an index for all documentation files, guiding the agent on which file to read and when.
    • Use the update doc command:
      • It includes instructions for the agent on how to initialize the documentation structure and update documentation.
      • Run this command after implementing features or correcting agent mistakes.
    • Example setup for a new project:
      1. Create a claude.md file.
      2. Add a section for docs explaining the desired documentation structure.
      3. Include rules that the agent folder docs are always updated after implementing features and that the readme is read first before planning any implementation to get the full context.
      4. Create a doc claude folder commands update doc.MD file. This is a simple prompt that tells the agent about the doc structure, what to do when initializing docs, what to do when asked to update docs, and specific rules for creating new doc files.
      5. Run /update doc initialize. This will set up the .agent folder structure and create a project architecture document as the first doc. A readme file will also be created under the .agent folder, listing all existing docs.
    • Example usage:
      1. Copy a doc and give the prompt: "How we build a text to image app using model above".
      2. Use plan mode.
      3. After the plan is finished, prompt to "save implementation plan in a do agent/task folder and start implementation".
      4. If the model fails, use the update doc command, e.g., "generate SOP integrating replicate model". This will create an SOP explaining the integration process, directory structure, and related documentation. It will also update the readme.
      5. To add a new capability, clear the conversation and give a prompt like: "help me add text to video capability using model above plan implementation and read do agent doc first for context". Use plan mode.
      6. Save the implementation plan to the /task folder and start implementing.
    • To apply to an existing codebase, ask Claude Code to generate system architecture documentation, including text project architecture, database schema, API endpoints, and more.

Step 2: Documentation System for Cloud Code

Documentation System for Cloud Code

The purpose of creating a documentation system is to generate summarized snapshots of your codebase. This allows the agent to read summarized documentation instead of performing deep research across the entire codebase. This approach reduces noise in the context window and ensures that relevant information is fed into the context, especially as your codebase grows larger.

The common structure for a documentation system is composed of the following folders and files:

.agent Folder Structure

This folder contains all relevant and useful information.

  1. task Folder:

    • This is where Product Requirement Documents (PRDs) are stored.
    • To create a PRD, turn on plan mode before implementing any feature and ask the agent to generate an implementation plan.
    • After the implementation plan is generated, store it in the task folder. This allows you to link to these implementation documents as a reference for similar future implementations.

  2. system Folder:

    • This folder contains information such as project structure, database schema, APIs, or other critical and complex parts of your codebase.
    • These items can span across different individual PRDs and are useful for the agent to gain an overall understanding. This is also the part that can grow significantly.

  3. SOPs (Standard Operating Procedures) Folder:

    • This is where standard processes for performing certain tasks or mistakes made by the agent are logged.
    • After an agent completes a task, ask it to generate an SOP for that specific process.
    • SOPs can be generic, such as "adding a new database table," or more granular, such as "how to integrate a new replicate model."

  4. README File:

    • As your codebase becomes more complicated, there will be many documentation files.
    • The README file acts as an index of all documentation files, indicating when to read which documentation. This helps the agent quickly get an overview of all relevant documentation and read injection history.

Setting Up Your Documentation System

Perform the following steps to set up your documentation system in a new project:

  1. Create cloud.md file:

    • Add a section specifically explaining the documentation structure you want the agent to follow.
    • Include rules such as "always update agent folder docs after implementing certain features" and "before planning any implementation, always read the README first to get the full context."

  2. Create doc_cloud_folder_commands_update_doc.MD:

    • This file contains a simple prompt that specifically tells the agent about the documentation structure.
    • It also defines what to do when initializing the documentation and what to do when asked to update the documentation, along with specific rules for creating new documentation files.

Updating Documentation

To continuously update your documentation, follow these steps:

  1. Initialize the documentation structure:
    • Run the command: /update doc initialize
    • This command will scan your current project and set up the .agent folder structure.
    • Upon completion, you will see the .agent folder created, with project_architecture as the first document.
    • A README file will also be present under the .agent folder, listing all current documents.

Example Workflow

Consider the following example:

  1. Building a text-to-image app:

    • Provide a prompt like: "How do we build a text-to-image app using the model above?"
    • Use plan mode.
    • After the plan is complete, prompt to save the implementation plan in the .agent/task folder and then begin implementation.

  2. Generating an SOP for model integration:

    • If a model fails to integrate, use the update doc command to generate an SOP.
    • For example: generate SOP integrating replicate model.
    • This will create a replicated_model_integration_SOP document.
    • This document will explain the step-by-step integration process, the directory structure to follow, and a section for related documentation.
    • The README will also be updated to include this new SOP.

  3. Adding new capabilities with existing context:

    • Clear the conversation if needed.
    • Provide a prompt, for example, for adding text-to-video capability: "help me add text-to-video capability using model above plan implementation and read .agent doc first for context."
    • Use plan mode.
    • The agent will read through different files to get the full picture.
    • Save the implementation plan to the /task folder and start implementation.

This approach allows for consistent performance and confidence when implementing new features, by leveraging a well-structured and continuously updated documentation system. You can apply the same process to your existing codebase by asking Cloud Code to generate system architecture documentation, including project architecture, database schema, and API endpoints.

Key Concepts

  • Context Engineering
  • Token Consumption
  • Sub-agents
  • /compact Command
  • .agent folder structure (task, system, SOPs, readme)
  • PRDs (Product Requirement Documents)
  • SOPs (Standard Operating Procedures)
  • update doc Command
  • AI Agents Unleashed Report

Conclusion

This tutorial guided you through optimizing Claude Code by implementing context engineering techniques and a robust documentation system. We covered strategies for token consumption reduction, improving agent accuracy, and leveraging sub-agents within the .agent folder structure. By applying these methods, you can manage complex codebases more effectively and enhance your project's overall performance.