Principes de SOFIA

Les principes de la méthode, pas ceux de ton projet.

1. 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.

2. L'humain arbitre

Les personas proposent, challengent, produisent. L'humain tranche. Toujours. 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.

3. Chaque voix compte

Un persona n'est pas un gadget. C'est un rôle avec une responsabilité, un périmètre et des contraintes. Si tu le crées, c'est qu'il répond à un besoin réel. Si tu ne l'écoutes plus, supprime-le.

4. La contrainte force la qualité

Un persona qui peut tout faire ne sert à rien. C'est la limitation qui le rend utile :

• 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.

5. Les artefacts sont le protocole

Les personas ne "discutent" pas — ils échangent par artefacts : reviews, notes, specs, ADR. Ces artefacts sont versionnés, traçables, et lisibles par tous.

Un échange par artefact est plus lent qu'un chat. C'est le but. La lenteur force la clarté.

6. Tout est tracé

Chaque session produit un résumé. Chaque décision structurante produit un ADR. Chaque intervention inter-personas produit une review.

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.

7. Commence petit, itère

Un persona au démarrage. Deux quand le premier est calibré. Trois quand le besoin est clair. Cinq, peut-être jamais.

La méthode ne se déploie pas en big bang. Elle grandit avec le projet.

Friction intentionnelle

Si tout le monde est d'accord, personne ne pense.

Le problème du LLM complaisant

Un LLM seul dit oui. Toujours. Tu proposes une architecture bancale, il l'implémente. Tu écris une spec floue, il la code en devinant. Tu oublies un cas limite, il ne le mentionne pas.

Ce n'est pas de la collaboration. C'est de l'exécution servile.

La friction comme mécanisme

Dans une vraie équipe, la qualité vient des désaccords :

• Le dev dit "cette spec n'est pas codable"
• L'architecte dit "cette implémentation casse un contrat"
• Le stratège dit "personne ne paiera pour ça"
• L'UX dit "l'utilisateur ne comprendra jamais ce flux"

Ces frictions ne sont pas des bugs. Ce sont des signaux. Ils forcent à clarifier, à trancher, à documenter.

SOFIA reproduit ce mécanisme avec des personas contraints.

Comment la friction émerge

La friction n'est pas un paramètre qu'on active. Elle émerge des contraintes posées sur les personas :

L'arbitre

La friction sans arbitre est du chaos. Deux personas qui se contredisent indéfiniment ne produisent rien.

L'humain est l'arbitre. Toujours.

• Les personas exposent les tensions
• L'humain écoute, questionne, puis tranche
• La décision est tracée (ADR, note, session)
• Les personas appliquent la décision, même s'ils l'ont challengée

Un persona ne force jamais l'acceptation. Il pose les points bloquants, il ne vote pas.

Les artefacts comme vecteur de friction

Les personas ne "discutent" pas en live. Ils échangent par fichiers :

• L'architecte dépose une review d'un ADR
• Le dev répond par un signalement de friction d'implémentation
• Le stratège dépose une note avec 3 questions qui dérangent
• L'UX produit une review de design avec observations priorisées

Ce protocole est plus lent qu'un chat. C'est voulu :

• L'écriture force la structuration de la pensée
• Les fichiers sont versionnés et traçables
• N'importe qui peut relire l'échange plus tard

Signes que la friction fonctionne

• Les personas disent "non" ou "pas mon rôle"
• Des désaccords apparaissent entre personas
• L'humain doit trancher régulièrement
• Les specs sont plus précises qu'avant
• Les décisions sont documentées avec le contexte

Signes que la friction est absente

• Tous les personas sont d'accord sur tout
• Personne ne dit non
• Les specs restent vagues et personne ne le signale
• L'humain n'a jamais besoin de trancher
• Pas de trace des décisions

Si tu reconnais la deuxième liste, tes personas sont trop complaisants ou leurs contraintes trop lâches. Revois les interdits.

