aissia/docs/01-architecture/claude-code-integration.md

Intégration Claude Code : Guide Technique

🎯 Objectif : Développement IA-First

Cette architecture est spécifiquement conçue pour maximiser l'efficacité de Claude Code dans le développement de jeux complexes.

🧠 Contraintes Cognitives de l'IA

Problème Fondamental : Context Window

• Claude Code limite : ~200K tokens de contexte
• Jeu AAA typique : 500K+ lignes de code interconnectées
• Résultat : IA ne peut pas appréhender le système complet

Solution : Micro-Contexts Autonomes

// Au lieu de ça (impossible pour l'IA) :
TankSystem.cpp (5000 lignes) +
PhysicsEngine.cpp (8000 lignes) +
NetworkLayer.cpp (3000 lignes) +
GraphicsRenderer.cpp (12000 lignes)
= 28000 lignes interconnectées

// On fait ça (parfait pour l'IA) :
TankModule.cpp (200 lignes)
= Logique pure, zéro dépendance

🏗️ Architecture Claude Code Friendly

Structure Cognitive Optimale

warfactory/
├── modules/tank/              # 🎯 Claude travaille ICI
│   ├── CLAUDE.md              # Instructions spécialisées
│   ├── CMakeLists.txt         # Build autonome (cmake .)
│   ├── shared/                # Headers locaux
│   ├── src/TankModule.cpp     # 200 lignes PURE logic
│   └── build/                 # → tank.so
└── [reste du projet invisible pour Claude]

Principe : Information Hiding Cognitif

• Claude voit SEULEMENT : TankModule.cpp + CLAUDE.md + interfaces
• Claude ne voit JAMAIS : Engine architecture, networking, threading
• Résultat : Focus 100% sur logique métier

📋 Workflow Claude Code Optimisé

1. Session Initialization

# Claude démarre TOUJOURS dans un module spécifique
cd modules/tank/

# Context loading minimal
files_to_read = [
    "CLAUDE.md",           # 50 lignes d'instructions
    "src/TankModule.cpp",  # 200 lignes de logic
    "shared/IModule.h"     # 30 lignes d'interface
]
# Total : 280 lignes vs 50K+ dans architecture classique

2. Development Loop

# 1. Claude lit le contexte micro
read("src/TankModule.cpp")

# 2. Claude modifie la logique pure
edit("src/TankModule.cpp")

# 3. Test instantané
cmake . && make tank-module
./build/tank-module

# 4. Hot-reload dans le jeu
# Aucune recompilation complète !

3. Parallel Development

Point 8 - Développement Parallèle : Multiple instances Claude Code simultanées sans conflits

# Instance Claude A
cd modules/tank/ && work_on("tank logic")

# Instance Claude B
cd modules/economy/ && work_on("market simulation")

# Instance Claude C
cd modules/ai/ && work_on("behavior trees")

# Zero conflicts, parallel development

Architecture de non-conflit :

• Isolation complète : Chaque module = contexte indépendant
• Builds autonomes : cmake . par module, zéro dépendance parent
• État séparé : Aucun fichier partagé entre modules
• Git-friendly : Commits isolés par module

🎯 Instructions CLAUDE.md Spécialisées

Point 9 - CLAUDE.md Spécialisés : Instructions contextuelles limitées par module

Principe révolutionnaire :

• CLAUDE.md global : Trop générique, 150+ lignes, inefficace
• CLAUDE.md par module : Ultra-spécialisé, 50 lignes max, efficacité maximale
• Instructions contextuelles : Tank ≠ Economy ≠ Factory ≠ War

Template Type par Module

modules/tank/CLAUDE.md

# Tank Module - Pure Combat Logic

## Context
You work EXCLUSIVELY on tank behavior. No networking, no threading.

## Responsibilities
- Movement: acceleration, turning, terrain interaction
- Combat: targeting, firing, armor calculations
- States: idle, moving, attacking, destroyed

## Interface Contract
Input JSON: {"type": "move", "direction": "north", "speed": 0.8}
Output JSON: {"position": [x, y], "facing": angle, "status": "moving"}

## File Limits
- TankModule.cpp: Max 250 lines
- Pure logic only: No sockets, threads, engine dependencies
- JSON in/out: All communication via JSON messages

## Build Commands
cmake . && make tank-module    # Builds tank.so
./build/tank-module           # Test standalone

NEVER leave this directory or reference parent paths!

modules/economy/CLAUDE.md

# Economy Module - Pure Market Logic

## Context
You work EXCLUSIVELY on economic simulation. No infrastructure.

## Responsibilities
- Market dynamics: supply/demand, pricing
- Trading: buy/sell orders, market makers
- Economics: inflation, market cycles

