Première feature

Ce tutoriel vous guide pas à pas pour implémenter votre première feature avec ATOOX.

Objectif

Ajouter une validation d'email en temps réel dans un formulaire d'inscription.

Prérequis

  • ATOOX installé (atoox doctor affiche ✅)
  • Un projet existant avec un formulaire
  • Votre agent IA ouvert (Claude Code, Cursor, etc.)

Étape 1 : Lancer ATOOX

Ouvrez votre agent IA et lancez la commande :

/atoox --auto "ajouter validation email temps réel dans le formulaire d'inscription"

Tip : Utilisez --auto pour une exécution fluide. Pour plus de contrôle, omettez ce flag.

Étape 2 : Observer le Centupling Engine

ATOOX commence par analyser votre demande :

╔══════════════════════════════════════════════════════════════╗
║  ◆ ATOOX · Email Validation                                  ║
║  Step 00c · Centupling Engine                                ║
╚══════════════════════════════════════════════════════════════╝

Analyse cognitive :
  Complexité      : Medium
  Framework       : CRAFT + Chain of Thought
  Experts         : Robert C. Martin, Kent Beck, Don Norman

Domaines détectés :
  ✓ Validation (forms)
  ✓ UX (real-time feedback)
  ✓ Testing (unit tests)

Étape 3 : Clarification automatique

ATOOX transforme votre demande en spécification :

Feature: Real-time Email Validation
Description: Validate email format as user types in signup form

Acceptance Criteria:
  - RFC 5322 compliant validation
  - Visual feedback (green check / red error)
  - Debounced validation (300ms)
  - Accessible error messages
  - Unit tests with 90%+ coverage

Scope:
  - src/components/SignupForm.tsx
  - src/hooks/useEmailValidation.ts (new)
  - src/lib/validations/email.ts (new)

Out of Scope:
  - SMTP verification
  - Domain blacklist

Étape 4 : Détection du contexte

ATOOX scanne votre projet :

Context Map:
  Stack       : Next.js 14 + TypeScript
  UI          : Tailwind CSS + shadcn/ui
  Validation  : Zod (détecté dans package.json)
  Testing     : Vitest + Testing Library
  Forms       : react-hook-form (détecté)

Conventions détectées :
  - Composants dans src/components/
  - Hooks dans src/hooks/
  - Utilitaires dans src/lib/

Étape 5 : Plan d'implémentation

Plan d'implémentation :

1. Créer le schéma de validation
   → src/lib/validations/email.ts
   → Schéma Zod RFC 5322

2. Créer le hook useEmailValidation
   → src/hooks/useEmailValidation.ts
   → Debounce 300ms
   → États: idle, validating, valid, invalid

3. Intégrer dans SignupForm
   → src/components/SignupForm.tsx
   → Connecter avec react-hook-form
   → Ajouter feedback visuel

4. Écrire les tests
   → src/hooks/useEmailValidation.test.ts
   → Happy path + edge cases

Étape 6 : Exécution

ATOOX écrit le code :

// src/lib/validations/email.ts
import { z } from 'zod';

export const emailSchema = z
  .string()
  .min(1, 'L\'email est requis')
  .email('Format d\'email invalide')
  .refine(
    (email) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email),
    'Format d\'email invalide'
  );

export type EmailValidation = z.infer<typeof emailSchema>;
// src/hooks/useEmailValidation.ts
import { useState, useCallback } from 'react';
import { useDebouncedCallback } from 'use-debounce';
import { emailSchema } from '@/lib/validations/email';

type ValidationState = 'idle' | 'validating' | 'valid' | 'invalid';

export function useEmailValidation() {
  const [state, setState] = useState<ValidationState>('idle');
  const [error, setError] = useState<string | null>(null);

  const validate = useDebouncedCallback((email: string) => {
    if (!email) {
      setState('idle');
      setError(null);
      return;
    }

    setState('validating');

    const result = emailSchema.safeParse(email);

    if (result.success) {
      setState('valid');
      setError(null);
    } else {
      setState('invalid');
      setError(result.error.errors[0]?.message ?? 'Email invalide');
    }
  }, 300);

  return { state, error, validate };
}

Étape 7 : Validation automatique

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 04 · Validate
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Running: npm run lint
  ✅ 0 errors, 0 warnings

Running: npm run typecheck
  ✅ Types OK

Complexity check:
  ✅ Max cyclomatic complexity: 4 (threshold: 10)

Étape 8 : Tests automatiques

ATOOX génère et exécute les tests :

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 07-08 · Tests
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Tests générés : 8
Tests exécutés : 8
Tests passés : 8

Coverage :
  Statements : 96%
  Branches   : 92%
  Functions  : 100%
  Lines      : 96%

Étape 9 : Commit et PR

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 09 · Finish
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Branch : feature/email-validation
Commit : feat(forms): add real-time email validation

  - Add RFC 5322 compliant Zod schema
  - Create useEmailValidation hook with debounce
  - Integrate with SignupForm component
  - Add comprehensive test coverage (96%)

PR created : #42
  https://github.com/your-org/your-repo/pull/42

Rapport final

╔═══════════════════════════════════════════════════════════════════╗
║  ◆ ATOOX — PIPELINE TERMINÉ                                      ║
╠═══════════════════════════════════════════════════════════════════╣
║  Feature    : Real-time Email Validation                         ║
║  Branche    : feature/email-validation                           ║
║  Mode       : --auto                                              ║
╠═══════════════════════════════════════════════════════════════════╣
║  Code       : ✅ 1 fichier modifié, 2 créés                      ║
║  Validation : ✅ lint + types OK                                 ║
║  Tests      : ✅ 8/8 passés (96% coverage)                       ║
╠═══════════════════════════════════════════════════════════════════╣
║  Commit     : abc1234                                             ║
║  PR         : https://github.com/org/repo/pull/42                ║
╚═══════════════════════════════════════════════════════════════════╝

Résumé

En une seule commande, ATOOX a :

  1. ✅ Analysé votre demande et sélectionné les experts
  2. ✅ Détecté votre stack et conventions
  3. ✅ Créé un plan d'implémentation
  4. ✅ Écrit le code (validation, hook, intégration)
  5. ✅ Validé (lint, types, complexité)
  6. ✅ Généré et exécuté les tests
  7. ✅ Créé le commit et la PR

Prochaines étapes