getting started

Getting Started Guide

📍 Navigation : README → Getting Started

Guide complet pour démarrer avec AI Agent Kit.

#tags: installation, configuration, setup, tutorial
#difficulty: débutant
#time: 15-30 minutes
#category: guide-pratique
#prerequisites: git, bash/powershell, ide

⚡ Démarrage en 5 Minutes

Étape 1 : Installation (2 min)

🔧 Nouveau : JSON Universel Cross-Platform

L'AI Agent Kit inclut maintenant une solution JSON universelle qui fonctionne sur Windows, Linux et macOS :

# Windows - Génération appsettings.json
.\scripts\create-appsettings-universal.ps1 -Path "." -Type "both"

# Windows - Génération package.json (React/Angular/Vue)
.\scripts\create-package-universal.ps1 -Path "." -FrontendType "react"

# Linux/macOS - Génération appsettings.json
./scripts/cross-platform-appsettings.sh -p "." -t "both"

# Linux/macOS - Génération package.json
./scripts/create-package-universal.sh -p "." -f "react"

Caractéristiques :

✅ Formatage LF (Unix/Linux) sur tous OS
✅ UTF8 sans BOM (compatible universel)
✅ PowerShell 5.1+ et Bash support
✅ Plus d'erreurs "objets vs chaînes"

Premiers pas — Configurer votre projet
Utilisation quotidienne — Exemples pratiques
Plateformes supportées — Claude Code, ChatGPT, etc.
Synchronisation des agents — Hook Git automatique

Concepts clés

Qu'est-ce que AI Agent Kit ?

C'est un système d'agents IA qui automatise le développement logiciel. Il fonctionne avec n'importe quel assistant IA (Claude, ChatGPT, Gemini, etc.).

Les 3 composants principaux

Composant	Rôle	Exemple
Agents	Spécialistes dans une tâche	`@architect`, `@developer`, `@tester`
Workflows	Séquences automatisées d'agents	`@chain:backend-feature`
Wizard	Configuration interactive	`@wizard:new-project`

Flux de travail

Installation : Le script installe les agents dans votre projet
Configuration : Le wizard configure votre stack technique
Développement : Les agents créent votre code, tests et documentation

Installation

Installation avec wizard (recommandé)

Le script universel détecte automatiquement votre OS et lance l'installation appropriée.

🔧 Nouveauté v2.1 : Solution cross-platform JSON avec formatage correct sur Windows, Linux et Mac !

Universel (tous OS)

curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash

Windows PowerShell

# Installation locale (si le kit est déjà téléchargé)
.\install.ps1

# Installation directe depuis GitHub
iwr -useb https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/install.ps1 | powershell -c -

Linux/Mac Bash

# Installation locale (si le kit est déjà téléchargé)
./scripts/install.sh

# Installation directe depuis GitHub
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/install | bash

🆕 Nouveau v2.1 : Les scripts Bash/Linux/Mac incluent maintenant la génération JSON cross-platform !

Windows WSL (Utilisation scripts Linux sous Windows)

# Smart Wizard Linux sous Windows
wsl -e bash -c "cd /mnt/c/Users/votre/chemin/ai-agent-kit && ./scripts/smart-wizard-linux.sh --help"

Le script affiche un menu interactif :

╔══════════════════════════════════════════════════════════════╗
║           🚀 AI Agent Kit - Installation                 ║
╚══════════════════════════════════════════════════════════════╝

Détecté: Windows PowerShell
Comment souhaitez-vous configurer votre projet ?

  1) 🧙 Wizard interactif (recommandé pour nouveaux projets)
  2) ⚡ Installation rapide .NET 10
  3) ⚡ Installation rapide Node.js 25
  4) ⚡ Installation rapide Python 3.13
  5) ⚡ Installation rapide Java 21
  6) ⚡ Installation rapide Go 1.22
  7) ⚡ Installation rapide Rust 1.75
  8) ⚡ Installation rapide React 19
  9) ⚡ Installation rapide Angular 19
 10) ⚡ Installation rapide Vue 3
 11) ⚡ Installation rapide Svelte 5
 12) ⚡ Installation rapide Next.js 15
 13) ⚡ Installation rapide Nuxt 3
 14) 🔧 Multi-stack (Backend + Frontend)

Installation rapide (stack spécifique)

Si vous connaissez déjà votre stack, vous pouvez l'installer directement :

.NET 10

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=dotnet

Node.js 25

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=nodejs

Python 3.13

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=python

React 19

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=react

Angular 19

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=angular

Vue 3

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=vue

Svelte 5

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=svelte

Next.js 15

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=nextjs

Nuxt 3

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=nuxt

Java 21

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=java

Go 1.22

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=go

