Skip to content

configuration reference

Jump to bottom
GitHub Actions edited this page Jan 29, 2026 · 7 revisions

Configuration Reference

📋 Vue d'ensemble

.ai-agents.yaml est le fichier de configuration principal de votre projet AI Agent Kit.

⚠️ IMPORTANT : Ce fichier est FONCTIONNEL - le système le lit pour savoir comment travailler avec votre projet.

🏗️ Structure complète (v2.0)

# =====================================
# Configuration des Agents IA
# =====================================
# 
# CE FICHIER :
# - Est la CONFIGURATION PRINCIPALE de votre projet AI Agent Kit
# - DÉFINIT comment les agents doivent travailler avec votre code
# - EST FONCTIONNEL : le système lit ce fichier pour fonctionner
# - DOIT ÊTRE ADAPTÉ selon votre stack technologique
#
# MODIFICATIONS :
# - Modifiez les valeurs selon vos besoins
# - Les commentaires servent de guide et de documentation
# - Sauvegardez après chaque modification
#
# EXEMPLE :
# Pour un projet .NET + React, configurez :
# - stacks: [dotnet, react] (multi-stacks)
# OU
# - stack: dotnet (backend principal)
# - contexts.dotnet: true (activer .NET)
# - contexts.react: true (activer React)

library:
  source: ".ai-agents"
  version: "2.0"

# Adaptateur LLM (claude | openai | gemini | ollama)
adapter: claude

# Contexte Technologique
# ===================
# DÉFINIT votre stack de développement principal
# - stack : Framework principal (backend par défaut pour fullstack)
# - stacks : Liste de stacks (pour projets multi-stacks)
# - version : Version du framework (utilise les variables d'environnement)
# - patterns : Architecture logicielle à appliquer
context:
  # Option 1 : Stack unique (pour projets simples)
  stack: dotnet                                     # OPTIONS : dotnet | nodejs | python | react | angular
  
  # Option 2 : Multi-stacks (pour projets fullstack)
  # stacks: [dotnet, react]                         # EXEMPLE : backend + frontend
  # stacks: ["dotnet", "react"]                     # FORMAT : liste YAML
  
  version: "{{ dotnet_version | default('10.0') }}" # VERSION .NET (8.0, 9.0, 10.0...)
  patterns: clean-architecture                      # OPTIONS : clean-architecture | n-tier | hexagonal

# Flags de Fonctionnalités Modulaires
# =================================
# CONTRÔLE ce qui est activé dans AI Agent Kit
# - core : Fonctionnalités de base (garder activé)
# - adapters : Connexions avec les plateformes
# - extensions : Fonctionnalités optionnelles
# - contexts : Technologies spécifiques à activer

features:
  # Modules principaux (toujours activés)
  # ====================================
  # NÉCESSAIRES pour le fonctionnement de base
  core:
    agents: true          # Agents IA (architect, developer, tester...)
    workflows: true       # Chaînes de travail (scaffold, feature...)
    templates: true       # Templates de code

  # Adaptateurs
  # ==========
  # Connexions avec les outils externes
  adapters:
    mcp: true                            # Support du protocole MCP (Model Context Protocol)
    cli: true                            # Interface ligne de commande
    api: false                           # Serveur API REST (désactiver pour l'instant)

  # Extensions (optionnelles)
  # =======================
  # Fonctionnalités additionnelles
  extensions:
    context7: true                       # Documentation à jour et contextuelle
    supabase: false                      # Intégration Supabase (base de données)
    grepai: false                        # Recherche sémantique de code (100% local)
    custom: []                           # Liste des extensions personnalisées

  # Contextes (spécifiques à la technologie)
  # ======================================
  # ACTIVEZ les technologies que vous utilisez
  contexts:
    dotnet: true        # ← ACTIVER pour projets .NET
    react: true         # ← ACTIVER pour projets React
    nodejs: false       # Désactiver si pas utilisé
    angular: false      # Désactiver si pas utilisé

# Préférences des Agents
agents:
  default_model: claude-opus-4-5-20251101 # claude-3-5-haiku-20241022 | claude-3-5-sonnet-20241022 | claude-opus-4-5-20251101 | inherit
  context_mode: full                      # minimal | standard | full
  timeout: 300                            # Délai d'attente de l'agent en secondes

# Paramètres des Workflows
workflows:
  auto-gates: true                        # Vérifier build/tests entre les phases
  max_iterations: 20                      # Nombre maximum de tentatives
  error_handling: continue                # stop | continue | retry

# Paramètres de Développement
development:
  debug_mode: false                       # Activer le mode debug
  log_level: info                         # debug | info | warn | error
  save_transcripts: true                  # Sauvegarder les conversations des agents

