tc-tracker

Visão geral da skill tc-tracker

Para que serve o tc-tracker

tc-tracker é uma skill de engenharia para rastreamento estruturado de Technical Changes: ela ajuda um agente de IA a criar, atualizar, validar, retomar e fechar registros JSON de mudanças em docs/TC/ dentro de um projeto. Em vez de depender da memória do chat, de anotações soltas ou de mensagens de commit, ela registra o que mudou, por quê, arquivos afetados, evidências de teste, status, bloqueios e contexto de passagem entre sessões.

Usuários e projetos ideais

A skill tc-tracker é uma ótima escolha para equipes que usam sessões de codificação com IA que podem atravessar vários chats, handoffs ou ciclos de revisão. Ela é especialmente útil quando você precisa de um acompanhamento parecido com issues para trabalho de implementação, trilhas de auditoria para mudanças de código ou resumos de status repetíveis em tarefas de feature, bugfix, refactor, infraestrutura, documentação, hotfix e melhoria.

Diferenciais principais para Issue Tracking

Diferente de um prompt genérico do tipo “crie um issue tracker”, tc-tracker já vem com um layout concreto de armazenamento, uma convenção de TC ID, um modelo de histórico de revisões append-only, scripts de validação e uma máquina de estados de ciclo de vida. Ele não substitui GitHub Issues ou Jira; está mais próximo de um log de implementação local ao repositório, conectando arquivos de código, testes, decisões e notas de handoff para IA.

Quando não usar tc-tracker

Evite tc-tracker para correções triviais de typo, edições apenas de formatação ou geração pontual de changelog a partir do histórico do git. Ele também pode ser pesado demais se o seu projeto já impõe um fluxo maduro de issues e você não quer adicionar registros JSON ao repositório.

Como usar a skill tc-tracker

Instalação do tc-tracker e primeiros arquivos para ler

Instale a skill em um ambiente compatível com skills usando:

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

Depois, inspecione o diretório de origem em engineering/skills/tc-tracker. Leia primeiro SKILL.md para entender as regras de acionamento do agente e o fluxo de trabalho, README.md para exemplos de scripts, e então references/lifecycle.md, references/tc-schema.md e references/handoff-format.md. Os auxiliares em Python dentro de scripts/ são recursos práticos, não apenas exemplos.

Inicialize o rastreamento em um projeto

O uso básico do tc-tracker começa com a criação de uma área de rastreamento local ao repositório:

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

Isso cria docs/TC/ com locais para configuração, registry, registros e evidências. O inicializador é idempotente, portanto executá-lo novamente deve informar o estado existente em vez de duplicar a configuração. Rode o comando a partir da raiz do projeto de destino ou passe um --root /path/to/project explícito.

Crie e atualize um Technical Change

Um bom primeiro prompt dá ao agente informações suficientes para criar um registro válido sem precisar adivinhar:

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.

O fluxo correspondente com scripts fica assim:

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"

À medida que o trabalho avança, adicione arquivos afetados, casos de teste, decisões e mudanças de status em vez de esperar até o final.

Use bem os comandos de handoff e status

O hábito mais valioso ao usar o guia do tc-tracker é escrever um handoff útil antes de encerrar uma sessão. Inclua progresso concreto, próximos passos pequenos o bastante para executar, bloqueios, decisões e arquivos em andamento:

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"

Verifique o trabalho com:

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

Para um prompt de retomada, peça ao agente para ler docs/TC/records/<TC-ID>/tc_record.json, especialmente session_context.handoff, e então continuar a partir dos próximos passos registrados.

FAQ da skill tc-tracker

tc-tracker é um issue tracker completo?

Não. tc-tracker para Issue Tracking é local ao repositório e focado em mudanças. Ele acompanha estado de implementação, arquivos, testes, decisões e contexto de handoff. Use GitHub Issues, Linear ou Jira para atribuição de equipe, discussões, labels, boards e fluxos com stakeholders externos.

O que o torna melhor do que um prompt comum?

Um prompt comum pode resumir o trabalho, mas normalmente não impõe schema, transições de ciclo de vida, revisões append-only nem um layout de diretórios repetível. tc-tracker dá ao agente de IA um formato durável e scripts para criar, atualizar, validar e listar registros de mudança.

tc-tracker é amigável para iniciantes?

Sim, se você se sente confortável executando scripts Python e versionando arquivos JSON. Iniciantes devem começar pelos comandos de quick-start em README.md e evitar editar manualmente o JSON dos TCs até entenderem references/tc-schema.md e references/lifecycle.md.

O que pode atrapalhar a adoção?

O principal custo de adoção é o overhead de processo. Toda mudança relevante precisa de um registro de TC, atualizações de status e um bom texto de handoff. Se a equipe não mantiver esses registros, o registry pode ficar desatualizado. A skill funciona melhor quando as atualizações de TC fazem parte do fluxo de codificação, não quando são tratadas como algo para fazer depois.

Como melhorar a skill tc-tracker

Dê entradas mais fortes ao tc-tracker

tc-tracker funciona melhor quando seu prompt inclui raiz do projeto, objetivo da mudança, escopo, prioridade, motivação, arquivos prováveis, expectativas de teste e incertezas atuais. Uma entrada fraca diz “track auth work”. Uma entrada forte diz “create a high-priority feature TC for JWT auth, affecting these files, with tests for valid token, invalid token, and missing token.”

Mantenha as transições de ciclo de vida realistas

Respeite a máquina de estados: planned, in_progress, blocked, implemented, tested e deployed. Não marque um TC como tested sem evidência de teste, e não pule do planejamento inicial diretamente para deployed. Se o trabalho regredir, volte para in_progress com uma justificativa.

Melhore a qualidade do handoff após cada sessão

O modo de falha mais comum é um texto de handoff vago. Troque “finish tests” por ações específicas, como “Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q.” Inclua bloqueios apenas quando eles estiverem de fato impedindo o progresso, e registre decisões com justificativa para que a próxima sessão de IA não precise rediscuti-las.

Itere com validação e revisão

Depois da primeira saída, execute os scripts de status e validação, e então peça ao agente para corrigir campos ausentes, transições inválidas, listas de arquivos desatualizadas ou evidências de teste fracas. Para resultados melhores no longo prazo, revise references/tc-schema.md e ajuste seus prompts para que todo TC contenha resumos prontos para revisão, arquivos afetados, casos de teste e contexto de sessão antes de ser fechado.