ambient-code · jeremyeder · Dec 2, 2025 · Nov 22, 2025 · Dec 2, 2025
diff --git a/.claude/repomix-guide.md b/.claude/repomix-guide.md
@@ -1,187 +1,143 @@
-# Repomix Context Switching Guide
+# Repomix Architecture View Guide
 
-**Purpose:** Quick reference for loading the right repomix view based on the task.
+**Purpose:** Guide for using the repomix architecture view for Claude Code context loading.
 
-## Available Views
+## Executive Decision: Single View Approach
 
-The `repomix-analysis/` directory contains 7 pre-generated codebase views optimized for different scenarios:
+After comprehensive analysis of 7 different repomix configurations (see `repomix-analysis/repomix-analysis-report.md`), we've adopted a **single-view approach** using only `03-architecture-only.xml`.
 
-| File | Size | Use When |
-|------|------|----------|
-| `01-full-context.xml` | 2.1MB | Deep dive into specific component implementation |
-| `02-production-optimized.xml` | 4.2MB | General development work, most common use case |
-| `03-architecture-only.xml` | 737KB | Understanding system design, new team member onboarding |
-| `04-backend-focused.xml` | 403KB | Backend API work (Go handlers, K8s integration) |
-| `05-frontend-focused.xml` | 767KB | UI development (NextJS, React Query, Shadcn) |
-| `06-ultra-compressed.xml` | 10MB | Quick overview, exploring unfamiliar areas |
-| `07-metadata-rich.xml` | 849KB | File structure analysis, refactoring planning |
+**Why one view?**
+- **Grade 8.8/10** - Highest quality score of all tested configurations
+- **187K tokens** - Optimal for context windows, leaves room for conversation
+- **Comprehensive coverage** - 132 critical files across all 7 components
+- **Simpler mental model** - No decision fatigue about which view to use
+- **Smaller repo** - 1M vs 19M for all 7 views
 
-## Usage Patterns
+See the [analysis heatmap](../repomix-analysis/repomix-heatmap.png) for visual comparison.
 
-### Scenario 1: Backend Development
+## Available View
 
-**Task:** Adding a new API endpoint for project settings
+The `repomix-analysis/` directory contains one pre-generated codebase view:
 
-**Command:**
+| File | Size | Tokens | Grade | Use For |
+|------|------|--------|-------|---------|
+| `03-architecture-only.xml` | 737KB | 187K | 8.8/10 | All development tasks, architecture understanding, planning |
 
-```
-"Claude, reference the backend-focused repomix view (04-backend-focused.xml) and help me add a new endpoint for updating project settings."
-```
-
-**Why this view:**
+**What's included:**
+- ✓ CLAUDE.md (project instructions)
+- ✓ All component READMEs (11 files)
+- ✓ Type definitions (17 files)
+- ✓ Design guidelines
+- ✓ Route definitions
+- ✓ Infrastructure manifests
+- ✓ CRD definitions
+- ✓ 132 critical files across all components
 
-- Contains all backend handlers and types
-- Includes K8s client patterns
-- Focused context without frontend noise
+**What's excluded:**
+- Test files (reduces noise)
+- Generated code
+- Dependencies (node_modules, vendor)
+- Build artifacts
 
-### Scenario 2: Frontend Development
+## Usage Examples
 
-**Task:** Creating a new UI component for RFE workflows
-
-**Command:**
+### General Development
 
 ```
-"Claude, load the frontend-focused repomix view (05-frontend-focused.xml) and help me create a new component for displaying RFE workflow steps."
+"Claude, load the repomix architecture view (repomix-analysis/03-architecture-only.xml)
+and help me understand how multi-repo support works in AgenticSessions."
 ```
 
-**Why this view:**
-
-- All React components and pages
-- Shadcn UI patterns
-- React Query hooks
-
-### Scenario 3: Architecture Understanding
-
-**Task:** Explaining the system to a new team member
-
-**Command:**
+### Architecture Understanding
 
 ```
-"Claude, using the architecture-only repomix view (03-architecture-only.xml), explain how the operator watches for AgenticSession creation and spawns jobs."
+"Claude, using the architecture view, explain how the operator watches for
+AgenticSession creation and spawns jobs."
 ```
 
-**Why this view:**
-
-- High-level component structure
-- CRD definitions
-- Component relationships
-- No implementation details
-
-### Scenario 4: Cross-Component Analysis
-
-**Task:** Tracing a request from frontend through backend to operator
-
-**Command:**
+### Planning New Features
 
 ```
-"Claude, use the production-optimized repomix view (02-production-optimized.xml) and trace the flow of creating an AgenticSession from UI click to Job creation."
+"Claude, reference the architecture view and help me plan where to add
+support for custom agent configurations in the frontend."
 ```
 
-**Why this view:**
-
-- Balanced coverage of all components
-- Includes key implementation files
-- Not overwhelmed with test files
-
-### Scenario 5: Quick Exploration
-
-**Task:** Finding where a specific feature is implemented
+### Combining with Context Files
 
