context-optimizer

Context Optimizer

Optimize data file structure and formatting for Claude's reasoning and information extraction.

Core Principle

Claude's attention follows a recency gradient: strongest at context boundaries (start/​end), weakest in the middle. Optimization strategy:

1. Position - Where content appears matters more than format choice
2. Structure - Explicit delimiters enable selective retrieval
3. Metadata - Source attribution enables grounding in evidence

Quick Reference

Workflow

Step 1: Classify Content

Determine content type and select format:

Structured data (schemas, records, API responses) → JSON Multi-document corpus (reports, research, contracts) → XML with metadata Tabular data (metrics, comparisons) → CSV or markdown tables Configuration (settings, parameters) → YAML Narrative/​progress → Unstructured markdown

Step 2: Apply Positioning Rule

┌─────────────────────────────────────┐
│  DOCUMENTS/​DATA (position: TOP)    │  ← Strongest attention
├─────────────────────────────────────┤
│  EXAMPLES (if applicable)          │
├─────────────────────────────────────┤
│  INSTRUCTIONS                      │
├─────────────────────────────────────┤
│  QUERY/​TASK (position: END)        │  ← Strongest attention
└─────────────────────────────────────┘

Placing queries at the end improves response quality by up to 30%.

Step 3: Structure Documents

For multi-document contexts, use the standard wrapper pattern:

<documents>
  <document index="1" priority="primary">
    <source>filename.pdf</​source>
    <type>financial_report</​type>
    <content>
      {{DOCUMENT_CONTENT}}
    </​content>
  </​document>
</​documents>

Always include:

• index - For unambiguous reference
• source - For citation/​attribution
• type - For semantic filtering

See references/​format-patterns.md for complete templates.

Step 4: Add Retrieval Instructions

For long documents, add explicit grounding instructions:

Find quotes from the documents that are relevant to [TASK].
Place these in <quotes> tags with document index references.
Then, based on these quotes, [PERFORM ANALYSIS].

This helps Claude cut through noise and ground responses in evidence.

Format Selection Guide

When to Use XML

• Multi-document corpora requiring source attribution
• Content with hierarchical structure
• When parseability of output matters
• Combining with chain-of-thought (<thinking>, <answer>)

When to Use JSON

• State tracking (test results, task status)
• API request/​response data
• When schema enforcement is needed
• Structured output requirements

When to Use Markdown Tables

• Comparisons and rankings
• Tabular data under ~50 rows
• When human readability matters

When to Use Plain Text

• Instructions and queries
• Progress notes and narrative
• Simple, single-purpose content

Critical Rules

1. Never bury instructions in data - Instructions surrounded by data get attention-diluted
2. Reference documents explicitly - Avoid "this document"; use document index="3"
3. Use consistent tag names - Same vocabulary throughout; reference by name in instructions
4. Nest semantically - <outer><inner></​inner></​outer> for hierarchical content
5. Include source attribution - Every document wrapper needs <source>

Common Pitfalls

See references/​pitfalls.md for detailed mitigations.

Transformation Script

For automated restructuring, use the transform script:

python scripts/​transform_context.py input.json --format xml --output optimized.xml
python scripts/​transform_context.py input.csv --format xml --add-metadata --output optimized.xml

See script help for all options: python scripts/​transform_context.py --help