Comment j'ai arrêté de me soucier des fichiers ReadMe

Comme la plupart des développeurs, je suis passé par là : je pousse une nouvelle fonctionnalité brillante à 2 h du matin, ressentant cette montée familière de dopamine lorsque la build réussit et se déploie avec succès. Mais trois semaines plus tard, lorsqu'un nouveau membre de l'équipe essaie de s'intégrer en utilisant mon ancien README, il se retrouve devant des instructions pour la version 2.1 alors que mon application fonctionne en version 3.2. Les commandes de configuration ne fonctionnent pas. Les points de terminaison de l'API ont changé. Ma belle documentation est devenue un fardeau.

Les équipes de développement ont souvent du mal à maintenir leur documentation à jour, car mettre à jour manuellement les fichiers README à chaque changement de code est irréaliste dans des environnements au rythme rapide. Par conséquent, la documentation devient rapidement obsolète et peu fiable, ce qui ralentit l'intégration et force les développeurs à s'interrompre les uns les autres pour obtenir des réponses. Cette perturbation constante épuise les ingénieurs seniors, accélérant l'épuisement professionnel et le roulement de personnel, et lorsqu'ils partent, des connaissances institutionnelles critiques partent avec eux.

Les Agent Hooks de Kiro résolvent ce problème. Les Agent Hooks sont des déclencheurs automatisés qui exécutent des actions d'agent prédéfinies lorsque des événements spécifiques se produisent dans votre IDE. Au lieu de mettre à jour manuellement la documentation, vous pouvez configurer des Hooks qui actualisent automatiquement votre README lorsque des fichiers sont sauvegardés, mettent à jour la documentation de l'API lorsque les points de terminaison changent, et génèrent des exemples dans votre documentation à mesure que votre code évolue.

1. Définir l'Agent Hook : Les utilisateurs peuvent définir leurs exigences en matière de documentation comme un Agent Hook en langage naturel. Exemple de requête : « Surveillez les nouvelles API ou celles retirées dans tous les fichiers Python de ce dépôt (fichiers *.py), mettez à jour le fichier YAML OpenAPI avec les nouvelles API et supprimez les API qui n'existent plus. Mettez à jour les fichiers ReadMe avec les mises à jour des fichiers *.py. La figure 1 montre l'utilisateur créant un Agent Hook.

2. Kiro crée la configuration de l'Agent Hook : Kiro traduit vos exigences en matière d'Agent Hook en une configuration comprenant un titre, une description, un événement, des chemins de fichiers à surveiller et des instructions envoyées à Kiro lorsque l'événement se produit. Consultez les bonnes pratiques pour définir les Hooks pour comprendre cela en détail.

Dans ce cas, la configuration suivante (dans la figure 2) a été créée en utilisant l'exemple de requête de l'étape 1. Kiro a généré le titre « API Documentation Sync », l'événement « File Saved » (autres types de Hooks), et a défini les chemins à surveiller comme tous les fichiers .py du dépôt. Les instructions pour l'Agent Hook sont également générées à partir de la requête initiale fournie par l'utilisateur lors de la création de l'Agent Hook.

Une fois l'Agent Hook créé, vous verrez qu'une configuration json est stockée dans le dossier .kiro/hooks sous forme de fichier .hook. Dans mon cas, la configuration ci-dessous dans la figure 3 est stockée. La configuration de l'Agent Hook peut être modifiée soit via l'interface utilisateur, soit via le fichier .hook généré. Configuration stockée sous .kiro/hook/api-documentation-sync.kiro.hook après la création de l'Agent Hook :

3. Le Hook est déclenché lorsque l'événement se produit : Lorsque des événements tels que la sauvegarde ou la création de fichier se produisent, l'Agent Hook est déclenché et une nouvelle session à l'intérieur de Kiro s'ouvre en arrière-plan et s'exécute. Les développeurs peuvent alors accepter ou modifier les changements proposés via la session de l'Agent Hook.

Testons le Hook. Disons que nous demandons à Kiro de « M'aider à ajouter une nouvelle API pour extraire des enregistrements en format CSV », Kiro ajoute le nouveau point de terminaison d'API dans le fichier .py concerné. En arrière-plan, une autre session nommée « Execute hook: API Documentation Sync » est créée, dans laquelle Kiro met à jour le fichier OpenAPI.yaml et les fichiers ReadMe. Kiro génère également un fichier CHANGELOG.md pour suivre le changement introduit.

La vidéo suivante montre comment le Hook API Documentation Sync est déclenché lorsqu'une nouvelle API est ajoutée au fichier « app.py ».

Bien que l'automatisation du README soit puissante, ce n'est que le début. Les Agent Hooks peuvent automatiser toute tâche routinière qui devrait se produire lorsque votre code change :

• Optimisation du code : Optimisez le code pour la lisibilité, la maintenabilité et les optimisations de performance.
• Localisation linguistique : Générez des traductions automatisées du contenu textuel destiné aux utilisateurs
• Documentation de sécurité : Mettez à jour les considérations de sécurité lorsque vous modifiez le code d'authentification
• Diagrammes d'architecture : Actualisez les diagrammes de système lorsque vous modifiez les intégrations de services
• Guides de déploiement : Mettez à jour les instructions de déploiement lorsque vous modifiez les configurations Docker
• Guides de dépannage : Générez des scénarios d'erreurs courantes basés sur votre code de gestion des exceptions
• Valider la conception Figma : Valide que les fichiers HTML/CSS suivent une conception Figma en utilisant le MCP Figma

Et bien plus encore. Voici une liste de quelques exemples avec des configurations d'Agent Hook détaillées.

Lorsque la documentation reste à jour automatiquement, quelque chose de magique se produit : les développeurs commencent à lui faire confiance à nouveau. Ils s'interrompent moins les uns les autres. Les développeurs passent plus de temps en état de concentration, la qualité du code s'améliore et les fonctionnalités sont livrées plus rapidement. Mais les avantages vont plus loin que les indicateurs de productivité.

Les nouveaux développeurs s'intègrent plus rapidement. Une documentation exacte devient votre mémoire institutionnelle. Lorsque les développeurs seniors partent, leurs connaissances ne disparaissent pas avec eux, elles vivent dans les guides que les Agent Hooks ont maintenus à jour pendant toute la durée de leur mandat. Votre documentation devrait être le reflet vivant de votre base de code, et non un instantané datant de trois mois. Avec les Agent Hooks de Kiro, vous pouvez vous concentrer sur la création d'excellents logiciels tandis que votre documentation évolue automatiquement en même temps que votre code.

J'ai hâte de vous voir tous essayer de configurer des Agent Hooks dans Kiro et de les voir en action sur vos projets. J'aimerais beaucoup connaître vos impressions sur notre serveur Discord. Vous pouvez commencer par le cas d'utilisation de documentation dont nous avons parlé dans ce billet et l'étendre à d'autres cas que nous avons évoqués ci-dessus ou mentionnés dans les exemples de documentation.

Lors de la mise en œuvre d'Agent Hooks avec des déclencheurs d'événements utilisant des expressions régulières (p. ex., **/*.py), il est essentiel d'évaluer soigneusement la portée du modèle. Des modèles trop larges peuvent entraîner des changements excessifs lors de l'exécution des Hooks, provoquant des mises à jour inutiles de la documentation dans les grands projets. Il est recommandé de mettre en œuvre une correspondance de modèles plus précise et ciblée afin de maintenir l'efficacité et la clarté de la documentation. Consultez le dépannage des Agent Hooks.