warfactoryracine/docs/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

# 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

🎯 Instructions CLAUDE.md Spécialisées

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

AI-Driven Development

1. Claude génère modules complets
2. Hot-reload testing automatique
3. AI balancing via config changes
4. Behavior learning from player data

Natural Language Debugging

# Future : Claude debug with natural language
claude> "Why is tank_mk1 slower than expected?"
debug> Analyzing TankModule... speed config: 35, current: 28
debug> Issue found: terrain modifier not applied correctly
debug> Suggesting fix in TankModule.cpp line 142

---

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.