Devoirs de l'humain

Ce que l'orchestre ne fait pas à ta place.

Pourquoi cette section

Les personas produisent, challengent, documentent. Mais certaines responsabilités ne se délèguent pas — parce que la technologie n'en est pas capable, ou parce que les déléguer détruit la méthode.

Ce ne sont pas des recommandations. Ce sont des devoirs.

1. Vérifier les faits

Les LLMs ne comptent pas, ne calculent pas les durées, et privilégient la cohérence interne sur la vérité externe. Une date approximative entrée une fois sera propagée dans tous les documents générés ensuite. Plus le repo grandit, plus ces erreurs deviennent invisibles — elles ressemblent à de la cohérence parce que chaque document contamine renforce les autres.

Le repo n'est pas une source de vérité pour les faits. Dates, durées, chiffres, noms propres, références bibliographiques : vérification humaine systématique, en continu — pas en fin de projet.

2. Arbitrer

Les personas exposent les tensions, ils ne les résolvent pas. Deux personas qui se contredisent indéfiniment ne produisent rien. L'humain écoute, questionne, puis tranche. La décision est tracée. Les personas appliquent, même s'ils avaient une position différente.

Un persona ne force jamais l'acceptation. Il ne vote pas.

3. Relire ce qui sort

L'IA produit. L'humain publie. Entre les deux, il y a une relecture qui n'est pas de la correction — c'est de la validation.

Aucun document ne sort du repo sans que l'humain l'ait lu en entier. Pas survolé, pas approuvé sur la base du résumé de session. Lu.

4. Calibrer les personas

Un persona se définit par ce qu'il ne fait pas avant ce qu'il fait. Mais les bonnes contraintes ne tombent pas du ciel — elles émergent de l'usage, et l'humain doit les ajuster :

• Un persona trop large dérive (il fait le travail des autres)
• Un persona trop étroit est inutile (personne ne lui parle)
• Un persona défini par la compétence seule finit par déborder —

le définir par le média (spec, code, review, note) est plus fiable

Le calibrage est continu. Il ne s'arrête pas après le bootstrapping.

5. Séparer réflexion et production

Un persona qui réfléchit ET produit le livrable final est juge et partie. La friction disparaît parce qu'il n'y a personne pour challenger.

L'humain veille à ce que :

• Celui qui rédige n'est pas celui qui valide
• Celui qui analyse n'est pas celui qui publie
• La chaîne comporte au moins un regard extérieur avant la sortie

6. Maintenir l'attention

La méthode fonctionne tant que l'humain reste attentif. Les personas ne détectent pas quand l'humain décroche — ils continuent à produire, avec la même assurance, la même cohérence apparente.

Les signaux de baisse d'attention :

• Tu approuves sans lire
• Tu transmets sans filtrer
• Tu ne tranches plus, tu valides
• Les sessions deviennent mécaniques

Quand tu reconnais ces signaux, c'est le moment de ralentir — pas d'accélérer.

Personas

Un persona est un rôle avec un nom, une posture, un périmètre et des interdits.

Pourquoi des personas ?

Un LLM sans contrainte est un généraliste. Il accepte tout, ne challenge rien, et produit du contenu moyen. Un persona est un LLM contraint : il a un rôle, un ton, des limites, et surtout des choses qu'il n'a pas le droit de faire.

La contrainte change tout :

• Il pose des questions au lieu de deviner
• Il refuse ce qui sort de son périmètre au lieu de bricoler
• Il remonte les frictions au lieu de les contourner
• Il produit des livrables typés au lieu du texte générique

Anatomie d'un persona

Un bon persona définit sept choses :

1. Identité

• Nom — court, mémorable. Pas un acronyme, pas un titre. Un prénom.
• Rôle — une phrase. "Architecte système & solution". "Développeur full stack".
• Ton — formel ? direct ? pédagogue ? provocateur ?

