tc-tracker
por alirezarezvanitc-tracker ayuda a las sesiones de codificación con IA a crear, actualizar, validar, reanudar y cerrar registros locales del repositorio de Technical Change en docs/TC/. Úsalo para un seguimiento estructurado de cambios similar a incidencias, estado del ciclo de vida, evidencia de pruebas y notas de traspaso.
Este skill obtiene 84/100, lo que lo convierte en una opción sólida para usuarios del directorio que buscan seguimiento estructurado de cambios técnicos y continuidad entre sesiones de IA. El repositorio ofrece suficiente documentación de flujo de trabajo, ejemplos de comandos, referencias y scripts para que un agente lo ejecute con bastante menos incertidumbre que con un prompt genérico, aunque conviene tener en cuenta algunas limitaciones de empaquetado y de superficie de comandos.
- Guía de activación clara: el skill indica cuándo usarlo para dar seguimiento a cambios técnicos, traspasos entre sesiones de IA, trazas de auditoría y solicitudes específicas de estilo `/tc`, además de cuándo no conviene usarlo.
- Concreto a nivel operativo: el inicio rápido del README ofrece comandos Python ejecutables para inicializar el seguimiento, crear un TC, actualizar estado/archivos, escribir contexto de traspaso y consultar el estado.
- Implementación reutilizable real: cinco scripts Python, más referencias de esquema, ciclo de vida y traspaso, respaldan registros JSON estructurados, transiciones de estado, vistas de registro/estado y validación.
- SKILL.md no incluye un comando de instalación explícito, por lo que los usuarios pueden necesitar herramientas del directorio o copiar archivos manualmente para saber dónde deben ubicarse los scripts.
- La descripción menciona flujos de reanudación, cierre y exportación, pero el conjunto de scripts visible cubre init/create/update/status/validation, no comandos dedicados para resume, close o export.
Descripción general de la skill tc-tracker
Para qué sirve tc-tracker
tc-tracker es una skill de ingeniería para el seguimiento estructurado de Technical Changes: ayuda a un agente de IA a crear, actualizar, validar, reanudar y cerrar registros de cambios en JSON bajo docs/TC/ dentro de un proyecto. En lugar de depender de la memoria del chat, notas sueltas o mensajes de commit, registra qué cambió, por qué, qué archivos se vieron afectados, evidencia de pruebas, estado, bloqueos y contexto de traspaso entre sesiones.
Usuarios y proyectos para los que mejor encaja
La skill tc-tracker encaja muy bien con equipos que usan sesiones de programación con IA que pueden extenderse por varios chats, traspasos o ciclos de revisión. Es especialmente útil cuando necesitas un seguimiento similar al de issues para trabajo de implementación, trazabilidad de cambios de código o resúmenes de estado repetibles en tareas de features, bugfixes, refactors, infraestructura, documentación, hotfixes y mejoras.
Diferenciadores clave para Issue Tracking
A diferencia de un prompt genérico del tipo “crea un issue tracker”, tc-tracker incluye una estructura concreta de almacenamiento, una convención de TC ID, un modelo de historial de revisiones solo acumulativo, scripts de validación y una máquina de estados para el ciclo de vida. No sustituye a GitHub Issues ni a Jira; se parece más a un registro de implementación local del repositorio que conecta archivos de código, pruebas, decisiones y notas de traspaso para IA.
Cuándo no conviene usar tc-tracker
Evita tc-tracker para correcciones triviales de erratas, cambios solo de formato o generación puntual de changelogs a partir del historial de git. También puede resultar demasiado pesado si tu proyecto ya aplica un flujo de issues maduro y no quieres añadir registros JSON adicionales al repositorio.
Cómo usar la skill tc-tracker
Instalación de tc-tracker y primeros archivos que conviene leer
Instala la skill en un entorno compatible con skills usando:
npx skills add alirezarezvani/claude-skills --skill tc-tracker
Después, revisa el directorio fuente en engineering/skills/tc-tracker. Lee primero SKILL.md para entender las reglas de activación del agente y el flujo de trabajo, README.md para ver ejemplos de scripts, y luego references/lifecycle.md, references/tc-schema.md y references/handoff-format.md. Los helpers de Python en scripts/ son recursos prácticos, no solo ejemplos.
Inicializar el seguimiento en un proyecto
El uso básico de tc-tracker empieza creando un área de seguimiento local al repositorio:
python3 scripts/tc_init.py --project "My Project" --root .
Esto crea docs/TC/ con ubicaciones para configuración, registro, records y evidencia. El inicializador es idempotente, así que al volver a ejecutarlo debería informar del estado existente en lugar de duplicar la configuración. Ejecútalo desde la raíz del proyecto de destino o pasa un --root /path/to/project explícito.
Crear y actualizar un Technical Change
Un buen primer prompt le da al agente suficiente información para crear un registro válido sin tener que adivinar:
Use tc-tracker to create a TC for adding JWT authentication. Project root is
.. Scope isfeature, priority ishigh. 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.
El flujo equivalente con scripts sería:
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"
A medida que avance el trabajo, añade archivos afectados, casos de prueba, decisiones y cambios de estado en lugar de esperar hasta el final.
Usar bien los comandos de handoff y estado
El hábito más valioso al trabajar con tc-tracker es escribir un handoff útil antes de terminar una sesión. Incluye avances concretos, próximos pasos lo bastante pequeños como para ejecutarse, bloqueos, decisiones y archivos en curso:
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"
Revisa el trabajo con:
python3 scripts/tc_status.py --root . --all
python3 scripts/tc_validator.py --root .
Para un prompt de reanudación, pide al agente que lea docs/TC/records/<TC-ID>/tc_record.json, especialmente session_context.handoff, y que continúe desde los próximos pasos registrados.
Preguntas frecuentes sobre la skill tc-tracker
¿tc-tracker es un issue tracker completo?
No. tc-tracker para Issue Tracking es local al repositorio y está centrado en cambios. Hace seguimiento del estado de implementación, archivos, pruebas, decisiones y contexto de traspaso. Usa GitHub Issues, Linear o Jira para asignación de equipo, discusión, etiquetas, tableros y flujos con stakeholders externos.
¿Qué lo hace mejor que un prompt común?
Un prompt común puede resumir trabajo, pero normalmente no impone un schema, transiciones de ciclo de vida, revisiones solo acumulativas ni una estructura de directorios repetible. tc-tracker le da al agente de IA un formato duradero y scripts para crear, actualizar, validar y listar registros de cambios.
¿tc-tracker es apto para principiantes?
Sí, si te sientes cómodo ejecutando scripts de Python y commiteando archivos JSON. Si estás empezando, conviene usar los comandos de inicio rápido de README.md y evitar editar manualmente el JSON de los TC hasta entender references/tc-schema.md y references/lifecycle.md.
¿Qué puede frenar la adopción?
El principal coste de adopción es la sobrecarga de proceso. Cada cambio significativo necesita un registro TC, actualizaciones de estado y un buen texto de handoff. Si tu equipo no mantiene esos registros, el registry puede quedar desactualizado. La skill funciona mejor cuando las actualizaciones de TC forman parte del flujo de programación, no cuando se dejan como una tarea posterior.
Cómo mejorar la skill tc-tracker
Dale mejores entradas a tc-tracker
tc-tracker funciona mejor cuando tu prompt incluye la raíz del proyecto, el objetivo del cambio, scope, prioridad, motivación, archivos probables, expectativas de prueba y dudas actuales. Una entrada débil dice “track auth work”. Una entrada fuerte dice “create a high-priority feature TC for JWT auth, affecting these files, with tests for valid token, invalid token, and missing token.”
Mantén realistas las transiciones del ciclo de vida
Respeta la máquina de estados: planned, in_progress, blocked, implemented, tested y deployed. No marques un TC como tested sin evidencia de pruebas, y no saltes directamente de la planificación inicial a deployed. Si el trabajo retrocede, vuelve a in_progress con un motivo.
Mejora la calidad del handoff después de cada sesión
El fallo más común es dejar un handoff demasiado vago. Sustituye “finish tests” por acciones específicas como “Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q.” Incluye bloqueos solo cuando estén impidiendo activamente el avance, y registra las decisiones con su justificación para que la siguiente sesión de IA no vuelva a discutirlas desde cero.
Itera con validación y revisión
Después del primer resultado, ejecuta los scripts de estado y validación, y luego pide al agente que corrija campos faltantes, transiciones inválidas, listas de archivos desactualizadas o evidencia de pruebas débil. Para obtener mejores resultados a largo plazo, revisa references/tc-schema.md y ajusta tus prompts para que cada TC contenga resúmenes listos para revisión, archivos afectados, casos de prueba y contexto de sesión antes de cerrarse.