Skip to content

stack guide

Jump to bottom
GitHub Actions edited this page Feb 4, 2026 · 1 revision

Stack Guide

Vue d'ensemble

Le système offre une flexibilité totale pour choisir les technologies selon vos besoins:

Mode Commande Description
Backend seul @chain:backend-feature --context=<backend> Développer uniquement l'API
Frontend seul @chain:frontend-feature --context=<frontend> Développer uniquement l'UI
Fullstack @chain:fullstack-feature Développer backend + frontend ensemble

Mode 1: Backend seul

@chain:backend-feature --context=<backend> "<description>"

Backends disponibles: dotnet, nodejs, python, java, go, rust

Exemples:

@chain:backend-feature --context=dotnet "Add user management API with CRUD"
@chain:backend-feature --context=nodejs "Add product API with Express"
@chain:backend-feature --context=python "Add authentication API with FastAPI"
@chain:backend-feature --context=java "Add order service with Spring Boot"
@chain:backend-feature --context=go "Add payment service with Gin"
@chain:backend-feature --context=rust "Add performance-critical service with Axum"

Mode 2: Frontend seul

@chain:frontend-feature --context=<frontend> "<description>"

Frontends disponibles: react, angular, vue, svelte, nextjs, nuxt

Exemples:

@chain:frontend-feature --context=react "Add user dashboard with data tables"
@chain:frontend-feature --context=angular "Add product listing page with filters"
@chain:frontend-feature --context=vue "Add blog interface with Composition API"
@chain:frontend-feature --context=svelte "Add real-time dashboard with Svelte 5"
@chain:frontend-feature --context=nextjs "Add enterprise portal with App Router"
@chain:frontend-feature --context=nuxt "Add e-commerce site with Vue 3"

Mode 3: Fullstack (Backend + Frontend)

@chain:fullstack-feature [--backend=<stack>] [--frontend=<stack>] [--adapter=<llm>] "<description>"

Paramètres

Paramètre Options Default Description
--backend dotnet, nodejs dotnet Stack backend
--frontend react, angular react Stack frontend
--adapter claude, openai, gemini, ollama config LLM à utiliser

Combinaisons supportées

Backend Frontend Architecture Backend Architecture Frontend
dotnet react Clean Architecture (.NET 10) Feature-Sliced Design (Next.js 15)
dotnet angular Clean Architecture (.NET 10) Feature Modules (Angular 19)
nodejs react Clean Architecture (Express/Fastify) Feature-Sliced Design (Next.js 15)
nodejs angular Clean Architecture (Express/Fastify) Feature Modules (Angular 19)

Exemples d'utilisation

Exemple 1: User Management (dotnet + react)

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

Résultat attendu:

Backend (.NET):

src/
├── Domain/Entities/User.cs
├── Application/
│   ├── Users/
│   │   ├── DTOs/UserDto.cs
│   │   ├── Commands/CreateUserCommand.cs
│   │   ├── Queries/GetUsersQuery.cs
│   │   └── Interfaces/IUserService.cs
├── Infrastructure/Users/UserService.cs
└── Api/Endpoints/UsersEndpoints.cs

tests/
├── Unit/Application.Tests/Users/
└── Integration/Api.IntegrationTests/Users/

Frontend (React/Next.js):

src/
├── features/users/
│   ├── api/
│   │   ├── types.ts          # Generated from .NET DTOs
│   │   ├── api.ts            # API service
│   │   └── hooks.ts          # TanStack Query hooks
│   ├── components/
│   │   ├── UserList.tsx
│   │   ├── UserForm.tsx
│   │   └── UserCard.tsx
│   └── pages/
│       └── UsersPage.tsx
├── __mocks__/
│   └── users.handlers.ts     # MSW handlers

__tests__/
└── features/users/

Exemple 2: Product Catalog (nodejs + angular)

@chain:fullstack-feature --backend=nodejs --frontend=angular "Add product catalog with search and filters"

Backend (Node.js/TypeScript):

src/
├── domain/entities/Product.ts
├── application/
│   ├── products/
│   │   ├── dtos/ProductDto.ts
│   │   ├── interfaces/IProductService.ts
│   │   └── handlers/
├── infrastructure/products/ProductService.ts
└── api/controllers/products.controller.ts

Frontend (Angular):

src/app/
├── features/products/
│   ├── services/
│   │   ├── products.types.ts
│   │   └── products.service.ts
│   ├── components/
│   │   ├── product-list/
│   │   ├── product-card/
│   │   └── product-filters/
│   ├── pages/
│   │   └── products-page/
│   └── products.routes.ts

Workflow détaillé

Phase 1: Architecture

L'agent architect conçoit l'architecture globale:

  • Contrat API (endpoints, DTOs, codes HTTP)
  • Architecture backend selon le pattern Clean Architecture
  • Architecture frontend selon le pattern du framework
  • Conventions de nommage cohérentes

Phase 2: Backend Implementation

L'agent developer implémente le backend:

  • Entités Domain avec validation
  • Application layer (DTOs, handlers, interfaces)
  • Infrastructure (persistence, services externes)
  • API endpoints RESTful

Gates: dotnet build --warnaserror ou pnpm run build

Phase 3: Backend Testing

L'agent unit-tester écrit les tests:

  • Tests unitaires Domain
  • Tests unitaires Application
  • Tests d'intégration API

Gates: Coverage ≥ 80%

Phase 4: API Integration

L'agent api-integrator génère la couche d'intégration:

  • Types TypeScript depuis les DTOs backend
  • Service API typé
  • Hooks (React) ou Services (Angular) pour data fetching
  • Handlers MSW pour les tests