Rust 1.75

# Universel
curl -fsSL https://raw.githubusercontent.com/krovomi/ai-agent-kit/main/scripts/install | bash -s -- --stack=rust

Premiers pas

1. Lancer le wizard

Après l'installation, ouvrez votre assistant IA et tapez :

@wizard:new-project

2. Répondre aux questions

Le wizard vous posera des questions simples :

🔹 Quel type de projet voulez-vous créer ?
   1. 🔌 API REST
   2. 🌐 Application Web Fullstack
   3. 🎨 Frontend uniquement

> 1

🔹 Quel stack backend ?
   1. .NET 10
   2. Node.js 22
   3. Python 3.13
   4. Java 21
   5. Go 1.22
   6. Rust 1.75

> 1

🔹 Quelle base de données ?
   1. PostgreSQL 17
   2. Supabase (PostgreSQL + Services)
   3. MongoDB 8.0
   4. SQLite

> 2

🔹 Authentification requise ?
   1. JWT
   2. OAuth
   3. Non

> 1

3. Valider la configuration

## Récapitulatif
| Élément | Choix |
|---------|-------|
| Type | API REST |
| Backend | .NET 10 |
| Database | PostgreSQL 17 |
| Auth | JWT |

✅ Générer le projet ?

Le wizard va alors :

Créer la structure de dossiers
Configurer les fichiers de base
Préparer les agents pour votre stack

Utilisation quotidienne

Avec Claude Code (recommandé)

Claude Code intègre nativement les commandes slash :

# Créer une nouvelle feature
/feature Ajouter la gestion des utilisateurs avec CRUD

# Corriger un bug
/bugfix L'utilisateur ne peut pas se connecter après 3 essais

# Faire une review complète
/review src/controllers/AuthController.cs

# Explorer le code
/explore Expliquer le module de paiement

# Planifier sans modifier
/plan Refactorer le module de paiement

# Audit de sécurité
/security Vérifier le module d'authentification

# Optimiser les performances
/optimize Améliorer les performances de la recherche

Avec tous les assistants IA

Utilisez la syntaxe @ universelle :

# Workflows complets
@chain:backend-feature "Add product catalog with pagination"
@chain:frontend-feature "Create user dashboard"
@chain:fullstack-feature --backend=dotnet --frontend=react "Add blog system"
@chain:bugfix "Fix null reference in UserService"
@chain:refactor "Optimize database queries"

# Agents individuels
@api-integrator "Generate TypeScript types from API"
@architect "Design authentication module"
@developer "Implement user entity"
@error-handler "Add error handling to UserService"
@frontend-developer "Create React components"
@integration-tester "Test API endpoints"
@performance-optimizer "Fix N+1 queries"
@reviewer "Review security vulnerabilities"
@security-hardener "Add OWASP protections"
@test-data-generator "Create test fixtures"
@unit-tester "Write tests for UserService"

# Wizards
@wizard:add-component    # Ajouter un composant
@wizard:new-project      # Nouveau projet

Mode Headless (CLI/CI/CD)

Pour l'automatisation et l'intégration continue :

# Utilisation de base en CLI
claude -p "Que fait le module d'auth ?"

# Sortie JSON structurée
claude -p "Résumer ce projet" --output-format json

# Autoriser automatiquement certains outils
claude -p "Lancer les tests et corriger les échecs" --allowedTools "Bash,Read,Edit"

Pour des exemples complets, voir : Headless/CLI Guide

Exemples pratiques

Backend seulement

@chain:backend-feature "Add Products API with pagination and filters"

→ Crée : Entités, DTOs, Repository, Service, Controller, Tests unitaires, Tests d'intégration

Fullstack

@chain:fullstack-feature --backend=dotnet --frontend=react "Add user management"

→ Crée :

Backend : API CRUD + Tests
Frontend : Composants React + Hooks TanStack Query + Types

Intégration API existante

@chain:api-integration --api-path="../backend-dotnet"

→ Génère : Types TypeScript, client API, hooks React, mocks

Supabase : PostgreSQL + Services

Supabase est une option populaire qui combine PostgreSQL avec des services cloud supplémentaires.

Pour choisir Supabase ?

Avantages :

PostgreSQL avec extensions (PostGIS, pgvector)
Authentification intégrée (email, OAuth, SAML)
Stockage de fichiers avec CDN
Real-time subscriptions (WebSocket)
Edge Functions (serverless)
Interface d'administration web

Inconvénients :

Dépendance à un service externe
Limitations gratuites (500MB DB, 1GB Storage)
Moins de contrôle sur l'infrastructure

Configuration avec AI Agent Kit