## Interface Contract
Input: {"type": "trade", "item": "steel", "quantity": 100, "action": "buy"}
Output: {"status": "executed", "price": 5.2, "total": 520.0}

## Focus Areas
1. Market algorithms (supply/demand curves)
2. Price discovery mechanisms
3. Economic modeling

NEVER reference networking, threading, or parent directories!

Contraintes Strictes pour Claude

1. NEVER cd .. ou référence parent
2. ALWAYS cmake . (pas cmake ..)
3. ONLY JSON communication avec autres modules
4. MAX 300 lignes par fichier
5. ZERO infrastructure code dans le contexte

🔧 Build System Cognitif

Autonomous Build : Zero Mental Overhead

# modules/tank/CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(TankModule)  # Self-contained

# Everything local
include_directories(shared)
add_library(tank-module SHARED src/TankModule.cpp)

# Local build directory
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/build)

Avantage Claude : Aucun concept de "projet parent" à comprendre !

Hot-Reload pour Rapid Iteration

// Engine hot-reload automatique
class ModuleLoader {
    void reloadIfChanged(const std::string& modulePath) {
        if(fileChanged(modulePath)) {
            unloadModule(modulePath);
            loadModule(modulePath);  // Reload .so
            // Game continue sans interruption !
        }
    }
};

Workflow Claude : Edit → Save → See changes instantly in game

🧪 Testing Strategy : AI-Optimized

Unit Tests Intégrés

// Dans TankModule.cpp
#ifdef TESTING
void runTests() {
    // Test 1: Movement
    auto input = json{{"type", "move"}, {"direction", "north"}};
    auto result = process(input);
    assert(result["status"] == "moving");

    // Test 2: Combat
    input = json{{"type", "attack"}, {"target", "enemy_1"}};
    result = process(input);
    assert(result["action"] == "fire");

    std::cout << "✅ All tank tests passed!" << std::endl;
}
#endif

Standalone Testing

# Claude peut tester sans le engine complet
cd modules/tank/
make tank-module
./build/tank-module  # Run standalone avec tests intégrés

Avantage IA : Testing sans infrastructure complexe !

🔄 Hot-Reload Architecture

Module State Preservation

class TankModule {
private:
    json persistentState;  // Sauvegardé lors hot-reload

public:
    json getState() override {
        return persistentState;  // Engine sauvegarde l'état
    }

    void setState(const json& state) override {
        persistentState = state;  // Restore après reload
    }
};

Seamless Development

1. Claude modifie TankModule.cpp
2. Engine détecte file change
3. Automatic save module state
4. Reload .so avec nouveau code
5. Restore state → Game continue
6. Test immediately nouvelles modifications

🎮 Debug Mode : IA Paradise

Debug Engine Features

class DebugEngine : public IEngine {
    // Execution step-by-step pour analyse
    void stepMode() { processOneModule(); }

    // Logging détaillé pour Claude
    void verboseLogging() {
        log("Module tank input: " + input.dump());
        log("Module tank output: " + output.dump());
    }

    // Module isolation pour debugging
    void isolateModule(const std::string& name) {
        // Run ONLY this module, others = mock
    }
};

Claude Debug Workflow

# 1. Set debug mode
echo '{"debug_mode": true, "isolated_module": "tank"}' > config/debug.json

# 2. Run with step mode
./warfactory-engine --step-mode

# 3. Claude voit EXACT input/output de son module
# Perfect pour comprendre les interactions !

📊 Métriques Claude Code

Avant : Architecture Monolithique

• Context size : 50K+ lignes (impossible)
• Build time : 2-5 minutes
• Iteration cycle : Edit → Compile → Restart → Test (10+ min)
• Bug localization : Needle in haystack
• Parallel work : Impossible (conflicts)

Après : Architecture Modulaire

• Context size : 200-300 lignes (parfait)
• Build time : 5-10 secondes
• Iteration cycle : Edit → Hot-reload → Test (30 sec)
• Bug localization : Surgical precision
• Parallel work : 3+ Claude instances

ROI Development

• Claude efficiency : 10x improvement
• Development speed : 5x faster iteration
• Code quality : Higher (focused contexts)
• Bug density : Lower (isolated modules)

🚀 Advanced Claude Patterns

Pattern 1: Progressive Complexity

// Iteration 1: Basic tank (Claude commence simple)
class TankModule {
    json process(const json& input) {
        if(input["type"] == "move") return basicMove();
        return {{"status", "idle"}};
    }
};

// Iteration 2: Add combat (Claude étend)
json process(const json& input) {
    if(input["type"] == "move") return advancedMove();
    if(input["type"] == "attack") return combat();
    return {{"status", "idle"}};
}

