Maintenance Docs

Que fait Maintenance Docs ?

1. Clarifier les responsabilités et le périmètre actuel

Utilisez cette compétence pour décider s'il faut créer ou réutiliser des enregistrements, organiser le contenu, vérifier les descriptions, exposer les lacunes et maintenir les relations, l'état et la navigation des sources. Cela nécessite un jugement d'ingénierie : investiguer les chemins réels lors de l'explication des mécanismes actuels ; ne pas simplement reformater la conversation ou créer une fausse certitude en remplissant des modèles.

• L'Agent qui exécute la tâche en cours gère les choix techniques, les compromis, le découpage des tâches, l'implémentation, le débogage et la vérification ; utilisez ces règles partagées lorsque les sorties doivent être conservées. Les investigations ciblées et les mises à jour de la documentation des sous-systèmes sont des tâches valides et ne nécessitent pas de lancer un processus de conception séparé au préalable.
• Utilisez to-docs pour créer des livrables de conception lisibles par l'humain que les personnes pourront consulter, modifier et référencer ultérieurement. Une conception lisible par l'humain peut être la source complète ; cette compétence guide la propriété et la cohérence des documents à partir du moment où ils sont sauvegardés. N'exigez pas d'enregistrement technique préalable ni ne créez d'appels circulaires entre compétences.
• Utilisez grilling pour clarifier le sujet actuel en profondeur ; grill-me est son point d'entrée explicite. Continuez à partir du contenu établi sans rouvrir les décisions ni ajouter de portes d'approbation pour chaque itération.
• Utilisez decision-notes pour trouver, enregistrer, remplacer et organiser les décisions à long terme. Cette compétence référence ses conclusions ; elle n'établit pas de processus d'entretien séparé ni de cycle de vie des décisions. Recherchez lorsque ses conditions de déclenchement s'appliquent, même s'il n'y a pas de lien direct.
• Utilisez handoff si nécessaire pour préparer ou vérifier une transition entre sessions ou Agents. Cette compétence continue de maintenir les matériels d'ingénierie et l'état ; ne créez pas un doublon complet simplement parce que la personne exécutant la tâche a changé, et ne créez pas d'appels circulaires entre compétences.
• La lecture ordinaire, les questions immédiates et les petites modifications qui n'affectent pas les matériels existants ne déclenchent pas indépendamment le processus de maintenance complet ; lisez néanmoins les matériels nécessaires à la tâche. Une demande uniquement documentaire n'étend pas l'autorisation de modifier le comportement du produit, d'exécuter des vérifications non liées ou de commiter du code ; l'autorisation existante pour les tâches d'ingénierie reste en vigueur.

Utilisez les noms réellement disponibles dans l'environnement. Si une compétence ne peut pas être invoquée, lisez plutôt la configuration guidée du projet ; ne prétendez pas avoir invoqué une compétence indisponible. La collaboration ne doit pas provoquer de chargement circulaire ni de recherches en double.

2. Localiser les sources et décider de réutiliser ou créer des enregistrements

Commencez par le point d'entrée Agent réel du projet pour localiser les contraintes, les exigences et les critères d'acceptation, les sous-systèmes pertinents, les enregistrements de modifications et les notes ; vérifiez le périmètre du travail en cours. Pour les projets existants, privilégiez les emplacements et noms existants ; n'exigez pas de migration. Pour les travaux intersous-systèmes, couvrez les interfaces pertinentes et les contraintes partagées.

Réutilisez le contexte déjà lu et vérifié pour la même tâche s'il s'applique toujours. Lorsque le périmètre, une prémisse clé ou une source change, ou qu'un conflit apparaît, revérifiez les zones affectées. Ne rescannez pas l'ensemble du référentiel ni ne redémarrez un entretien simplement en raison d'un changement de tour ou de compétence.

Lorsque vous choisissez des emplacements, noms, fractionnements de fichiers ou navigation, lisez Organisation et Sources.