Choisissez "Supabase" dans le wizard (base de données)
Le scaffold génère :
- SupabaseService.cs : Client CRUD pour l'API Supabase
- DbContext.cs : EF Core avec connexion Supabase
- appsettings.json : Configuration des clés Supabase
- README-Supabase.md : Guide de configuration détaillé

Après génération :

# Configurez vos clés dans appsettings.json
{
  "Supabase": {
    "Url": "https://votre-projet.supabase.co",
    "Key": "votre-anon-key"
  }
}

Exemples d'utilisation

// CRUD avec le service Supabase
var userService = new SupabaseService(config);

// Créer un utilisateur
var user = await userService.Create(new User { Email = "test@example.com" });

// Authentification
var auth = new SupabaseClient(url, key);
await auth.Auth.SignUp("email@example.com", "password");

Styles de sortie (Output Styles)

Les output styles modifient la manière dont Claude interagit avec vous pour s'adapter à différents besoins d'apprentissage.

Styles disponibles

📚 Explanatory

Fournit des insights éducatifs entre l'aide pour accomplir les tâches d'ingénierie logicielle.

Idéal pour :

Comprendre les choix d'implémentation
Apprendre les patterns de design
Explorer les alternatives et trade-offs

Activation :

/output-style explanatory

🎓 Learning

Mode collaboratif où vous implémentez vous-même des parties du code.

Idéal pour :

Apprentissage par la pratique
Renforcer la compréhension
Développer l'autonomie

Activation :

/output-style learning

Styles spécialisés

.NET Explanatory

Style explanatory spécialisé pour l'écosystème .NET avec focus sur :

Patterns C# modernes
Best practices Microsoft
Entity Framework Core
Architecture .NET

React Learning

Style learning spécialisé pour React avec :

Hooks progressifs
Patterns modernes
Tests avec React Testing Library
Écosystème React

Utilisation

# Changer le style de sortie
/output-style explanatory
/output-style learning
/output-style dotnet-explanatory
/output-style react-learning

# Menu interactif
/output-style

# Configurer comme défaut
/output-style explanatory --save

Créer votre propre style

Créez un fichier dans .claude/output-styles/mon-style.md :

---
name: mon-style
description: Description de ce que fait ce style
keep-coding-instructions: true
---

# Instructions personnalisées

Vous êtes un assistant qui...
[Vos instructions ici]

Plateformes supportées

Le kit fonctionne avec tous les assistants IA :

Plateforme	Type	Configuration requise
Claude Code (CLI/IDE)	Desktop	Automatique avec commandes slash + mode headless
Windsurf	Desktop	Script `integrate.sh -p windsurf`
Antigravity	Desktop	Template `AI-SETUP.md` dédié
OpenCode	Desktop	Template `AI-SETUP.md` dédié
Cursor	Desktop	Ajouter `AGENTS.md` dans `.cursorrules`
Continue	Desktop	Ajouter dans `config.json`
Aider	Desktop	Inclure via `.aider.conf.yml`
---	---	---
Claude Code (Web)	Web	Installation manuelle des agents
Claude.ai	Web	Projects → Coller `AGENTS.md` dans Instructions
GitHub Copilot	Web	Créer `.github/copilot-instructions.md`
ChatGPT	Web	Custom Instructions ou GPT personnalisé
---	---	---
CI/CD	Automation	Support JSON/CLI pour GitHub Actions, GitLab CI

Astuces par plateforme

Claude Code

Utilisez Shift+Tab pour le mode Plan (analyse sans modifier)
Nommez vos sessions : /rename auth-feature
Référencez des fichiers : @src/models/User.cs

Autres plateformes

Gardez AGENTS.md ouvert dans un onglet
Copiez-collez les commandes au besoin
Utilisez le contexte pour inclure vos fichiers

Synchronisation des agents

🔄 Hook Git automatique

AI Agent Kit utilise un hook Git pour synchroniser automatiquement les agents entre deux formats :

📁 Double format d'agents

Répertoire	Format	Usage
`.ai-agents/agents/`	Universel (Markdown)	Édition manuelle
`.claude/agents/`	Claude Code (structuré)	Utilisation IDE

⚙️ Fonctionnement automatique

# Quand vous modifiez un fichier :
echo "# Modification" >> .ai-agents/agents/common/developer.md

# Et que vous faites un commit :
git add .ai-agents/agents/common/developer.md
git commit -m "update: improve developer agent"

# Le hook s'exécute automatiquement :
🔄 Checking for agent changes...
📝 Agent files detected, running synchronization...
✅ Synchronized 13 agents!
📁 Added synchronized agents to commit

🎯 Avantages

Édition unique - Vous ne modifiez que les fichiers .ai-agents/
Synchronisation transparente - Pas besoin de penser au format Claude
Compatibilité - Fonctionne avec tous les outils AI
Consistance - Évite les divergences entre formats

