RAPIDS - Ship Fast, Make Money

Token Optimization

Save 60-80% on token usage with the .agent/ documentation system. Read concise docs instead of full source code.

🎯 Core Principles

1. Lazy Loading

Only read files when absolutely necessary

2. Parallel Execution

Run independent tasks concurrently

3. Subagent Efficiency

Use subagents for isolated, complex tasks

4. Smart Context

Minimize context pollution with .agent/ docs

📁 The .agent/ Documentation System

Structure your project knowledge for AI consumption:

.agent/
├── readme.md              # Documentation index (read this first!)
├── task/                  # Implementation plans & PRDs
│   ├── template-feature-plan.md
│   └── archive/          # Completed plans
├── system/               # Architecture documentation
│   ├── architecture-overview.md
│   ├── database-schema.md
│   ├── api-endpoints.md
│   ├── critical-paths.md
│   └── stack-decisions.md
└── sop/                  # Standard Operating Procedures
    └── template-sop.md

🔄 Optimization Workflow

1. Before Implementing

/update-doc plan <feature-name>

Create structured plan instead of reading entire codebase

2. During Implementation

Read only relevant .agent/ docs (not entire codebase)
• .agent/system/architecture-overview.md
• .agent/system/database-schema.md
• .agent/system/api-endpoints.md

3. After Implementation

/update-doc system

Update docs if architecture changed

4. When Fixing Issues

/update-doc sop <issue-description>

Create Standard Operating Procedure for future reference

5. Context Switching

Clear thread, rely on .agent/ docs for context (no need to re-read codebase)

💰 Token Savings Example

Before RAPIDS (Traditional Approach)

You: "Add user authentication"
Claude: *reads entire codebase* (50,000 tokens)

After RAPIDS (Optimized Approach)

You: "Add user authentication"
Claude: *reads .agent/system/architecture-overview.md* (2,000 tokens)
Claude: *reads .agent/system/database-schema.md* (1,000 tokens)
Claude: *reads .agent/task/auth-plan.md* (500 tokens)

Token Savings: 93% (50K → 3.5K tokens)

🛠️ Available Commands

/update-doc initialize

Set up .agent/ folder structure

/update-doc plan <feature-name>

Create feature implementation plan

/update-doc system

Update architecture, DB, API docs

/update-doc sop <description>

Create Standard Operating Procedure

/update-doc index

Refresh documentation index

/update-doc archive <plan>

Move completed plan to archive

✨ Key Benefits

60-80% Token Savings

Massive reduction vs full codebase reads

Faster Context Loading

Read only what's needed for the task

Scalable

Grows with project without bloating context

🤖

Sub-Agent Isolation

Research tasks in separate threads, return summaries only

🏆 Best Practices

✅ Always check .agent/readme.md first before reading any source files

✅ Use sub-agents for token-heavy research (returns summaries only)

✅ Read files only when .agent/ docs are missing specific details

✅ Use Grep/Glob for searching instead of reading multiple files

✅ After major changes, run /update-doc system to keep docs fresh

✅ Clear conversation thread when switching features (rely on .agent/ docs)

📚 Next Steps

→ Learn about AI Agents

→ Use Stack Templates

→ Migrate Existing Project