Audit AGENTS.md
Auditez les instructions par rapport à l'état du projet et à la politique établie. Priorisez les affirmations qui pourraient induire un agent en erreur. La forme et la fréquence d'édition seules ne constituent pas un défaut. Ne signalez aucun défaut lorsque les vérifications n'en démontrent aucun ; une documentation d'amorçage brève et des instructions précises inchangées peuvent suffire.
Maintenez l'audit en lecture seule par défaut, y compris l'index et l'historique Git. Préparez des corrections et un message de point de contrôle pour révision. Appliquez les correctifs ou créez un point de contrôle lorsque la demande autorise cette action ; utilisez l'autorisation existante sans la redemander. Exécutez les vérifications sans option de correction automatique ou autre option d'écriture de source, et signalez les prérequis d'exécution qui ne sont pas disponibles.
Couverture
Enregistrez la couverture comme les fichiers, affirmations, historique et vérifications réellement examinés.
- Enregistrez la révision du dépôt et l'état de l'arbre de travail. Inventoriez les fichiers d'instructions, les règles ancêtres pertinentes, les surcharges, les importations, les liens et les cartes de modules dans le dépôt. Incluez les systèmes CLAUDE.md existants plutôt que de supposer que AGENTS.md est leur point d'entrée actif.
- Confirmez quels fichiers le mécanisme prévu découvre et lesquels nécessitent des lectures explicites. Vérifiez les chemins de chargement pertinents et les budgets de taille par rapport à la configuration disponible ou à la documentation du mécanisme actuel. Marquez une livraison inconnue comme non vérifiée ; les noms de fichiers et le placement dans les répertoires seuls ne prouvent pas le chargement.
- Indiquez les fichiers et affirmations à vérifier, tout échantillonnage, les prérequis de commande et l'historique disponible. Limitez le verdict lorsque le dépôt est sale, que l'historique est superficiel ou indisponible, ou que les vérifications ne peuvent pas s'exécuter. Auditez les modifications locales séparément d'un instantané validé ; ne les attribuez pas à son SHA. Lorsqu'une vérification s'exécute sur des fichiers qui diffèrent de l'instantané validé, comme un arbre de travail avec des modifications locales, indiquez où elle s'est exécutée et quels chemins différaient.
Historique et résultats antérieurs
Pour un dépôt Git, sélectionnez la ligne de base avant de vérifier les modifications intermédiaires. Sans historique Git, vérifiez l'état actuel et signalez que la vérification historique n'est pas disponible.
Un audit terminé a terminé ses vérifications déclarées de l'ensemble du dépôt ; il peut signaler des défauts, un échantillonnage et des vérifications indisponibles avec des limites explicites. Un résultat propre signifie qu'aucun défaut n'a été démontré dans le cadre des vérifications terminées. Un audit qui ne peut pas se terminer produit un rapport mais pas de point de contrôle.
Un point de contrôle est un commit Git vide à parent unique dont le message stocke le rapport d'un audit terminé et les en-têtes du modèle de message de point de contrôle. Son unique parent est la révision auditée, l'instantané validé examiné par cet audit. Les modifications locales sont distinctes de cet instantané. Un commit est un point de contrôle uniquement lorsqu'il remplit toutes les conditions de Sélection de la ligne de base ; tout autre commit est un commit ordinaire, quel que soit son message.
Une ligne de base est le point de contrôle le plus proche sur l'historique du premier parent de la branche cible. Elle définit la limite historique, la révision après laquelle l'audit inspecte les modifications jusqu'à la révision auditée. Ses résultats Nouveaux et Reportés sont l'ensemble complet des résultats ouverts antérieurs. Un audit qui ne produit aucun point de contrôle laisse la ligne de base inchangée.
La sortie d'amorçage reste une documentation candidate jusqu'à vérification et ne peut à elle seule fournir une ligne de base.
Sélection de la ligne de base
Parcourez l'historique du premier parent de la branche cible à partir de HEAD. Traitez les commits avec un en-tête Agents-Audit-Version comme candidats ; identifiez-les par l'en-tête plutôt que par le sujet. Par exemple :
git log --first-parent --format='%H' --grep='^Agents-Audit-Version: 1$' HEAD
git show -s --format=%B <candidat> | git interpret-trailers --parse
Ces commandes trouvent les candidats. Un candidat est un point de contrôle uniquement lorsque son message et ses objets Git remplissent toutes ces conditions :
- Chaque en-tête du modèle de message a une valeur non conflictuelle, la version est prise en charge, et la révision de la compétence ou le hachage de contenu est identifiable.
- Le commit a exactement un parent. Le SHA complet de ce parent est égal à
Agents-Audit-Commit, et les arbres du parent et du commit sont tous deux égaux àAgents-Audit-Tree. L'égalité des arbres seule ne peut pas détecter une relecture sur un historique différent qui produirait par hasard les mêmes fichiers. - Le commit se trouve sur l'historique du premier parent de la cible.
Agents-Audit-Previousnomme le point de contrôle antérieur le plus proche sur l'historique du premier parent de la révision auditée, ounonepour une limite historique initiale explicitement établie. Le commit nommé doit lui-même être un point de contrôle.- Le message contient chaque section de rapport du modèle, avec la couverture déclarée. Sauf si
Agents-Audit-Previousestnone, chaque ID sous les résultats Nouveaux ou résultats Reportés dans le point de contrôle nommé apparaît sous les résultats Reportés ou résultats Fermés.
Parce que chaque prédécesseur doit lui-même être un point de contrôle, vérifiez les candidats du plus ancien au plus récent et réutilisez chaque résultat ; chaque commit est alors vérifié une fois. Sélectionnez le candidat le plus proche qui remplit ces conditions comme ligne de base. Traitez tout autre candidat comme un commit ordinaire dans la fenêtre historique : ne lisez aucun résultat ou fermeture de son message et ne l'incluez pas dans le rapport ni dans le message du point de contrôle. Lorsqu'un prédécesseur n'est pas disponible ou qu'un historique superficiel empêche ces vérifications, indiquez l'écart. Ne remplacez pas silencieusement une limite historique connue par les derniers commits ou ne déclarez pas le travail comme un premier audit. Si aucune ligne de base ne peut être établie, vérifiez l'état actuel dans des limites explicites et laissez la couverture historique non vérifiée. Pour un véritable premier audit sans point de contrôle antérieur, vérifiez l'état actuel et indiquez une limite historique initiale explicite.
Le rebasage, le cherry-pick et le squash donnent aux commits de nouveaux parents, vérifiez donc à nouveau les conditions après avoir réécrit l'historique. Établissez des points de contrôle durables après l'intégration lorsque l'historique de fonctionnalité est écrasé.
Vérifications
Exactitude et politique
- Vérifiez les commandes par rapport à la configuration du projet et à leurs prérequis. Exécutez les vérifications réalisables dans un environnement approprié. Attribuez les échecs à une invocation obsolète, à un défaut d'implémentation, à un prérequis indisponible ou à une vérification incomplète ; une commande de test valide trouvant une régression n'est pas obsolète.
- Résolvez les références nommées, les chemins, les importations et les entrées de carte de module. Inspectez les renommages, la propriété partagée et les règles ancêtres applicables avant de déclarer une instruction manquante. Démontrez le défaut, puis jugez sa sévérité par la conséquence probable pour un agent suivant l'instruction, et non par un symbole manquant seul.
- Vérifiez les invariants importants par rapport à l'implémentation et aux tests, en traitant les docstrings et les commentaires comme des affirmations plutôt que des preuves. Vérifiez une affirmation conditionnelle avec des entrées des deux côtés de sa condition. Distinguez les descriptions de la politique : du code intentionnel peut toujours violer une limite établie. Résolvez les conflits en utilisant l'autorité de la tâche et les décisions enregistrées ; ne réécrivez pas la politique simplement pour correspondre au code qui la viole.
- Inspectez les avertissements par rapport à des chemins concrets d'échec ou de régression. Supprimez les détails obsolètes ou superficiels, conservez une barrière de sécurité utile lorsque la contourner reste un risque réaliste, et taillez les explications déjà suffisamment portées par les tests ou l'application. Préférez les conseils présents à un historique d'échecs corrigés.
Signalez les défauts démontrés comme obsolètes, contredits, manquants, conflits de politique ou avertissements obsolètes. Conservez les affirmations incertaines sous les vérifications non vérifiées. Incluez l'instruction affectée, la preuve du dépôt, la conséquence et la correction proposée.
Maintenance
Inspectez les modifications de code, de configuration, de dépendance et d'instructions depuis la limite historique. Mappez chaque modification pertinente aux affirmations qu'elle pourrait invalider, y compris les fichiers d'instructions inchangés. Utilisez les mots-clés des messages de commit et les comptes facultatifs des commits qui ont modifié le code et les instructions ensemble pour choisir les modifications à inspecter, non pour juger la qualité de la documentation.
Ne signalez un défaut de maintenance que lorsqu'une modification a invalidé une affirmation documentée ou a omis une instruction nécessaire. Autorisez un invariant précis à survivre à de nombreuses modifications intactes. Traitez les corrections indépendantes, les commits d'amorçage, les réparations d'audit et les commits de point de contrôle comme un travail légitime. Une refactorisation entre modules n'a pas besoin de modifier les instructions dont les affirmations restent vraies.
Décisions et avertissements
Inspectez les décisions architecturales indépendamment de la découverte de corrections de bugs. Recherchez les choix acceptés dont la conséquence devrait contraindre les modifications futures et dont la raison n'est pas apparente à partir du code. Utilisez une explication enregistrée ou une confirmation par le décideur ; un diff prouve une modification, pas son intention. Rédigez la règle, la raison et les conditions de reconsidération uniquement lorsqu'elles sont prouvées et toujours utiles. Laissez une alternative rejetée digne d'être mentionnée dans un commentaire dans la source qu'elle affecte, où un agent modifiant ce code la trouvera. Pendant l'amorçage, continuez à utiliser uniquement les sources actuelles ; ne fouillez pas l'historique Git pour des raisons ou n'inventez pas de justification.
Pour les bugs significatifs diagnostiqués, vérifiez si la leçon empêche toujours une erreur coûteuse ou répétée. Proposez une entrée concise enregistrant le symptôme, le mécanisme et la reconnaissance ou l'évitement uniquement lorsqu'elle ajoute des conseils utiles. Lorsque contourner une abstraction pourrait réintroduire l'échec, reformulez l'avertissement comme une barrière de sécurité concise et expliquez pourquoi. Proposez la suppression lorsque le mécanisme a disparu, que l'erreur est superficielle ou que l'application porte déjà la leçon de manière adéquate. Conservez les mécanismes incertains comme des propositions pour confirmation.
Forme
Vérifiez la forme après l'exactitude. Placez les règles à l'échelle du dépôt dans le fichier racine, les règles partagées par les modules dans un fichier racine source ou de package (un hub), et les règles de module distinctes dans un fichier local (une feuille). Utilisez uniquement les portées qui ont besoin de conseils séparés ; autorisez les projets à fichier unique, les hubs multiples et les sections vides omises. Conservez une explication canonique et autorisez un bref rappel limité avec un lien lorsque cela améliore la découverte. Préservez les versions applicables, les dates de vérification, les plateformes et les conditions de mesure. Supprimez la narration de progrès obsolète, la justification inventée, la duplication inutile et les instructions qui n'aident plus avec une modification. Jugez la spécificité par des décisions utiles, non par la fréquence de changement du texte.
Rapport
Indiquez si les instructions vérifiées sont exactes et limitez cette conclusion aux affirmations examinées. Enregistrez la révision, le contenu sale ou ignoré examiné, l'inventaire des instructions, les affirmations vérifiées ou échantillonnées, la limite historique, les résultats des commandes, l'environnement et les versions pertinents, et les vérifications non résolues. Gardez le rapport interprétable à partir du dépôt lui-même, en utilisant des chemins relatifs au dépôt et des révisions Git comme preuve.
Revérifiez chaque résultat ouvert de la ligne de base et placez-le sous les résultats Reportés ou résultats Fermés avant de finaliser le rapport.
Séparez les résultats dans ces sections ; écrivez Aucun lorsque l'une est vide :
- Enregistrez les nouveaux résultats avec des ID stables frais, les instructions affectées, les preuves, les conséquences et les corrections requises.
- Reportez chaque résultat non résolu de la ligne de base, y compris ceux qu'elle listait comme nouveaux, avec son ID, son point de contrôle source (le point de contrôle qui l'a enregistré pour la première fois) et un compte rendu complet de ses preuves, conséquence et correction requise. Gardez un résultat ouvert lorsque sa résolution ne peut pas être vérifiée et divulguez les preuves qui ne peuvent pas être validées.
- Fermez les résultats avec la résolution vérifiée ou la suppression et les preuves à l'appui. Enregistrez chaque fermeture une fois, puis omettez-la des rapports ultérieurs. Conservez son historique dans le point de contrôle antérieur plutôt que d'agrandir une archive dans chaque rapport.
Allouez les ID sans réutiliser ceux retirés ; par exemple, utilisez un horodatage UTC spécifique à l'audit plus un compteur et conservez cet ID par la suite. Indiquez dans le rapport si l'audit s'est terminé ; un audit interrompu ou inachevé se termine par le rapport. Ne revendiquez un résultat propre que dans le cadre des vérifications qui le démontrent.
Message de point de contrôle
Préparez le message suivant dans le cadre de la livraison d'un audit terminé. Incluez le rapport d'audit lui-même, pas des pointeurs vers un système de suivi de problèmes externe, un rapport local ou une autre source externe. Utilisez le sujet sans en-tête et les en-têtes exactement comme indiqué, avec des en-têtes ## et des lignes vides pour les sections du rapport. Enregistrez des ID d'objet complets et une révision de compétence ou un hachage identifiable plutôt que de vous fier à un chemin installé.
chore: enregistrer l'audit de la documentation de l'agent
## Couverture
Fichiers d'instructions examinés <fichiers ou répertoires relatifs au dépôt>.
Vérifications effectuées <affirmations et vérifications réalisées, y compris tout échantillonnage>.
Historique inspecté de <limite historique> à la révision auditée.
Environnement et versions d'outils utilisés <environnement et versions d'outils pertinents, et où les vérifications ont eu lieu>.
## Vérifications non effectuées
<Vérifications non terminées et leurs raisons, ou Aucune.>
## Nouveaux résultats
<ID stable, instruction et section affectées, résultat, preuve,
conséquence et correction requise pour chaque nouveau résultat ; ou Aucun.>
## Résultats reportés
<ID stable, point de contrôle source et compte rendu autonome de chaque
résultat non résolu, y compris preuves, conséquence et correction
requise ; ou Aucun.>
## Résultats fermés
<ID stable, résolution ou suppression, et preuves à l'appui
pour chaque résultat que cet audit ferme ; ou Aucun.>
Agents-Audit-Version: 1
Agents-Audit-Commit: <SHA complet du commit parent audité>
Agents-Audit-Tree: <SHA de l'arbre audité>
Agents-Audit-Skill-Revision: <révision de la compétence ou hachage de contenu>
Agents-Audit-Previous: <SHA du point de contrôle de la ligne de base ou none>
Création du point de contrôle
Créez un point de contrôle uniquement pour un audit terminé et uniquement avec l'autorisation pour cette écriture. Exigez que la révision auditée soit toujours HEAD et que les instructions et le code audités soient représentés dans son arbre. Validez d'abord les corrections autorisées et vérifiez l'instantané résultant avant d'enregistrer son point de contrôle. Rafraîchissez le rapport et les en-têtes pour décrire cet instantané vérifié si les corrections ont modifié la révision auditée. Excluez le contenu non validé ou ignoré des affirmations sur l'instantané validé et enregistrez toute limite de couverture résultante. Refusez d'enregistrer un point de contrôle pour un état sale observé comme s'il était propre ; en cas de saleté, demandez une autorisation claire pour ignorer ou rebasculer, n'attribuez pas cette autorisation et ne lisez pas une demande d'audit pour autoriser implicitement l'exécution du point de contrôle. Confirmez que le commit parent est toujours un point de contrôle valide ou augmentez la portée de l'audit pour inclure les modifications de l'historique intermédiaire.
Pour enregistrer un point de contrôle, utilisez un commit vide :
git commit --allow-empty --only -m "<message du point de contrôle>"
L'absence d'édition de l'index ou de l'arbre de travail par la commande elle-même réduit le risque d'écriture involontaire. Si la demande d'audit a également autorisé des corrections, validez-les en un ou plusieurs commits avant l'étape ci-dessus, en utilisant les commits de correction comme le ou les parents du point de contrôle lorsque l'audit a examiné l'arbre corrigé, ou en utilisant le SHA de la correction comme Agents-Audit-Commit lorsque l'audit a examiné l'arbre avant correction. Chaque correction, comme le point de contrôle lui-même, nécessite une autorisation.