Règles et décisions d’équipe

Une décision prise dans la session d’agent d’une personne reste dans cette session. La session suivante, ou l’agent d’un collègue, n’en entend jamais parler. Les règles d’équipe donnent à ces décisions un emplacement que chaque agent lit : un dépôt pour l’organisation, un fichier par dépôt, et un outil de lecture.

C’est une convention accompagnée d’un outil. Il n’y a rien à activer.

Où se trouvent les règles

Les fichiers sont lus sur la branche par défaut de chaque dépôt : une règle change donc par une pull request, comme toute autre modification, avec revue et historique.

Chaque titre ## ouvre une règle (ou une décision) ; le titre lui donne son nom. Le texte situé avant le premier titre ## est conservé comme préambule.

# Rules

## Migrations
Every migration is expand-only. A column is dropped in a later release, never in the one that stops using it.

## Review
One approval from someone who did not write the change.

Comment se combinent les règles de l’organisation et du dépôt

Les règles de l’organisation et celles du dépôt sont fusionnées par titre. Une règle de dépôt portant le même titre qu’une règle de l’organisation la remplace (la casse et la ponctuation ne comptent pas) : un dépôt peut ainsi durcir ou assouplir une règle sans recopier les autres. Les règles propres au dépôt viennent après celles de l’organisation.

<!-- web/.forgejo/RULES.md -->
## Review
Two approvals: this repository takes payments.

get_team_rules : l’outil qu’appellent les agents

Il renvoie chaque règle avec son kind (rules ou decisions), son title, son body, son origine, organisation ou dépôt (scope), le fait qu’elle remplace ou non une règle de l’organisation (overrides_org), et sa source (dépôt, chemin et branche). files liste chaque fichier recherché et indique s’il a été trouvé. digest change dès que les règles fusionnées changent.

Il nécessite findings:read (ou orgs:read) et un accès en lecture au dépôt. Une personne qui peut lire le dépôt mais pas le dépôt .rules n’obtient que les règles du dépôt ; les fichiers de l’organisation sont alors listés comme not_readable.

Les règles sont des instructions destinées à vos agents, au même titre que le fichier AGENTS.md du dépôt, et toute personne disposant d’un accès en écriture au dépôt .rules ou au dépôt concerné peut les modifier. Accordez l’accès en écriture à .rules en conséquence. Une règle n’accorde jamais de permission.

Mettez les règles dans AGENTS.md ou CLAUDE.md

Les agents qui lisent un fichier AGENTS.md ou CLAUDE.md mais n’appellent pas d’outils peuvent porter les règles dans ce fichier. ?format=agents-md renvoie un bloc Markdown placé entre deux marqueurs :

<!-- fremforge:team-rules:start -->
...
<!-- fremforge:team-rules:end -->

Le bloc contient exactement les mêmes octets pour les mêmes règles. Pour l’ajouter ou le mettre à jour, exécutez ceci depuis la racine du dépôt (seul le bloc est remplacé, et il est ajouté à la fin la première fois) :

ORG=<org>; REPO=<repo>; FILE=AGENTS.md
curl -fsS -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/$ORG/repos/$REPO/team-rules?format=agents-md" > .team-rules.md
touch "$FILE"
python3 - "$FILE" .team-rules.md <<'PY'
import sys
path, block = sys.argv[1], open(sys.argv[2]).read().strip()
cur = open(path).read()
s, e = '<!-- fremforge:team-rules:start -->', '<!-- fremforge:team-rules:end -->'
if s in cur and e in cur:
    new = cur[:cur.index(s)] + block + cur[cur.index(e) + len(e):]
else:
    new = cur.rstrip() + ('\n\n' if cur.strip() else '') + block + '\n'
open(path, 'w').write(new)
PY
rm .team-rules.md

Commitez le résultat dans une pull request. Pour vérifier en CI que la copie est à jour, comparez le digest: du bloc du fichier avec l’en-tête X-Fremforge-Rules-Digest de la même requête.

Si vous préférez ne pas recopier les règles dans le fichier, une seule ligne suffit pour les agents capables d’appeler des outils :

At the start of a task, call get_team_rules for this repository and follow the rules it returns.

Décisions

DECISIONS.md a la même forme que RULES.md : un titre ## par décision. Écrivez la décision, sa date et sa justification, afin qu’un agent qui retombe sur la question ne la tranche pas une seconde fois :

## Kysely, not Drizzle (2026-10-01)
New database code uses Kysely. Drizzle stays only in the frozen migrations.