# Sécurité
security:
  restrict_tools: false                   # Appliquer les restrictions d'outils par agent
  sandbox_mode: false                     # Isoler les agents du système
  audit_log: true                         # Journaliser toutes les actions des agents

# Configuration MCP (Model Context Protocol)
mcp:
  enabled: true                           # Activer les serveurs MCP pour ce projet
  server_mode: true                       # Mode serveur MCP
  auto_discover: true                     # Découvrir automatiquement les serveurs MCP

  # Paramètres d'Intégration MCP
  integration:
    map_prompts_to_slash: true            # Mapper les prompts MCP en commandes /
    auto_auth: true                       # Déclencher automatiquement OAuth si disponible
    fallback_to_agents: true              # Utiliser les agents si le serveur MCP n'est pas disponible

# Chargement Modulaire
modular:
  lazy_loading: true                      # Charger les modules à la demande
  cache_enabled: true                     # Mettre en cache les modules chargés
  parallel_load: true                     # Charger les modules compatibles en parallèle

📚 Sections détaillées

Library

library:
  source: ".ai-agents"              # Source locale des agents
  version: "2.0"                    # Version du système

Adapter

adapter: claude                      # Adaptateur LLM principal

# Options disponibles :
# - claude      : Anthropic Claude (recommandé)
# - openai      : OpenAI GPT
# - gemini      : Google Gemini
# - ollama      : Ollama (local)

Context (Stack principal)

context:
  # Option 1 : Stack unique
  stack: dotnet                     # Stack principal pour les agents
  version: "10.0"                   # Version du framework
  patterns: clean-architecture      # Architecture logicielle

  # Option 2 : Multi-stacks (NOUVEAU)
  stacks: [dotnet, react]           # Liste de stacks pour projets fullstack
  version: "{{ dotnet_version | default('10.0') }}"
  patterns: clean-architecture

Stack disponibles :

  • dotnet : .NET (backend par défaut pour fullstack)
  • nodejs : Node.js/TypeScript
  • python : Python/FastAPI
  • react : React (frontend uniquement)
  • angular : Angular (frontend uniquement)

Patterns disponibles :

  • clean-architecture : Clean Architecture (recommandé)
  • n-tier : N-Tier Architecture
  • hexagonal : Hexagonal Architecture

🆕 Multi-stacks (v2.1+)

Pour les projets fullstack, utilisez le format stacks :

# Fullstack .NET + React
stacks: [dotnet, react]

# Fullstack .NET + Angular
stacks: [dotnet, angular]

# Backend uniquement
stacks: [dotnet]

# Frontend uniquement
stacks: [react]

Avantages :

  • Plus clair : Une seule ligne pour définir toutes les stacks
  • Cohérent : Format uniforme pour single et multi-stacks
  • Auto-généré : L'installateur crée automatiquement ce format

Features (Contrôle des fonctionnalités)

Core (toujours activés)

core:
  agents: true                     # Agents IA (architect, developer...)
  workflows: true                  # Workflows automatisés
  templates: true                  # Templates de code

Adapters (intégrations externes)

adapters:
  mcp: true                       # Model Context Protocol
  cli: true                       # Interface ligne de commande
  api: false                      # Serveur API REST

Extensions (optionnelles)

extensions:
  context7: true                  # Documentation contextuelle
  supabase: false                 # Intégration Supabase
  grepai: false                   # Recherche sémantique
  custom: []                      # Extensions personnalisées

Contextes (technologies spécifiques)

contexts:
  dotnet: true                    # ← ACTIVER pour projets .NET
  react: true                     # ← ACTIVER pour projets React
  nodejs: false                   # Désactiver si non utilisé
  angular: false                  # Désactiver si non utilisé

Agents (préférences des agents)

agents:
  default_model: claude-opus-4-5-20251101  # Modèle LLM par défaut
  context_mode: full                      # Niveau de contexte
  timeout: 300                            # Timeout en secondes

# Modèles disponibles :
# - claude-3-5-haiku-20241022    : Rapide, économique
# - claude-3-5-sonnet-20241022   : Équilibré
# - claude-opus-4-5-20251101     : Plus puissant
# - inherit                     : Hériter de l'adaptateur

# Modes de contexte :
# - minimal    : Contexte réduit (économie tokens)
# - standard   : Contexte standard (recommandé)
# - full       : Contexte complet

Workflows (paramètres des workflows)

workflows:
  auto-gates: true                # Vérifier build/tests automatiquement
  max_iterations: 20              # Nombre max de tentatives
  error_handling: continue         # stop | continue | retry

