Skip to content

CLAUDE_MD_OPTIMIZATION_PLAN.md

Latest commit

 

History

History
292 lines (216 loc) · 9.23 KB

CLAUDE_MD_OPTIMIZATION_PLAN.md

File metadata and controls

292 lines (216 loc) · 9.23 KB
Raw

CLAUDE.md Optimization Plan

Goal: Reduce token usage by 30% while preserving ALL instructions and restrictions

🎯 Optimization Strategy

Move detailed implementation guides to docs, keep mandatory rules in CLAUDE.md

  • ✅ ALL restrictions preserved - Zero information loss
  • ✅ ALL mandatory rules stay in CLAUDE.md - Immediately visible
  • ✅ Detailed guides moved to docs - Referenced with links
  • ✅ 30% token reduction - From 685 lines to ~476 lines

📋 Section-by-Section Plan

1. Hardcoding Prevention (Lines 81-152) - 72 lines → 8 lines

STAYS in CLAUDE.md:

## 🚫 HARDCODING PREVENTION (AUTOMATED ENFORCEMENT)

**⚠️ MANDATORY RULE: NO HARDCODED VALUES**

**What constitutes hardcoding:**
- IP addresses (use `NetworkConstants` or `.env`)
- Port numbers (use `NetworkConstants` or `.env`)
- LLM model names (use `config.get_default_llm_model()`)
- API keys, passwords, secrets (use environment variables)

👉 **Full guide**: [`docs/developer/HARDCODING_PREVENTION.md`](docs/developer/HARDCODING_PREVENTION.md)

MOVES to docs/developer/HARDCODING_PREVENTION.md:

  • Automated detection scripts
  • Pre-commit hook details
  • Code examples (BAD vs GOOD)
  • How to fix violations (3 detailed examples)
  • Override procedures
  • Script locations

Restrictions preserved: ✅ MANDATORY RULE stays visible

2. Redis Client Usage (Lines 155-238) - 84 lines → 10 lines

STAYS in CLAUDE.md:

## 🔴 REDIS CLIENT USAGE (MANDATORY PATTERN)

**⚠️ MANDATORY RULE: ALWAYS USE CANONICAL REDIS UTILITY**

**Canonical pattern**: `src/utils/redis_client.py::get_redis_client()`

```python
# ✅ CORRECT
from src.utils.redis_client import get_redis_client
redis_client = get_redis_client(async_client=False, database="main")

# ❌ FORBIDDEN - Direct instantiation
import redis
client = redis.Redis(host="...", port=...)

👉 Full guide: docs/developer/REDIS_CLIENT_USAGE.md


**MOVES to** `docs/developer/REDIS_CLIENT_USAGE.md`:
- Detailed code examples
- Database separation patterns
- Backend infrastructure details
- Deprecated utilities table
- Migration status tracking
- When refactoring Redis code checklist

**Restrictions preserved**: ✅ MANDATORY RULE + forbidden patterns stay visible

---

### 3. Infrastructure & Deployment (Lines 410-448) - 39 lines → 10 lines

**STAYS in CLAUDE.md**:
```markdown
## 🚀 INFRASTRUCTURE & DEPLOYMENT

**SSH Keys**: `~/.ssh/autobot_key` (configured for all 5 VMs)

**Sync files to VMs**:
```bash
./scripts/utilities/sync-to-vm.sh <vm> <local-path> <remote-path>

🚨 MANDATORY: Local-Only Development

  • ❌ NEVER edit code on remote VMs (-25)
  • ✅ Edit locally in /opt/autobot
  • ✅ Sync immediately using sync scripts

Why: VMs are ephemeral - remote edits = PERMANENT WORK LOSS

👉 Full guide: docs/developer/INFRASTRUCTURE_DEPLOYMENT.md


**MOVES to** `docs/developer/INFRASTRUCTURE_DEPLOYMENT.md`:
- Detailed sync examples (multiple files)
- Network configuration details
- Service binding rules
- VM IP address reference

**Restrictions preserved**: ✅ MANDATORY local-only rule stays visible with rationale

---

### 4. Subtask Execution (Lines 315-381) - 67 lines → 35 lines

**STAYS in CLAUDE.md** (condensed):
```markdown
## 🔄 SUBTASK EXECUTION (MANDATORY)

**⚠️ MANDATORY RULE: EVERY TASK MUST BE EXECUTED AS SUBTASKS**

### The Subtask Principle
- **All tasks MUST be broken down** into smaller, atomic subtasks
- **Execute ONE subtask at a time** - Complete fully before moving to next
- **Track each subtask** in TodoWrite with clear status
- **Never execute monolithic tasks** - Always decompose first

### Workflow
1. **Receive Task** - Understand the overall goal
2. **Break Down** - Decompose into 3-10 smaller subtasks
3. **Create TodoWrite** - List all subtasks with clear descriptions
4. **Execute Sequentially** - Complete one subtask fully before next
5. **Mark Progress** - Update TodoWrite after each subtask completion
6. **Verify Completion** - Ensure each subtask is truly done

