Changer le profile technique

Ce tutoriel explique comment utiliser, configurer et créer des profiles techniques pour adapter le comportement du framework à votre stack.

Qu'est-ce qu'un profile ?

Un profile injecte des connaissances techniques dans un agent : conventions de code, patterns à suivre, anti-patterns à éviter, commandes de toolchain.

Un profile ne change pas le rôle de l'agent (c'est la définition de l'agent qui fait ça). Il change ce que l'agent sait sur votre stack.

Exemple concret : un agent executor avec profile: rust sait utiliser thiserror, éviter les unwrap() en production, et lancer cargo clippy. Le même agent avec profile: vue-typescript sait utiliser la Composition API, typer les props avec defineProps<>(), et lancer vite.

Profiles disponibles

Profile	Stack	Fichier
rust	Rust 2021, tokio, thiserror, anyhow	framework/profiles/rust.md
tauri	Tauri 2, commandes IPC, permissions	framework/profiles/tauri.md
vue-typescript	Vue 3, Composition API, TypeScript	framework/profiles/vue-typescript.md
xterm	xterm.js, addons, PTY, terminal UI	framework/profiles/xterm.md

Utiliser un profile dans un step

Dans un fichier de step (ex: steps/step-03-execute.md), le champ profile: est passé à l'agent :

### Step 03 — Execute

<agent>
  type: executor
  profile: rust
</agent>

1. Implémenter le module PTY selon le plan
2. Suivre les conventions error handling du profil
3. Lancer `cargo clippy` avant de valider

Pour le frontend, même step mais profile différent :

### Step 03 — Execute (frontend)

<agent>
  type: executor
  profile: vue-typescript
</agent>

1. Créer le composant Vue avec la Composition API
2. Typer toutes les props et emits
3. Lancer `vite build` pour valider

Multi-profiles

Un agent peut recevoir plusieurs profiles simultanément. Utile quand le code touche deux couches à la fois :

<agent>
  type: executor
  profile: [rust, tauri]
</agent>

L'agent combine les conventions des deux profiles. Ne dépassez pas 2-3 profiles pour éviter les conflits de conventions.

Ordre des profiles

En cas de conflit entre deux profiles (conventions contradictoires), le premier dans la liste a la priorité. Mettez le plus spécifique en premier : profile: [tauri, rust] pour du code Tauri qui suit aussi les conventions Rust génériques.

Créer un nouveau profile

Étape 1 : Créer le fichier

touch framework/profiles/python-fastapi.md

Étape 2 : Écrire le frontmatter

---
name: python-fastapi
description: Profil pour les projets Python avec FastAPI — conventions, patterns, toolchain.
tags: [backend, python, fastapi, api]
---

Étape 3 : Sections du profile

Un profile complet contient 4 sections :

Conventions — règles de style et structure :

## Conventions

- **Python** : 3.11+, type hints partout
- **Formatting** : `black` + `isort`
- **Linting** : `ruff` (remplace flake8 + pylint)
- **API versioning** : prefix `/api/v1/` sur tous les routers
- **Async** : fonctions async par défaut pour les endpoints

Patterns — comment faire les choses :

## Patterns à suivre

### Structure de projet
\`\`\`
src/
├── main.py              ← FastAPI app, lifespan, middleware
├── config.py            ← Settings (pydantic-settings)
├── database.py          ← Engine, session, Base
└── modules/
    ├── users/
    │   ├── router.py    ← APIRouter
    │   ├── service.py   ← Logique métier
    │   ├── models.py    ← SQLAlchemy models
    │   └── schemas.py   ← Pydantic schemas
    └── ...
\`\`\`

### Endpoint type
\`\`\`python
@router.get("/{id}", response_model=UserResponse)
async def get_user(id: int, service: UserService = Depends()):
    user = await service.get_by_id(id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user
\`\`\`

### Error handling
\`\`\`python
from fastapi import HTTPException

# Toujours utiliser HTTPException avec un detail explicite
raise HTTPException(status_code=422, detail="Email already registered")
\`\`\`

Anti-patterns — ce qu'il ne faut pas faire :

## Anti-patterns à éviter

- Logique métier dans les routers — tout dans les services
- `session.commit()` dans les endpoints — utiliser le pattern Unit of Work
- Schemas Pydantic sans validation stricte — utiliser `model_config = ConfigDict(strict=True)`
- Endpoints synchrones pour du I/O — toujours `async def`
- Secrets en dur — utiliser `pydantic-settings` avec `.env`

Toolchain — commandes utiles :

## Commandes clés

\`\`\`bash
uvicorn src.main:app --reload    # Dev server
pytest                           # Tests
ruff check .                     # Lint
black .                          # Format
alembic upgrade head             # Migrations
\`\`\`

## Dépendances courantes

| Package | Usage |
|---------|-------|
| `fastapi` | Framework web |
| `pydantic-settings` | Configuration via env |
| `sqlalchemy` + `alembic` | ORM + migrations |
| `pytest-asyncio` | Tests async |
| `httpx` | Client HTTP pour les tests |

Exemple complet : python-fastapi.md

---
name: python-fastapi
description: Profil pour les projets Python avec FastAPI — conventions, patterns, toolchain.
tags: [backend, python, fastapi, api]
---

# Profil Python / FastAPI

## Conventions

- Python 3.11+, type hints partout
- Formatting : black + isort
- Linting : ruff
- Async par défaut pour les endpoints

## Patterns à suivre

### Structure
src/ -> modules/ -> router.py + service.py + models.py + schemas.py

### Endpoint
@router.get("/{id}", response_model=Schema)
async def get_item(id: int, service: Service = Depends()):
    ...

## Anti-patterns à éviter

- Logique métier dans les routers
- Endpoints synchrones pour du I/O

## Commandes clés

uvicorn src.main:app --reload
pytest
ruff check .

Bonnes pratiques

Profile vs Agent

Si vous avez seulement besoin d'ajouter des connaissances techniques (conventions, toolchain), créez un profile. Si vous avez besoin de changer le rôle, les responsabilités ou le menu d'actions, créez un agent.

La plupart du temps, un nouveau profile suffit.

Gardez les profiles focalisés

Un profile = une stack. Ne mettez pas les conventions FastAPI ET les conventions React dans le même profile. Créez deux profiles et combinez-les avec profile: [fastapi, react].

Pas de contradictions entre profiles combinés

Avant de combiner deux profiles, vérifiez qu'ils n'ont pas de conventions contradictoires (ex: deux formatters différents, deux styles d'error handling incompatibles). En cas de doute, documentez la priorité dans le profile le plus spécifique.