From 08ce0f843b353f64cfcf5efc4a1c3b432a86ccbc Mon Sep 17 00:00:00 2001 From: Git Admin Date: Tue, 2 Dec 2025 10:28:25 +0000 Subject: [PATCH] # Summary instructions --- CLAUDE.md | 7 + code.md | 431 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 438 insertions(+) create mode 100644 code.md diff --git a/CLAUDE.md b/CLAUDE.md index c15a818..c9e6e9e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,13 @@ --- +# Summary Instructions +When you are using compact, please focus on test output and code changes + +--- + +--- + ## 📊 CURRENT STATUS ### ✅ What's Working: diff --git a/code.md b/code.md new file mode 100644 index 0000000..16f1272 --- /dev/null +++ b/code.md @@ -0,0 +1,431 @@ +# Code Efficiency & Sub-Agents Guide - Phase 3 + +**Purpose:** Optimize code efficiency, reduce API costs, and leverage OpenHands sub-agents for Phase 3 autonomous build testing. + +--- + +## 🤖 OpenHands Sub-Agents + +### What Are Sub-Agents? +Sub-agents are specialized AI agents within OpenHands that handle specific tasks: +- **File Editor** - Create, edit, view files +- **Bash Runner** - Execute shell commands +- **Search Agent** - Find files, code patterns +- **Code Analyzer** - Review code structure + +### Benefits for Phase 3 +- ✅ **Targeted Actions** - Each sub-agent is optimized for specific tasks +- ✅ **Cost Efficiency** - More focused tasks = fewer tokens +- ✅ **Faster Execution** - Specialized agents work quicker +- ✅ **Better Results** - Right tool for the right job + +### Using Sub-Agents in Phase 3 + +#### 1. File Creation & Editing +``` +Task: "Create a package.json for Node.js project" +→ Uses: File Editor sub-agent +Result: Optimized package.json with correct dependencies +``` + +#### 2. Build Script Execution +``` +Task: "Run npm install && npm run build" +→ Uses: Bash Runner sub-agent +Result: Executed commands with exit codes +``` + +#### 3. Code Review & Analysis +``` +Task: "Analyze build errors in /workspace/project" +→ Uses: Code Analyzer sub-agent +Result: Identified syntax errors, missing dependencies +``` + +#### 4. Error Diagnosis +``` +Task: "Find all TypeScript errors in the project" +→ Uses: Search Agent + Code Analyzer +Result: List of files with errors + solutions +``` + +--- + +## 💰 Reducing API Usage Costs + +### 1. Efficient Task Formulation + +**❌ Bad (High Cost):** +``` +"Build the project, test it, fix any errors, optimize performance, +and make sure everything works perfectly" +``` + +**✅ Good (Low Cost):** +``` +Task: "Build project at /workspace/my-project" +Follow-up: "Fix npm install errors" +Follow-up: "Resolve TypeScript compilation errors" +``` + +**Why:** Smaller, specific tasks = fewer tokens = lower cost + +### 2. Use Structured Commands + +**✅ Instead of:** +``` +"Please look at my code and see if there are any issues" +``` + +**✅ Use:** +``` +Task: "Search for console.log statements in /workspace/project/src" +``` + +### 3. Leverage File Editor for Batch Operations + +**✅ Efficient Pattern:** +``` +1. Task: "Create /workspace/project/test.js with basic tests" +2. Task: "Edit /workspace/project/index.js to import test.js" +3. Task: "Run npm test" +``` + +### 4. Cache & Reuse Context + +**Strategy:** +- Use same workspace for multiple builds +- Keep dependencies installed +- Reuse configuration files + +--- + +## ⏱️ Reducing Execution Time + +### 1. Parallel Sub-Agent Execution +OpenHands can run multiple sub-agents concurrently: +``` +Task: [ + "Install npm dependencies", + "Check TypeScript configuration", + "Verify package.json scripts" +] +→ Runs in parallel = 3x faster +``` + +### 2. Incremental Builds +**Instead of full rebuild:** +``` +Task: "Build only changed files" +→ Checks git diff +→ Rebuilds modified components +→ Saves time on large projects +``` + +### 3. Smart Dependency Caching +```bash +# Cache node_modules +Task: "Copy cached node_modules from /workspace/cache to /workspace/project" + +# Skip npm install if cached +Task: "Check if node_modules exists, if yes skip npm install" +``` + +### 4. Pre-configured Build Environments +``` +Task: "Use pre-configured Docker build environment" +→ Skip environment setup +→ Start build immediately +``` + +--- + +## 🔧 Best Practices for Phase 3 + +### 1. Build Task Optimization + +**Template for Build Tasks:** +``` +Task: "Build project: /workspace/{project_name} +Commands: + 1. cd /workspace/{project_name} + 2. npm install # Only if node_modules missing + 3. npm run build # Or build command from package.json + 4. Report exit code and any errors" +``` + +### 2. Error Handling Pattern + +**Standard Error Response:** +```json +{ + "success": false, + "exit_code": 1, + "errors": [ + { + "file": "src/index.ts", + "line": 15, + "error": "Type 'string' is not assignable to type 'number'" + } + ], + "suggestions": [ + "Fix type annotation on line 15", + "Convert string to number or update type definition" + ] +} +``` + +### 3. Retry-Friendly Tasks + +**Each task should be:** +- ✅ Idempotent - Can run multiple times safely +- ✅ Self-contained - Includes context +- ✅ Actionable - Clear next steps +- ✅ Specific - Not vague or multi-part + +**❌ Avoid:** +``` +"Fix the build issues" +``` + +**✅ Prefer:** +``` +Task: "Fix TypeScript error: Type 'string' is not assignable to type 'number' in src/index.ts:15 +Solution: Add type conversion: const num = parseInt(str)" +``` + +### 4. Progress Tracking + +**For Long Builds:** +``` +Progress: "Building project... (1/4 steps: npm install)" +Progress: "Building project... (2/4 steps: TypeScript compilation)" +Progress: "Building project... (3/4 steps: Webpack bundling)" +Progress: "Build completed successfully" +``` + +--- + +## 📊 Cost Optimization Strategies + +### 1. Token Budget Management + +**Per Retry Budget:** +- **1st Attempt:** 500 tokens (basic task) +- **2nd Attempt:** 750 tokens (with error context) +- **3rd Attempt:** 1000 tokens (detailed debugging) + +**Implementation:** +```javascript +// In n8n Code node +const retryCount = $workflow.staticData.retry_count || 0; +const tokenLimit = 500 + (retryCount * 250); // 500, 750, 1000 + +return { + task: `Build project with ${tokenLimit} token budget`, + retry_count: retryCount +}; +``` + +### 2. Smart Error Collection + +**Collect Only Relevant Errors:** +```javascript +// Extract only build-blocking errors +const errors = buildOutput.stderr + .split('\n') + .filter(line => line.includes('error')) + .slice(0, 5) // Limit to 5 errors + .join('\n'); +``` + +### 3. Cached Dependencies + +**Reduce Install Time:** +```bash +# Check cache first +if [ -d "/workspace/cache/node_modules" ]; then + cp -r /workspace/cache/node_modules /workspace/project/ + echo "Used cached dependencies" +else + npm install + cp -r node_modules /workspace/cache/ +fi +``` + +### 4. Selective Testing + +**For Large Projects:** +``` +Task: "Run tests only for modified files (git diff --name-only)" +→ Tests: {list of changed files} +→ Time saved: 90% +``` + +--- + +## 🚀 Sub-Agent Usage Examples + +### Example 1: Quick Build Test +``` +Task: "Test build in /workspace/project +Steps: + 1. Check if package.json exists + 2. Run npm install (if needed) + 3. Run npm run build + 4. Verify build/ directory created + 5. Report: success/failure + exit code" +``` + +### Example 2: Error Diagnosis +``` +Task: "Diagnose build failure in /workspace/project +Steps: + 1. Read last 50 lines of build output + 2. Identify error type (TS, Webpack, Runtime) + 3. Find source file causing error + 4. Suggest specific fix + 5. Return actionable error report" +``` + +### Example 3: Code Optimization +``` +Task: "Optimize build performance in /workspace/project +Steps: + 1. Check bundle size (webpack-bundle-analyzer) + 2. Identify large dependencies + 3. Suggest tree-shaking improvements + 4. Propose code splitting strategy" +``` + +--- + +## 📈 Phase 3 Implementation Tips + +### 1. Task Granularity + +**Fine-grained tasks (Recommended):** +```javascript +const tasks = [ + "Install dependencies", + "Compile TypeScript", + "Bundle with Webpack", + "Run unit tests", + "Generate build report" +]; +``` + +**Instead of one large task:** +```javascript +const task = "Build and test the entire project" +``` + +### 2. State Persistence + +**Use n8n staticData:** +```javascript +$workflow.staticData = $workflow.staticData || {}; +$workflow.staticData.build_state = { + stage: "installing", + completed_steps: [], + errors: [] +}; +``` + +### 3. Resource Limits + +**Per Task Limits:** +- **Timeout:** 300 seconds max +- **Token Budget:** 1000 tokens max +- **Retries:** 3 attempts max +- **Concurrency:** 1 task at a time + +### 4. Monitoring + +**Track Performance:** +```javascript +const startTime = Date.now(); +await runBuildTask(); +const duration = Date.now() - startTime; + +return { + success: true, + duration_ms: duration, + cost_estimate: calculateCost(tokens_used) +}; +``` + +--- + +## 🎯 Phase 3 Success Metrics + +### Performance Targets +- **Build Time:** < 60 seconds (simple project) +- **Error Detection:** < 10 seconds +- **Retry Success Rate:** > 70% +- **API Cost:** < $0.10 per build +- **Token Usage:** < 3000 tokens per workflow + +### Quality Targets +- **Error Accuracy:** 95%+ (correctly identify real issues) +- **False Positives:** < 5% +- **Build Success Rate:** 90%+ (after retries) +- **Documentation:** All errors documented with solutions + +--- + +## 🔍 Troubleshooting Sub-Agents + +### Common Issues & Solutions + +**Issue:** Sub-agent timeout +**Solution:** Break task into smaller pieces + +**Issue:** Token limit exceeded +**Solution:** Reduce task scope, use more specific commands + +**Issue:** Build hangs +**Solution:** Add timeout wrapper, kill long-running processes + +**Issue:** Errors not captured +**Solution:** Use structured error collection, check exit codes + +--- + +## 📚 Reference Commands + +### Testing Sub-Agent Efficiency +```bash +# Test single sub-agent +Task: "Create file /workspace/test.txt with 'Hello'" + +# Test parallel execution +Task: [ + "Create /workspace/file1.txt", + "Create /workspace/file2.txt", + "List /workspace directory" +] +``` + +### Monitoring API Usage +```javascript +// Track tokens per task +const tokenCount = estimateTokens(task); +if (tokenCount > 1000) { + console.warn(`High token usage: ${tokenCount}`); +} +``` + +### Caching Strategy +```bash +# Cache directory structure +/cache/ + /node_modules/ + /dist/ + /test-results/ +``` + +--- + +*Code Efficiency Guide - Last Updated: 2025-12-02* +*Optimized for Phase 3 Autonomous Build Testing*