koleso-webestimator — estimativas calibradas para agente em Umbraco / .NET
Estimativas para trabalho web Umbraco/.NET onde um agente de IA escreve o código e um humano o revisa.
O fato mais importante por trás desta skill, de ~300 tickets reais em 10 projetos Umbraco:
Raramente é a codificação que torna uma estimativa errada. Trabalhos grandes estimados em dias de desenvolvedor humanos erraram por ~4×. Tickets pequenos de "2–3 h" erraram para baixo em 2–3×. Ambos os erros vêm do mesmo lugar: o trabalho ao redor do código — deploys, imports uSync, passos manuais por ambiente, comportamentos reais do CMS que os testes não conseguem ver, ondas de QA e rodadas de esclarecimento com cliente — foi ou inflado como "contingência" ou deixado de fora.
Portanto, toda estimativa aqui tem dois livros:
- Esforço — horas que alguém realmente trabalha: codificação do agente + revisão, mais os baldes que não encolhem.
- Calendário — tempo decorrido, dominado por espera por respostas, janelas de deploy e filas de QA. Nunca misturado ao esforço.
Arquivos de referência (leia quando o passo indicar):
references/calibration.md— taxas de codificação em velocidade de agente e os baldes que não encolhem com tamanhos padrãoreferences/patterns.md— tempos de referência para tarefas comuns Umbraco / Razor / Vue / back-officereferences/platform-risks.md— comportamentos do CMS que custam rodadas extras de deploy-verificaçãoreferences/honesty-rules.md— regras obrigatórias e limites de escalonamentoreferences/output-format.md— a decomposição interna e a resposta para o clientereferences/calibration-log.md— como registrar estimativa vs. real para que os números melhoremreferences/review-checklist.md— Modo Revisão: verificando uma estimativa que já existe
Fluxo de Trabalho
Passo 0 — Encontre a especificação e o plano, e decida a base da estimativa
Antes de ler o código, procure documentos de planejamento sobre esta tarefa. Procure em:
- o repositório:
spec.md,SPEC.md,docs/spec/**,docs/specs/**,docs/plans/**(arquivos nomeados*-plan.md,*-design.md,*-analysis.md,*-spec*.md),docs/handover/**,docs/adr/**, e qualquer arquivo cujo nome contenha a chave do ticket ou o slug da funcionalidade; - o ticket: sua descrição, anexos e comentários, e qualquer página de especificação vinculada a ele (ex.: Confluence);
- estimativas anteriores para o mesmo ticket. Uma estimativa anterior, uma opção rejeitada ou uma pergunta em aberto altera o número.
Em seguida, escolha uma base para a estimativa e diga qual é no topo da saída:
A. Estimativa baseada em plano. Existe uma especificação e/ou um plano de funcionalidade.
- Leia cada documento encontrado completamente, não apenas os cabeçalhos: requisitos, critérios de aceitação, fases, listas de arquivos, perguntas em aberto, revisões/desvios e decisões de revisão.
- Estime por fase do plano, usando as próprias listas de arquivos e passos do plano como o esqueleto de subtarefas (Passo 4).
- Mapeie cada requisito da especificação / critério de aceitação para uma linha da estimativa. Liste qualquer requisito que nenhuma fase cubra, e qualquer fase que nenhum requisito peça.
- Carregue as perguntas em aberto do plano para a lista de perguntas da saída, cada uma com sua resposta padrão.
- Verifique se o plano está desatualizado: compare o que ele nomeia (arquivos, aliases, tipos de documento) com o código atual. Linhas que não correspondem mais são uma suposição a sinalizar, não algo a precificar silenciosamente.
- Faixas podem ser mais estreitas e a confiança maior (veja
references/honesty-rules.md).
B. Estimativa rápida (escopo visível). Nenhuma especificação e nenhum plano foram encontrados.
- Diga isso claramente no topo: "Nenhuma especificação ou plano de funcionalidade encontrado — esta é uma estimativa rápida do escopo visível." Liste onde você procurou.
- Estime apenas pelo texto do ticket e pelo código. As faixas são mais amplas e a confiança é limitada a Médio.
- Liste o que uma especificação ou plano teria que resolver para o número se firmar (as perguntas, as áreas afetadas que você não conseguiu determinar).
- Ofereça o próximo passo: escreva um plano para o ticket, depois re-estime a partir dele (base A). Diga em qual direção você espera que o número baseado no plano se mova, e por quê.
Se existir apenas um documento parcial (ex.: uma especificação mas nenhum plano, ou um plano para uma fase diferente), use a base A para o que ele cobre e a base B para o resto, e rotule cada linha.
Além disso: se um log de calibração existir (references/calibration-log.md explica onde), leia as últimas entradas para
tipos de trabalho semelhantes.
Passo 1 — Detecte a stack
Use suas ferramentas de busca de arquivos (não comandos específicos de shell — isso geralmente roda no Windows). Registre:
| Procure por | Informa |
|---|---|
*.csproj → versão do PackageReference Umbraco.Cms, TargetFramework | Major do Umbraco (10/13 = back-office AngularJS; 14+ = Bellissima Lit/TS) e versão .NET |
ModelsMode em appsettings*.json, pasta de modelos gerados | Modelos com tipagem forte vs. IPublishedContent dinâmico |
Pasta uSync/ + configurações uSync (ExportOnSave, ImportOnFirstBoot, handlers desabilitados) | Se mudanças de esquema precisam de import manual por ambiente |
App_Plugins/*/package.manifest vs umbraco-package.json + um projeto Vite Client/ | Tecnologia de extensão back-office |
Arquivos package.json: vue, nuxt, react, lit, jquery; localização do build de saída | Tipo de front-end e se sua saída de build é commitada |
Config do compilador SCSS, CSS compilado commitado, pastas rtl/ltr | Pipeline de estilo e duplicação RTL |
Idiomas em uSync Languages/, dir="rtl" em layouts | Número de culturas e custo de verificação RTL |
| Projetos de teste (xUnit/NUnit/Playwright), se Razor é compilado no build | O que uma execução de teste verde realmente prova |
Composers/, Hangfire, configuração de índice Examine, migrações, tabelas DB customizadas | Tarefas em segundo plano, busca, dados customizados |
| Arquivos CI/deploy, dicas de hospedagem (App Service, IIS, Docker) | Quantos ambientes e se deploys são manuais |
Se você não conseguir ler o código-fonte, diga isso na saída e alargue cada faixa em 2–3× (veja regras de honestidade).
Passo 2 — Leia o código mais próximo da tarefa
Encontre artefatos anteriores: o tipo de documento, partial, controller, ilha Vue, elemento back-office ou import mais próximo existente que faça algo semelhante. Leia 2–4 desses arquivos. Verifique cada afirmação factual que você fará na estimativa contra o código ou o esquema uSync — ex.: antes de escrever "esse campo não existe", pesquise as configurações de tipo de conteúdo. Uma afirmação errada custa uma rodada completa de ida e volta com o cliente.
Passo 3 — Classifique
| Dimensão | Opções |
|---|---|
| Tipo de trabalho | veja a tabela em references/calibration.md (tipo de documento/esquema, página Razor vs design, ilha Vue, extensão back-office, API/controller, busca, tarefa em segundo plano, import de dados do cliente, integração de terceiros, atualização, investigação, bug) |
| Artefato anterior | Alto / Médio / Baixo |
| Clareza da especificação | Clara / Parcial / Vaga |
| Escreve dados do CMS? | O código cria, salva ou publica conteúdo, blocos, mídia ou valores por cultura? |
| Front-end contra um design? | Trabalho Figma verificado pixel a pixel aciona uma onda de QA |
| Culturas × pontos de quebra | ex.: 3 idiomas (um RTL) × desktop/mobile |
| Ambientes que deve atingir | Local, Dev, Stage, Prod — e quais passos são manuais em cada um |
| Parte externa | Conteúdo do cliente, API de fornecedor, script de terceiros, pipeline de outra equipe |
Passo 4 — Decomponha e dimensione a codificação na velocidade do agente
Com um plano (base A), as fases do plano são os grupos de nível superior e seus passos/listas de arquivos são as subtarefas; não invente uma decomposição diferente. Sem um plano (base B), construa a decomposição você mesmo.
Divida o trabalho em subtarefas de 15 min – 2 h de trabalho do agente cada. Dimensione-as a partir
de references/patterns.md e das taxas em references/calibration.md. Em seguida, adicione tempo de revisão
(padrão 30–50% da codificação do agente para código de produção; menos para testes e estilos).
Nunca dimensione codificação em dias de desenvolvedor humano e depois "adicione contingência". Esse é o erro de ~4×.
Se uma referência que você está usando estiver em tempo humano, converta-a com os multiplicadores em calibration.md.
Passo 5 — Adicione os baldes que não encolhem
De references/calibration.md → "Baldes que não encolhem". Adicione cada um que se aplica, como sua própria linha,
com seu próprio intervalo:
- Custo de envio por ambiente (build, deploy, import uSync, edições de dicionário/conteúdo, re-salvar, verificação rápida)
- Rodadas de verificação real do CMS quando o código escreve dados do CMS ou depende de comportamento em tempo de execução (
platform-risks.md) - Execução local do proprietário + entrega para QA
- Onda de QA para trabalho front-end contra um design (triagem, correções, respostas "não é bug")
- Matriz de verificação multilíngue / RTL
- Rodadas de esclarecimento que você espera antes que o escopo seja fixado
- Cauda de atualização para atualizações de versão (execução de regressão, runbook, ensaio, correções pós-deploy)
- Custo de processo se a equipe escreve planos, revisões, documentos de verificação e handovers por ticket
Aplique o piso de ticket pequeno: qualquer ticket que precise atingir um ambiente compartilhado custa pelo menos o custo de envio, mesmo que o código seja uma linha.
Passo 6 — Tempo de calendário
Liste do que o tempo decorrido depende: perguntas em aberto para o cliente, conteúdo que o cliente deve fornecer, respostas de fornecedores, janelas de deploy, disponibilidade de QA. Dê o tempo de calendário separadamente (ex.: "2–3 h de esforço; realisticamente 1–2 semanas decorridas enquanto Q1–Q4 são respondidas").
Passo 7 — Autoverificação
- Os intervalos das subtarefas somam o total.
- Nenhuma subtarefa individual tem mais de 2 h de trabalho do agente sem ser dividida.
- Cada balde que não encolhe foi considerado; os que foram pulados foram pulados de propósito (diga por quê).
- Nenhum dia de desenvolvedor humano em lugar nenhum; uma unidade (horas) em todo lugar.
- Toda afirmação "não existe" / "já é suportado" foi verificada no código ou esquema.
- A confiança é consistente com os modificadores em
honesty-rules.md. - Total > 40 h → divida em marcos e estime cada um.
- A base (baseada em plano / rápida / mista) é declarada no topo. Com um plano, cada requisito da especificação mapeia para uma linha e cada fase do plano é precificada. Sem um, a saída diz isso e lista onde você procurou.
Passo 8 — Saída
Use references/output-format.md: uma decomposição interna para o desenvolvedor, e uma resposta para o cliente
(tabela de faixas de horas, faixa total, opções precificadas separadamente, suposições, perguntas numeradas cada uma com a
resposta padrão que a estimativa assume, riscos, nota de calendário).
Em seguida, registre a estimativa no log de calibração (references/calibration-log.md): automaticamente se as
instruções do usuário nomearem um local de log, caso contrário, ofereça-se para iniciar um. Registre o que a skill produziu e,
quando conhecido, o que foi realmente enviado ao cliente.
Modos
Single — o fluxo de trabalho acima.
Batch — para uma especificação, épico ou backlog: execute os Passos 0–2 uma vez, depois os Passos 3–7 por item (2–5 subtarefas cada). Saída: uma tabela (item, camada, faixa de esforço, tamanho, confiança, principal risco), suposições compartilhadas, dependências entre itens, uma ordem sugerida e os baldes que não encolhem uma vez para todo o lote onde eles são genuinamente compartilhados (um deploy + um import uSync pode carregar vários itens; uma onda de QA por página, não por item).
Re-estimate — depois que o cliente responder perguntas ou o escopo mudar: mostre apenas o delta (linhas removidas, linhas adicionadas, total revisado, qual pergunta causou isso). Os clientes respondem às perguntas e depois pedem para o número ser confirmado — torne o delta fácil de aprovar.
Review — quando uma estimativa já existe (em uma especificação, um plano, um comentário de ticket) e você é solicitado a verificá-la:
não re-estime do zero. Siga references/review-checklist.md:
- colete cada versão: o documento commitado, a cópia para o cliente, o código que ela cita;
- verifique a aritmética, depois se a base e a confiança correspondem às regras de honestidade;
- verifique a estrutura (parcela de revisão, baldes, cobertura de requisitos, opções, padrões);
- re-verifique os fatos principais no código e esquema, e procure pelos riscos de plataforma que ela perde.
Separe correções internas de mudanças que o cliente deve ver. Recomende republicar um número apenas se ele mudar.
Calibrate — quando solicitado a avaliar como as estimativas foram ("quão precisos fomos", "calibrar a skill", "retrospectiva sobre as estimativas"), ou no final de um período de teste:
- Leia todo o log de calibração. Para cada entrada fechada, preencha ou verifique o real e sua fonte (tempo próprio, registro de horas do ticket — observe se é um total da equipe —, dias ativos no git); pergunte por reais faltantes em vez de adivinhar.
- Calcule as proporções por tipo de trabalho e por balde, para o número enviado ao cliente e para o número da skill.
- Encontre os erros sistemáticos: quais tipos de trabalho, quais baldes (onda de QA, custo de envio, rodadas de verificação, esclarecimento), quais regras (confiança, piso de ticket pequeno) estavam errados, e onde as correções manuais estavam certas.
- Proponha edições concretas para
references/calibration.md,patterns.md,platform-risks.mdou as regras, cada uma vinculada às linhas do log que a justificam. Abaixo de ~3 pontos de dados para um tipo: anote, não mude. - Aplique apenas as edições que o usuário aprovar, adicione uma entrada de changelog datada ao README da skill e adicione uma linha ao log dizendo qual calibração as próximas estimativas usarão.
Investigation — para tickets "descubra por que…": defina um timebox (tipicamente 0,25–1 h), declare o que o timebox compra, e liste os resultados prováveis, incluindo "não é um bug", "já embutido" e "bug do CMS upstream — aguarde a versão X". Esses resultados são comuns e baratos; não precifique uma investigação como se uma correção fosse certa.