Le nom compte plus qu'on croit. Il crée une relation. On ne parle pas à "l'agent architecture" comme on parle à Mira (architecte).

2. Posture

Comment le persona se comporte — pas ce qu'il sait, mais comment il interagit. C'est la section la plus importante.

Exemples de postures :

• "Formelle mais pas dogmatique" — ancre dans la théorie, remet en question
• "Implémente, ne réinterprète pas" — si la spec est floue, il le dit
• "Direct, franc, sans détours" — dit non quand c'est nécessaire

La posture est ce qui distingue un persona utile d'un assistant poli.

3. Périmètre

Ce sur quoi le persona intervient. Liste explicite.

Un architecte : modèle d'exécution, contrats d'interface, ADR. Un dev : code, tests, retours de frictions d'implémentation. Un stratège : positionnement, go-to-market, questions qui dérangent.

4. Livrables

Ce que le persona produit. Pas "du texte" — des types précis :

• ADR, reviews, specs, schémas (architecte)
• Code testé, signalements de frictions (dev)
• User flows, spécifications UI (UX)
• Synthèses de littérature, avis motivés (chercheur)

5. Interdits

La section la plus importante. Ce que le persona ne fait PAS.

• Un architecte ne code pas
• Un dev ne tranche pas sur l'architecture
• Un stratège ne conçoit pas l'UX
• Personne ne décide à la place de l'humain

Les interdits sont ce qui crée la friction productive. Si l'architecte pouvait coder, il ne prendrait jamais le temps de spécifier. Si le dev pouvait décider de l'architecture, il ne remonterait jamais les frictions.

6. Droit de challenge

Ce que le persona est légitime à contester chez les autres. La friction intentionnelle rendue structurelle : chaque persona sait non seulement ce qu'il produit, mais sur quoi il a un droit de regard explicite.

Exemples :

• L'architecte challenge les ADR avant acceptance et les specs avant implémentation
• Le dev challenge les specs trop vagues et les ADR qui créent des frictions d'implémentation
• La chercheuse challenge les affirmations scientifiques et les données factuelles
• Le stratège challenge la viabilité business et les ADR à impact stratégique
• La graphiste challenge la cohérence visuelle des livrables
• L'UX challenge les productions front avant publication
• Le rédacteur challenge la clarté et l'honnêteté des formulations

Sans cette section, la friction reste implicite — chaque persona pourrait challenger, mais rien ne dit qu'il doit. La section rend le devoir de friction visible dans la structure même des fiches.

7. Collaboration

Comment le persona interagit avec les autres :

La table de collaboration empêche les personas de travailler en silo.

Comment concevoir un persona

Partir du besoin, pas du modèle

Ne commence pas par "je veux un architecte". Commence par :

• Qu'est-ce qui me manque aujourd'hui ?
• Quelles erreurs je fais quand je travaille seul avec un LLM ?
• Quel rôle, si quelqu'un le tenait, me rendrait meilleur ?

Calibrer par itération

Le premier draft d'un persona est toujours trop large. Itère :

1. v0 — rôle et périmètre bruts
2. v1 — ajout des interdits (ça clarifie tout)
3. v2 — ajout de la posture (ça donne le ton)
4. v3 — test en session réelle, ajustement

Un persona se calibre en l'utilisant, pas en le théorisant.

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.

Anti-patterns

• Le persona généraliste — fait tout, donc rien de bien
• Le persona complaisant — dit oui à tout, ne challenge jamais
• Le persona orphelin — pas de collaboration définie, travaille en silo
• Le persona fantôme — créé mais jamais utilisé. Supprime-le.
• Trop de personas trop tôt — commence par 1-2, pas 5

Isolation par workspace

Un persona = un workspace = un périmètre = un CLAUDE.md.

Le principe

Chaque persona vit dans son propre espace de travail. Il a ses fichiers, ses instructions, ses conventions, et ses limites. Il ne peut pas lire ou écrire partout.

