Claude Code pour votre projet web : guide complet

Introduction à Claude Code

Claude Code est la plateforme d'Anthropic qui permet d'intégrer Claude (l'IA) dans vos projets web. Ce n'est pas juste une API, c'est un système complet pour construire des agents intelligents.

Les trois piliers de Claude Code sont :

• Agent — L'intelligence qui prend les décisions
• Skill — Les capacités (actions) qu'il peut faire
• Memory — La mémoire persistante (souviens-toi de ça)

Ensemble, ils créent un système où Claude devient autonome et contextuel, capable de gérer des tâches complexes sans intervention humaine constante.

Les concepts clés

Avant de commencer, comprendre ces 5 concepts :

Agent — L'intelligence centrale

Un Agent est une instance de Claude configurée pour prendre des décisions autonomes et exécuter des tâches.

Caractéristiques d'un Agent :

• Autonome — Prend ses propres décisions (pas juste répondre à des questions)
• Contextuel — Peut accéder à des informations (fichiers, base de données via Skills)
• Itératif — Peut faire plusieurs étapes pour résoudre un problème
• Actionneur — Peut déclencher des actions via les Skills

Exemple mental :

Vous dites : "Trie mon backlog GitHub par priorité"

L'Agent :

1. Réfléchit : "Je dois accéder à GitHub via une Skill"
2. Exécute : Appelle la Skill "fetch_github_issues"
3. Analyse : "Voici les issues, je les trie par priorité"
4. Agit : Appelle la Skill "update_github_labels" pour tagger les issues
5. Rapporte : "Fait ! Voici le résumé"

Skill — Ajouter des capacités

Une Skill est une fonction/action que vous donnez à Claude Code. C'est comment l'Agent interagit avec le monde réel.

Exemples de Skills :

• 📧 "send_email" → Envoyer un email
• 🗄️ "query_database" → Lire/écrire en base de données
• 📁 "read_file" → Lire un fichier du serveur
• 🌐 "fetch_api" → Appeler une API externe (GitHub, Stripe, etc.)
• 📝 "create_document" → Créer un fichier/document
• 🔍 "search_web" → Chercher sur le web

Comment fonctionne une Skill :

// Skill simple : envoyer un email
const skill_send_email = {
  name: "send_email",
  description: "Envoyer un email à un utilisateur",
  parameters: {
    to: "email de destination",
    subject: "sujet",
    body: "contenu du mail"
  }
};

// L'Agent peut décider :
// "Je dois envoyer un email de bienvenue"
// → Appelle send_email({ to: "user@example.com", ... })

Règles importantes pour les Skills :

• Nommer clairement : "send_email" pas "s_e" ou "mail"
• Description détaillée : Claude doit savoir quand l'utiliser
• Paramètres précis : "user_id: integer" pas "user_id: anything"
• Retour explicite : "Succès : email envoyé" vs "Erreur : email invalide"
• Sécurité : Valider les inputs (pas d'injection SQL)

Memory — Persistent storage

La Memory est le système de mémoire persistante. C'est comment Claude se souvient entre les sessions.

Types de Memory :

1. Short-term Memory (contexte actuel)

• Durée : Une conversation/session (quelques minutes à quelques heures)
• Usage : Contexte de la conversation actuelle
• Exemple : "L'utilisateur a dit X, je dois m'en souvenir pour répondre"

2. Long-term Memory (données persistentes)

• Durée : Plusieurs sessions (jours, mois, années)
• Usage : Instructions, préférences, historique utilisateur
• Exemple : "Cet utilisateur préfère les réponses courtes, le mémoriser"

// Exemple Memory
memory = {
  instructions: [
    "Toujours être poli",
    "Cet utilisateur est un développeur, parle technique",
    "Langue préférée : français"
  ],
  user_preferences: {
    language: "fr",
    response_style: "concis",
    timezone: "Europe/Paris"
  },
  historical_data: {
    previous_interactions: [...],
    completed_tasks: [...]
  }
}

Où stocker la Memory :

Architecture Claude Code

Architecture générale :

┌─────────────────────────────────────────────────────┐
│              Votre Application Web                  │
│  (Frontend React/Vue + Backend Node/Python/PHP)    │
└────────┬────────────────────────────────┬───────────┘
         │                                │
         ▼                                ▼
   ┌──────────────┐           ┌──────────────────────┐
   │   Frontend   │           │   Backend API        │
   │ (Interface)  │           │  (Logique métier)    │
   └──────┬───────┘           └──────┬───────────────┘
          │                          │
          └──────────┬───────────────┘
                     ▼
          ┌──────────────────────┐
          │   Claude Code Agent  │
          │  (L'IA autonome)     │
          └──────┬───────────────┘
                 │
         ┌───────┴────────┬─────────────┐
         ▼                ▼             ▼
    ┌─────────┐      ┌────────┐   ┌─────────┐
    │  Skill  │      │ Memory │   │  Tools  │
    │  Layer  │      │ Layer  │   │ (MCP)   │
    └────┬────┘      └────┬───┘   └────┬────┘
         │                │            │
    ┌────▼────────────────▼────────────▼──┐
    │  Connecteurs externes              │
    │  - Email, API, Database, Files...   │
    └───────────────────────────────────┘

Flux d'une requête :

1. Utilisateur demande quelque chose via votre site web
2. Backend reçoit la demande
3. Backend crée/lance un Agent Claude Code
4. Agent charge sa Memory (contexte, instructions)
5. Agent pense : "Je dois faire X, Y, Z"
6. Agent exécute les Skills nécessaires (appels API, BDD, etc.)
7. Agent retourne un résultat au backend
8. Backend envoie la réponse au frontend
9. Utilisateur voit le résultat

Intégrer dans un projet web

Étapes pour ajouter Claude Code à votre projet :

Étape 1 : Installer le SDK Claude Code

// Node.js / JavaScript
npm install @anthropic-sdk/sdk

// Python
pip install anthropic

// PHP (via Composer)
composer require anthropic/sdk

Étape 2 : Créer votre Agent avec Memory

// Exemple Node.js
const Anthropic = require('@anthropic-sdk/sdk');

const agent = new Anthropic.Agent({
  name: "MonAgentWeb",
  instructions: [
    "Tu es un assistant pour notre site web de commerce",
    "Tu as accès aux skills: create_order, fetch_product, send_email",
    "Sois toujours poli et professionnel"
  ],
  memory: {
    user_id: "user123",
    preferences: { language: "fr" }
  }
});

Étape 3 : Définir vos Skills

const skills = [
  {
    name: "create_order",
    description: "Créer une commande pour un utilisateur",
    parameters: {
      user_id: "string",
      product_id: "string",
      quantity: "integer"
    }
  },
  {
    name: "send_email",
    description: "Envoyer un email de confirmation",
    parameters: {
      email: "string",
      subject: "string",
      body: "string"
    }
  }
];

agent.addSkills(skills);

Étape 4 : Exécuter l'Agent

// Dans votre endpoint API
app.post('/api/chat', async (req, res) => {
  const userMessage = req.body.message;

  // Lancer l'Agent
  const response = await agent.process(userMessage);

  // Retourner au frontend
  res.json({ response: response });
});

Étape 5 : Connecter au Frontend

// React / Vue
const handleUserRequest = async (message) => {
  const response = await fetch('/api/chat', {
    method: 'POST',
    body: JSON.stringify({ message })
  });

  const data = await response.json();
  displayResult(data.response);
};

Exemple pratique complet

Cas d'usage : Assistant de gestion de tâches pour un site de productivité

// 1. Créer l'Agent
const taskAgent = new Agent({
  name: "TaskManager",
  instructions: [
    "Tu gères les tâches des utilisateurs",
    "Tu peux créer, modifier, et archiver des tâches",
    "Sois toujours en français"
  ],
  memory: {
    workspace_id: "ws123",
    user_timezone: "Europe/Paris",
    working_hours: "9-17"
  }
});

// 2. Définir les Skills
taskAgent.addSkills([
  {
    name: "create_task",
    description: "Créer une nouvelle tâche",
    parameters: {
      title: "string",
      description: "string",
      due_date: "date",
      priority: "high|medium|low"
    }
  },
  {
    name: "fetch_tasks",
    description: "Récupérer toutes les tâches",
    parameters: {
      status: "open|closed|all"
    }
  },
  {
    name: "send_notification",
    description: "Envoyer une notification à l'utilisateur",
    parameters: {
      message: "string",
      type: "email|in-app|sms"
    }
  }
]);

// 3. Lancer l'Agent
const userRequest = "Crée-moi une tâche 'Finir rapport' pour demain à 17h, priorité haute";

const result = await taskAgent.process(userRequest);

// Résultat :
// Agent pense: "L'utilisateur veut créer une tâche"
// → Appelle skill create_task avec les bons paramètres
// → Appelle skill send_notification pour confirmer
// → Retourne: "Tâche créée avec succès ! Notification envoyée."

Ce qui s'est passé :

1. Agent reçoit la requête en français naturel
2. Agent comprend l'intention (créer une tâche)
3. Agent extrait les paramètres (title, due_date, priority)
4. Agent exécute skill create_task
5. Agent envoie une notification
6. Agent retourne un message de confirmation

Bonnes pratiques

1. Memory — Soyez explicite dans les instructions

// ❌ Mauvais : flou
memory: {
  instructions: ["Aide l'utilisateur"]
}

// ✅ Bon : détaillé et contextuel
memory: {
  instructions: [
    "Tu es un support client e-commerce",
    "L'utilisateur est un client VIP (depuis 3 ans)",
    "Offre des réductions jusqu'à 20%",
    "Réponds toujours en français",
    "Sois courtois et rapide"
  ]
}

2. Skills — Nommer et documenter clairement

// ❌ Mauvais : pas clair
{ name: "db_op", description: "Faire un truc en BDD" }

// ✅ Bon : précis et actionnable
{
  name: "fetch_user_orders",
  description: "Récupérer toutes les commandes d'un utilisateur",
  parameters: {
    user_id: "integer (obligatoire)",
    status: "string (open|shipped|delivered, optionnel)"
  },
  returns: "Array of orders with id, date, total, status"
}

3. Sécurité — Valider les inputs

// Dans chaque Skill
const validateInput = (parameters) => {
  // Valider user_id
  if (!parameters.user_id || typeof parameters.user_id !== 'number') {
    throw new Error("user_id invalide");
  }

  // Valider email
  if (!isValidEmail(parameters.email)) {
    throw new Error("email invalide");
  }

  // Pas d'injection SQL
  const sanitized = sanitizeSQL(parameters.query);

  return true;
};

4. Gestion d'erreurs

// ✅ Retourner des erreurs claires
try {
  await skill_create_order({ user_id, product_id });
  return { success: true, message: "Commande créée" };
} catch (error) {
  return {
    success: false,
    error: "user_id invalide ou produit inexistant",
    code: "ORDER_CREATION_FAILED"
  };
}

5. Tester votre Agent

// Test : Agent peut-il accomplir sa tâche ?
const testCases = [
  { input: "Crée une tâche", expected: "Skill create_task appelée" },
  { input: "Montre mes tâches", expected: "Skill fetch_tasks appelée" },
  { input: "Spam attack !@#$%", expected: "Rejeté pour sécurité" }
];

testCases.forEach(test => {
  const result = await agent.process(test.input);
  assert(result.includes(test.expected));
});

Conclusion

Claude Code transforme votre site web en système intelligent. Au lieu d'avoir un chatbot basique, vous avez une IA autonome capable de lire vos données, prendre des décisions, et agir.