Guide agent IA contributeur

Ce guide s’adresse aux agents IA (Claude, Codex, Gemini, etc.) qui contribuent du code à arka-deck via la CLI ou un éditeur intégré. Il rassemble les working rules à respecter pour que les contributions soient propres et sûres.

Les contributeurs humains peuvent aussi le consulter — les règles s’appliquent universellement.

Règles de base

Respecter le périmètre demandé. Si la tâche dit “modifier core/use-cases/projects/”, ne pas toucher à adapters/inbound/web/ui/. En cas de besoin légitime hors périmètre, le documenter avant d’éditer.
Worktree partagé. Un dépôt arka-deck en cours de chantier peut avoir des modifications non commitées d’autres contributeurs. Ne jamais reverter ce qui n’a pas été créé par vous. Les modifications non liées à votre tâche restent telles quelles.
Lire avant d’écrire. Avant de modifier un fichier, lire son contenu et son contexte. Le code n’est pas du contenu interchangeable — il a une histoire et des dépendances.
Une PR = une intention. Pas de mélange “refactor + nouvelle feature + fix linter”. Découper.
Pas d’opportunisme. Pas de “tant que j’y suis je nettoie ce fichier”. Le scope de la PR est défini par la tâche, pas par votre humeur.

Lecture obligatoire

Avant de toucher au code, lire :

L’architecture : ../architecture/overview
Le bus d’événements : ../architecture/event-bus
Les ADR pertinents : ../../adr/README.md
Le module touché (la fiche addon ou la référence du domaine concerné)

Pour les modifications non triviales, lire aussi les tests existants — ils documentent le comportement attendu.

Frontières d’import

Le linter ESLint applique des frontières strictes (ADR 0001) :

Source	Interdit d’importer
`core/**`	`adapters/`, `composition/`, `addons/`, `providers/`
`core/domain/**`	`core/use-cases/**`
`adapters/inbound/**`	`adapters/outbound/**`
`adapters/**`	`addons/**`

Une violation = lint qui échoue = CI rouge. Ne pas tenter de contourner.

Conventions de commit

Conventional commits : <type>(arka-deck): <description courte> (docs, feat, fix, refactor, ci, style, chore).
DCO sign-off : git commit -s (ajoute Signed-off-by:).
Description précise : verbes actifs, focus sur le WHY, pas seulement le WHAT.

Exemple :

docs(arka-deck): refonte documentaire — produit/dev séparés, bilingue strict

Refond docs/ en deux portes d'entrée distinctes pour clarifier
l'audience PM vs contributeur dev.

Tests obligatoires

Pour toute modification de code :

Ajouter ou mettre à jour les tests dans le périmètre touché.
npm test doit passer localement.
Pour les routes HTTP, ajouter un test dans adapters/inbound/web/server/src/__tests__/.
Pour les modifications de sécurité (URL, secrets), tests unitaires directs sur la politique.

Anti-patterns à éviter

Mocker `fs` ou `node:fs` globalement

❌ Utiliser InMemoryFilesystem injecté en deps.

Écrire dans `.claude/settings.json`

❌ arka-deck ne mute jamais .claude/settings.json (settings utilisateur Claude Code). Voir le pattern Materializer.

Référencer `.input/`

❌ Le dossier .input/ est interne (gitignored). Ne jamais le citer dans un fichier versionné.

Promesses non livrées

❌ Ne pas écrire “marketplace tiers actif” ou “Tauri disponible” tant que ce n’est pas vrai en production. Les promesses futures vont dans ROADMAP.md.

Logger un secret

❌ Pas de logger.info('instance créée', instance) si instance peut contenir une clé. Loguer uniquement l’id.

Self-check avant de soumettre

La tâche est complète (pas d’implémentation partielle).
Les tests existants passent (npm test).
Les nouveaux comportements sont testés.
npm run lint passe.
npm run typecheck passe.
Les frontières d’import sont respectées (lint).
Aucun .input/ ou fichier interne référencé.
Commit signé DCO (git commit -s).
Description claire du WHY dans le commit.

Voir aussi

GitNexus pour la navigation et l’impact : ./gitnexus
Conventions détaillées : ./conventions
CI gates : ./ci-gates