// Iteration 3: Add AI (Claude sophistique)
// Etc... Progression naturelle

Pattern 2: Behavior Composition

// Claude peut composer behaviors facilement
class TankModule {
    MovementBehavior movement;
    CombatBehavior combat;
    AiBehavior ai;

    json process(const json& input) {
        auto context = getCurrentContext();

        if(ai.shouldMove(context)) return movement.process(input);
        if(ai.shouldAttack(context)) return combat.process(input);
        return ai.idle(context);
    }
};

Pattern 3: Data-Driven Logic

// Claude travaille avec config, pas hard-coding
class TankModule {
    json tankConfig;  // Loaded from config/tanks.json

    json process(const json& input) {
        auto stats = tankConfig["tank_mk1"];
        auto speed = stats["max_speed"].get<double>();
        auto armor = stats["armor_thickness"].get<int>();

        // Logic basée sur data, pas constantes
        return processWithStats(input, speed, armor);
    }
};

🔮 Future Claude Integration

Point 48 : AI-Driven Development

Claude Code génère modules complets via prompts naturels

# Future workflow: Natural language → Working module
User: "Create a tank module with advanced combat AI"

Claude:
1. Generates TankModule.cpp (250 lines)
2. Includes behavior trees, targeting systems
3. Auto-generates unit tests
4. Configures build system
5. Hot-reloads into running game
6. Result: Fully functional tank AI in minutes

Technical Implementation:

class AIModuleGenerator {
    json generateModule(const std::string& prompt) {
        auto spec = parseNaturalLanguage(prompt);
        auto code = generateSourceCode(spec);
        auto tests = generateUnitTests(spec);
        auto config = generateConfig(spec);

        return {
            {"source", code},
            {"tests", tests},
            {"config", config},
            {"build_commands", generateBuild(spec)}
        };
    }
};

Benefits:

• Rapid prototyping : Idée → Module fonctionnel en minutes
• AI pair programming : Claude comprend context et génère code adapté
• Automatic optimization : Claude optimise performance selon targets
• Self-validating code : Tests générés automatiquement

Point 49 : Natural Language Debugging

Debug conversation Claude vs tools complexes

# Traditional debugging (avoid)
gdb ./warfactory
(gdb) break TankModule::process
(gdb) run
(gdb) print variables...
# 20+ commands, complex analysis

# Natural Language Debugging (future)
User: "Tank moves too slowly in mud terrain"

Claude Debug Session:
🔍 Analyzing TankModule...
📊 Current speed: 28 (expected: 35)
🎯 Issue found: terrain modifier not applied correctly
📝 Location: TankModule.cpp line 142
⚡ Suggested fix: Update terrain calculation
✅ Fix applied: Tank speed now correct

# Single conversation → Problem solved

Technical Architecture:

class NaturalLanguageDebugger {
    void analyzeIssue(const std::string& description) {
        // 1. Parse natural language problem description
        auto issue = parseIssueDescription(description);

        // 2. Analyze relevant module state
        auto moduleState = getModuleState(issue.moduleName);

        // 3. Compare expected vs actual behavior
        auto analysis = performAnalysis(issue, moduleState);

        // 4. Generate human-readable explanation
        auto explanation = generateExplanation(analysis);

        // 5. Suggest specific fixes
        auto suggestions = generateFixSuggestions(analysis);

        // 6. Apply fixes if approved
        if(user.approves(suggestions)) {
            applyFixes(suggestions);
        }
    }
};

Debug Conversation Examples:

User: "Economy module prices seem unstable"
Claude: Detected oscillation in price calculation. Market clearing frequency too high.
        Suggested fix: Reduce clearing cycle from 1h to 4h.

User: "Tank targeting is weird"
Claude: Found issue: Target selection prioritizes distance over threat.
        Current: target = findClosest(enemies)
        Better: target = findBestThreat(enemies, threatMatrix)

User: "Factory belt isn't working"
Claude: Belt module shows input blockage.
        Problem: Inserter rate 30/min > Belt capacity 20/min
        Fix: Upgrade belt or reduce inserter speed

Benefits:

• Intuitive debugging : Description naturelle → Solution précise
• Context-aware analysis : Claude comprend module interactions
• Proactive suggestions : Fixes suggérés avant implementation
• Learning system : Claude améliore analysis avec experience

---

Conclusion

Cette architecture transforme Claude Code d'un assistant de développement en développeur principal capable de créer des systèmes de jeu complexes de manière autonome.

Clé du succès : Réduire la complexité cognitive à un niveau où l'IA peut exceller, tout en maintenant la puissance architecturale nécessaire pour un jeu AAA.