tc-tracker

Présentation de la skill tc-tracker

À quoi sert tc-tracker

tc-tracker est une skill d’ingénierie dédiée au suivi structuré des Technical Change : elle aide un agent IA à créer, mettre à jour, valider, reprendre et clôturer des enregistrements de changement JSON dans docs/TC/ au sein d’un projet. Au lieu de s’appuyer sur la mémoire de la conversation, des notes éparses ou des messages de commit, tc-tracker consigne ce qui a changé, pourquoi, les fichiers concernés, les preuves de test, le statut, les blocages et le contexte de reprise entre sessions.

Profils et projets pour lesquels tc-tracker est le plus adapté

La skill tc-tracker convient particulièrement aux équipes qui utilisent des sessions de codage avec IA pouvant s’étendre sur plusieurs conversations, passages de relais ou cycles de revue. Elle est surtout utile lorsque vous avez besoin d’un suivi proche d’un ticket pour du travail d’implémentation, de traces d’audit pour des changements de code, ou de synthèses d’état reproductibles sur des fonctionnalités, corrections de bugs, refactorings, travaux d’infrastructure, documentation, hotfixes et améliorations.

Ce qui distingue tc-tracker pour l’Issue Tracking

Contrairement à un prompt générique du type « crée un issue tracker », tc-tracker fournit une structure de stockage concrète, une convention d’identifiants TC, un modèle d’historique de révisions en ajout uniquement, des scripts de validation et une machine d’états de cycle de vie. Ce n’est pas un remplacement de GitHub Issues ou Jira ; c’est plutôt un journal d’implémentation local au dépôt, qui relie fichiers de code, tests, décisions et notes de passage de relais pour l’IA.

Quand éviter tc-tracker

Évitez tc-tracker pour de simples corrections de coquilles, des modifications uniquement liées au formatage ou la génération ponctuelle d’un changelog à partir de l’historique git. La skill peut aussi être trop lourde si votre projet impose déjà un workflow de suivi mature et que vous ne souhaitez pas ajouter des enregistrements JSON supplémentaires dans le dépôt.

Comment utiliser la skill tc-tracker

Installer tc-tracker et lire les premiers fichiers

Installez la skill dans un environnement compatible avec les skills :

npx skills add alirezarezvani/claude-skills --skill tc-tracker

Inspectez ensuite le répertoire source engineering/skills/tc-tracker. Commencez par SKILL.md pour comprendre les règles de déclenchement côté agent et le workflow, puis lisez README.md pour les exemples de scripts, et enfin references/lifecycle.md, references/tc-schema.md et references/handoff-format.md. Les assistants Python dans scripts/ sont des outils directement exploitables, pas de simples exemples.

Initialiser le suivi dans un projet avec tc-tracker

L’utilisation de base de tc-tracker commence par la création d’un espace de suivi local au dépôt :

python3 scripts/tc_init.py --project "My Project" --root .

Cette commande crée docs/TC/ avec les emplacements de configuration, de registre, d’enregistrements et de preuves. L’initialiseur est idempotent : si vous le relancez, il doit signaler l’état existant plutôt que dupliquer la configuration. Exécutez-le depuis la racine du projet cible ou passez explicitement --root /path/to/project.

Créer et mettre à jour un Technical Change

Un bon premier prompt donne à l’agent suffisamment d’informations pour créer un enregistrement valide sans devoir deviner :

Use tc-tracker to create a TC for adding JWT authentication. Project root is .. Scope is feature, priority is high. Summary: add login endpoint, JWT signing, and auth middleware. Motivation: protected API routes need authenticated access. Initial files likely affected: src/auth.py, src/middleware.py, tests/test_auth.py.

Le flux de scripts correspondant ressemble à ceci :

python3 scripts/tc_create.py --root . \
  --name "user-auth" \
  --title "Add JWT authentication" \
  --scope feature --priority high \
  --summary "Adds JWT login endpoint, signing, and middleware" \
  --motivation "Required for protected API endpoints"

python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
  --set-status in_progress --reason "Starting implementation"

Au fil de l’avancement, ajoutez les fichiers concernés, les cas de test, les décisions et les changements de statut au lieu d’attendre la fin du travail.