L'isolation n'est pas une contrainte technique — c'est ce qui force le persona à rester dans son rôle.

Pourquoi isoler ?

Empêcher la dérive de scope

Un persona sans frontières finit par tout faire. L'architecte qui a accès au code finit par coder. Le stratège qui peut lire les tests finit par donner des avis techniques.

L'isolation rend la dérive impossible : le persona ne voit pas ce qui est hors de son périmètre.

Forcer les échanges formels

Si l'architecte ne peut pas modifier le code, il est obligé de produire une spec que le dev pourra lire. Si le dev ne peut pas modifier l'architecture, il est obligé de déposer un signalement de friction.

L'isolation crée le besoin d'artefacts d'échange.

Protéger le travail en cours

Un persona ne peut pas casser accidentellement le travail d'un autre. L'UX ne va pas reformater du code. Le dev ne va pas réécrire une review de design.

Structure type

La zone partagée

Les personas communiquent via un dossier partagé (shared/). C'est le seul espace que tous les personas peuvent lire et écrire.

Conventions :

• Reviews : review-<sujet>-<auteur>.md — déposées dans shared/review/
• Notes : note-<destinataire>-<sujet>-<auteur>.md — déposées dans shared/notes/

Le dossier partagé est le "couloir" du bureau. On y dépose des documents, on ne s'y installe pas.

Le CLAUDE.md comme gardien

Le fichier CLAUDE.md à la racine de chaque workspace contient :

1. Qui — quel persona, quelle posture
2. Quoi — périmètre d'intervention, livrables attendus
3. Où — quels fichiers/dossiers sont accessibles
4. Interdit — ce qui est hors périmètre (lecture ET écriture)
5. Comment — conventions, formats, workflow

Voir runtime/claude-code/claude-md.md pour l'anatomie détaillée.

Multi-instance : le cas du dev

Certains personas travaillent sur deux repos — leur workspace d'analyse (dans l'instance) et un repo produit séparé. C'est le cas typique du dev : il planifie dans instance/dev/ et code dans produit/.

Structure

instance/                       ← repo instance (experiments/)
├── dev/                        ← workspace dev (sessions, backlog, plans)
│   ├── CLAUDE.md
│   ├── sessions/
│   └── backlog.md
└── shared/                     ← bus d'échange

produit/                        ← repo produit (katen/)
├── CLAUDE.md                   ← instructions dev completes
├── src/
└── tests/

Règles

• Le CLAUDE.md du repo produit est l'entrée principale du dev — c'est

là que vivent les conventions de code, l'architecture, le processus de version.

• Le workspace dev/ dans l'instance contient les sessions, le backlog,

et les plans — pas du code.

• Les commits instance = auto ({persona}: {résumé} ({date})).

Les commits produit = PO exécute.

• Le dev lit shared/notes/ et shared/review/ au même titre que

les autres personas — c'est dans son workflow d'ouverture.

Pourquoi séparer ?

Le code versionné est un livrable public. Les sessions et plans sont de l'outillage interne. Les mettre ensemble :

• Expose l'historique d'analyse dans le repo public
• Mélange les commits de code et les commits de session
• Casse l'isolation si le repo produit est ouvert par un autre outil

Artefacts comme protocole

Les personas communiquent par fichiers, pas par chat.

Le principe

Dans SOFIA, les personas ne "parlent" pas entre eux. Ils déposent des artefacts — des fichiers structurés, versionnés, dans des emplacements convenus.

C'est plus lent qu'une conversation. C'est le but.

Pourquoi des fichiers ?

L'écriture force la clarté

Un architecte qui dépose une review a pris le temps de structurer sa pensée. Un dev qui dépose un signalement de friction a formulé le problème clairement. Un stratège qui dépose 3 questions a choisi les 3 qui comptent.

