Tutorial: Context Optimization

Learn to optimize the context provided to AI agents for better results, faster execution, and lower costs. Good context management is the difference between mediocre and excellent orchestrations.

Time: 15-20 minutes Prerequisites: Completed First Orchestration Tutorial

Introduction

Why Context Matters

AI agents work better with the right context:

  • Too little: Agent guesses, makes inconsistent choices
  • Too much: Agent gets confused, slower execution, higher costs
  • Just right: Agent understands patterns, produces consistent code

The Cost of Context

Every file in context costs tokens:

Context Size Input Tokens Cost (Claude Sonnet)
5 files ~5,000 ~$0.015
20 files ~20,000 ~$0.06
50 files ~50,000 ~$0.15
100 files ~100,000 ~$0.30

Multiply by streams and waves — context optimization pays off quickly.

Step 1: Understanding `owns` and `reads`

Orchex uses two fields to manage context:

`owns` — Files You're Creating/Modifying

streams:
  - id: auth-service
    owns:
      - src/services/auth.ts
      - tests/auth.service.test.ts

What happens:

  • These files are included in context if they exist
  • The agent knows it's responsible for these files
  • Other streams see this ownership and avoid conflicts

`reads` — Files for Context Only

streams:
  - id: auth-service
    owns:
      - src/services/auth.ts
    reads:
      - src/types/user.ts      # Understand user types
      - src/config.ts          # Understand configuration
      - src/utils/jwt.ts       # Understand JWT utilities

What happens:

  • These files are included in context
  • The agent can reference them but won't modify them
  • Helps maintain consistency with existing code

Step 2: The Goldilocks Principle

Too Few Reads

# Bad: No context about existing patterns
- id: create-service
  owns: [src/services/orders.ts]
  reads: []  # ← Problem!
  prompt: Create an orders service

Result: Agent might:

  • Use different coding style than existing services
  • Duplicate existing utilities
  • Miss established patterns

Too Many Reads

# Bad: Information overload
- id: create-service
  owns: [src/services/orders.ts]
  reads:
    - src/**/*.ts        # Every TypeScript file!
    - docs/**/*.md       # All documentation!

Result:

  • Slower execution (processing all that context)
  • Higher costs (more input tokens)
  • Potential confusion from irrelevant files
  • Risk of timeout

Just Right

# Good: Focused, relevant context
- id: create-service
  owns: [src/services/orders.ts]
  reads:
    - src/types/order.ts         # Types for orders
    - src/services/users.ts      # Example service pattern
    - src/db/connection.ts       # Database utilities

Result:

  • Agent understands the patterns
  • Consistent with existing code
  • Fast execution, reasonable cost

Step 3: Practical Context Patterns

Pattern 1: Reference Implementation

Give one good example to follow:

- id: create-orders-service
  owns: [src/services/orders.ts]
  reads:
    - src/services/users.ts      # "Follow this pattern"
    - src/types/order.ts
  prompt: |
    Create orders service following the pattern in users.ts.
    Use the same structure, error handling, and export style.

Pattern 2: Type-Driven Development

Include types that define the contract:

- id: implement-api
  owns: [src/api/orders.ts]
  reads:
    - src/types/api.ts           # API types
    - src/types/orders.ts        # Domain types
    - src/types/errors.ts        # Error types
  prompt: |
    Implement the orders API using the types defined in the reads.
    The function signatures should match the types exactly.

Pattern 3: Configuration-Aware

Include config when behavior depends on it:

- id: create-mailer
  owns: [src/services/mailer.ts]
  reads:
    - src/config/email.ts        # Email configuration
    - src/templates/            # Email templates directory
  prompt: |
    Create email service using configuration from email.ts.
    Support all templates in the templates directory.

Pattern 4: Test Context

Include related tests for consistency:

- id: add-validation
  owns:
    - src/utils/validate.ts
    - tests/validate.test.ts
  reads:
    - tests/helpers.ts           # Test utilities
    - src/utils/sanitize.ts      # Related utility for patterns
  prompt: |
    Add validation utilities with tests.
    Use test helpers from tests/helpers.ts.

Step 4: Context Optimization Checklist

Before finalizing your manifest, ask:

✅ Essential Context

  • Types/interfaces the stream needs
  • One or two example files showing patterns
  • Configuration if behavior depends on it
  • Utilities the stream will use

❌ Skip These

  • Unrelated services/modules
  • Test files (unless writing tests)
  • Documentation/README files
  • Configuration for other features
  • Build/tooling configuration