1. Cherchez d'abord la documentation existante qui s'applique toujours au même changement ; un sujet similaire ne signifie pas nécessairement le même changement. Pour poursuivre un travail existant, localisez son enregistrement original et vérifiez l'état actuel plutôt que d'écrire automatiquement un document de transition complet.
2. Créez ou mettez à jour des enregistrements lorsque les conceptions cibles, les plans de migration, les dépendances ou les questions à investiguer ou vérifier doivent être conservés pour une implémentation ultérieure, une acceptation ou une continuation intersession. Cela s'applique également pendant l'investigation et la comparaison de solutions.
3. Les petits changements clairs réalisés dans le tour actuel peuvent être livrés uniquement par conversation, tout en maintenant la documentation existante affectée et les notes requises par les règles établies. Si l'utilisateur demande explicitement de sauvegarder quelque chose, enregistrez-le, en privilégiant une source existante appropriée.
4. Ne créez pas mécaniquement des enregistrements basés sur le nombre de lignes, de fichiers, de tours de conversation ou de commits. Ne créez pas à l'avance des pages vides ou une bibliothèque de documentation complète, et ne demandez pas à chaque fois s'il faut écrire de la documentation.

3. Vérifier et maintenir les matériels selon leur objectif

Travail en cours	Lire selon les besoins	Propriété de l'information
Vérifier la propriété et l'alignement entre les conceptions lisibles par l'humain et les matériels d'ingénierie	Organisation et Sources	Les conceptions lisibles par l'humain conservent la source complète des objectifs, scénarios et comportements ; les matériels d'ingénierie les référencent et les complètent
Décrire un sous-système actuel ou corriger les différences entre documentation et implémentation	Documentation du Sous-système	Responsabilités actuelles, mécanismes, contrats et navigation vers le code source, les tests et les notes
Enregistrer les objectifs de changement, conceptions, tâches et contexte de continuation	Conceptions et Plans de Changement	Objectifs actuels, écarts par rapport à l'état existant, questions non résolues, plans d'implémentation et de vérification
Mettre à jour l'état ; compléter, suspendre, annuler, reprendre ou fermer des enregistrements	État et Clôture	Progrès global, résultats des tâches, vérification réelle et disposition du travail restant

Maintenez chaque fait à un seul endroit ; résumez-le et liez-le ailleurs. docs/designs/<topic>.md peut être la source de conception lisible par l'humain complète. Ajoutez les détails d'ingénierie, dépendances, vérification et progrès dans .agents/changes/ uniquement si nécessaire ; ne dupliquez pas la conception. Ne transformez pas un aperçu d'une source existante en une copie complète, ne créez pas un second enregistrement d'état ou de progrès dans un index, et ne maintenez pas de justification à long terme en dehors de sa source de notes.

Le point d'entrée du changement d'ingénierie, le README, le plan et les règles d'état global s'appliquent uniquement aux travaux nécessitant un enregistrement de changement d'ingénierie ; ils ne sont pas imposés aux conceptions lisibles par l'humain. Le contenu résolu ou non résolu d'une conception n'est pas un progrès d'ingénierie. N'introduisez pas de machine d'état de conception obligatoire ni ne créez un répertoire d'ingénierie compagnon pour chaque conception.

Distinguez les conclusions établies, les recommandations non résolues, les hypothèses et les éléments à investiguer de la vérification du code source, de la couverture de test existante et de la vérification réelle à l'exécution. Les liens doivent expliquer le mécanisme, le comportement couvert ou le sujet de décision qu'ils soutiennent. L'existence d'un test ne signifie pas qu'il a été exécuté avec succès. L'adoption d'un objectif ne signifie pas qu'il a été implémenté ni qu'il supprime automatiquement les obligations de transition ou de compatibilité.

Lorsque la documentation et l'implémentation divergent, vérifiez le code source pertinent, les tests, les exigences, les notes applicables et l'état d'implémentation. Déterminez si la documentation est obsolète, si l'implémentation diverge du comportement attendu, ou si une transition est incomplète. Corrigez les erreurs de documentation vérifiées ; traitez les erreurs d'implémentation dans le cadre de l'autorisation existante. Ne décrivez pas un défaut comme un contrat normal et n'utilisez pas une ancienne documentation pour outrepasser une nouvelle instruction utilisateur. Si le comportement clé ou les compromis restent flous, décrivez le conflit et demandez à l'utilisateur de décider tout en poursuivant le travail qui ne dépend pas de cette décision.

4. Maintenir les matériels en phase avec les changements substantiels

