Architecture et carte de contribution

Utilisez cette page lorsqu’une modification est plus importante qu’une simple coquille et que vous ne savez pas avec certitude quels documents d’architecture, de fondation, de contributeur ou de mainteneur s’appliquent.

Cette page n’est qu’un plan. Les fichiers liés demeurent la source de vérité.

Commencer ici

Lisez d’abord AGENTS.md à la racine du dépôt. Il contient le contrat concis de sécurité et de contribution, toujours chargé.
Consultez Comment contribuer pour les mécanismes de PR, les attentes en matière de validation et le processus de revue.
Utilisez les tableaux ci-dessous pour choisir l’architecture et les documents de référence qui correspondent au changement.
Consultez les directives des agents de codage lorsqu’une tâche de codage effectuée par une IA nécessite des exemples de référence faisant autorité, une politique relative aux risques et à la stabilité, la découverte de compétences ou des documents opérationnels protégés.
Si le changement franchit des limites de sous-système, de configuration, de sécurité, de flux de travail, de gouvernance ou de publication, consultez le processus RFC avant de procéder à l’implémentation.

Chemins de modification courants

Modifier	À lire d’abord	Pourquoi
Nouveau fournisseur	Vue d’ensemble de l’architecture, Crates, Fournisseurs personnalisés, Configuration des fournisseurs	Les fournisseurs sont des adaptateurs en périphérie derrière le trait de fournisseur, avec le câblage de la configuration et de la fabrique.
Sélection du profil du fournisseur, routes de modèles, remplacements de session, changement de modèle à l’exécution, nouvelle tentative, solution de repli ou attribution du fournisseur	Cycle de vie du routage des fournisseurs, Routage, Configuration des fournisseurs	Conservez la sélection des routes, la politique de tentatives, la construction des profils et l’attribution entre ce qui est demandé et ce qui est servi dans les couches qui en sont responsables.
Analyse du flux du fournisseur, terminaison ou rejeu au niveau du tour	Cycle de vie du routage des fournisseurs, Diffusion en continu, Tests	Conservez la complétion sur le wire dans l’adaptateur et le rejeu de l’appel complet dans le runtime. Ne rejouez jamais après que la sortie d’événement immuable est visible.
Nouveau canal	Vue d’ensemble de l’architecture, Crates, Cycle de vie du runtime des canaux, Vue d’ensemble des canaux, implémentations existantes dans `crates/zeroclaw-channels/`	Les canaux sont des limites de confiance visibles par l’utilisateur ; validez le comportement du cycle de vie entrant, sortant, d’appariement, d’autorisation, de dispatch et de réponse.
Dispatch de canal, ingress webhook, intent de réponse, brouillons en streaming, cycle de vie du listener ou comportement de rechargement du canal	Cycle de vie du runtime de canal, Cycle de vie de la requête, API HTTP de la Gateway, Protocole de plugin, Tests	Les modifications du cycle de vie des canaux nécessitent un chemin unique de dispatch et de tour, au lieu d’adaptateurs ou de mini-orchestrateurs de passerelle ponctuels.
Nouvel outil intégré ou nouvelle politique d’outil	Vue d’ensemble des outils, Inventaire des outils intégrés, Cycle de vie d’exécution des outils, ADR-004: Propriété de l’état partagé des outils, Protocole des plugins, Vue d’ensemble de la sécurité, Reçus d’outils	Les outils exécutent des actions pour l’agent. Vérifiez d’abord si la capacité appartient au core, puis validez l’enregistrement, l’approbation, le dispatch, l’audit, les reçus, la localisation, l’attribution et la propriété de l’état partagé.
Exécution, boucle d’agent, état, diffusion de jetons du fournisseur ou comportement de la boucle d’outils	Cycle de vie des requêtes, État d’exécution et persistance, Cycle de vie d’exécution des outils, Crates, FND-001, Tests	Les changements du runtime affectent souvent plusieurs chemins utilisateur et nécessitent des tests au niveau des frontières. Le streaming de tokens du provider reste sous la responsabilité du runtime ; le streaming de brouillon de canal ou d’indicateur de frappe suit la ligne du cycle de vie du canal. Les changements de la boucle d’outils doivent préciser s’ils affectent l’approbation, le dispatch, les reçus, les événements d’observateur, l’historique ou l’annulation.
Comportement de Cron, des SOP, de la délégation, des sous-agents, du mode objectif, de l’attente, de l’annulation ou de la récupération après redémarrage	Cycle de vie du travail en arrière-plan, Délégation et SubAgents, Tests	L’exécution en arrière-plan ne constitue pas un cycle de vie unique. Répertoriez les surfaces actuelles de propriété et d’état, distinguez les enregistrements durables du travail pouvant être repris après un redémarrage, et vérifiez l’annulation et la récupération à la limite modifiée.
Mémoire, historique de session, contexte de la demande, résultats des outils, charges utiles de fichiers/médias ou troncation du contexte	Cycle de vie de la mémoire et des payloads, État du runtime et persistance, Gestion de l’historique, Internes du runtime, Tests	Les modifications de payload nécessitent un propriétaire, une portée, une durabilité, une confidentialité et des limites de troncature clairs.
Journalisation, observabilité, persistance des traces d’exécution, pagination des journaux, rétention ou migration de schéma	Architecture de la journalisation, Journaux et observabilité, État d’exécution et persistance, API HTTP de la passerelle, Vue d’ensemble de la sécurité, Tests	Un événement canonique est fourni indépendamment à la diffusion en direct et au JSONL persistant ; une projection Observer typée facultative s’exécute uniquement lorsqu’elle est liée. Vérifiez les champs de projection, la durée de vie du curseur du fichier actif, le comportement de réécriture et de rétention, la compatibilité des migrations et la confidentialité à la destination modifiée.
Comportement de la passerelle, de l’API web ou du tableau de bord	API HTTP de la passerelle, Création du tableau de bord web, Cycle de vie d’une requête, Vue d’ensemble de la sécurité, Guide du relecteur	Les modifications du gateway peuvent affecter l’authentification, l’exposition publique, les contrats API générés, les consommateurs du tableau de bord et les risques de revue. Utilisez la ligne du cycle de vie du canal pour le dispatch de webhooks ou le comportement des réponses.
Comportement visible par l’utilisateur ou preuve de validation pour une commande, un terminal, un démon, un navigateur, un canal, un fournisseur, un outil, une tâche en arrière-plan ou un chemin d’installation	Preuve de délimitation utilisateur, Tests et le document d’architecture ou de fonctionnalité pour la surface modifiée	Associez chaque affirmation de comportement à la plus petite preuve crédible qui atteint la limite où un utilisateur l’observe. N’ajoutez de preuves manuelles ou spécifiques à l’environnement que pour une lacune nommée dans la couverture automatisée.
Schéma de configuration, variables d’environnement, valeurs par défaut ou comportement de rechargement	Cycle de vie de la configuration, Variables d’environnement, État d’exécution et persistance, Configuration du fournisseur, FND-001, Processus RFC	Les modifications de configuration affectent les chemins de mise à niveau, le comportement de rechargement, les limites de la source de vérité, et peuvent nécessiter une migration ou une discussion autour d’une RFC.
Références générées, préprocesseurs mdBook, extraits de documentation ou déploiement de la documentation	Pipeline de documentation généré, Générer la documentation en local et Cycle de vie de la configuration lorsque les références de configuration changent	Nommez la source canonique, le matérialiseur, la sortie suivie ou générée uniquement, le consommateur et la vérification de dérive.
catalogues Fluent/gettext, registre des locales, repli des traductions ou verrouillage des versions des catalogues	Cycle de vie du catalogue de localisation, Docs & Traductions, Pipeline de documentation générée	Un catalogue présent dans le dépôt ne prouve pas qu’un runtime ou un build de site le consomme. Vérifiez le chemin du loader, du materializer ou du pin.
CI, release, GitHub Actions ou actions autorisées	CI & Actions, FND-004, Processus PR	Les changements d’infrastructure présentent un risque élevé lorsqu’ils modifient ce que le code peut exécuter ou livrer.
Structure de la documentation, recommandations pour les contributeurs ou organisation des connaissances	FND-002, Docs & Traductions, cette page	Les modifications de la documentation doivent réduire le coût de recherche et préserver le fil des décisions.
Gouvernance, étiquettes, flux de travail du tableau ou processus de contribution	FND-003, Processus RFC, Étiquettes, Guide pratique du relecteur	Les changements de processus affectent les mainteneurs et les contributeurs ; gardez-les durables et explicites.
Culture de contribution, de remplacement ou de revue assistée par IA	FND-005, PR de remplacement, Protocole de revue de PR	Le travail assisté par IA est le bienvenu, mais le parrain humain est responsable de l’exactitude, de l’attribution et de la réponse aux relectures.
Santé du code de production, gestion des erreurs ou nettoyage du code mort	FND-006, Testing, `AGENTS.md` à la racine du dépôt	La discipline des erreurs, le code inutilisé et la préparation à la production sont des critères de revue, et non des préférences de style.

