I was using sub-agents wrong... Here is my way after 20+ hrs test

Key Concepts

• Sub-agents: Specialized agents within the Cloud Code environment designed to handle specific tasks, primarily research and planning.
• Context Engineering/Optimization: The primary goal of sub-agents is to reduce token consumption and improve performance by managing and summarizing context effectively.
• Parent Agent: The main Cloud Code agent responsible for orchestrating tasks and delegating work to sub-agents.
• MCP (Meta-Command Palette) Tool: Custom tools designed for specific services (e.g., Chassen) to retrieve relevant information and code examples.
• Context File: A Markdown file (.md) used to store project context, implementation plans, and research reports, facilitating information sharing between agents.
• Token Consumption: The number of tokens used by the language model, which impacts performance and cost.
• System Prompt: The initial instructions and knowledge provided to an agent, guiding its behavior and capabilities.

Sub-Agent Design and Best Practices

The Initial Problem: Token Consumption and Performance

• Cloud Code agents use a tool called "agent" equipped with tools like "read file" and "edit files."
• The "read file" tool can consume a lot of tokens by including the entire file content in the conversation history.
• Before sub-agents, the main Cloud Code agent handled everything, potentially using 80% of the context window before implementation.
• This often triggered "compact conversation," which summarizes the conversation and degrades performance by losing context.

The Solution: Sub-Agents for Context Optimization

• Cloud Code introduced "task tool" to delegate tasks to sub-agents.
• Sub-agents have the same tools as the main agent (read file, search file).
• Sub-agents scan the codebase to understand relevant files and create implementation plans.
• The parent agent only sees a summary of the sub-agent's research report, not the detailed actions, saving tokens.
• This turns massive token consumption from "read file" actions into a few hundred token summary.

The Pitfalls: Sub-Agents for Implementation

• The initial idea of using sub-agents for direct implementation (e.g., front-end dev agent, back-end dev agent) proved problematic.
• If a sub-agent's implementation is not 100% correct, fixing it becomes difficult.
• Each sub-agent has limited information about the overall project and other sub-agents' actions.
• The parent agent only sees task assignments and completion summaries, not the specific file changes.
• Debugging becomes challenging because the parent agent lacks detailed context about the sub-agent's work.

The Best Practice: Sub-Agents as Researchers

• Consider sub-agents as researchers who create planning and research steps to improve the AI coding workflow.
• Adam Wolf (Cloud Code engineer) suggests sub-agents work best when looking for information and providing a small summary back to the main conversation.

Expert Sub-Agents for Service Providers

• Create specialized sub-agents for each service provider (e.g., Vercel AI SDK, Supabase, Tailwind).
• These agents are equipped with the latest documentation, best practices, and design knowledge.
• They analyze the codebase and create implementation plans.
• Example: A Vercel AI SDK expert loaded with the latest Vercel AI SDK v5 documentation.
• Example: A Stripe expert loaded with the latest Stripe documentation and tools like Context 7 for usage-based pricing.

Context Sharing and Management

File System as Ultimate Context Management System

• Inspired by Manus's approach to long-running tasks, use the file system for context management.
• Instead of storing tool results directly in the conversation history, save them to local files.
• Example: Save web scraping content to a local MD file instead of including the entire script in the conversation.

Implementation: docloud Folder Structure

• Create a docloud folder with a task subfolder containing context for each feature.
• The parent agent creates a context file with project information.
• Sub-agents read the context file before starting work to understand the project plan.
• Sub-agents update the context file with core steps and save research reports to MD files in the doc folder.
• The parent agent and other sub-agents can read these files for more context.

Workflow

1. Parent agent creates a context file in docloud/task/.
2. Parent agent assigns a task to a sub-agent, passing the context file name.
3. Sub-agent reads the context file.
4. Sub-agent performs research and creates an implementation plan.
5. Sub-agent saves the research report to an MD file in docloud/doc/.
6. Sub-agent updates the context file with the steps taken.
7. Parent agent reads the research report and implementation plan.
8. Parent agent executes the implementation steps.
9. Parent agent updates the context file with the completed tasks.

Building Sub-Agents: Practical Steps

General Rules

• Include important documentation directly in the system prompt.
• Provide tools for retrieving relevant context (e.g., MCP tools).

Chassen Expert Example

• MCP tools:
  • chassen component MCP: Retrieves components, example code, and relevant blocks.
  • chassen sync tool: Retrieves well-designed scenes for reference.
• Open terminal to code.claw.json to configure global settings and MCP server.
• Open terminal and then do code doc claw to configure personal settings for Cloud Code.
• Create a new agent (project-specific or personal-level).
• Generate a title, description, and system prompt based on a quick explanation.
• Paste documentation into the system prompt and attach special MCP tools and rules.

System Prompt Structure

• Goal: Design and propose a detailed implementation plan, but never do the actual implementation. Save the design file to docloud/doc/.
• Output Format: Instruct the agent to output a message like "I've created plan as this file, please read that first before you proceed."
• Rules:
  • Always look at the context file first.
  • Update the context file after finishing work.
  • Prevent the sub-agent from running cloud MCP client to call itself.

Vercel AI SDK Expert Example

• Same structure as the Chassen expert.
• Include detailed documentation about the latest Vercel AI SDK v5.
• Include a migration guide to highlight the differences between versions 4.0 and 5.0.

Demonstration: Building a ChatGPT Replica

Steps

1. Set up a Next.js project with Chassen.
2. cd my-app and claw to set up the initial project.
3. init to initialize the codebase and create a base Cloud Code rule.
4. Create a cloud.md file with rules for sub-agents.
   • Keep the project plan in doc/task/context_session.md.
   • Update the MD file after finishing work.
   • Delegate tasks to Chassen and Vercel AI SDK sub-agents.
   • Pass the MD file name to sub-agents.
   • Sub-agents must read the documentation before executing tasks.
5. Prompt: "Help me build a replica of ChatGPT using Chassen as front end and Vercel as SDKs AI service. Let's firstly build the UI making sure we consult sub agent."
6. The parent agent creates a context session MD file.
7. The parent agent triggers the Chassen agent with the context file and specific tasks.
8. The Chassen agent reads the context file and runs the chassen components MCP tool.
9. The Chassen agent creates a doc file with the UI design, layout, and components.
10. The parent agent reads the plan and breaks down the implementation.
11. The parent agent finishes the implementation and updates the context session file.
12. Run the application.
13. Fix any errors by pasting them into the parent agent.
14. Ask the parent agent to connect to the Vercel SDK, consulting the sub-agent.
15. The Vercel AI SDK agent reads the context file and looks through the codebase.
16. The Vercel AI SDK agent creates a doc file with the implementation plan and updates the context session MD file.
17. The parent agent reads the implementation plan and implements the steps.
18. The parent agent updates the context file.

Results

• The UI is high fidelity and almost identical to the first version of ChatGPT.
• The application connects to the large language model and returns results in one shot.

Conclusion

The key to effectively using sub-agents in Cloud Code is to treat them as specialized researchers and planners. By focusing on context optimization and leveraging a file-based context management system, developers can significantly improve the performance and success rate of their AI coding workflows. The demonstration of building a ChatGPT replica highlights the power of this approach, showcasing how specialized sub-agents can contribute to complex projects.