🛠️ Scripts manuels

Si nécessaire, vous pouvez lancer la synchronisation manuellement :

PowerShell (Windows)

powershell -ExecutionPolicy Bypass -File "scripts/sync-agents.ps1"

Bash (Linux/macOS/WSL)

bash "scripts/sync-agents.sh"
bash "scripts/sync-agents.sh" --verbose  # Sortie détaillée

🔧 Maintenance

Réparer le hook

# Clone du projet
git clone https://github.com/krovomi/ai-agent-kit.git
cd ai-agent-kit

# Installation rapide
./scripts/install.sh --quick

✅ Vérification :

# Vérifier l'installation
ai-agent-kit --version
# Expected: AI Agent Kit v2.0.0

Étape 2 : Configuration (1 min)

# Configuration minimale
echo "stack: dotnet" > .ai-agents.yaml
echo "adapter: claude" >> .ai-agents.yaml

✅ Vérification :

# Valider la configuration
ai-agent-kit --validate-config
# Expected: Configuration valide

Étape 3 : Premier Agent (2 min)

# Utiliser votre premier agent
@architect "Créer une API REST simple avec .NET"

✅ Résultat attendu :

Architecture de l'API générée

GrepAI est intégré dans AI Agent Kit pour une recherche sémantique avancée :

Guide complet : Documentation GrepAI

Installation

# Activer GrepAI (déjà inclus dans l'installation)
echo "features:" > .ai-agents.yaml
echo "  extensions:" >> .ai-agents.yaml
echo "    grepai: true" >> .ai-agents.yaml

Utilisation de base

# Rechercher par signification
grepai search "authentication logic"

# Analyser les dépendances
grepai trace "UserService"

# Optimiser le contexte avant d'envoyer à l'AI
grepai search "payment processing" --limit 5

Agents spécialisés GrepAI

# Recherche sémantique
@semantic-searcher "Trouve la logique d'authentification"

# Analyse architecturale
@code-explorer "Analyse l'architecture du projet"

Configuration avancée

# Dans .ai-agents.yaml
features:
  extensions:
    grepai: true
  optimization:
    semantic_search: true
    context_reduction: true

�📑 Table des matières

Concepts clés — Comprendre le système
Installation — Configurer le kit
- Installation avec wizard
- Installation rapide (stack spécifique)
Premiers pas — Configurer votre projet
Utilisation quotidienne — Exemples pratiques
Plateformes supportées — Claude Code, ChatGPT, etc.
Synchronisation des agents — Hook Git automatique

🎯 Parcours Guidé

👤 Si vous êtes débutant

[Overview] → [Getting Started] → [Usage Guide] → [Use Cases]
   10 min        15 min           20 min         30 min

🔧 Si vous êtes développeur

[Installation] → [Configuration] → [Agents Reference] → [Integrations]
     5 min            5 min              15 min              20 min

🏢 Si vous êtes en entreprise

[Enterprise MCP] → [Architecture] → [Security] → [Headless/CLI]
      20 min           15 min         15 min              25 min

Besoin d'aide ?

Issues : GitHub Issues
Discussions : GitHub Discussions
Documentation : Documentation complète

Composant	Statut	Description
Agents	✅ Actif	81 agents spécialisés (Backend/Frontend/Common)
Commands	✅ Actif	15 commandes slash (/feature, /bugfix, /review...)
Skills	✅ Actif	8 compétences Supabase (auth, RLS, migrations...)
Stacks	✅ Actif	11 technologies (6 backends + 5 frontends)
Contextes	✅ Actif	6 configurations de stack (.NET, React, Python...)
Adapters LLM	✅ Actif	4 fournisseurs IA (Claude, GPT, Gemini, Ollama)
Platforms	✅ Actif	7 IDE supportés (Claude Code, Cursor, Continue...)
Workflows	✅ Actif	8 workflows automatisés
Scripts	✅ Actif	17 scripts utilitaires (install, sync, cloud-setup)

Prochaines étapes

Lisez le Overview pour la vue d'ensemble complète
Consultez les Use Cases pour des exemples pratiques
Lisez le Usage Guide pour des exemples avancés
Consultez Headless/CLI pour l'automatisation et CI/CD
Consultez la Reference pour la liste complète des agents
Explorez les Integrations pour les services cloud

Besoin d'aide ?

Issues : GitHub Issues
Discussions : GitHub Discussions
Documentation : Documentation complète

📚 Ressources

🤝 Contribuer

Les contributions sont bienvenues ! Voir CONTRIBUTING.md

This documentation is automatically synced from the main repository.

Navigation

Home

Getting Started
- Installation
- Project Structure