Rastreamento de Funcionalidades

Visão Geral

O Rastreamento de Funcionalidades mantém uma memória leve e nativa do repositório para trabalhos de funcionalidades de longa duração. Ele oferece aos agentes de codificação de IA um local estável para encontrar o status atual, documentos autoritativos, comportamento verificado, decisões duráveis, riscos e mudanças recentes, sem tratar o histórico de chat ou planos desatualizados como verdade.

O fluxo de trabalho usa um índice global mais uma trilha Markdown por funcionalidade em docs/features/. Ele complementa rastreadores de issues, especificações e código-fonte, vinculando as evidências que ainda importam em vez de duplicá-las.

Quando Usar Esta Habilidade

• Use ao iniciar ou retomar o trabalho em uma funcionalidade após uma mudança de sessão, agente ou ferramenta.
• Use quando o conhecimento da funcionalidade estiver espalhado por PRDs, notas de API, planos, issues e commits antigos.
• Use quando uma funcionalidade de longa duração precisar de decisões duráveis, riscos, restrições de rollout ou notas de migração.
• Use ao revisar ou finalizar o trabalho de uma funcionalidade e registrar o resultado verificado para agentes futuros.
• Use ao adotar memória de projeto leve em um repositório existente sem reorganizar toda a documentação.

Não use esta habilidade meramente para registrar cada edição de código ou substituir um rastreador de issues existente. Use-a quando futuros contribuidores precisarem de uma visão concisa e atual de uma funcionalidade inteira.

Como Funciona

Etapa 1: Descobrir Memória Existente da Funcionalidade

Antes de alterar uma funcionalidade:

1. Leia docs/features/README.md se existir.
2. Identifique o ID da funcionalidade a partir da solicitação, módulo de código, rota, domínio ou documentação existente.
3. Leia docs/features/<feature-id>/README.md se existir.
4. Siga seus links atuais de fonte de verdade antes de propor ou implementar mudanças.

Nunca assuma que um plano antigo é autoritativo apenas porque é detalhado. Prefira código atual, testes, especificações aceitas e decisões verificadas recentes.

Etapa 2: Criar a Estrutura Mínima Quando Ausente

Use lowercase hyphen-case para IDs de funcionalidades:

docs/features/
├── README.md
└── <feature-id>/
    ├── README.md
    ├── prd/
    ├── api/
    ├── plans/
    └── archive/

Para um repositório existente, crie apenas os diretórios necessários no momento. Vincule documentos úteis onde eles já residem antes de considerar uma migração.

O índice global deve permanecer uma superfície compacta de navegação e status:

# Feature Tracks

| Feature | Status | Track | Source of Truth | Updated | Notes |
|---|---|---|---|---|---|
| Checkout | active | `checkout/README.md` | `checkout/prd/checkout.md` | 2026-07-13 | Payment retry work in progress |

Use nomes de status locais do projeto quando o repositório já os definir. Caso contrário, prefira um pequeno vocabulário como planned, active, stable, paused ou deprecated.

Etapa 3: Manter a Trilha da Funcionalidade

Cada docs/features/<feature-id>/README.md deve resumir a verdade atual e vincular a evidências detalhadas:

# Checkout Feature Track

## Current Status

Checkout supports one-time card payments. Automatic payment retry is in progress.

## Source of Truth

- Checkout PRD: `prd/checkout.md`
- Payments API: `api/payments.md`
- Current implementation plan: `plans/payment-retry.md`

## Current Behavior

- Customers can complete one-time card payments.
- Failed payments currently require a manual retry.

## Decisions

- Preserve idempotency keys across automatic retries.
- Keep retry policy in the payments service.

## Known Risks

- The provider sandbox does not reproduce every production decline code.

## Changelog

- 2026-07-13: Added the retry plan and recorded idempotency requirements.

Atualize a trilha quando qualquer um destes itens mudar:

• comportamento visível ao usuário ou ao sistema,
• endpoints, modelos de dados, dependências ou integrações,
• decisões duráveis e trade-offs,
• restrições de rollout, migrações, riscos ou acompanhamentos,
• testes, planos, especificações ou outros links de fonte de verdade.

Mantenha requisitos e designs detalhados em seus próprios documentos. A trilha da funcionalidade deve explicar o que é verdade agora e onde encontrar a prova.

Etapa 4: Conciliar a Trilha Antes da Conclusão

Antes de declarar o trabalho da funcionalidade como concluído:

1. Atualize a trilha da funcionalidade com o resultado verificado real, não apenas o plano pretendido.
2. Atualize o índice global quando o status, data, links ou notas mudaram.
3. Verifique se todos os links relativos do Markdown resolvem.
4. Confirme se a trilha contém o status atual, links de fonte de verdade, decisões, riscos e um changelog datado.
5. Registre explicitamente bloqueadores ou acompanhamentos não resolvidos.

…