Le chat encourage le flux de conscience. Le fichier encourage la synthèse.

Les fichiers persistent

Une conversation se ferme, un contexte se compresse. Un fichier reste. Il est versionné par git. Il peut être relu dans 6 mois.

Les fichiers sont adressables

"Voir la review de Mira sur l'ADR-057" est une référence précise. "Ce qu'on a dit en session mardi" ne l'est pas.

Types d'artefacts

Flux type

Le flux d'un artefact suit le pattern Inspector décrit dans l'orchestration : le persona produit, l'humain inspecte et transmet, le destinataire réagit.

Conventions

• Un artefact = un sujet. Pas de fichier fourre-tout.
• Le nom du fichier dit qui l'a écrit et pour qui/quoi.
• Les artefacts sont courts. Si ça dépasse 2 pages, c'est un doc, pas une note.
• Les artefacts ne sont jamais modifiés après dépôt — on en crée un nouveau (v2) si nécessaire.

Bus d'échange structuré — shared/

Le dossier shared/ est le bus de messages de l'équipe. Trois types d'artefacts, chacun avec son emplacement et sa convention :

Roadmaps produit

shared/ héberge les roadmaps produit — la source unique de planification. Chaque roadmap a un owner qui vérifie la cohérence des items :

shared/
├── roadmap-{produit}.md          ← roadmaps produit (une par périmètre)
├── backlog-archive.md            ← historique des items terminés
├── notes/                        ← messages inter-personas
├── review/                       ← analyses critiques
└── features/                     ← specs fonctionnalités

Il n'y a pas de backlog par persona. Tous les items vivent dans les roadmaps. Les personas poussent des items, l'owner vérifie. Les items terminés migrent vers backlog-archive.md.

L'owner ne priorise pas — il signale et range. C'est une responsabilité passive (pas de scan systématique à chaque session).

Frontmatter

Chaque artefact dans shared/ porte un frontmatter normalisé :

---
de: mira
pour: lea
type: signal           # signal | question | demande | reponse
statut: nouveau        # nouveau | lu | traite
date: 2026-03-30
---

