fp-control: Análise de Pontos de Função como Skill de IA, Não como Aplicação

Eu tinha um repositório no GitHub chamado fp-control que originalmente era uma API Flask publicada no AWS Lambda. Não estava fazendo muita coisa. Decidi reaproveitá-lo por completo e transformá-lo em algo que eu realmente queria usar: uma skill de IA agnóstica de plataforma para planejar sistemas de software usando Análise de Pontos de Função.

O fato de ter começado como uma aplicação dedicada vale ser destacado. Uma skill bem estruturada pode substituir um número surpreendente de ferramentas leves — a contrapartida é que você passa a depender do custo de uma assinatura de agente, ou do esforço maior de rodar um LLM local com capacidade suficiente para seguir instruções complexas com consistência. Um modelo local dá mais controle e, talvez, mais espaço para ideias não convencionais, já que você não está dentro dos limites de um serviço comercial. Mas para a maioria dos casos de uso, um agente hospedado com um bom arquivo de skill é o caminho mais direto.

O que é uma skill, exatamente? #

No contexto dos assistentes de programação com IA, uma skill é um arquivo Markdown que um agente lê e segue como um conjunto de instruções. O Claude Code chama de commands; o Cursor chama de rules; o Windsurf chama de memories. O formato varia um pouco, mas a ideia é a mesma — você escreve as instruções uma vez e o agente sabe como se comportar para aquela tarefa em todas as sessões futuras.

O desafio das skills é a distribuição. Se eu escrever uma para o Claude Code, ela só funciona lá. Eu queria algo que qualquer agente pudesse usar.

O padrão de auto-instalação #

A primeira decisão de design foi fazer a skill se instalar sozinha. Quando um agente lê o fp-control.md pela primeira vez, as próprias instruções do arquivo dizem a ele para detectar em qual plataforma está rodando e copiar o arquivo para o diretório de configuração global correspondente. O Claude Code recebe ~/.claude/commands/fp-control.md. O Cursor recebe ~/.cursor/rules/fp-control.mdc. O Windsurf tem seu próprio caminho. Qualquer outro agente recebe a instrução de usar o equivalente da sua plataforma.

O usuário não precisa mais pensar em configuração depois da primeira leitura. Se confiar no agente para fazer automaticamente, funciona. Se preferir fazer manualmente, o README tem uma tabela com o comando exato para cada plataforma.

O fluxo de Análise de Pontos de Função #

Uma vez instalada, invocar /fp-control inicia uma sessão de Análise de Pontos de Função seguindo o método IFPUG. A skill guia o usuário por oito etapas:

1. Definir a fronteira do sistema — o que está dentro, o que está fora
2. Identificar Arquivos Lógicos Internos (ILF) — dados que o sistema mantém
3. Identificar Arquivos de Interface Externa (EIF) — dados externos que o sistema lê mas não mantém
4. Contar Entradas Externas (EI) — operações de escrita que criam, atualizam ou excluem dados internos
5. Contar Saídas Externas (EO) — relatórios e resultados calculados enviados para fora da fronteira
6. Contar Consultas Externas (EIQ) — consultas somente leitura sem processamento derivado
7. Calcular os Pontos de Função Não Ajustados e produzir um resumo de planejamento
8. Opcionalmente salvar a análise como arquivo Markdown estruturado e gerar um relatório HTML

A skill faz uma pergunta por vez, raciocina sobre as contagens de RET, DET e FTR a partir das descrições do usuário quando ele tem dúvidas, e mantém o total acumulado visível ao longo de toda a sessão. Ela também detecta o idioma em que o usuário escreve e conduz toda a sessão — incluindo o HTML gerado — nesse idioma.

Testando com um sistema real #

Para testar a skill, rodei uma sessão completa de APF para uma plataforma multi-empresa com controle de acesso baseado em papéis e modelo de atribuição de profissionais. O tipo de sistema que, no papel, parece simples mas revela sua profundidade quando você começa a contar o que ele realmente faz.

A análise produziu 329 Pontos de Função Não Ajustados em 74 itens: 13 Arquivos Lógicos Internos (91 PF), nenhum Arquivo de Interface Externa, 33 Entradas Externas (111 PF), 12 Saídas Externas (62 PF) e 16 Consultas Externas (65 PF). Usando benchmarks típicos da indústria, isso se traduz em aproximadamente 4.600 horas de esforço de desenvolvimento — uma linha de base concreta antes de uma única linha de código ser escrita.

O relatório HTML #

Ao final da sessão, a skill gera um arquivo HTML autocontido sem nenhuma dependência externa. Tudo — CSS, JavaScript, dados — está embutido no arquivo. O relatório é organizado como uma interface com abas: uma aba de Visão Geral com a fronteira do sistema, um gráfico de barras e o resumo de UFP, seguida por uma aba para cada tipo de função (ILF, EIF, EI, EO, EIQ) e uma aba final de Esforço e Riscos.

Cada aba de tipo de função inclui um cartão de referência de complexidade com a matriz IFPUG correspondente, e uma tabela completa de itens com uma coluna “Regra aplicada” que torna o raciocínio transparente — por exemplo, FTR 2, DET 5–15 → Médio. Qualquer pessoa que leia o relatório pode rastrear exatamente como cada item foi classificado.

O relatório também tem um toggle de modo claro/escuro e dois botões de impressão: um que imprime o relatório completo sempre em modo claro, independentemente do tema atual, e um segundo que imprime um resumo simplificado mostrando apenas a aba de Visão Geral.

Continuidade de sessão com .fpa.md #

Uma limitação de trabalhar com agentes de IA é que as sessões terminam. A compactação de contexto trunca o histórico. Uma sessão completa de APF para um sistema moderadamente complexo envolve dezenas de itens em cinco tipos de função — não é algo que se queira reconstruir de memória.

A skill resolve isso salvando a análise como um arquivo .fpa.md. O arquivo tem duas partes: um bloco de frontmatter YAML com todos os dados estruturados (cada item, suas contagens, complexidade e valor em PF), e um corpo em Markdown com o resumo de planejamento legível por humanos logo abaixo. Quando o usuário abre uma nova sessão e referencia o arquivo, o agente lê o frontmatter e oferece retomar exatamente de onde parou — apresentar o resumo, atualizar itens específicos ou ir direto para a geração do HTML.

Um único arquivo serve a dois propósitos: legível por máquina o suficiente para um agente restaurar o estado, e legível por humano o suficiente para abrir em qualquer editor e entender de imediato.

Por que Pontos de Função ainda importam #

Há uma pergunta razoável sobre se medir o tamanho funcional ainda é relevante quando a IA pode gerar código mais rápido do que nunca. Minha visão é que importa mais, não menos. A IA acelera a implementação, mas não reduz os requisitos. Um sistema com 300 Pontos de Função tem a mesma complexidade funcional independentemente de ser construído por uma equipe de dez pessoas em três meses ou por um desenvolvedor solo com um assistente de IA em duas semanas. O escopo é o mesmo; apenas a produtividade mudou.

Pontos de Função oferecem uma linha de base agnóstica de tecnologia para esse escopo — comparável entre projetos, defensável em contratos e útil para recalibrar benchmarks à medida que dados de produtividade com desenvolvimento assistido por IA se acumulam. Saber o que você está pedindo para a IA construir, e quanto disso, ainda é o primeiro passo antes de pedir para ela construir qualquer coisa.

O repositório está em github.com/adautomeira/fp-control e é distribuído sob a licença MIT.