Guide utilisateur SOFIA

Des rôles spécialisés qui pensent avec vous. Le produit émerge de leur friction.

En une minute

SOFIA est une méthode pour orchestrer des assistants IA spécialisés sur un projet. Chaque assistant a un rôle, un périmètre et des interdits. Ils ne se parlent pas — c'est toi qui portes le contexte entre eux. La friction entre les rôles produit de meilleures décisions.

Pour commencer : clone le repo, lance claude, et Sofia — le guide intégré — te propose ton premier persona. Si le flow ne se lance pas, le mode manuel couvre la même chose étape par étape.

Alpha preview — Sofia repose sur le comportement conversationnel du runtime. Les résultats peuvent varier selon l'environnement.

git clone https://github.com/oxynoe-dev/sofia
cd sofia
claude

Git n'est pas obligatoire pour utiliser SOFIA, mais il est fortement conseillé. Les résumés de session, les notes et les reviews sont des fichiers — git te donne la traçabilité et la persistence du contexte entre les sessions.

1. L'essentiel

Un persona = un rôle strict

Un persona n'est pas un assistant générique. C'est un LLM contraint : un nom, un ton, un périmètre, et surtout des choses qu'il n'a pas le droit de faire.

La contrainte change tout. Un architecte qui ne code pas est obligé de spécifier. Un dev qui ne décide pas de l'architecture est obligé de questionner. Un stratège sans accès au code pense en valeur, pas en implémentation.

Définis ce que le persona ne fait pas avant de définir ce qu'il fait.

La friction est productive

Si tous tes personas sont d'accord, ils ne servent à rien. La friction — un architecte qui challenge le dev, un stratège qui remet en question la priorité — c'est le mécanisme qui produit de meilleures décisions.

La friction sans arbitre est du chaos. L'arbitre, c'est toi.

L'humain arbitre. Toujours.

Les personas proposent, challengent, produisent. L'humain tranche. Un persona ne valide jamais ses propres propositions. Un persona ne force jamais l'acceptation d'une décision. C'est la règle non négociable de SOFIA.

Les fichiers sont le protocole

Les personas ne "discutent" pas — ils échangent par artefacts : reviews, notes, specs. Ces artefacts sont versionnés, traçables, et lisibles par tous. Un échange par fichier est plus lent qu'un chat. C'est le but. La lenteur force la clarté.

Commence petit, itere

Un persona au démarrage. Deux quand le premier est calibré. Trois quand le besoin est clair. La méthode ne se déploie pas en big bang. Elle grandit avec le projet.

2. Ce que tu viens de cloner

Le repo SOFIA n'est pas ton projet — c'est la méthode. Il contient :

• core/ — les invariants : principes, personas, friction, devoirs
• protocol/ — le contrat d'interface : artefacts, conventions, isolation, orchestration
• runtime/ — l'implémentation concrète pour Claude Code (d'autres providers suivront)
• doc/ — guides, workflows, patterns, retours terrain

Ton projet vivra ailleurs, dans son propre repo. SOFIA t'aide à organiser les assistants IA qui travaillent dessus. La section L'isolation détaille les configurations possibles.

3. Démarrage avec Sofia

Alpha preview — Sofia repose sur le comportement conversationnel du runtime. Les résultats peuvent varier selon le provider, la version du modèle et l'environnement. Si le flow ne se lance pas ou dérive, passe en mode manuel (voir section suivante).

Sofia est le guide intégré de SOFIA. Quand tu lances claude dans le repo, il te guide pour créer ton premier persona.

Le flow

