compression

Guide Compression de Contexte

Introduction

La compression de contexte réduit la consommation de tokens tout en préservant l'information essentielle. Économie typique : 20-40% en plus des context modes.

Stratégies Disponibles

1. Code Reference

Au lieu d'inclure le code complet, référencer le fichier.

Avant (180 tokens) :

public class ProductService
{
    private readonly IProductRepository _repository;

    public ProductService(IProductRepository repository)
    {
        _repository = repository;
    }

    public async Task<Product> GetByIdAsync(Guid id)
    {
        var product = await _repository.GetByIdAsync(id);
        if (product == null)
            throw new NotFoundException($"Product {id} not found");
        return product;
    }

    // ... 50 more lines
}

Après (25 tokens) :

📁 `src/Application/Products/ProductService.cs` (lignes 1-65)
> public class ProductService : IProductService

Configuration :

code_reference:
  enabled: true
  max_inline_lines: 15
  format: "Voir {file_path}:{start_line}-{end_line}"

2. Diff Only

Montrer uniquement les changements, pas le fichier complet.

Avant :

Fichier complet avec 200 lignes, 3 lignes modifiées

Après :

@@ -45,6 +45,8 @@ public class ProductService
     public async Task<Product> GetByIdAsync(Guid id)
     {
+        ArgumentNullException.ThrowIfNull(id);
+
         var product = await _repository.GetByIdAsync(id);

Configuration :

diff_only:
  enabled: true
  context_lines: 3
  format: unified

3. Schema Summary

Résumer les structures de données volumineuses.

Avant (120 tokens) :

interface ProductDto {
  id: string;
  name: string;
  description: string;
  price: number;
  currency: string;
  category: CategoryDto;
  tags: string[];
  images: ImageDto[];
  variants: VariantDto[];
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
  // ... 15 more properties
}

Après (30 tokens) :

ProductDto (18 properties):
- id, name, description, price, currency
- category (CategoryDto), tags[], images[], variants[]
- ... 9 more (audit fields)

Configuration :

schema_summary:
  enabled: true
  max_properties: 10
  nested_depth: 2

4. History Summarization

Résumer l'historique des itérations (Ralph Loop).

Avant :

Iteration 1: [full output - 500 tokens]
Iteration 2: [full output - 450 tokens]
Iteration 3: [full output - 480 tokens]

Après :

Iteration 1: Added Product entity → 3 files created
Iteration 2: Fixed validation → tests passing
Iteration 3: Added error handling → 87% coverage

Configuration :

history_summarization:
  enabled: true
  keep_recent: 3
  summary_max_tokens: 100

Règles par Type de Fichier

file_type_rules:
  test_files:
    patterns: ["*.test.*", "*.spec.*"]
    strategy: reference_only
    reason: "Tests rarement nécessaires en contexte complet"

  dto_files:
    patterns: ["*Dto.cs", "*.dto.ts"]
    strategy: schema_summary

  entity_files:
    patterns: ["*Entity.cs", "*/domain/*"]
    strategy: full  # Entités toujours complètes

  generated_files:
    patterns: ["*.generated.*", "*/node_modules/*"]
    strategy: exclude

Sizing Dynamique

Le contexte s'adapte automatiquement selon la tâche :

dynamic_sizing:
  rules:
    # Tests → réduire contexte métier
    - trigger: "test|spec"
      reduce: ["standards.rfc", "architecture.principles"]
      boost: ["test_patterns", "coverage_rules"]

    # Urgent → mode minimal
    - trigger: "urgent|hotfix"
      force_mode: minimal

    # Review → focus sécurité
    - trigger: "review|audit"
      boost: ["security_checklist", "solid_principles"]

    # API → focus contrats
    - trigger: "api|endpoint"
      boost: ["http_standards", "openapi_spec"]
      reduce: ["frontend_patterns"]

Intégration avec Context Modes

Chaque mode applique ses propres stratégies :

Mode	Stratégies	Max Tokens
ultra-minimal	reference, summary	100
minimal	reference, diff	300
standard	diff, history	1000
api-focused	summary, reference	1200
test-focused	reference, diff	800
full	(aucune)	2500

Mesurer l'Efficacité

Métriques trackées

metrics:
  - tokens_before_compression
  - tokens_after_compression
  - compression_ratio
  - strategy_usage

Seuils d'alerte

Métrique	Seuil	Action
Compression < 10%	Info	Vérifier config
Compression > 60%	Warning	Risque perte info

Rapport inline

Tokens: 2,450 | Compression: 35% | Strategies: diff, reference

Best Practices

1. Ne pas sur-compresser

La compression excessive peut perdre du contexte crucial. Équilibrez :

• Tests : compression OK (reference)
• Entités : garder complet
• DTOs : résumer OK

2. Utiliser les bonnes stratégies

Situation	Stratégie
Montrer des modifications	diff_only
Référencer du code existant	code_reference
Documenter une API	schema_summary
Ralph Loop long	history_summarization

3. Configurer par projet

Adaptez context-compression.yaml à votre codebase :

• Gros projet → compression agressive
• Petit projet → moins de compression
• Code complexe → garder plus de contexte

4. Monitorer les résultats

Si les agents font des erreurs :

1. Vérifiez si trop de compression
2. Ajustez les seuils
3. Exemptez certains fichiers

Configuration Complète

Voir .claude-portable/config/context-compression.yaml pour tous les paramètres.

Exemples

Projet .NET typique

file_type_rules:
  # Garder complet
  - patterns: ["*Entity.cs", "*Aggregate.cs"]
    strategy: full

  # Résumer
  - patterns: ["*Dto.cs", "*Request.cs", "*Response.cs"]
    strategy: schema_summary

  # Référencer
  - patterns: ["*Tests.cs", "*Spec.cs"]
    strategy: reference_only

  # Exclure
  - patterns: ["*/obj/*", "*/bin/*", "*.Designer.cs"]
    strategy: exclude

Projet React typique

file_type_rules:
  # Garder complet
  - patterns: ["*/hooks/*", "*/context/*"]
    strategy: full

  # Résumer
  - patterns: ["*.types.ts", "*/api/*.ts"]
    strategy: schema_summary

  # Référencer
  - patterns: ["*.test.tsx", "*.stories.tsx"]
    strategy: reference_only

  # Exclure
  - patterns: ["*/node_modules/*", "*.d.ts"]
    strategy: exclude