Phase 5: Frontend Implementation

L'agent frontend-developer implémente l'UI:

  • Structure feature/module
  • Composants page et réutilisables
  • États loading/error/empty
  • Formulaires avec validation

Gates: pnpm run build + pnpm run lint

Phase 6: Frontend Testing

L'agent frontend-tester écrit les tests:

  • Tests composants avec Testing Library
  • Tests hooks/services
  • Mocking API avec MSW

Gates: Coverage ≥ 80%

Phase 7: Review

L'agent reviewer valide l'ensemble:

  • Cohérence contrat API
  • Gestion d'erreurs cross-stack
  • Sécurité
  • Performance

Phase 8: Documentation

L'agent docwriter met à jour la documentation:

  • OpenAPI/Swagger pour l'API
  • Documentation composants frontend
  • Exemples d'intégration

Configuration projet

Pour définir les defaults au niveau projet, créez .ai-agents.yaml:

library:
  source: ".ai-agents"

adapter: claude

# Configuration fullstack
fullstack:
  backend:
    stack: dotnet
    overrides:
      coverage_target: 100
  frontend:
    stack: react
    overrides:
      coverage_target: 100

# Règles additionnelles
rules:
  - "Use FluentValidation for backend validation"
  - "Use Zod for frontend validation"
  - "All API calls must have error handling"

Tips

Reprendre une chain interrompue

# Reprendre à partir du frontend
@chain:fullstack-feature --start=api-integration "Continue user management"

# Reprendre à partir de la review
@chain:fullstack-feature --start=review "Continue user management"

Utiliser un LLM différent par phase

# Utiliser Claude pour l'architecture (meilleur raisonnement)
@chain:fullstack-feature --adapter=claude "Add complex feature"

# Ou configurer dans .ai-agents.yaml
fullstack:
  adapters:
    architecture: claude
    implementation: openai
    testing: gemini

Ajouter des tests E2E

# Activer les tests E2E (Playwright)
@chain:fullstack-feature --include-e2e "Add user management"

Contract-First Development

Quand frontend et backend sont développés en parallèle ou alternativement, utilisez l'approche Contract-First : définir le contrat API avant l'implémentation.

Principe

┌─────────────────────────────────────────────────────────────┐
│              CONTRAT API (source unique de vérité)          │
│                                                             │
│   contracts/openapi.yaml  ou  contracts/api.schema.json     │
└─────────────────────────────────────────────────────────────┘
                │                           │
                ▼                           ▼
       ┌───────────────┐           ┌───────────────┐
       │    Backend    │           │   Frontend    │
       │  (any stack)  │           │  (any stack)  │
       │               │           │               │
       │ Implémente ou │           │ Génère types  │
       │ génère DTOs   │           │ + mocks API   │
       └───────────────┘           └───────────────┘

Configuration (agnostique du stack)

# .ai-agents.yaml
library:
  source: ".claude"

adapter: claude

# Mode Contract-First
contract:
  enabled: true
  path: "contracts/openapi.yaml"    # ou "contracts/api.schema.json"
  format: openapi                    # openapi | jsonschema | asyncapi

# Options de génération (utilisent le stack installé automatiquement)
generation:
  backend:
    output: "src/Application/DTOs"   # Chemin adapté au stack
    auto_generate: false             # true = génère depuis le contrat
  frontend:
    output: "src/api/types"
    auto_generate: true
    include_mocks: true              # Génère les mocks MSW/similaire

Workflow

1. Définir le contrat (architecte ou équipe)

@architect "Design API contract for user management"
# Produit: contracts/openapi.yaml

2. Frontend peut commencer immédiatement

# Génère types + mocks depuis le contrat
@api-integrator "Generate types and mocks from contract"

# Développe avec les mocks
@frontend-developer "Implement user list page"

3. Backend peut commencer immédiatement

# Implémente l'API selon le contrat
@developer "Implement user API according to contract"

4. Intégration

# Vérifie la conformité des deux côtés
@reviewer "Validate API contract compliance on both sides"

Avantages

Avantage Description
Parallélisation Frontend et backend avancent indépendamment
Pas de duplication Le contrat génère les types des deux côtés
Mocks automatiques Le frontend fonctionne sans attendre le backend
Validation Le contrat valide la conformité des implémentations

Commandes utiles

# Générer le contrat depuis une description
@architect "Create OpenAPI contract for: GET/POST/PUT/DELETE /api/products"

# Mettre à jour le contrat après un changement
@architect "Update contract: add pagination to GET /api/products"

# Regénérer les types après modification du contrat
@api-integrator "Regenerate types from updated contract"

FAQ

Q: Comment le système connaît-il les types TypeScript à générer?

Le contexte backend définit un type_map qui convertit les types:

.NET / Node.js TypeScript
string string
int, long, number number
bool, boolean boolean
DateTime, Date string (ISO 8601)
Guid string
List<T>, T[] T[]
Dictionary<K,V>, Record<K,V> Record<K, V>
T? T | null

Q: Puis-je utiliser Python comme backend?

Oui, mais pas encore dans la chain fullstack-feature. Utilisez:

@chain:backend-feature --context=python "Add API endpoint"
@chain:frontend-feature "Add UI for API"

Q: Comment personnaliser les templates de code?

Chaque contexte définit des code_templates. Vous pouvez les surcharger dans .ai-agents.yaml:

fullstack:
  backend:
    stack: dotnet
    templates:
      entity: |
        // Custom entity template

📚 Ressources

🤝 Contribuer

Les contributions sont bienvenues ! Voir CONTRIBUTING.md

This documentation is automatically synced from the main repository.

Navigation

Clone this wiki locally