• Lorsque les responsabilités, limites, chemins principaux, interfaces, état, comportement de défaillance, comportement de compatibilité ou navigation nécessaire d'un sous-système changent, mettez à jour la documentation pertinente parallèlement au changement vérifié plutôt que d'attendre la fin du projet. Ne réécrivez pas mécaniquement des descriptions qui restent exactes après un refactoring interne, mais réparez les liens cassés.
• Mettez à jour les conceptions lorsque les objectifs, le périmètre, les choix clés ou les prémisses changent clairement ; continuez à étiqueter le contenu non résolu comme tel. Mettez à jour les plans lorsque les résultats des tâches, dépendances, blocages ou étapes suivantes changent d'une manière qui affecte l'exécution ou la continuation. Synchronisez les changements d'échéancier importants avant d'exécuter les étapes affectées ; ne consignez pas chaque opération d'outil.
• Gérez les ajustements dans le cadre de l'autorisation existante de manière autonome. Les mises à jour de documentation n'ajoutent pas d'exigences d'approbation et ne peuvent pas remplacer une décision utilisateur nécessaire. Demandez à l'utilisateur de décider des changements de comportement, de périmètre ou de compromis clés qui dépassent l'autorisation ; ne reconfirmez pas les questions réglées.
• Avant la livraison, la pause ou la transition, vérifiez que les matériels pertinents nécessitant une conservation continue permettent à l'Agent suivant d'identifier l'état actuel, l'écart par rapport à l'objectif, le travail restant et la prochaine étape. N'attendez pas ces moments pour créer le premier enregistrement.

Ne traitez que le périmètre pertinent pour la tâche en cours. Conservez les faits actuels dans la documentation du sous-système, les décisions à long terme dans decision-notes et faites référencer ces informations par d'autres emplacements.

5. Vérifier et livrer

Vérifiez le périmètre convenu pour cette tâche ; ne la transformez pas en un audit de l'ensemble du référentiel :

1. Couverture et propriété : Conservez le contenu qui doit persister ; réutilisez les sources appropriées sans prose en double, placeholders vides ou contexte de continuation laissé uniquement dans la conversation temporaire.
2. Exactitude : Rendez l'état actuel, les objectifs, les points résolus et non résolus, ainsi que les preuves clairs ; ne confondez pas la progression des étapes, les modifications de code, la vérification réussie et l'acceptation manuelle requise.
3. État et continuation : Si un enregistrement de changement d'ingénierie existe, maintenez son statut global uniquement au point d'entrée du changement et marquez les tâches selon l'avancement réel. Rendez les blocages, lacunes, prochaines étapes et travail restant localisables ; conservez les conclusions et preuves nécessaires dans les enregistrements de clôture.
4. Liens et cohérence : Maintenez les exigences et critères d'acceptation, conceptions, plans, sous-systèmes et notes pertinents correctement connectés ; assurez-vous que les liens fonctionnent. La réorganisation des matériels ou des enregistrements ne doit pas perdre d'informations uniques.
5. Périmètre de vérification : Exécutez les vérifications existantes applicables en fonction de la tâche et du projet, et examinez les résultats ; effectuez une revue manuelle si aucun outil dédié n'existe. N'imposez pas de vérifications non liées, une suite de tests complète ou une nouvelle chaîne d'outils uniquement pour terminer la documentation. Réutilisez les résultats vérifiés lorsque le contenu n'a pas changé, et décrivez avec précision les zones non vérifiées ou contraintes.

Terminer la tâche de documentation en cours signifie que les informations convenues sont exactes, les sources sont localisables, les inconnues et les lacunes de vérification sont divulguées, et les matériels soutiennent la continuation. Cela ne prouve pas que la conception est suffisante, que l'implémentation est correcte ou que la fonctionnalité est complète. Vérifiez l'achèvement du changement global séparément à l'aide de État et Clôture.

Livrez les modifications, vérifications et lacunes nécessaires de ce tour avec une explication concise et des liens vers les fichiers réels ; placez les résultats nécessitant une maintenance continue dans le référentiel. Gardez le code, la documentation et les notes connexes ensemble en tant que livrable en attente. La sauvegarde de la documentation n'autorise pas le commit, push, PR ou publication ; suivez les règles de confirmation de commit existantes du projet et ne commitez pas tôt simplement parce que la documentation a été sauvegardée.