-**Command:**
+For even better results, combine the architecture view with context files:
 
 ```
-"Claude, use the ultra-compressed repomix view (06-ultra-compressed.xml) to help me find where multi-repo support is implemented."
+"Claude, load the architecture view and the backend-development context file,
+then help me add a new endpoint for project settings."
 ```
 
-**Why this view:**
-
-- Fast to process
-- Good for keyword searches
-- Covers entire codebase breadth
-
-### Scenario 6: Refactoring Planning
-
-**Task:** Planning to break up large handlers/sessions.go file
-
-**Command:**
-
 ```
-"Claude, analyze the metadata-rich repomix view (07-metadata-rich.xml) and suggest how to split handlers/sessions.go into smaller modules."
+"Claude, load the architecture view and security-standards context file,
+then review this PR for authentication issues."
 ```
 
-**Why this view:**
+## Quick Reference Table
 
-- File size and structure metadata
-- Module boundaries
-- Import relationships
+| Task Type | Command Pattern | Context Files |
+|-----------|----------------|---------------|
+| Backend API work | Load architecture view | backend-development.md |
+| Frontend UI work | Load architecture view | frontend-development.md |
+| Security review | Load architecture view | security-standards.md |
+| Architecture planning | Load architecture view | - |
+| Pattern implementation | Load architecture view | patterns/*.md |
 
-### Scenario 7: Deep Implementation Dive
+## Regenerating the View
 
-**Task:** Debugging a complex operator reconciliation issue
+The architecture view is a snapshot in time. Regenerate monthly or after major changes:
 
-**Command:**
+```bash
+# Regenerate the architecture-only view
+repomix --output repomix-analysis/03-architecture-only.xml --style xml
 
-```
-"Claude, load the full-context repomix view (01-full-context.xml) and help me understand why the operator is creating duplicate jobs for the same session."
+# Uses exclusion patterns from .repomixignore
 ```
 
-**Why this view:**
-
-- Complete implementation details
-- All edge case handling
-- Full operator logic
+**When to regenerate:**
+- After major architectural changes
+- Monthly (scheduled maintenance)
+- Before major refactoring efforts
+- When codebase structure changes significantly
 
-## Best Practices
+**Tip:** Add to monthly maintenance calendar alongside dependency updates.
 
-### Start Broad, Then Narrow
+## Why Not Multiple Views?
 
-1. **First pass:** Use `03-architecture-only.xml` to understand where the feature lives
-2. **Second pass:** Use component-specific view (`04-backend` or `05-frontend`)
-3. **Deep dive:** Use `01-full-context.xml` for specific implementation details
+The original analysis tested 7 different configurations:
 
-### Combine with Context Files
+1. **01-full-context.xml** (550K tokens) - Too large, poor token efficiency
+2. **02-production-optimized.xml** (1.1M tokens) - Excessive, unusable
+3. **03-architecture-only.xml** (187K tokens) - ✅ **Perfect balance**
+4. **04-backend-focused.xml** (103K tokens) - Too narrow, grade 6.6
+5. **05-frontend-focused.xml** (196K tokens) - Too narrow, grade 6.4
+6. **06-ultra-compressed.xml** (2.6M tokens) - Catastrophically large
+7. **07-metadata-rich.xml** (216K tokens) - Redundant with #03
 
-For even better results, combine repomix views with context files:
+**The verdict:** #03 provides the best balance of:
+- Token efficiency (fits in context window)
+- Architecture visibility (complete picture)
+- Code navigation (132 critical files)
+- Context completeness (all components)
 
-```
-"Claude, load the backend-focused repomix view (04) and the backend-development context file, then help me add user token authentication to the new endpoint."
-```
+See `repomix-analysis/repomix-analysis-report.md` for full analysis details and the heatmap visualization.
 
-### Regenerate Periodically
+## Advanced: Generate-on-Demand
 
-Repomix views are snapshots in time. Regenerate monthly (or after major changes):
+For specialized needs, you can generate custom views on-demand:
 
 ```bash
-# Full regeneration
-cd repomix-analysis
-./regenerate-all.sh  # If you create this script
-
-# Or manually
-repomix --output 02-production-optimized.xml --config repomix-production.json
-```
-
-**Tip:** Add to monthly maintenance calendar.
-
-## Quick Reference Table
-
-| Task Type | Repomix View | Context File |
-|-----------|--------------|--------------|
-| Backend API work | 04-backend-focused | backend-development.md |
-| Frontend UI work | 05-frontend-focused | frontend-development.md |
-| Security review | 02-production-optimized | security-standards.md |
-| Architecture overview | 03-architecture-only | - |
-| Quick exploration | 06-ultra-compressed | - |
-| Refactoring | 07-metadata-rich | - |
-| Deep debugging | 01-full-context | (component-specific) |
+# Backend-only view (if you need it)
+repomix --include "components/backend/**" --output backend-custom.xml --style xml
 
-## Maintenance
+# Frontend-only view
+repomix --include "components/frontend/**" --output frontend-custom.xml --style xml
 
-**When to regenerate:**
-
-- After major architectural changes
-- Monthly (scheduled)
-- Before major refactoring efforts
-- When views feel "stale" (>2 months old)
+# Security-focused view
+repomix --include "**/handlers/**,**/middleware/**,CLAUDE.md" --output security-custom.xml --style xml
+```
 
-**How to regenerate:**
-See `.repomixignore` for exclusion patterns. Adjust as needed to balance completeness with token efficiency.
+But in practice, the architecture-only view works for 95% of tasks.
diff --git a/.repomixignore b/.repomixignore
@@ -0,0 +1,66 @@
+# Repomix Ignore Patterns - Production Optimized
+# Designed to balance completeness with token efficiency for AI agent steering
+
+# Test files - reduce noise while preserving architecture
+**/*_test.go
+**/*.test.ts
+**/*.test.tsx
+**/*.spec.ts
+**/*.spec.tsx
+**/test_*.py
+tests/
+cypress/
+e2e/cypress/screenshots/
+e2e/cypress/videos/
+
+# Generated lock files - auto-generated, high token cost, low value
+**/package-lock.json
+**/go.sum
+**/poetry.lock
+**/Pipfile.lock
+
+# Documentation duplicates - MkDocs builds site/ from docs/
+site/
+
+# Virtual environments and dependencies - massive token waste
+# Python virtual environments
+**/.venv
+**/.venv/
+**/.venv-*/
+**/venv
+**/venv/
+**/env
+**/env/
+**/.env-*/
+**/virtualenv/
+**/.virtualenv/
+
+# Node.js and Go dependencies
+**/node_modules/
+**/vendor/
+
+# Build artifacts - generated output, not source
+**/.next/
+**/dist/
+**/build/
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+**/*.so
+**/*.dylib
+
+# OS and IDE files
+**/.DS_Store
+**/.idea/
+**/.vscode/
+**/*.swp
+**/*.swo
+
+# E2E artifacts
+e2e/cypress/screenshots/
+e2e/cypress/videos/
+
+# Temporary files
+**/*.tmp
+**/*.temp
+**/tmp/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -48,13 +48,15 @@ This repository uses a structured **memory system** to provide targeted, loadabl
 
 **Load these files when working in specific areas:**
 
