FAQ - Foire Aux Questions

Questions et réponses courantes sur Claude Craft.

---

Installation

Quels sont les prérequis minimum ?

• Node.js 20+ - Pour NPX et CLI
• Bash - Pour les scripts d'installation
• yq v4+ - Pour la configuration YAML
• Git - Pour le contrôle de version

Voir Prérequis pour les détails complets.

Comment installer Claude Craft ?

Méthode la plus rapide (NPX) :

npx @the-bearded-bear/claude-craft install ~/mon-projet --tech=symfony --lang=fr

Alternative (Makefile) :

git clone https://github.com/TheBeardedBearSAS/claude-craft.git
cd claude-craft
make install-symfony TARGET=~/mon-projet RULES_LANG=fr

Puis-je installer plusieurs technologies ?

Oui ! Exécutez plusieurs commandes d'installation ou utilisez la configuration YAML :

make install-symfony TARGET=~/projet
make install-react TARGET=~/projet

Ou avec YAML :

modules:
  - path: "."
    tech: [symfony, react]

Comment mettre à jour une installation existante ?

make install-symfony TARGET=~/projet OPTIONS="--update"
# ou
./Dev/scripts/install-symfony-rules.sh --update ~/projet

Comment réinstaller complètement ?

make install-symfony TARGET=~/projet OPTIONS="--force --backup"

---

Configuration

Où se trouve le fichier de configuration ?

• Niveau projet : ~/mon-projet/.claude/CLAUDE.md
• Index : ~/mon-projet/.claude/INDEX.md
• Déclencheurs de contexte : ~/mon-projet/.claude/context.yaml

Comment personnaliser le contexte du projet ?

Éditez .claude/rules/00-project-context.md ou exécutez :

/common:setup-project-context

Comment changer la langue de la documentation ?

Utilisez l'option --lang ou RULES_LANG lors de l'installation :

make install-symfony TARGET=~/projet RULES_LANG=fr

Disponibles : en, fr, es, de, pt

Quelle est la différence entre CLAUDE.md et INDEX.md ?

• CLAUDE.md : Config minimale chargée automatiquement (~200 tokens)
• INDEX.md : Référence rapide chargée à la demande via @ (~1,300 tokens)
• references/ : Documentation complète chargée explicitement

---

Commandes

Comment lister toutes les commandes disponibles ?

Dans Claude Code :

/help

Ou voir Référence des Commandes.

Quelle est la différence entre /common: et /symfony: ?

• /common: - Commandes transversales pour toute technologie
• /symfony:, /react:, etc. - Commandes spécifiques à une technologie

Comment créer une commande personnalisée ?

Ajoutez un fichier markdown dans .claude/commands/{namespace}/ :

---
description: Ce que fait cette commande
argument-hint: <arg1> [arg2]
---

# Ma Commande Personnalisée

Instructions pour Claude...

Pourquoi ma commande n'apparaît pas ?

1. Vérifiez que l'extension du fichier est .md
2. Vérifiez que le frontmatter YAML est valide
3. Redémarrez la session Claude Code

---

Agents

Comment invoquer un agent ?

Utilisez la mention @ :

@api-designer Aide-moi à concevoir une API REST
@symfony-reviewer Passe en revue ce code

Puis-je utiliser plusieurs agents ensemble ?

Oui :

@tdd-coach @react-reviewer Aide-moi à faire du TDD sur ce composant

Comment créer un agent personnalisé ?

Ajoutez un fichier markdown dans .claude/agents/ :

---
name: mon-agent
description: Expert en X. À utiliser quand Y.
---

# Mon Agent

## Identité
...

## Capacités
...

---

Framework BMAD

Qu'est-ce que BMAD ?

BMAD (Build, Measure, Analyze, Deliver) est le framework de gestion de projet de Claude Craft avec :

• 9 agents spécialisés (pm, ba, architect, po, sm, dev, qa, ux, bmad-master)
• Routage de stories basé sur le statut
• 5 quality gates
• Traitement par lots

Comment commencer à utiliser BMAD ?

# Initialiser BMAD dans votre projet
/bmad:init

# Vérifier le statut
/bmad:status

Quels sont les quality gates ?

Gate	Seuil	Objectif
PRD Gate	≥80%	Vision → PRD
Tech Spec Gate	≥90%	PRD → Tech Spec
Backlog Gate	INVEST 6/6	Tech Spec → Backlog
Sprint Ready	100%	Backlog → Sprint
Story DoD	100%	Dev → Done

Voir Guide Pratique BMAD.

---

Ralph Wiggum

Qu'est-ce que Ralph Wiggum ?

Ralph Wiggum est une boucle d'agent IA continue qui exécute Claude de manière itérative jusqu'à ce que :

• Tous les validateurs de Definition of Done (DoD) passent
• Le nombre maximum d'itérations est atteint
• Le circuit breaker se déclenche

Comment utiliser Ralph ?

/common:ralph-run "Implémenter l'authentification utilisateur"
# ou
npx @the-bearded-bear/claude-craft ralph "Corriger le bug de connexion"