Bien utiliser les commandes de handoff et de statut

L’habitude la plus utile avec tc-tracker consiste à rédiger un passage de relais exploitable avant la fin d’une session. Incluez l’avancement concret, les prochaines étapes suffisamment petites pour être exécutées, les blocages, les décisions et les fichiers en cours :

python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
  --handoff-progress "Implemented JWT signing and wired middleware into router" \
  --handoff-next "Add integration test for invalid token returning 401" \
  --handoff-blocker "Need final test fixture shape for user records"

Vérifiez le travail avec :

python3 scripts/tc_status.py --root . --all
python3 scripts/tc_validator.py --root .

Pour un prompt de reprise, demandez à l’agent de lire docs/TC/records/<TC-ID>/tc_record.json, en particulier session_context.handoff, puis de continuer à partir des prochaines étapes enregistrées.

FAQ de la skill tc-tracker

tc-tracker est-il un issue tracker complet ?

Non. tc-tracker pour l’Issue Tracking est local au dépôt et centré sur les changements. Il suit l’état d’implémentation, les fichiers, les tests, les décisions et le contexte de passage de relais. Utilisez GitHub Issues, Linear ou Jira pour l’assignation d’équipe, les discussions, les labels, les tableaux et les workflows impliquant des parties prenantes externes.

Qu’apporte tc-tracker par rapport à un prompt ordinaire ?

Un prompt ordinaire peut résumer le travail, mais il n’impose généralement pas de schéma, de transitions de cycle de vie, de révisions en ajout uniquement ni de structure de répertoires reproductible. tc-tracker fournit à l’agent IA un format durable et des scripts pour créer, mettre à jour, valider et lister les enregistrements de changement.

tc-tracker est-il accessible aux débutants ?

Oui, si vous êtes à l’aise avec l’exécution de scripts Python et le commit de fichiers JSON. Les débutants devraient commencer par les commandes de démarrage rapide dans README.md et éviter de modifier manuellement les JSON de TC tant qu’ils n’ont pas compris references/tc-schema.md et references/lifecycle.md.

Qu’est-ce qui peut freiner l’adoption de tc-tracker ?

Le principal coût d’adoption est la charge de processus. Chaque changement significatif nécessite un enregistrement TC, des mises à jour de statut et un bon texte de passage de relais. Si votre équipe ne maintient pas ces enregistrements, le registre peut devenir obsolète. La skill fonctionne le mieux lorsque les mises à jour TC font partie intégrante du workflow de développement, et non lorsqu’elles sont traitées après coup.

Comment améliorer la skill tc-tracker

Fournir de meilleures entrées à tc-tracker

tc-tracker donne de meilleurs résultats lorsque votre prompt inclut la racine du projet, l’objectif du changement, le périmètre, la priorité, la motivation, les fichiers probables, les attentes de test et les incertitudes actuelles. Une entrée faible dit « track auth work ». Une entrée solide dit « create a high-priority feature TC for JWT auth, affecting these files, with tests for valid token, invalid token, and missing token. »

Garder des transitions de cycle de vie réalistes

Respectez la machine d’états : planned, in_progress, blocked, implemented, tested et deployed. Ne marquez pas un TC comme tested sans preuve de test, et ne passez pas directement de la planification initiale à deployed. Si le travail régresse, revenez à in_progress avec une raison.

Améliorer la qualité du handoff après chaque session

Le cas d’échec le plus fréquent est un texte de passage de relais trop vague. Remplacez « finish tests » par des actions précises comme « Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q. » N’indiquez des blocages que lorsqu’ils empêchent réellement la progression, et consignez les décisions avec leur justification afin que la session IA suivante ne les remette pas en débat.

Itérer avec validation et revue

Après la première sortie, exécutez les scripts de statut et de validation, puis demandez à l’agent de corriger les champs manquants, les transitions invalides, les listes de fichiers obsolètes ou les preuves de test trop faibles. Pour de meilleurs résultats à long terme, relisez references/tc-schema.md et ajustez vos prompts afin que chaque TC contienne, avant sa clôture, des résumés prêts pour la revue, les fichiers concernés, les cas de test et le contexte de session.