-| Task Type | Context File | Repomix View | Pattern File |
-|-----------|--------------|--------------|--------------|
-| **Backend API work** | `.claude/context/backend-development.md` | `repomix-analysis/04-backend-focused.xml` | `.claude/patterns/k8s-client-usage.md` |
-| **Frontend UI work** | `.claude/context/frontend-development.md` | `repomix-analysis/05-frontend-focused.xml` | `.claude/patterns/react-query-usage.md` |
-| **Security review** | `.claude/context/security-standards.md` | `repomix-analysis/02-production-optimized.xml` | `.claude/patterns/error-handling.md` |
+| Task Type | Context File | Architecture View | Pattern File |
+|-----------|--------------|-------------------|--------------|
+| **Backend API work** | `.claude/context/backend-development.md` | `repomix-analysis/03-architecture-only.xml` | `.claude/patterns/k8s-client-usage.md` |
+| **Frontend UI work** | `.claude/context/frontend-development.md` | `repomix-analysis/03-architecture-only.xml` | `.claude/patterns/react-query-usage.md` |
+| **Security review** | `.claude/context/security-standards.md` | `repomix-analysis/03-architecture-only.xml` | `.claude/patterns/error-handling.md` |
 | **Architecture questions** | - | `repomix-analysis/03-architecture-only.xml` | See ADRs below |
 
+**Note:** We use a single repomix architecture view (grade 8.8/10, 187K tokens) for all tasks. See `.claude/repomix-guide.md` for details.
+
 ### Available Memory Files
 
 **1. Context Files** (`.claude/context/`)
@@ -80,8 +82,8 @@ This repository uses a structured **memory system** to provide targeted, loadabl
 
 **4. Repomix Usage Guide** (`.claude/repomix-guide.md`)
 
-- How to use the 7 existing repomix views effectively
-- When to use each view based on the task
+- Guide for using the architecture view effectively
+- Why we use a single view approach (vs. 7 views)
 
 **5. Decision Log** (`docs/decisions.md`)
 
@@ -91,12 +93,13 @@ This repository uses a structured **memory system** to provide targeted, loadabl
 ### Example Usage
 
 ```
-"Claude, load the backend-development context file and the backend-focused repomix view (04),
-then help me add a new endpoint for listing RFE workflows in a project."
+"Claude, load the architecture view (repomix-analysis/03-architecture-only.xml) and the
+backend-development context file, then help me add a new endpoint for listing RFE workflows."
 ```
 
 ```
-"Claude, reference the security-standards context file and review this PR for token handling issues."
+"Claude, load the architecture view and security-standards context file,
+then review this PR for token handling issues."
 ```
 
 ```