fp-control: AFP, Contagem de Melhorias e Design para Agentes Pequenos

Poucos dias depois de publicar a primeira versão do fp-control, continuei usando a skill em sessões reais de planejamento e fui encontrando os limites do que ela conseguia fazer. Três coisas estavam faltando: uma forma de aplicar o Fator de Ajuste de Valor, um modo para medir mudanças em sistemas já em produção e um formato de arquivo que não sobrecarregasse um agente menor em sistemas grandes. Adicionei as três.

Pontos de Função Ajustados #

A versão original da skill produzia Pontos de Função Não Ajustados (UFP) — a contagem bruta antes de qualquer ajuste do sistema. O IFPUG também define os Pontos de Função Ajustados (AFP), que aplicam um Fator de Ajuste de Valor derivado de 14 Características Gerais do Sistema: coisas como comunicações de dados, requisitos de performance, taxa de transação, reusabilidade e facilidade de instalação. Cada característica é avaliada de 0 a 5, as notas somam um Grau de Influência, e a fórmula é:

VAF = 0,65 + (GI × 0,01)
AFP = UFP × VAF

O intervalo vai de 0,65 a 1,35, ou seja, o AFP pode ser até 35% menor ou maior que o UFP.

O AFP é opcional na skill — e opcional na prática. A comunidade IFPUG tem se afastado progressivamente dele porque as avaliações são subjetivas e a variação de ±35% raramente muda uma decisão. Mas contratos e projetos governamentais ainda pedem, e algumas equipes o usam para incorporar características que o UFP ignora. Por isso o adicionei como um passo opcional após o cálculo do UFP, com a tabela completa das 14 características e uma explicação do que cada uma mede para os casos em que o usuário não tiver certeza de como avaliá-la.

Contagem de Projetos de Melhoria #

A versão original só tratava da contagem para Projetos de Desenvolvimento — medir um sistema novo do zero. Isso cobre a primeira versão, mas não o que vem depois da implantação.

O IFPUG trata melhorias de forma diferente. Em vez de recontar todas as funções, você classifica cada uma das existentes como Adicionada, Modificada ou Excluída:

ADD — novas funções sendo introduzidas
CHG — funções existentes sendo modificadas, contadas no novo tamanho
DEL — funções existentes sendo removidas

A métrica de tamanho da melhoria é o DEFP (Pontos de Função do Projeto de Melhoria):

DEFP = ADD + CHG_depois

E o baseline atualizado da aplicação após a implantação é:

UFP Atualizado = Baseline − DEL − CHG_antes + ADD + CHG_depois

DEFP e UFP Atualizado respondem a perguntas diferentes. O DEFP é o escopo do trabalho sendo feito agora — o que você usa para estimar esforço. O UFP Atualizado é o novo estado do sistema depois que a melhoria vai para produção, e se torna o baseline para o próximo ciclo.

A skill agora detecta qual modo usar no início da sessão. Se o usuário referencia um arquivo .fpa.yaml existente e indica que está medindo mudanças, ela entra no Modo de Projeto de Melhoria — carrega o baseline, percorre a classificação de cada função existente, coleta as novas e produz a tabela de reconciliação. Sem arquivo referenciado, o padrão é o Modo de Desenvolvimento.

Design para agentes pequenos #

Uma restrição que não havia considerado com cuidado suficiente na primeira versão: o que acontece quando o arquivo de saída fica grande?

Um sistema com 100 funções produz aproximadamente 3.000 tokens de YAML. Some o prompt da skill, o histórico de conversa e um system prompt, e um agente menor já está com 8.000–10.000 tokens antes de o usuário dizer qualquer coisa. Um sistema com 200 funções empurra isso para um território onde modelos menores começam a ter dificuldade.

Defini um limiar de 50 funções totais. Abaixo disso, tudo fica em um único arquivo. Acima disso, o passo de salvamento produz um arquivo índice mais um arquivo de detalhes por tipo de função:

meu-sistema.fpa.yaml         ← índice: totais, AFP, esforço, lista compacta de funções
meu-sistema.fpa.ilf.yaml     ← detalhes completos de ILF
meu-sistema.fpa.ei.yaml      ← detalhes completos de EI
...

O índice contém tudo o que é necessário para um resumo ou para o baseline de uma futura melhoria — nomes e valores de FP das funções, contagens por tipo, AFP e esforço. Os arquivos de detalhes contêm as variáveis completas de contagem (RET, DET, FTR, complexidade) e são carregados sob demanda pela skill de HTML, uma aba por vez.

A extensão também mudou de .fpa.md para .fpa.yaml. Os arquivos agora são somente YAML — não há estrutura Markdown. O relatório HTML é o artefato legível por humanos; o arquivo YAML é estritamente legível por máquinas. Manter a extensão compatível com o formato real evita uma confusão pequena mas persistente.