### Subtask Guidelines
Each subtask should be:
- **Atomic** - Single, well-defined action
- **Testable** - Clear success criteria
- **Independent** - Can be executed without waiting on other tasks
- **Trackable** - Can mark as in_progress/completed in TodoWrite

**Even "simple" tasks need 2-3 subtasks minimum** (research, implement, test, review)

**THIS POLICY ENSURES QUALITY, TRACKING, AND PREVENTS SKIPPED STEPS - NO EXCEPTIONS**

REMOVED from CLAUDE.md (redundant examples):

  • Verbose good/bad task breakdown examples
  • Detailed 7-step execution workflow diagram
  • "When Tasks Seem Simple" section (condensed into one line)

Restrictions preserved: ✅ MANDATORY RULE + workflow steps stay, just more concise

5. Architecture Notes (Lines 451-472) - 22 lines → 12 lines

STAYS in CLAUDE.md (condensed):

## Architecture Notes

### Service Layout - Distributed VM Infrastructure

| Service | IP:Port | Purpose |
|---------|---------|---------|
| **Main Machine (WSL)** | <backend-ip>:8443 | Backend API + VNC Desktop (6080) |
| **VM1 Frontend** | <frontend-ip>:5173 | Web interface (SINGLE FRONTEND) |
| **VM2 NPU Worker** | <npu-ip>:8081 | Hardware AI acceleration |
| **VM3 Redis** | <database-ip>:6379 | Data layer |
| **VM4 AI Stack** | <aiml-ip>:8080 | AI processing |
| **VM5 Browser** | <browser-ip>:3000 | Web automation (Playwright) |

REMOVED from CLAUDE.md (redundant):

  • "Key Files" list (already documented in other sections)
  • Bullet point format infrastructure overview (replaced with table)

Restrictions preserved: ✅ All VM info preserved, just more compact

📊 Token Savings Summary

Section Before After Saved Status
Hardcoding Prevention 72 lines 8 lines 64 lines Move to docs
Redis Client Usage 84 lines 10 lines 74 lines Move to docs
Infrastructure Details 39 lines 10 lines 29 lines Move to docs
Subtask Execution 67 lines 35 lines 32 lines Condense
Architecture Notes 22 lines 12 lines 10 lines Condense
TOTAL REDUCTION 284 lines 75 lines 209 lines 30% savings

New CLAUDE.md size: 476 lines (~3,800 tokens vs current ~5,500) Token savings: ~1,700 tokens per conversation (~31% reduction)

✅ Verification Checklist

All restrictions preserved:

  • NO TEMPORARY FIXES POLICY - Complete section stays
  • Hardcoding prevention MANDATORY RULE - Stays with link to guide
  • Redis client MANDATORY RULE - Stays with forbidden patterns
  • Local-only development MANDATORY - Stays with rationale
  • Subtask execution MANDATORY - Stays, just condensed
  • Single frontend server restriction - Complete section stays
  • Workflow requirements - Complete section stays
  • All agent delegation rules - Complete section stays
  • All critical policies table - Complete section stays

All instructions preserved:

  • TodoWrite workflow - Complete section stays
  • Memory MCP integration - Complete section stays
  • Agent delegation patterns - Complete section stays
  • Code review requirements - Complete section stays
  • Development guidelines - Complete section stays
  • Quick reference checklist - Complete section stays

Zero information loss:

  • Detailed guides moved to docs, not deleted
  • All code examples preserved in docs
  • All troubleshooting info preserved in docs
  • All links functional and correct

📁 New Documentation Files

To be created:

  1. docs/developer/HARDCODING_PREVENTION.md

    • Pre-commit hook setup
    • Detection script usage
    • Fix patterns for IPs/ports/models
    • Override procedures
    • Exception file format

  2. docs/developer/REDIS_CLIENT_USAGE.md

    • Canonical pattern examples
    • Database separation guide
    • Migration tracking
    • Deprecated utilities reference
    • Backend infrastructure details

  3. docs/developer/INFRASTRUCTURE_DEPLOYMENT.md

    • SSH key setup
    • Sync script detailed usage
    • Network configuration
    • Service binding rules
    • VM management

🚀 Implementation Plan

  1. Create new documentation files (3 files)
  2. Move content from CLAUDE.md to docs (preserve formatting)
  3. Update CLAUDE.md with condensed sections (add doc links)
  4. Verify all links work
  5. Test that all restrictions are still visible
  6. Commit changes with detailed message

Estimated time: 15-20 minutes Risk level: Low (all content preserved, just reorganized) User approval required: Yes (before implementation)

🎯 Expected Outcome

Before:

  • CLAUDE.md: 685 lines, ~5,500 tokens
  • Loaded every conversation
  • Detailed implementation guides inline

After:

  • CLAUDE.md: 476 lines, ~3,800 tokens (30% reduction)
  • All mandatory rules immediately visible
  • Detailed guides in docs (loaded only when needed)
  • 100% information preserved
  • Zero restrictions lost

Benefits:

  • ✅ Lower token costs per conversation
  • ✅ Faster context loading
  • ✅ Better organized documentation
  • ✅ All rules still immediately visible
  • ✅ More budget for actual work