Quels validateurs DoD sont disponibles ?

Validateur	Description
command	Exécuter des commandes shell (tests, lint)
output_contains	Vérifier des patterns dans la sortie
file_changed	Vérifier que des fichiers ont été modifiés
hook	Intégrer avec quality-gate.sh
human	Approbation manuelle

Voir Guide Ralph.

---

Workflow

Quelles pistes de workflow sont disponibles ?

Piste	Temps	Idéal Pour
Quick Flow	< 5 min	Corrections de bugs, hotfixes
Standard	< 15 min	Nouvelles fonctionnalités
Enterprise	< 30 min	Plateformes, migrations

Comment démarrer un workflow ?

/workflow:init              # Auto-détection
/workflow:init --quick      # Mode correction de bug
/workflow:init --enterprise # Méthodologie complète

Quelles sont les phases du workflow ?

1. Analyser - Recherche et exploration (Enterprise uniquement)
2. Planifier - Générer PRD, personas, backlog
3. Concevoir - Tech spec, architecture, ADRs
4. Implémenter - Développement sprint avec TDD/BDD

---

Dépannage

"yq: command not found"

Installez yq v4 :

brew install yq      # macOS
sudo apt install yq  # Ubuntu

Assurez-vous que c'est la version de Mike Farah :

yq --version
# Doit afficher : yq (https://github.com/mikefarah/yq/)

"Permission denied" sur les scripts

chmod +x Dev/scripts/*.sh
# ou
make fix-permissions

Commandes non reconnues dans Claude Code

1. Redémarrez la session Claude Code
2. Vérifiez que les fichiers sont dans .claude/commands/
3. Vérifiez la syntaxe du frontmatter YAML

L'installation échoue avec "directory not found"

Créez d'abord le répertoire :

mkdir -p ~/mon-projet
make install-symfony TARGET=~/mon-projet

Fichiers écrasés de manière inattendue

Utilisez --preserve-config pour conserver vos personnalisations :

make install-symfony TARGET=~/projet OPTIONS="--force --preserve-config"

Voir Guide de Dépannage pour plus de solutions.

---

Gestion de Projet

Comment créer une user story ?

/project:add-story EPIC-001 "En tant qu'utilisateur, je veux..."

Comment suivre la progression du sprint ?

/sprint:status
/project:board

Comment exécuter un sprint TDD ?

/sprint:dev next

---

Intégration

Claude Craft fonctionne-t-il avec d'autres outils IA ?

Oui ! Utilisez les bundles web :

• bundles/chatgpt/ - Pour ChatGPT
• bundles/claude/ - Pour Claude Projects
• bundles/gemini/ - Pour Gemini Gems

Puis-je utiliser des serveurs MCP ?

Oui, Claude Craft inclut des templates MCP :

# Copier les templates MCP
cp .claude/mcp/* ~/.claude/mcp/

Disponibles : Context7, GitHub, PostgreSQL, Slack

Est-ce que ça fonctionne dans les monorepos ?

Oui ! Utilisez la configuration YAML :

projects:
  - name: "mon-monorepo"
    root: "~/Projets/mon-monorepo"
    modules:
      - path: "frontend"
        tech: react
      - path: "backend"
        tech: symfony

---

Migration

Comment migrer de v3 vers v4 ?

Voir Guide de Migration.

Qu'est-ce qui change en v4 ?

Changements principaux :

• Structure TCL (Tiered Context Loading)
• Changements de format BMAD v6
• Quelques renommages de commandes

Puis-je utiliser v3 et v4 côte à côte ?

Non recommandé. Migrez les projets un par un.

---

Bonnes Pratiques

Quel est le workflow recommandé pour une nouvelle fonctionnalité ?

1. Démarrer avec /workflow:init
2. Utiliser @api-designer pour la conception d'API
3. Générer le code avec /symfony:generate-crud
4. Écrire les tests avec @tdd-coach
5. Faire la revue avec @symfony-reviewer
6. Valider avec /common:pre-commit-check

À quelle fréquence exécuter les audits ?

• Pré-commit : Toujours (/common:pre-commit-check)
• Audit complet : Hebdomadaire ou avant les releases
• Audit de sécurité : Avant chaque release

Dois-je commiter le dossier .claude ?

Oui ! Le dossier .claude/ doit être commité dans le contrôle de version pour que tous les membres de l'équipe utilisent les mêmes règles et commandes.

---

Contribuer

Comment ajouter une nouvelle technologie ?

Utilisez la commande :

/common:add-technology "nextjs"

Cela génère tous les fichiers pour 5 langues.

Comment signaler un bug ?

Ouvrir une issue sur GitHub

Puis-je contribuer aux traductions ?

Oui ! Les traductions sont dans Dev/i18n/{lang}/. Les PRs sont les bienvenues !

---

Encore des questions ?

• Consultez Dépannage
• Lisez la Documentation Complète
• Ouvrez une issue GitHub