Outra otimização para a cadeia de melhorias: todo arquivo de melhoria carrega um bloco baseline_functions — um snapshot compacto de todas as funções com apenas o nome e o valor de FP. Quando uma futura melhoria carrega esse arquivo, lê esse bloco diretamente e nunca precisa abrir nenhum arquivo anterior. A cadeia permanece autocontida um arquivo por vez, independente de quantas melhorias se acumulem ao longo do tempo.

Duas skills em vez de uma #

A geração do relatório HTML passou para uma skill separada: fp-control-html. A skill principal /fp-control cuida da sessão de contagem e salva o resultado em um arquivo .fpa.yaml. Gerar o relatório visual é uma etapa separada: /fp-control-html lê qualquer .fpa.yaml — desenvolvimento ou melhoria, arquivo único ou dividido — e produz um HTML autocontido com navegação em abas, gráficos SVG, modo escuro/claro e suporte a impressão. O nome do arquivo de saída é derivado diretamente do nome do YAML: meu-sistema.fpa.yaml vira meu-sistema.html.

A separação mantém os dois arquivos menores e atualizáveis de forma independente. Também significa que é possível regenerar o relatório a qualquer momento sem precisar refazer a sessão de contagem.

Registrando o que fica fora da contagem #

Sessões de contagem revelam mais do que funções dentro do escopo. Stakeholders frequentemente concordam em adiar algo para uma fase futura, cortar algo explicitamente da rodada atual, ou deixar uma observação sobre uma negociação que moldou o número final. Nada disso cabia em assumptions, que trata de decisões de contagem e riscos — não de decisões de escopo.

Adicionei três campos opcionais ao schema do YAML:

deferred — funcionalidades que ficou combinado tratar em uma fase futura (uma lista simples de strings)
rejected — funcionalidades explicitamente excluídas do escopo, com a justificativa embutida na string
notes — um registro datado de negociações, cada entrada um par {date, text}

Eles vivem apenas no arquivo índice — nunca nos arquivos de detalhes nem nos snapshots de baseline — porque descrevem a conversa de planejamento, não o inventário de funções. O relatório HTML os exibe em uma nova aba Scope: itens adiados recebem um tratamento âmbar de “pendente”, itens rejeitados um tratamento discreto em vermelho/cinza, e as observações são renderizadas como uma tabela Data · Nota ordenada da mais recente para a mais antiga. A aba, e cada uma de suas três seções, só aparece quando há algo para mostrar.

Refinando o relatório HTML #

Algumas rodadas gerando relatórios reais revelaram detalhes que valia a pena corrigir na própria skill, em vez de improvisar a cada vez:

Tipos sem itens desaparecem completamente. Se um sistema não tem nenhum EIF, o relatório deixa de mostrar uma aba EIF vazia — a aba, seu input de rádio e seu painel são todos omitidos. A mesma regra vale para qualquer tipo de função.
Os subtotais mostram a composição de complexidade. Cada tabela de tipo de função agora termina com algo como Low×28 · Avg×25 · High×26 ao lado do total de FP, deixando visível de relance a forma da contagem, não só sua soma.
A tabela de visão geral mostra proporção, não só total. Uma coluna % of UFP deixa imediatamente claro qual tipo de função domina a contagem.

Também defini o layout que eu realmente queria para esses relatórios, depois de comparar dois gerados lado a lado: um cartão centralizado em estilo “documento impresso” — fundo cinza-claro, container de ~960px, banner de cabeçalho em gradiente índigo, um badge de UFP compacto — em vez de um painel em largura total. Isso agora é o padrão da skill, e antes de gerar o relatório ela mostra brevemente esses padrões (layout, cor de destaque, tema inicial) e pergunta se o usuário quer mudar algo.

Por fim, para sistemas grandes o suficiente para precisar do formato YAML dividido, a skill agora monta o HTML de forma incremental — escrevendo primeiro o esqueleto da página e depois anexando um painel de tipo de função por vez, em vez de tentar tudo de uma só vez. Isso reflete a forma como os próprios arquivos de detalhes são carregados durante uma sessão: um tipo de função por vez, cada um mantido em um tamanho administrável.

Arquivos de contexto para agentes #

Dois arquivos pequenos foram adicionados à raiz do repositório: agents.md e CLAUDE.md.

O agents.md é agnóstico de plataforma: explica o que as duas skills fazem e como invocá-las, e também cuida da auto-instalação — gravando tanto fp-control.md quanto fp-control-html.md no local global apropriado para a plataforma detectada. O CLAUDE.md é uma única linha — @agents.md — que é a sintaxe de importação do Claude Code. Quando o Claude Code abre o diretório do repositório, carrega o CLAUDE.md automaticamente, que puxa o agents.md, disparando a instalação e tornando as duas skills disponíveis sem nenhuma configuração manual.

Outras plataformas não carregam o CLAUDE.md automaticamente, então usuários do Cursor e do Windsurf ainda dependem do mecanismo de auto-instalação do agents.md. Mas o conteúdo — o que as skills fazem e como usá-las — vive no agents.md agnóstico de plataforma, legível por qualquer ferramenta.

O repositório está em github.com/adautomeira/fp-control.