zehuichan/vibe-harness

Norme documentaire

Faites que chaque page soit trouvable, lisible par un nouvel arrivant et suffisamment précise pour les agents et les mainteneurs. Les niveaux, les règles de rédaction, les budgets et la checklist de médiocrité se trouvent dans docs/AGENTS.md ; cette compétence possède le workflow pour les appliquer. Préservez un propriétaire par fait : source, tests, catalogues générés, README, guides et Notes d'Agent gardent chacun leur propre type de vérité. Ceci est une directive, pas une checklist.

Workflow

Suivez cette séquence pour chaque périmètre demandé. Gardez le chemin commun du lecteur bref, mais ne supprimez pas les échecs, la propriété, les limitations ou autres contrats requis pour réduire le nombre de mots.

1. Lisez les fichiers AGENTS.md racine et sous-arbre, docs/AGENTS.md, la page cible, sa source et ses tests, ainsi que son propriétaire de navigation.
2. Classez la page par un travail principal et un lecteur : démarrage rapide, guide de tâche utilisateur, tutoriel contributeur, vue d'ensemble architecture, référence module, référence générée, instruction agent, registre de décision ou brouillon.
3. Placez la page chez son propriétaire le plus proche. Gardez les contrats de module à côté du code du module ; utilisez docs/ pour l'apprentissage inter-modules, le matériel utilisateur, développeur et architecture.
4. Définissez l'état de départ du lecteur, le résultat observable, l'échec probable, le chemin de récupération et la prochaine profondeur utile avant d'écrire les détails.
5. Écrivez dans l'ordre donné par structure de page : titre, Résumé, contenu, contenu orienté utilisateur, contenu orienté développeur, Exploration supplémentaire optionnelle.
6. Lorsque le profil active surfaces.bilingual-docs, mettez à jour la contrepartie dans la même passe et gardez les en-têtes, listes, tableaux, code et liens alignés ligne par ligne.
7. Vérifiez chaque affirmation par rapport au code, aux tests, aux générateurs, aux métadonnées du paquet ou à un propriétaire de décision actuel, et exécutez les opérations que la page instruit (voir la procédure de vérification ci-dessous). Mettez à jour le propriétaire avant tout artefact dérivé.
8. Exécutez commands.docs-check du profil et git diff --check, puis relisez la totalité du diff une fois pour l'exactitude et une fois pour la concision et l'adéquation.

Procédure de vérification : testez, ne supposez pas

La documentation décrit le comportement du produit aujourd'hui, et la seule preuve admissible pour une affirmation opérationnelle est de l'avoir exécutée. Cela s'applique à chaque nouvelle page et à chaque nouveau paragraphe qui prétend décrire une commande, une valeur par défaut, une erreur, une sortie ou une différence de plateforme.

1. Classez le sujet avant d'écrire des instructions d'installation ou d'utilisation. Lisez les faits (manifests, points d'entrée, exports), pas le nom du dossier. Une bibliothèque, un plugin, une CLI et un service ont chacun un chemin d'utilisation différent ; ne copiez jamais de guidance écrite pour un autre type.
2. Exécutez chaque opération revendiquée par rapport au checkout actuel. Exécutez chaque commande, extrait de configuration et exemple exactement comme la page le montrera ; notez uniquement ce que vous avez observé, y compris les avertissements et les modes d'échec. Si une affirmation dépend d'informations d'identification ou d'un réseau que vous n'avez pas, dites-le et nommez le propriétaire de la vérification au lieu d'affirmer le comportement.
3. Supprimez ce que vous n'avez pas pu reproduire. Ne transportez jamais une commande, un champ, une valeur par défaut ou un comportement de mémoire, d'analogie ou d'un README voisin. Lorsqu'une affirmation échoue à être reproduite, corrigez l'affirmation, pas le test.
4. Vérifiez les anciennes docs par rapport à la dernière branche par défaut. Avant de réviser une page existante, récupérez et comparez par rapport à la branche par défaut ; corrigez les déclarations obsolètes par rapport au code, pas par rapport à l'ancienne prose.

