Cas d'usage concrets

Ce guide montre comment utiliser le framework au quotidien avec des exemples réels.

Cas 1 — Nouvelle feature sur un projet existant

Contexte : Vous travaillez sur une API FastAPI et devez ajouter un endpoint d'authentification JWT.

Étape 1 : Choisir le bon skill

Changement	Skill
Feature complexe, besoin de clarifier	/feature
Feature claire, prête à coder	/apex
Changement trivial (1-2 fichiers)	/oneshot

Ici, l'auth JWT est complexe → on utilise /apex.

Étape 2 : Lancer APEX

/apex -a -s -t implement JWT authentication with refresh tokens

• -a : auto mode (pas de confirmation à chaque step)
• -s : sauvegarder les outputs dans docs/apex/
• -t : inclure les tests

Étape 3 : Ce qui se passe automatiquement

Step 00 — Init
  → Charge les profiles (rust? python? selon votre CLAUDE.md)
  → Crée docs/apex/01-jwt-auth/

Step 01 — Analyze (persona: architect, exploration)
  → Explore le codebase, identifie les fichiers existants
  → Repère les patterns utilisés (routers, services, models)

Step 02 — Plan (persona: architect, design)
  → Plan fichier par fichier :
    1. models/user.py — ajouter champ hashed_password
    2. schemas/auth.py — créer LoginRequest, TokenResponse
    3. services/auth.py — créer AuthService (hash, verify, JWT)
    4. routers/auth.py — POST /login, POST /refresh
    5. tests/test_auth.py — tests unitaires

Step 03 — Execute (persona: developer)
  → Implémente chaque fichier selon le plan

Step 04 — Validate
  → Vérifie que ça compile et que les tests passent

Step 07-08 — Tests (flag -t)
  → Écrit les tests + les exécute

Step 09 — Finish
  → Résumé + commit

Étape 4 : Résultat

Vous avez :

• Du code implémenté suivant les patterns existants du projet
• Des tests
• Une trace complète dans docs/apex/01-jwt-auth/

---

Cas 2 — Bug en production

Contexte : L'endpoint /api/users retourne 500 quand l'email est null.

Option A : Cause connue

/bugfix known-cause handle null email in user endpoint

Saute directement au fix (Step 03) puisque vous connaissez la cause.

Option B : Cause inconnue

/bugfix /api/users returns 500 when email is null

Pipeline complet :

Step 01 — Reproduire le bug (créer un cas de test minimal)
Step 02 — Diagnostiquer (trouver POURQUOI email peut être null)
Step 03 — Corriger (fix + test de régression)
Step 04 — Review (vérifier pas de régression)
Step 05 — Commit (fix(api): handle null email in user endpoint)

---

Cas 3 — Décision technique

Contexte : Vous hésitez entre PostgreSQL full-text search, Elasticsearch et Meilisearch.

/brainstorm -d -s search engine: PostgreSQL FTS vs Elasticsearch vs Meilisearch

Le skill explore depuis 4 perspectives :

Perspective	Ce qu'elle analyse
Pragmatique	Effort d'intégration, complexité opérationnelle
Visionnaire	Scalabilité, features futures
Critique	Limites, single points of failure
Économique	Coût d'hébergement, maintenance

Output : une matrice de comparaison + recommandation justifiée dans docs/brainstorm/search-engine.md.

---

Cas 4 — Review avant merge

Contexte : Vous avez terminé une feature et voulez la valider avant de merger.

/review-code src/api/ src/services/

3 passes automatiques :

1. Qualité — logique, conventions, SOLID, edge cases
2. Sécurité — OWASP, injection, secrets, auth
3. Tests — couverture, régressions, edge cases

Verdict : ✅ Approuvé / 🟡 Avec réserves / ❌ Refusé

---

Cas 5 — Nettoyage de code

Contexte : Après plusieurs features, le code a accumulé de la dette technique.

/clean-code src/services/

Le skill scanne, classifie par impact/effort, et propose les corrections :

Quick wins (5 min) :
  - Supprimer 3 imports inutilisés
  - Renommer getUserData → fetchUserProfile

Améliorations (30 min) :
  - Extraire la logique de validation dans un service dédié
  - Réduire la complexité cyclomatique de processOrder()

Refactoring lourd (à planifier) :
  - Découper UserService (400 lignes) en sous-services

---

Cas 6 — Nouveau projet from scratch

Contexte : Vous démarrez un projet Rust + Tauri.

1. Initialiser le framework

/init

2. Configurer les profils

/profile add rust tauri vue-typescript xterm

3. Rédiger le PRD

/feature Rédiger les spécifications du terminal ArcTerm

L'Analyst vous pose des questions, puis produit docs/specs/arcterm.md.

4. Découper en features

Depuis le PRD, identifier les features indépendantes et lancer APEX sur chacune :

/apex -a -s -t implement PTY management
/apex -a -s -t implement tab system with vertical tabs
/apex -a -s -t implement split panes
/apex -a -s -t implement statusline

Chaque feature est implémentée avec les conventions Rust/Tauri grâce aux profils.

---

Workflow quotidien résumé

# Matin — reprendre le travail
/apex -r 03-split-panes

# Feature claire
/apex -a -s -t implement drag and drop for tabs

# Bug remonté
/bugfix tab crash when closing last pane

# Hésitation technique
/brainstorm -s rendering: canvas vs WebGL vs DOM for terminal

# Review avant merge
/review-code src/

# Commit propre
/commit

# Nettoyage
/clean-code src/services/