Documents fondateurs en un écran

Foundation	Lire lorsque la modification demande…
FND-001 : Architecture intentionnelle	Est-ce que cela correspond à l’orientation microkernel/runtime ? Quelle couche devrait en être responsable ?
FND-002 : Normes de documentation	Où le savoir doit-il résider ? Comment la documentation peut-elle rester navigable et durable ?
FND-003 : Gouvernance	Qui décide ? Quels labels, tableau de projet ou processus RFC doivent porter l’état ?
FND-004 : Infrastructure d’ingénierie	Comment l’intégration continue (CI), l’automatisation des versions ou GitHub Actions doivent-elles se comporter ?
FND-005 : Culture de contribution	Comment les contributeurs, les mainteneurs et les travaux assistés par IA doivent-ils communiquer et effectuer les revues ?
FND-006 : Aucun compromis en pratique	Quel niveau de qualité s’applique au code de production, aux erreurs, au code mort et à la préparation pour la mise en production ?

Points d’entrée de l’agent de codage

Les agents de codage doivent utiliser la même documentation publique que les humains, ainsi que les contrats d’agent locaux au dépôt.

Suivez le fichier AGENTS.md à la racine du dépôt. Inspectez .claude/skills/*/SKILL.md et utilisez la compétence intégrée au dépôt correspondante lorsqu’elle s’applique ; le fichier de compétence fait autorité.
Considérez les documents fondateurs comme un contexte décisionnel. Ils expliquent pourquoi une revue peut demander une scission, une RFC, une validation plus robuste ou un propriétaire différent.
Gardez les mécanismes internes du workflow hors des descriptions de PR publiques, des commentaires d’issues et des revues. Le texte public doit citer le comportement concret, les chemins source, les commandes, les preuves de validation, les issues liées et le risque visible par l’utilisateur.
Si un brouillon généré ou rédigé par une compétence entre en conflit avec le code source, le fichier AGENTS.md actuel ou un document de référence ratifié, arrêtez-vous et résolvez le conflit avant de publier ou d’implémenter.

Points de contrôle RFC et PR

Cette carte ne remplace pas le processus RFC ni le modèle de PR ; elle vous aide seulement à trouver le bon document. Le processus RFC contient le tableau canonique « est-ce au format RFC ? », consultez-le donc plutôt que de deviner à partir d’une liste reformulée ici. Une fois les tranches de politique de la RFC #6808 promues, suivez FND-003, Labels, PR workflow et Reviewer playbook.

Si un changement est ambigu mais pas clairement de type RFC, consultez un mainteneur ou réduisez la portée de la PR avant l’implémentation.
Avant d’ouvrir une PR, répondez aux questions du modèle de PR (.github/pull_request_template.md). Si ces réponses ne sont pas claires, rédigez d’abord la note de conception ou la RFC.