🤔 Case-by-Case

  • Similar implementations (maybe 1-2, not all)
  • Database schemas (only if directly relevant)
  • API routes (only if integrating with them)

Step 5: Real-World Example

Let's optimize an e-commerce feature orchestration:

Before: Unoptimized

streams:
  - id: cart-service
    owns: [src/services/cart.ts]
    reads:
      - src/**/*.ts              # Everything!
    prompt: Create shopping cart service

Problems:

  • src/**/*.ts might include 100+ files
  • Irrelevant files like authentication, admin, analytics
  • High cost, slow execution, confused output

After: Optimized

streams:
  - id: cart-service
    owns:
      - src/services/cart.ts
      - tests/cart.service.test.ts
    reads:
      - src/types/cart.ts        # Cart types
      - src/types/product.ts     # Product types (cart contains products)
      - src/services/products.ts # Pattern example + integration point
      - src/db/models/cart.ts    # Database model
    prompt: |
      Create shopping cart service:
      - Follow the pattern in products.ts for service structure
      - Use types from cart.ts and product.ts
      - Interact with the cart database model
      - Include methods: addItem, removeItem, getCart, clearCart

Improvements:

  • 5 specific files instead of 100+
  • Clear pattern reference
  • Explicit integration points
  • Detailed prompt with methods

Step 6: Advanced: The 4-File Rule

A practical heuristic from production experience:

If a stream reads more than 4 files, consider splitting it.

Why?

High reads count correlates with:

  • Higher timeout risk
  • More complex synthesis required
  • Higher chance of confusion

Example: Splitting a Complex Stream

Before:

- id: create-dashboard
  owns: [src/components/Dashboard.tsx]
  reads:
    - src/hooks/useUsers.ts
    - src/hooks/useOrders.ts
    - src/hooks/useAnalytics.ts
    - src/hooks/useNotifications.ts
    - src/components/Card.tsx
    - src/components/Chart.tsx

6 reads — consider splitting!

After:

- id: dashboard-layout
  owns: [src/components/Dashboard.tsx]
  reads:
    - src/components/Card.tsx    # UI pattern
    - src/types/dashboard.ts     # Types
  prompt: Create Dashboard layout with Card containers

- id: dashboard-data
  owns: [src/hooks/useDashboard.ts]
  reads:
    - src/hooks/useUsers.ts      # Pattern example
    - src/types/dashboard.ts
  prompt: |
    Create useDashboard hook that combines:
    - User data (follow useUsers pattern)
    - Order data
    - Analytics data
    Return unified dashboard state.
  dependencies: [dashboard-layout]

Now each stream has ≤3 reads, more focused tasks.

Step 7: Measuring Context Effectiveness

Signs of Good Context

✓ Agent produces code consistent with codebase ✓ Uses existing utilities instead of reimplementing ✓ Matches established patterns ✓ Execution completes without timeouts ✓ Few or no fix streams needed

Signs of Poor Context

✗ Inconsistent coding style ✗ Reimplements existing utilities ✗ Ignores established patterns ✗ Frequent timeouts ✗ Multiple fix stream attempts

Iteration Approach

  1. Start with minimal context
  2. If results are inconsistent, add pattern examples
  3. If still missing something, add specific utility/type files
  4. If too slow/expensive, remove less relevant files

Cost Optimization Summary

Strategy Impact Example
Specific file paths 10x fewer tokens src/auth.ts vs src/**/*.ts
Pattern examples Better first-try success Include one similar service
Type files Consistent interfaces Include relevant .d.ts
Skip docs Reduce noise Don't include README/CHANGELOG
4-file rule Prevent timeouts Split streams with >4 reads

Cost Calculation

Tokens per stream ≈ system_prompt + (reads × avg_file_size) + prompt
                 ≈ 2000 + (N × 500) + 500

5 reads: 2000 + 2500 + 500 = 5000 tokens (~$0.015)
20 reads: 2000 + 10000 + 500 = 12500 tokens (~$0.04)

For a 10-stream orchestration:

  • Optimized (5 reads/stream): ~$0.15
  • Unoptimized (20 reads/stream): ~$0.40

Savings: 60%

What You've Learned

✅ How owns and reads affect context

✅ The Goldilocks principle for context size

✅ Practical patterns for effective context

✅ The 4-file rule for stream splitting

✅ How to measure and optimize for cost

Next Steps

Optimized context = better results, faster execution, lower costs!