CommunityRédaction et éditiongithub.com

NOC Living Docs (Documentation Vivante du Projet)

Protocole de documentation vivante et compétence Codex pour maintenir la synchronisation entre les modifications de code assistées par IA, les exigences, l'état, les garde-fous, les tests et les enregistrements de changement.

Qu'est-ce que NOC Living Docs (Documentation Vivante du Projet) ?

Cette compétence transforme la documentation de votre projet en une mémoire exécutable et vivante. Elle est conçue pour les agents d'IA comme Codex (et similaires) et garantit que chaque modification de code est accompagnée d'une mise à jour appropriée de la documentation du projet. La compétence fonctionne en acheminant toutes les actions pertinentes via un répertoire dédié `noc_docs/`, en lisant uniquement les documents affectés (comme `requirements.md`, `status.md`, `guardrails.md`), puis en mettant à jour ces documents lorsque le code ou l'intention change. Elle offre également une interface CLI via `scripts/noc.py` pour créer des plans de travail, vérifier la cohérence avant les commits et indexer le projet. L'objectif principal est d'empêcher la divergence entre le code et sa documentation : lorsque l'IA modifie le comportement, les exigences ou les contraintes, la documentation vivante est automatiquement mise à jour. La compétence inclut des règles d'arrêt claires pour éviter les modifications non autorisées et une définition précise du « fait » (Definition of Done) qui valide que la documentation a bien été vérifiée, mise à jour et vérifiée par l'outil CLI avant de considérer la tâche comme terminée.

Compatible avec~Claude Code✓Codex CLI~Cursor
npx skills add SmallNoc/noc-living-docs

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Documentation Vivante du Projet

Utilisez NOC Living Docs comme mémoire exécutable du projet. Acheminez via noc_docs/, lisez uniquement les documents affectés, mettez à jour la documentation vivante lorsque le code ou l'intention change, puis vérifiez avec l'interface CLI.

Déclencheur

Utilisez cette compétence pour :

  • initialiser ou migrer noc_docs/
  • discuter d'une exigence puis modifier du code
  • nouvelles fonctionnalités, corrections de bugs, refontes, modifications d'API/données/sécurité/déploiement
  • vérifier si les modifications de code nécessitent des mises à jour de la documentation
  • interroger ou auditer la documentation vivante du projet

Ne l'utilisez pas pour des questions générales qui n'impliquent pas la mémoire du projet, le comportement du code, les exigences, les garde-fous, les tests ou la documentation NOC.

Exécution

  1. Identifiez la fonctionnalité/domaine affecté à partir de la demande, des chemins modifiés et de noc_docs/.living-docs/feature-map.json.
  2. Exécutez un plan de travail lorsque le code peut changer :
python scripts/noc.py work /chemin/vers/projet --feature <fonctionnalité> --intent "<exigence convenue>"

Utilisez --path <chemin/code> lorsque les chemins sont plus clairs que les noms de fonctionnalités.

  1. Lisez les plus petits documents pertinents : agent-guide.md, requirements.md, status.md, guardrails.md, test-record.md, plus les garde-fous de domaine lorsqu'ils sont présents.
  2. Écrivez les nouvelles intentions confirmées/modifiées dans requirements.md ; placez les discussions incertaines dans notes.md.
  3. Modifiez le code.
  4. Mettez à jour status.md, test-record.md, change-record.md et guardrails.md lorsque le comportement, la vérification, les modifications importantes ou les contraintes ont changé.
  5. Exécutez python scripts/noc.py index <projet> après les modifications de documentation, de fonctionnalité ou de mappage.
  6. Exécutez python scripts/noc.py check <projet> --staged --warn-only avant le commit lorsque Git est disponible.

Pour des règles de workflow détaillées, lisez references/workflow.md.

Ne Pas Procéder

Arrêtez-vous et demandez à l'utilisateur avant de modifier le code lorsque :

  • la demande entre en conflit avec guardrails.md ou les garde-fous de domaine
  • l'intention du produit entre en conflit avec requirements.md et la direction visée n'est pas claire
  • la fonctionnalité/domaine affecté ne peut pas être identifié et la modification n'est pas évidemment globale
  • les documents requis sont manquants et la tâche dépend d'exigences ou de contraintes inconnues
  • l'utilisateur demande de réécrire silencieusement les exigences pour correspondre au code actuel
  • la modification touche la sécurité, les permissions, la facturation, la perte de données, les migrations ou les contrats d'API publique et le comportement demandé est ambigu

Définition de Fait

Une tâche utilisant cette compétence n'est terminée que lorsque :

  • les documents affectés ont été identifiés via la carte des fonctionnalités, les chemins ou le nom de fonctionnalité explicite
  • les documents requis ont été lus ou les documents manquants ont été signalés
  • les modifications de code et les modifications de documentation concordent
  • requirements.md a été modifié uniquement pour des changements de comportement intentionnels
  • status.md reflète le comportement actuel après les modifications de code
  • test-record.md enregistre la vérification ou explique pourquoi la vérification n'a pas été exécutée
  • change-record.md enregistre les modifications d'implémentation importantes
  • les indexations/vérifications ont été exécutées lorsque disponibles, ou ignorées avec une raison

Format de Réponse Finale

Terminez par :

NOC Living Docs :
- docs vérifiés :
- docs mis à jour :
- docs intentionnellement inchangés :
- commandes exécutées :
- tests exécutés :
- risques restants :

Gardez les listes courtes. Utilisez aucun lorsqu'une catégorie ne s'applique pas.

Références

  • references/workflow.md : sélection de mode, règles de repli, gestion des conflits, boucle de travail
  • references/feature-doc-template.md : ce que chaque document de fonctionnalité doit contenir
  • references/domain-mode-guide.md : quand et comment utiliser le mode domaine
  • references/codex-prompts.md : invites utilisateur recommandées pour les workflows Codex plan/objectif/code

Skills associés