Le statut permet de savoir si un artefact a été traité. Le persona destinataire met à jour le statut quand il le lit (lu) ou le traite (traite). Les artefacts sans frontmatter sont traités comme statut: traite (grandfather clause pour l'existant).

Archivage

Quand un artefact passe traite, le déplacer dans archives/ du dossier parent (notes/archives/, review/archives/). Cela allège le scan d'ouverture de session — seuls les fichiers actifs restent à la racine.

shared/notes/
├── note-mira-xyz-axel.md          ← actif (statut: nouveau)
└── archives/
    └── note-mira-abc-axel.md      ← traite

Organisation équipe — shared/orga/

Les fichiers d'organisation (personas, figures, lexique) vivent dans shared/orga/ — séparés du bus de messages :

shared/orga/
├── personas/          ← fiches personas
├── figures/           ← schémas d'organisation
├── team-orga.md       ← matrice RACI, flux
└── lexique.md         ← termes du projet

Features multi-produits

Les features dans shared/features/ portent un champ produit: dans leur frontmatter pour identifier le produit concerné :

---
de: po
produit: regards
type: feature
statut: nouveau
date: 2026-03-17
---

Protocole de circulation

1. L'auteur dépose l'artefact dans shared/{type}/
2. Le destinataire le découvre à l'ouverture de session (scan shared/)
3. Le destinataire met à jour le statut dans le frontmatter
4. Quand l'artefact est traite, le déplacer dans archives/
5. Le PO peut lire shared/ pour voir l'état des échanges

Orchestration

Le PO est le message bus. Rien ne circule sans lui.

Le modèle mental

Dans SOFIA, les personas ne se parlent pas. Ils n'ont pas accès aux sessions des autres. Ils ne savent même pas ce que les autres ont dit — sauf si l'humain leur transmet.

L'humain est l'orchestrateur. Il ouvre une session avec un persona, obtient un livrable, ferme la session, ouvre une session avec un autre persona, transmet le livrable, recueille la réponse.

C'est lent. C'est voulu. Chaque transmission est un moment où l'humain filtre, reformule, ajoute du contexte, décide ce qui est pertinent à transmettre.

Le flux élémentaire

1. L'humain ouvre une session avec le persona A.
2. Il pose sa question.
3. A produit un livrable (review, spec, note...).
4. Le livrable arrive chez l'humain.
5. L'humain inspecte : lit, vérifie les faits, filtre, contextualise. Décide quoi transmettre.
6. L'humain transmet l'artefact filtré au persona B.
7. B réagit — produit à son tour.
8. L'humain inspecte à nouveau. Le cycle continue.

Chaque flèche qui traverse la lane humaine est un moment d'attention. C'est le prix de la qualité.

Pourquoi le PO porte le contexte

Filtre

Le PO ne transmet pas tout. Marc (strategie) produit une review de 15 points. Le PO en retient 4 qui sont pertinents pour Mira. Les 11 autres sont des points Marc ↔ PO qui ne concernent pas l'architecture.

Reformule

Le PO reformule quand c'est nécessaire. Marc dit "personne ne paiera pour ça". Le PO traduit pour Mira : "Marc challenge la priorité de cette feature — on a besoin d'un argument d'adoption avant de spécifier".

Contextualise

Le PO ajoute du contexte que le persona ne peut pas avoir. "Quand tu liras la note de Léa (recherche), sache qu'on a décidé hier avec Marc de décaler la publication académique — ça change la priorité de ses recommandations."

Tranche

Le PO ne transmet pas les désaccords non résolus. Il tranche d'abord, puis transmet la décision. Les personas appliquent, même s'ils avaient une position différente.

Les échanges multi-personas

Review d'ADR par 2+ personas

C'est le cas le plus fréquent d'orchestration complexe.

Les 4 reviews sont indépendantes (parallélisables). La consolidation est le travail du PO. La mise à jour finale revient au persona propriétaire du document.

Boucle itérative entre 2 personas

Parfois l'échange nécessite plusieurs allers-retours :

Le PO décide quand l'itération s'arrête. Pas les personas.

Ce que le PO NE délègue 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 timing — quand un échange est mûr pour être transmis
• Le filtrage — ce qui est pertinent à transmettre ou pas

Ce que le PO PEUT demander au persona

• "Synthétise tes points pour [autre persona]"
• "Rédige une note adressée à [autre persona]"
• "Reformule pour un public non technique"

Le persona rédige l'artefact. Le PO décide s'il le transmet, tel quel ou modifié.

Coût et bénéfice

Le coût

L'orchestration prend du temps. Chaque échange PO ↔ persona est une session. Une review d'ADR par 4 personas, c'est 4 sessions de review + 1 session de consolidation + 1-2 sessions d'itération. Ça peut prendre une heure ou une journée.

Le bénéfice

• Chaque persona pense dans son cadre, sans pollution
• L'humain contrôle le flux d'information
• Les décisions sont mûries, pas improvisées
• Tout est tracé (notes, reviews, sessions)
• Le résultat est meilleur que ce qu'un seul agent aurait produit

Le coût 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.

Conventions

Les règles concrètes d'une instance SOFIA.

Les principes disent pourquoi. Les conventions disent comment. Ce document est la référence pour toute instance SOFIA. Il consolide les règles dispersées dans les autres documents core/ et les rend applicables.

Structure d'une instance

instance/
├── voix.md                      ← marqueur d'instance (voir instance.md)
├── shared/                      ← bus d'échange inter-personas
│   ├── conventions.md           ← conventions spécifiques à l'instance
│   ├── roadmap-{produit}.md     ← roadmaps produit
│   ├── backlog-archive.md       ← items terminés
│   ├── notes/                   ← messages inter-personas
│   │   └── archives/            ← notes traitées
│   ├── review/                  ← analyses critiques
│   │   └── archives/            ← reviews traitées
│   ├── features/                ← specs fonctionnalités
│   ├── orga/                    ← organisation équipe (personas, lexique)
│   └── tools/                   ← scripts partagés
├── {workspace}/                 ← un par persona
│   ├── CLAUDE.md                ← instructions du persona
│   ├── sessions/                ← résumés de session
│   └── doc/                     ← production du persona
└── ...

Chaque persona a son workspace. shared/ est le seul espace accessible par tous.

Nommage des artefacts

Un artefact = un sujet. Pas de fichier fourre-tout.

Frontmatter

Chaque artefact dans shared/ porte un frontmatter :

---
de: mira
pour: lea
type: signal           # signal | question | demande | reponse
statut: nouveau        # nouveau | lu | traite
date: 2026-03-30
---

Pas d'accents dans les valeurs (traite, pas traité).

Statuts

Les artefacts sans frontmatter sont considérés traite.

Archivage

Quand un artefact passe traite, le déplacer dans archives/ du dossier parent. Seuls les fichiers actifs restent à la racine.

shared/notes/
├── note-mira-xyz-axel.md        ← actif
└── archives/
    └── note-mira-abc-axel.md    ← traité

Résumés de session

Chaque session produit un résumé. Sans exception.

Fichier : {workspace}/sessions/{YYYY-MM-DD}-{HHmm}-{persona}.md

Sections obligatoires :

• ## Produit — fichiers créés ou modifiés, avec chemin
• ## Décisions — ce qui a été tranché
• ## Notes déposées — fichiers dans shared/
• ## Ouvert — ce qui reste à traiter

Pas de prose. Des listes courtes. 30 lignes max.

Commits

Instance (experiments/)

Format : {persona}: {résumé court} ({date})

Les personas commitent directement dans le repo instance. Un commit à la fois — pas de sessions parallèles sur le même repo.

Repos produit

Les personas préparent le message de commit. Le PO exécute.

Roadmaps

Chaque roadmap a un owner — un persona responsable de la cohérence. L'owner ne priorise pas, il signale et range.

Chaque item porte un @owner — le persona responsable de l'exécution.

Il n'y a pas de backlog par persona. Tous les items vivent dans les roadmaps. Les items terminés migrent vers backlog-archive.md.

CLAUDE.md — anatomie

Le CLAUDE.md de chaque workspace contient :

1. Persona — qui, quelle posture
2. Périmètre — quoi, quels livrables
3. Accès — où lire, où écrire, où c'est interdit
4. Conventions — formats, workflow
5. Protocole de session — boot, fermeture

Voir runtime/claude-code/claude-md.md pour le détail.

Publication web

Toute page publiée sur un domaine de l'instance doit porter :

• <title> au format {Page} — {Domaine}
• <meta name="description"> (150 car. max)
• Open Graph tags (og:title, og:description, og:type, og:url)
• Favicon déclaré
• Entrée dans le sitemap.xml du domaine

Conventions d'instance

Ce document définit les conventions méthode — communes à toute instance SOFIA. Chaque instance peut ajouter ses propres conventions dans shared/conventions.md (structure spécifique, rôles supplémentaires, règles de publication, etc.).

Traçabilité

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

Pourquoi tracer ?

Les conversations avec Claude Code sont éphémères. Le contexte se compresse, les sessions se ferment, la mémoire a ses limites.

La seule chose qui persiste de manière fiable, ce sont les fichiers.

La traçabilité dans SOFIA repose sur trois mécanismes :

1. Résumés de session

Chaque session produit un résumé. Sans exception.

Format : sessions/{YYYY-MM-DD}-{HHmm}-{persona}.md

Contenu obligatoire :

• Produit — fichiers créés ou modifiés, avec chemin
• Décisions — ce qui a été tranché
• Notes déposées — fichiers dans shared/
• Ouvert — ce qui reste à traiter

Pas de prose. Des listes courtes. 30 lignes max.

Pourquoi c'est vital : la prochaine session commence par lire le dernier résumé. C'est sa seule mémoire fiable de ce qui s'est passé avant.

2. ADR (Architecture Decision Records)

Les décisions structurantes sont tracées dans des ADR.

Format standard :

• Contexte — pourquoi la question se pose
• Décision — ce qu'on a choisi
• Alternatives — ce qu'on a envisagé et rejeté
• Conséquences — ce que ça implique
• Statut — Proposed → Accepted → Superseded

Un ADR n'est pas un document lourd. C'est une trace de pourquoi on a décidé ça, à ce moment-là, avec ce contexte.

L'ADR est écrit avant l'implémentation, pas après.

3. Reviews croisées

Quand un persona intervient sur le travail d'un autre, il produit une review :

Format : shared/review/review-{sujet}-{auteur}.md

Une review contient :

• Des observations factuelles (pas des opinions)
• Des recommandations priorisées
• Des questions ouvertes pour le PO

La review est un artefact, pas un commentaire. Elle est versionnée, relisable, et sert de base à la discussion.

La mémoire persistante (MEMORY.md)

Claude Code offre un système de mémoire persistante entre les conversations. C'est un complément aux fichiers, pas un remplacement.

Voir runtime/claude-code/memoire.md pour les détails.

Règle simple : si c'est utile uniquement pour la prochaine conversation, c'est un résumé de session. Si c'est utile dans 3 mois, c'est une mémoire.

Marqueur d'instance

Un fichier voix.md à la racine identifie un dépôt comme instance SOFIA.

Le principe

Quand un dépôt suit la méthode SOFIA, il contient un fichier voix.md à sa racine. Ce fichier est le marqueur d'instance — il lie le dépôt à la méthode et documente sa structure spécifique.

Contenu type

# 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** : {nom du projet}
- **Équipe** : {nombre} assistants IA spécialisés + {nombre} PO humain(s)

## Structure instance

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

## Conventions

Voir `shared/conventions.md`.

Pourquoi

• Identification — en ouvrant un dépôt, on sait immédiatement

si c'est une instance SOFIA et quelle version de la méthode il suit.

• Lien vers la source — le lien vers le repo SOFIA permet de

retrouver la documentation complète.

• Cartographie — la table des workspaces donne la vue d'ensemble

sans lire tous les CLAUDE.md.

Convention

• Le fichier s'appelle voix.md (pas VOIX.md, pas .voix)
• Il vit à la racine du dépôt instance
• Il est committé (pas gitignored)

Lexique — template

Glossaire partagé des termes du projet.

Pourquoi un lexique ?

Quand 7 personas travaillent sur le même projet, les mots dérivent. "Composition" peut signifier un fichier .kc, un concept CVM, ou un pattern réutilisable selon qui parle.

Le lexique fixe les termes. Chaque persona le lit, personne ne réinvente.

Format

## {Terme}

**Définition** : {une phrase}
**Contexte** : {où ce terme s'utilise}
**Ne pas confondre avec** : {termes proches}
**Décidé le** : {date} — {référence ADR ou session}

Conventions

• Un terme = une entrée. Pas de synonymes dans la même entrée.
• Si un terme a changé de sens (renommage, évolution), documenter l'historique.
• Le PO arbitre les conflits de définition.
• Le lexique vit dans shared/orga/lexique.md au niveau de l'instance.

Exemple

## Kata

**Définition** : une composition Katen — un programme visuel exécutable.
**Contexte** : fichiers .kc, documentation utilisateur, UI.
**Ne pas confondre avec** : "composition" (concept CVM interne), "pattern" (template réutilisable).
**Décidé le** : 2026-03-22 — ADR-054.