Development (paramètres de développement)

development:
  debug_mode: false               # Mode debug
  log_level: info                 # debug | info | warn | error
  save_transcripts: true          # Sauvegarder les conversations

Security (paramètres de sécurité)

security:
  restrict_tools: false           # Restreindre les outils par agent
  sandbox_mode: false             # Mode isolé
  audit_log: true                 # Journaliser les actions

MCP (Model Context Protocol)

mcp:
  enabled: true                   # Activer MCP
  server_mode: true               # Mode serveur MCP
  auto_discover: true             # Découverte automatique

  integration:
    map_prompts_to_slash: true    # Mapper prompts en commandes /
    auto_auth: true               # OAuth automatique
    fallback_to_agents: true      # Utiliser agents si MCP indisponible

Modular (chargement modulaire)

modular:
  lazy_loading: true              # Charger à la demande
  cache_enabled: true             # Mettre en cache
  parallel_load: true            # Charger en parallèle

🎯 Exemples de configuration par stack

.NET + React (Fullstack)

# Configuration recommandée pour projet .NET + React
context:
  stack: dotnet                                     # Backend principal
  version: "{{ dotnet_version | default('10.0') }}"
  patterns: clean-architecture

features:
  core:
    agents: true
    workflows: true
    templates: true
  adapters:
    mcp: true
    cli: true
  contexts:
    dotnet: true        # ← Backend .NET
    react: true         # ← Frontend React
    nodejs: false
    angular: false

Node.js + Angular (Fullstack)

# Configuration pour projet Node.js + Angular
context:
  stack: nodejs                                      # Backend principal
  version: "{{ nodejs_version | default('20.0') }}"
  patterns: clean-architecture

features:
  contexts:
    dotnet: false
    react: false
    nodejs: true        # ← Backend Node.js
    angular: true       # ← Frontend Angular

Python uniquement (Backend API)

# Configuration pour projet Python/FastAPI uniquement
context:
  stack: python
  version: "{{ python_version | default('3.12') }}"
  patterns: hexagonal

features:
  contexts:
    python: true        # ← Backend Python
    dotnet: false
    react: false
    nodejs: false
    angular: false

React uniquement (Frontend)

# Configuration pour projet React frontend uniquement
context:
  stack: react                                       # Frontend principal
  version: "{{ react_version | default('18.0') }}"
  patterns: component-based

features:
  contexts:
    react: true         # ← Frontend React
    dotnet: false
    nodejs: false
    python: false
    angular: false

🚀 Guide de configuration rapide

Étape 1 : Choisir le stack principal

context:
  stack: dotnet        # ou nodejs, python, react, angular

Étape 2 : Activer les technologies utilisées

features:
  contexts:
    dotnet: true       # Si vous utilisez .NET
    react: true        # Si vous utilisez React
    nodejs: true       # Si vous utilisez Node.js
    angular: true      # Si vous utilisez Angular

Étape 3 : Configurer les fonctionnalités

features:
  core:
    agents: true       # Toujours activé
    workflows: true    # Toujours activé
    templates: true    # Toujours activé
  adapters:
    mcp: true          # Recommandé
    cli: true          # Recommandé

Étape 4 : Personnaliser les agents (optionnel)

agents:
  default_model: claude-opus-4-5-20251101
  context_mode: full
  timeout: 300

🔧 Variables d'environnement

# Variables pour les templates
export DOTNET_VERSION="10.0"
export NODEJS_VERSION="20.0"
export PYTHON_VERSION="3.12"
export REACT_VERSION="18.0"
export ANGULAR_VERSION="17.0"

# Clés API (si nécessaire)
export ANTHROPIC_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GOOGLE_API_KEY="your-key"

❓ Questions fréquentes

Q : Quelle est la différence entre context.stack et features.contexts ?

R :

  • context.stack : Stack principal (backend par défaut pour fullstack)
  • features.contexts : Technologies spécifiques à activer

Q : Dois-je activer tous les contexts ?

R : Non, activez uniquement les technologies que vous utilisez. Cela améliore les performances.

Q : Puis-je changer la configuration après l'installation ?

R : Oui, modifiez .ai-agents.yaml à tout moment. Les changements sont pris en compte immédiatement.

Q : Comment savoir si ma configuration est correcte ?

R : Testez avec un agent simple :

@architect "Design a simple user management feature"

📚 Référence supplémentaire

📚 Ressources

🤝 Contribuer

Les contributions sont bienvenues ! Voir CONTRIBUTING.md

This documentation is automatically synced from the main repository.

Navigation

Clone this wiki locally