1. Ton projet — Sofia te demande ce que tu construis (1-2 tours)
2. Premier persona — il te propose un rôle structurant adapté à ton contexte. Pas une liste de choix — une proposition directe que tu valides ou ajustes
3. Calibrage — nom, ton, périmètre (ce qu'il fait et ne fait pas). Sofia propose, tu ajustes
4. Génération — Sofia produit le CLAUDE.md et te donne trois clés de départ

L'heuristique du premier persona

Le premier persona est toujours un rôle structurant — jamais un exécutant. C'est lui qui va cadrer ta démarche. Les autres viendront après.

Le briefing de départ

Après avoir généré ton premier CLAUDE.md, Sofia te dit trois choses :

• Ton persona va te dire non. C'est voulu. Quand il refuse une demande parce que c'est hors périmètre, c'est un signal — pas un bug.
• Les autres personas viendront. Pas maintenant. Quand le travail les fera émerger.
• Tu peux revenir. Relance Sofia à tout moment pour ajouter un persona ou ajuster celui-ci.

4. Travailler avec un persona

Le CLAUDE.md

C'est le contrat entre toi et ton persona. Il contient :

• Qui — nom, rôle, posture
• Quoi — périmètre d'intervention, livrables attendus
• Où — quels fichiers/dossiers sont accessibles
• Interdit — ce qui est hors périmètre (lecture ET écriture)
• Comment — conventions, formats, workflow de session

Vise 60-100 lignes. Au-delà, le contexte se dilue.

Ouverture de session

Le persona lit le dernier résumé dans sessions/. L'humain décide quoi regarder. Pas de récitation systématique.

Fermeture de session

1. Résumé dans sessions/ — Produit, Décisions, Notes déposées, Ouvert
2. Commit direct dans l'instance — {persona}: {résumé court} ({date})
3. Si le persona a produit des changements pour ton projet (code, site, etc.) — préparer le message de commit, l'humain vérifie et exécute

Pas de prose. Listes courtes. 30 lignes max.

Le test du "non"

Un persona bien calibré dit "non" régulièrement :

• "Ce n'est pas mon rôle, vois avec [autre persona]"
• "La spec n'est pas assez précise pour que je code"
• "Cette décision nécessite un ADR avant que j'implémente"

Si ton persona ne dit jamais non, ses contraintes sont trop lâches.

5. Émergence — les personas suivants

Les personas suivants ne se planifient pas. Ils émergent du travail.

Le mécanisme

Chaque CLAUDE.md généré par Sofia inclut une section Émergence :

## Emergence
Quand tu deflectes une question parce qu'elle sort de ton perimetre,
note le domaine. Si tu deflectes 3+ fois sur le meme domaine,
signale-le explicitement :
"Je recois regulierement des questions sur [domaine] —
c'est en dehors de mon perimetre. Tu pourrais avoir besoin
d'un persona dedie. Relance Sofia si tu veux qu'on en cree un."

Le persona ne crée pas le nouveau persona — il signale le manque. Tu reviens vers Sofia qui reprend le flow.

Exemple concret

Tu travailles avec un architecte. Au bout de quelques sessions :

• Il te dit 3 fois "je ne code pas, il faudrait quelqu'un pour implémenter"
• Il te signale : "Tu pourrais avoir besoin d'un persona dev dédié"
• Tu relances Sofia, qui te propose un dev calibré pour ton projet

C'est exactement ce qui s'est passé sur le projet Katen : le premier persona (architecte) a été posé. Les 6 autres ont émergé par nécessité au fil du travail. Personne ne les avait prévus.

6. L'isolation

Instance et projet

Une instance SOFIA n'est pas ton projet. C'est l'espace où tes personas réfléchissent, planifient, et échangent. Ton projet (le code, le produit, le site) vit ailleurs, dans son propre repo.

L'instance pense. Le projet livre. Les personas travaillent dans l'instance et produisent des livrables qui atterrissent dans le projet. Les commits dans l'instance sont automatiques. Les commits dans le projet passent par l'humain.

Trois configurations possibles :

• Un seul repo — l'instance vit dans un sous-dossier du projet. Simple à démarrer, tu sépareras si le besoin se fait sentir.
• Un repo instance + un repo projet — le cas standard. L'historique d'analyse ne pollue pas le repo produit. Si le projet est public, l'outillage interne reste privé.
• Un repo instance + plusieurs projets — les personas ont une vue transverse. Les roadmaps dans shared/ font le lien. Les CLAUDE.md référencent les repos produit via des chemins absolus.

Anatomie d'une instance

Une instance contient des workspaces (un par persona) et une zone partagée (shared/). Chaque workspace est isolé — un persona ne peut pas lire ou écrire dans le workspace d'un autre. La seule communication passe par shared/.

La zone partagée — shared/

C'est le seul espace que tous les personas peuvent lire et écrire. Les échanges passent par des artefacts déposés ici :

Chaque artefact porte un frontmatter (de, pour, type, statut, date). Quand il est traité, il migre dans archives/.

Les roadmaps

La planification vit dans shared/roadmap-{produit}.md. Chaque roadmap a un owner (gardien de la cohérence) et chaque item porte un @owner (responsable de l'exécution).

Il n'y a pas de backlog par persona. Tous les items vivent dans les roadmaps.

7. L'orchestration — le rôle de l'humain

Tu es le message bus

Les personas ne se parlent pas. Tu portes le contexte. Tu peux ouvrir plusieurs terminaux en parallèle — un par persona — pour accélérer les échanges :

1. Tu ouvres une session avec un persona
2. Il produit un livrable
3. Tu fermes la session
4. Tu ouvres une session avec un autre persona
5. Tu transmets le livrable
6. Tu recueilles la reaction

Chaque transmission est un moment où tu filtres, reformules, ajoutes du contexte, décides ce qui est pertinent à transmettre.

Ce que tu ne délègues pas

• La priorisation — quel persona intervient, dans quel ordre
• La consolidation — synthétiser les retours de N personas
• La décision — trancher quand les personas divergent
• Le filtrage — ce qui est pertinent à transmettre ou pas

Le coût

L'orchestration prend du temps. C'est le prix de la qualité. Si l'échange n'en vaut pas le coût, c'est que le sujet ne nécessitait pas plusieurs personas.

8. La traçabilité

Les artefacts de traçabilité

1. Résumés de session — chaque session produit un résumé. C'est le pont entre les conversations. Format : sessions/{YYYY-MM-DD}-{HHmm}-{persona}.md
2. Notes — messages inter-personas déposés dans shared/notes/. Format : note-{destinataire}-{sujet}-{auteur}.md
3. Reviews croisées — quand un persona intervient sur le travail d'un autre, il produit une review avec des observations factuelles, des recommandations priorisées, et des questions ouvertes. Format : review-{sujet}-{auteur}.md
4. Features — specs fonctionnelles partagées. Format : feature-{sujet}.md dans shared/features/
5. ADR — les décisions structurantes sont tracées : contexte, décision, alternatives, conséquences, statut. L'ADR est écrit avant l'implémentation.

Si ce n'est pas tracé, ça n'existe pas

La prochaine session n'aura pas ton contexte en tête. Les résumés sont sa mémoire.

9. Anti-patterns

Pour aller plus loin

La méthode en profondeur

• Principes — les 7 principes en détail
• Personas — anatomie d'un persona, calibrage, itération
• Friction — la friction intentionnelle comme mécanisme

Le protocole

• Orchestration — le rôle de l'humain comme message bus
• Isolation — l'isolation par workspace
• Traçabilité — sessions, ADR, reviews
• Artefacts — le bus d'échange shared/

L'implémentation Claude Code

• CLAUDE.md — anatomie d'un CLAUDE.md
• Sessions — format des résumés de session
• Mémoire — mémoire persistante entre sessions

Apprendre par l'exemple

Les exemples ci-dessous viennent du projet Katen. Les livrables mentionnés (ADR, design system, notes de recherche...) sont spécifiques à ce projet — adapte-les à ton contexte. Ce qui est transposable, c'est la structure : rôles contraints, isolation, artefacts tracés.

• Workflows — 6 processus clés (dev, publication, ADR, recherche...)
• Patterns — 7 structures récurrentes (challenger, distillerie, escalade...)
• Retours terrain — retours Katen, contexte d'identification des patterns (N=1)
• Personas Katen — 7 fiches personas en production, référence de calibrage
• Mode manuel — installer SOFIA sans Sofia, pas à pas

Démarrer sans Sofia — mode manuel

Installer les personas à la main, fichier par fichier.

Quand utiliser le mode manuel

• Tu veux comprendre chaque pièce avant de l'assembler
• Tu as déjà une idée précise des rôles dont tu as besoin
• Tu préfères garder le contrôle sur la structure
• Tu veux adapter la méthode à un autre provider

Le mode manuel produit exactement le même résultat que Sofia. Il n'y a pas de version "allégée" — juste un chemin différent pour y arriver.

Vue d'ensemble

mon-projet/
├── voix.md                  ← marqueur d'instance
├── shared/
│   ├── conventions.md       ← règles d'échange
│   ├── orga/
│   │   └── personas/        ← fiches persona
│   ├── notes/               ← échanges inter-personas
│   ├── review/              ← reviews croisées
│   └── roadmap-{produit}.md ← planification
├── {workspace-1}/
│   ├── CLAUDE.md            ← contrat du persona
│   └── sessions/            ← résumés de session
├── {workspace-2}/
│   ├── CLAUDE.md
│   └── sessions/
└── ...

Avant de commencer : instance et projet

Une instance SOFIA n'est pas ton projet — c'est l'atelier où les personas réfléchissent. Le projet (code, produit) vit dans un repo séparé. Voir la section L'isolation > Instance et projet du guide utilisateur pour le détail et les trois configurations possibles.

Étape 1 — Cloner le repo SOFIA

git clone https://github.com/oxynoe-dev/sofia

C'est ta référence. Les templates et la documentation sont dedans. Tu n'as pas besoin de le garder dans ton projet — juste de le consulter.

Étape 2 — Créer le marqueur d'instance

À la racine de ton projet, crée voix.md :

# Instance SOFIA

Ce dépôt est une **instance de la méthode SOFIA**.

- **Méthode** : [oxynoe-dev/sofia](https://github.com/oxynoe-dev/sofia)
- **Version méthode appliquée** : v0.2.x
- **Projet** : {ton projet}
- **Équipe** : {nombre} assistants IA + 1 humain orchestrateur

## Structure instance

| Dossier | Rôle | Persona |
|---------|------|---------|
| `{workspace}/` | {description} | {persona} |
| `shared/` | Bus d'échange inter-personas | Partagé |

Étape 3 — Créer la structure partagée

mkdir -p shared/orga/personas shared/notes shared/review

conventions.md

Crée shared/conventions.md. C'est le contrat d'échange entre personas. Au minimum :

# Conventions

## Échanges inter-personas

Les personas ne se parlent pas. Ils échangent par artefacts déposés dans shared/.

### Notes
- Format : `note-{destinataire}-{sujet}-{auteur}.md`
- Emplacement : `shared/notes/`
- Quand traitée : déplacer dans `shared/notes/archives/`

### Reviews
- Format : `review-{sujet}-{auteur}.md`
- Emplacement : `shared/review/`
- Quand traitée : déplacer dans `shared/review/archives/`

## Commits
- Instance : `{persona}: {résumé court} ({date})`
- Repos produit : l'humain vérifie et commit

Étape 4 — Définir ton premier persona

Commence par un seul. Les autres viendront.

Choisir le rôle

Le premier persona est un rôle structurant — celui qui va cadrer la démarche.

Créer la fiche persona

Crée shared/orga/personas/persona-{nom}.md. Utilise le template core/templates/persona.md du repo SOFIA comme base. Les champs essentiels :

# {Nom} — {Rôle}

## Profil
{En une phrase : qui est ce persona et quelle est sa posture.}

## Domaines d'intervention
- {domaine 1}
- {domaine 2}

## Ce qu'il/elle ne fait PAS
- {interdit 1}
- {interdit 2}

## Ce qu'il/elle challenge
- {axe de friction 1}

La section "Ce qu'il ne fait pas" est la plus importante. C'est elle qui crée la contrainte productive.

Étape 5 — Créer le workspace

mkdir -p {workspace}/sessions

Le CLAUDE.md

Crée {workspace}/CLAUDE.md. C'est le fichier que Claude Code lit à chaque conversation. Vise 60-100 lignes.

# {Projet} — Instructions Claude Code

## Persona
Claude incarne **{Nom}** — {rôle}.
Voir `shared/orga/personas/persona-{nom}.md` pour la fiche complète.

## Posture
- {comportement 1 — comment il s'exprime}
- {comportement 2 — ce qu'il privilégie}
- {comportement 3 — son rapport aux autres}

## Périmètre
Ce workspace contient :
- {type de contenu}

## Documents clés
| Fichier | Rôle |
|---------|------|
| `{chemin}` | {description} |

## Isolation
- Ne jamais lire/écrire en dehors de `{périmètre autorisé}`

## Conventions
- **Langue** : français
- **Reviews** : `review-<sujet>-{nom}.md` dans `shared/review/`
- **Bus shared/** : voir `shared/conventions.md`

## Workflow
0. **Ouverture** : lire le dernier résumé dans `sessions/`
1. Lire les documents existants avant toute intervention
2. Produire des {types de livrables}
3. Ne pas {interdit principal}

## Émergence
Quand tu deflectes une question parce qu'elle sort de ton périmètre, note le domaine. Si tu deflectes 3+ fois sur le même domaine, signale-le :
"Je reçois régulièrement des questions sur [domaine] — c'est en dehors de mon périmètre. Ce sujet relève d'un autre persona."

## Résumé de session — obligatoire
- `sessions/{YYYY-MM-DD}-{HHmm}-{nom}.md`
- Sections : Produit, Décisions, Notes déposées, Ouvert
- Pas de prose, 30 lignes max

Étape 6 — Première session

Lance Claude Code dans le workspace :

cd {workspace}
claude

Le persona va lire son CLAUDE.md et se comporter selon le contrat. Demande-lui quelque chose dans son périmètre. Observe :

• Il refuse ce qui est hors périmètre ? Bon signe.
• Il accepte tout ? Resserre les contraintes dans le CLAUDE.md.
• Il est trop rigide ? Assouplis la posture.

Le calibrage se fait en 2-3 sessions. C'est normal.

Ajouter un deuxième persona

Quand le besoin émerge — pas avant. Les signaux :

• Le premier persona te dit régulièrement "ce n'est pas mon rôle"
• Tu passes du temps à faire un travail qu'un persona pourrait structurer
• Deux domaines distincts sont en tension

Reprends à l'étape 4. Crée la fiche, crée le workspace, lance une première session.

Checklist

• [ ] voix.md à la racine
• [ ] shared/conventions.md
• [ ] shared/orga/personas/persona-{nom}.md
• [ ] {workspace}/CLAUDE.md (60-100 lignes)
• [ ] {workspace}/sessions/
• [ ] Première session lancée
• [ ] Le persona dit "non" quand il faut

Onboarding d'un nouveau persona

Comment intégrer un nouveau persona dans une instance SOFIA existante.

Quand ajouter un persona ?

Un persona se justifie quand :

• Un domaine émerge que personne ne couvre correctement
• Deux personas existants sont en tension sur un sujet récurrent
• Le PO passe du temps à faire un travail qu'un persona pourrait structurer

Un persona ne se justifie pas quand :

• C'est une tâche, pas un rôle (utilise une note ou un backlog item)
• Le domaine est couvert mais "pas assez bien" (améliore le persona existant)

Étapes

1. Définir le rôle

Avant de nommer le persona, définir :

• Quoi — quels types de livrables il produit
• Pas quoi — ce qu'il ne fait explicitement pas (le plus important)
• Avec qui — ses interactions principales

2. Créer la fiche persona

Utiliser le template core/templates/persona.md. Champs clés :

• Profil, posture, domaines d'intervention
• Collaboration (tableau avec/mode)
• Ce qu'il ne fait pas

3. Créer le workspace

{instance}/
└── {workspace}/
    ├── CLAUDE.md      ← généré depuis core/templates/workspace/CLAUDE.md
    ├── backlog.md     ← généré depuis core/templates/backlog.md
    └── sessions/      ← vide, le persona écrira son premier résumé

Le CLAUDE.md doit contenir :

• Persona + lien vers la fiche
• Périmètre + documents clés
• Isolation (lecture/écriture autorisées)
• Workflow (ouverture/fermeture de session)
• Conventions du projet

4. Briefer le persona

À la première session, le persona doit :

1. Lire sa fiche persona
2. Lire les documents clés de son domaine
3. Scanner shared/notes/ pour d'éventuels messages
4. Déposer un premier résumé de session

5. Présenter au reste de l'équipe

Déposer une note dans shared/notes/ :

note-equipe-nouveau-persona-{auteur}.md

Contenu : qui, pourquoi, quel périmètre, avec qui il interagit. Les autres personas le découvriront à leur prochaine ouverture de session.

Exemple : onboarding Sofia (Katen, mars 2026)

Sofia a été onboardée par Nora (UX) (UX) :

1. Fiche persona définie avec posture "le détail fait le produit"
2. Workspace graphisme/ créé avec CLAUDE.md spécifique
3. Brief : liste de lecture ciblée (design-principles, design-system, feature-v022)
4. Première session : exploration visuelle, planche de référence v1

Le brief était un document dédié (onboarding-sofia.md) — court, ordonné, avec des renvois vers les docs existants plutôt que du contenu dupliqué.

Anti-patterns

• Le persona fourre-tout — "il fait un peu de tout". Si tu ne peux pas

dire ce qu'il ne fait pas, il n'est pas calibré.

• Le persona orphelin — aucune interaction avec les autres. Un persona

isolé ne génère pas de friction utile.

• Le persona miroir — il fait la même chose qu'un autre avec un nom

différent. Fusionne plutôt que de dédoubler.