Règles de voix

• Le Résumé dit ce que le sujet fait. Les sections Résumé et orientées utilisateur décrivent ce qu'un lecteur peut faire avec le sujet (résultats, quand le choisir, coût principal), jamais son identité interne ou ses enregistrements. Omettez les identifiants source sauf si le lecteur les utilise directement dans une configuration, une commande ou une API publique.
• Les sections Développeur expliquent, ne listent jamais. Le détail Développeur couvre le concept de conception, l'architecture et le flux de données approximatif, suffisamment pour comprendre comment cela fonctionne, et renvoie au code pour les détails exacts. Pas de catalogues d'API complets, listes de colonnes ou reformulation de documentation d'API.
• État actuel uniquement. La documentation ordinaire décrit la base de code actuelle ; l'historique appartient aux Notes d'Agent, aux post-mortems, aux notes de version et aux guides de mise à niveau.
• Anglais technique contrôlé. Donnez à chaque phrase un acteur explicite et une action principale lorsque l'ambiguïté peut changer le comportement ; réutilisez un terme par concept ; séparez les instructions empilées ; préservez la modalité et les exceptions. Voir structure de page.

Critères de qualité

• Concis : le chemin commun ne contient que les faits nécessaires à son résultat ; la vérité exhaustive est à un lien ou une couche de détail.
• Intuitif : les prérequis précèdent les concepts dépendants, une prochaine action est évidente et les en-têtes utilisent des termes que les lecteurs recherchent.
• Aimable : les lecteurs peuvent reconnaître le succès, comprendre le risque avant d'agir, se remettre d'un échec probable et choisir d'aller plus loin.
• Précis : chaque affirmation durable a un propriétaire et un chemin de vérification proportionné à son risque.
• Lisible par l'agent : en-têtes, ancres, terminologie et propriété stables permettent une récupération ciblée sans charger l'ensemble du corpus.
• Complet pour le nouvel arrivant : un ingénieur sans contexte de dépôt peut reconstruire l'architecture ou la fonctionnalité pertinente à travers trois à cinq pages liées.

N'appliquez pas de limite de mots universelle aux références exhaustives ; mesurez la longueur du chemin d'entrée, le nombre de documents non pertinents parcourus par consultation et la plus grande section, et scindez par un propriétaire de domaine existant lorsque le coût de récupération est élevé.

Auditer le corpus

Appliquez l'ordre de rédaction de docs/AGENTS.md à chaque document humain dans le périmètre (pas aux Notes d'Agent) : localisez le document et énoncez son sujet ; définissez son niveau de détail autorisé et déplacez les explications plus approfondies vers les descendants propriétaires ; classez le tutoriel ou la référence en fonction de l'utilisation prévue, pas du chemin ; scindez les formes mixtes substantielles. Un déplacement est atomique avec chaque lien entrant réparé dans le même changement ; les catalogues générés ne sont jamais édités manuellement.

Ensuite, chassez la checklist de médiocrité dans docs/AGENTS.md, sondes les moins coûteuses d'abord : utilisez trim-cot-leakage pour les fuites de transcript de raisonnement, recherchez des phrases distinctives pour les règles dupliquées, remplacez les catalogues écrits manuellement par leurs propriétaires autoritaires et retirez le langage de spécification des Notes d'Agent implémentées. Si la suppression de prose modifierait le comportement promis plutôt que son explication, proposez d'abord le changement de comportement (voir find-simplifications). Gardez chaque règle porteuse de charge, de préférence en une à trois lignes plus un lien vers sa justification.

Références détaillées

• Structure et style de page : ordre de la page, progression des sections, pliage, anglais technique contrôlé et emphase.
• Critères de révision : le test du nouvel arrivant, l'examen des preuves et la révision du README.

Utilisez prose-standard pour la couverture contractuelle au niveau de la phrase et le jugement éditorial.