Requisitos funcionais e não funcionais, planejando um blog do zero

Por que este blog existe

A ideia de ter um blog já é antiga, mas sempre travava na mesma pergunta, que era qual conteúdo eu traria e de que forma. O que eu sempre gostei de acompanhar foi gente escrevendo sobre uma experiência de verdade, uma ferramenta que usou no trabalho, um problema bem específico que precisou resolver, e não o tutorial genérico que a documentação oficial já cobre melhor. Decidi então que era esse o formato: posts longos, sem me preocupar com tempo de leitura nem com público alvo definido no papel, porque se o assunto pede espaço, o texto ocupa o espaço.

O que me convenceu de vez foi lembrar de como eu aprendo. Atualmente eu uso IA para agilizar demanda grande, planejando prompt, escrevendo spec e montando skill antes de deixar a execução rodar, mas eu continuo desenvolvendo e não delego tudo, principalmente quando o assunto é novo para mim. Não é desconfiança da ferramenta, é o jeito que eu aprendo: passando pelo processo, testando alternativa e lendo o que outras pessoas escreveram sobre o mesmo problema, fica muito mais fácil avaliar o que voltou, comparar com o que já deu errado antes e corrigir o rumo antes de virar problema.

E esse percurso quase nunca aparece escrito, porque o que se publica é o resultado pronto, já num ambiente controlado, com tudo funcionando. Escrever sobre ele é o que eu quis fazer aqui, e o primeiro assunto é o próprio blog. Menos sobre como eu construí, mais sobre como eu decidi.

O que eu chamo de sucesso aqui

Antes dos requisitos vem o objetivo, e o meu não começa em número.

O primeiro motivo é voltar a cuidar do portfólio, com uma ideia que saísse do papel em pouco tempo e que fosse publicada de verdade, mesmo sendo simples. Projeto parado em pasta local não conta, e projeto grande demais não sai. Um blog cabe nas duas restrições: é pequeno o suficiente para terminar e público o suficiente para valer como portfólio.

A partir disso, uma direção de ritmo: pelo menos três posts por mês. Direção é diferente de cota. Se num mês eu só tiver dois assuntos que valem a pena, publico dois, porque encher a listagem com texto que não agrega derruba o motivo do blog existir. A meta serve para eu não parar, não para eu produzir volume.

Sobre prazo, aliás: mesmo sem ninguém cobrando, definir data ajuda, porque simula o ambiente de trabalho e tira da procrastinação, já que passa a existir entrega marcada. Projeto pessoal sem data corre o risco de ficar em andamento para sempre.

A concepção, antes de qualquer decisão técnica

A prática de organizar isso veio de exercícios de produto que ando fazendo, que começam sempre por entender o que o produto precisa ser antes de escolher com o que ele vai ser feito. A primeira coisa que eu escrevi não foi código nem tela, foi uma lista do que eu queria ver funcionando:

• uma home explicando a proposta do projeto com detalhe suficiente para alguém entender por que ele existe
• as três postagens mais recentes na própria home
• uma seção com as ferramentas que eu comento nos posts
• uma listagem de posts separada da home
• o tempo de leitura em cada post

Isso ainda é concepção e não requisito, porque era a fase em que eu estava descobrindo o que o produto é. Nenhum dos cinco itens menciona framework, banco, hospedagem ou CMS.

Funcional e não funcional, na prática

Requisito funcional é o que o sistema deve fazer, o comportamento que dá para observar de fora. Requisito não funcional é a característica de como ele faz aquilo.

Um carro deixa a diferença bem visível.

Requisitos funcionais, o que o carro deve fazer:

1. O carro deve desacelerar até a parada total quando o motorista pisa no pedal do freio.
2. O carro deve sinalizar a conversão para quem está atrás.

Requisitos não funcionais, como ele deve fazer:

1. A frenagem de 100 km/h até a parada total deve acontecer em menos de 40 metros.
2. O consumo em ciclo urbano deve ficar acima de 10 km por litro.

Repare que o assunto do primeiro item é o mesmo nas duas listas, freio, e o que muda é o nível da exigência. Um carro sem freio falha no requisito funcional. Um carro que freia em 90 metros atende ao funcional e falha no não funcional, e é esse segundo tipo de falha que costuma passar batido no planejamento, porque ninguém esquece de pedir freio e quase todo mundo esquece de dizer em quantos metros.

Requisito não é solução

Tem uma segunda separação que confunde mais que funcional e não funcional, e ela aparece direto em documento de projeto.

"O conteúdo deve ser escrito por interface, sem editar arquivo à mão" é requisito. Descreve comportamento e não diz com o que fazer, e existem muitas ferramentas que atendem.

"Usar Keystatic" é solução. É uma das opções que atende aquele requisito.

O teste rápido é ver se a frase nomeia um produto. Se nomeia, provavelmente é solução vestida de requisito, e o problema não é purismo: requisito com produto dentro encerra a comparação antes de ela começar, porque não sobra critério para julgar o resto. Quem revisa depois vai discutir a ferramenta, e não a necessidade.

E o disfarce pode ser mais sutil que nomear, como fica claro na minha primeira lista.

Os primeiros requisitos

Com a concepção na mão, escrevi a primeira lista de requisitos. Ficou curta, porque o projeto é pequeno.

Funcionais:

1. O blog deve ter uma página inicial.
2. O blog deve ter uma página com a listagem dos posts.
3. A listagem deve ter paginação, com limite de 10 posts por página.
4. A página inicial deve apresentar a proposta do projeto e a abordagem dos posts.
5. Cada post deve exibir o tempo de leitura.

Não funcionais:

1. Deve ser usada uma ferramenta de conteúdo com plano gratuito amplo, difícil de estourar.
2. O conteúdo deve ser escrito por interface, sem editar arquivo à mão.

Duas observações sobre essa lista, e as duas eu fiz depois.

A primeira é o caso da seção anterior, na versão sutil. "Plano gratuito amplo, difícil de estourar" não nomeia produto nenhum, e descreve o Prismic quase palavra por palavra, que era a ferramenta com a qual eu já trabalhava. Não é solução escrita como requisito, é pior: é a solução escondida dentro do critério. Em time é o tipo de linha que passa por qualquer revisão, porque parece técnica e parece neutra.

A segunda é de classificação. "O conteúdo deve ser escrito por interface, sem editar arquivo à mão" não é requisito não funcional, é funcional. É comportamento, coisa que o sistema faz e que dá para observar de fora, exatamente como o freio do carro. Eu classifiquei errado, e ele terminou no lugar certo, como item 10 da lista final.

O reencontro com o Prismic

Com os requisitos escritos, a ferramenta parecia resolvida. O Prismic atendia os dois não funcionais, eu já tinha trabalhado com ele, e até esse ponto eu não estava procurando alternativa nenhuma. Abri a conta para começar.

O que encontrei foi uma ferramenta maior do que a que eu lembrava. Slices, mais camada de configuração, mais conceito para entender antes de escrever a primeira linha de texto. Nada disso é defeito, é evolução de produto, e faz todo sentido para quem monta página de marketing com um time de conteúdo. Para um blog de texto e imagem, mantido por uma pessoa, era ferramenta demais para o tamanho do problema.

E foi aí que a pergunta apareceu, não antes. Se eu ia precisar reaprender a ferramenta que eu já conhecia, a familiaridade deixava de ser vantagem. Se o esforço seria parecido de qualquer jeito, valia olhar o que existe hoje, porque a última vez que eu comparei CMS foi anos atrás.

A pesquisa começou nesse ponto, e começou com os requisitos na mão, não com uma lista de ferramentas para escolher. É a diferença entre procurar o que resolve o seu caso e procurar o que é mais popular.

Foi também aqui que eu voltei para uma sequência que eu uso quando o assunto é novo:

• estudar
• planejar
• experimentar
• executar

Experimentar é provar a ferramenta, não o código: instalar, criar um post de mentira, ver como é o dia a dia dela. Teste de software vem depois, dentro da execução. Essa sequência é hábito de trabalho e não substitui a sequência do projeto, que aparece mais adiante.

Isso é regra universal? Não, depende de prazo e de contexto. Mas quando eu estou aprendendo algo novo e tenho tempo, ela paga.

Onde o conteúdo vai morar

As ferramentas que eu já conhecia

Estas vieram de projetos e testes ao longo dos anos:

• Prismic. Plano gratuito muito bom, difícil de estourar num blog. O que empurra para o pago ali costuma ser quantidade de usuário e de idioma, não volume de acesso, então para um autor sozinho ele seguiria gratuito por muito tempo. O problema no meu caso não era preço, era tamanho.
• Hygraph. Ferramenta excelente, e a operação de uma pessoa só encaixava bem. O limite do plano gratuito é contado por operação de API e por volume de registro, e leitura passa por CDN, então o que morde primeiro é a quantidade de conteúdo e não o acesso.
• Sanity. O plano gratuito mais folgado entre os que eu testei. O custo dele é de aprendizado, principalmente pela linguagem de consulta própria, e não de crescimento: não é ferramenta que vira paga porque o blog cresceu, é ferramenta que cobra tempo de estudo na entrada.

As que apareceram na pesquisa

• Contentful. É o mais voltado para time entre os que eu olhei, com papel de usuário e fluxo de aprovação. Para o meu caso isso é peso e não vantagem, porque não existe segunda pessoa nesse processo.
• Storyblok. Vi pela primeira vez agora e gostei da proposta, com editor visual, recursos de IA e suporte a idioma. Cai no mesmo ponto do Prismic: para um blog de texto e imagem, é mais ferramenta do que o problema pede.
• Strapi, Directus e Payload. Os três têm oferta gerenciada hoje, e o Payload roda dentro do próprio projeto Next.js. O ponto é que o caminho gratuito deles é o auto-hospedado, e nesse caminho a hospedagem e o banco passam a ser meus, que é custo e manutenção que eu não quero neste projeto.

Nenhuma dessas ferramentas é ruim, e apontar um ponto contra não apaga o resto. Elas só não batiam com os critérios que eu levei para a pesquisa:

• gratuito de forma definitiva, e não gratuito até um limite
• proporcional ao problema, sem recurso que eu não vou usar
• simples de operar por uma pessoa
• custo de aprendizado baixo, porque o que eu quero fazer é pequeno

O que eu quase fiz, e o que eu encontrei

Uma das opções na mesa era a mais bruta possível: um projeto Next.js, posts em Markdown, e eu adicionando arquivo na mão com git add. Atende quase tudo, e falha justamente no requisito de escrever por interface, que é a diferença entre publicar um post e fazer um deploy.

Foi aí que encontrei o Keystatic, e a proposta dele batia com o que eu tinha escrito: interface gráfica para escrever, nada a pagar no modo que eu preciso, e os arquivos gerados são exatamente os que eu ia digitar à mão. O git add continua acontecendo, só que como commit no repositório, disparado pela interface.

Fiquei curioso para saber se existia mais coisa nesse formato, e existe bastante:

• Outstatic
• TinaCMS
• Decap
• Sveltia CMS

Por que Keystatic

Testei e continuei com ele, pelos seguintes motivos:

• schema em TypeScript tipado, então o modelo do conteúdo é código versionado e não configuração num painel de terceiro
• nenhuma chamada a serviço externo para renderizar o conteúdo público
• a interface mais prática entre as que testei, e sem recurso sobrando para o meu caso
• o modo que eu uso, gravando direto no repositório, não tem cobrança. Existe um Keystatic Cloud como produto separado, e ele é opcional para mim
• curva de aprendizado praticamente nula para o que eu preciso fazer

E um ganho que eu não tinha pedido em requisito nenhum: como o conteúdo é arquivo dentro do meu repositório, ele fica versionado junto com o código, vai comigo se eu trocar de hospedagem, e não depende de exportação se a ferramenta fechar amanhã. Não estava na lista, apareceu junto, e hoje é um dos motivos de eu não querer voltar atrás.

O preço da escolha, que eu prefiro dizer do que esconder: como o conteúdo mora no repositório, cada post publicado dispara um build; imagem entra no histórico do git e engorda o repositório com o tempo; e não existe prévia do site dentro do editor, então para ver o post renderizado antes de publicar é preciso abrir o build da branch. Trabalhando sozinho isso não me atrapalha, e num time exigiria combinado.

Vale registrar o risco que passou perto. Se eu não tivesse aberto o Prismic para usar, eu teria ido de familiaridade e provavelmente encontraria o Keystatic no meio da construção, quando trocar já custa retrabalho. O que me salvou não foi critério, foi ter voltado a mexer na ferramenta antes de começar.

Por que Next.js, e a decisão que eu não revi

Se este post defende escolher depois do requisito, ele precisa admitir onde eu não fiz isso, e o lugar é o framework.

O Next.js entrou por familiaridade, do mesmo jeito que o Prismic quase entrou. Essa parte eu não submeti a pesquisa nenhuma, e existem boas alternativas para blog que eu simplesmente não comparei.

O que sustenta a decisão é que ela bate com os requisitos quando conferida depois:

• página estática gerada no build, com exceção pontual resolvida por requisição, é o modelo padrão do App Router
• conteúdo lido do sistema de arquivos direto no componente de servidor, sem camada de API no meio
• o Keystatic mantém integração oficial para Next, então o admin monta dentro do próprio projeto em vez de virar um serviço separado para manter
• a hospedagem gratuita que eu uso trata esse tipo de projeto sem configuração extra

Isso é conferência, não escolha. Se algum desses pontos não tivesse batido, o custo seria refazer a base com conteúdo já dentro, que é o pior momento possível para trocar. Escolha por hábito às vezes acerta, e continua sendo escolha por hábito: o que muda não é o método, é o tamanho do prejuízo quando ela erra.

E já que apareceu: o blog está hospedado na Vercel, no plano gratuito. Como cheguei lá, com domínio, DNS e certificado, é assunto de outro post, porque não é decisão de planejamento e sim de operação.

A sequência que segui neste projeto

Antes da sequência, uma correção sobre a minha própria ordem: ela não foi tão limpa quanto a lista abaixo sugere. Eu fechei a lista final de requisitos depois de escolher a ferramenta, porque foi mexendo nela que apareceram exigências que eu não tinha visto. A sequência serve de guia, não de ata.

Dito isso, não existe ordem única, e ela muda conforme o tamanho do projeto, o time e o prazo. A que eu segui aqui veio dos estudos de system design, e tem uma característica que eu quis manter: a arquitetura fica por último.

1. Requisitos
2. Entidades
3. API
4. Arquitetura

Escrito assim parece óbvio, e ainda assim é o passo que costuma ser abreviado, porque escolher tecnologia dá sensação de progresso imediato, enquanto requisito só mostra o valor depois, quando evita o retrabalho que ninguém viu chegando.

Neste blog as entidades saíram curtas, apenas post e ferramenta, com tag sendo texto livre dentro do post. E o passo de API praticamente não existiu, porque não existe API aqui: o conteúdo é arquivo lido pelo próprio site, sem camada no meio. O equivalente foi definir o schema do conteúdo, ou seja, quais campos um post tem e o que é obrigatório, mais as rotas que o site expõe. Quando um passo não se aplica ao seu caso, você troca ele pelo que faz o papel dele naquele projeto, em vez de simplesmente pular.

Vale ver o que essa ordem evitou, porque é o ganho concreto e não teórico. Se eu tivesse começado pela arquitetura, o desenho óbvio para post e ferramenta seria tabela em banco com uma API na frente, que é o formato que a gente monta no automático. Aí eu teria banco para manter, migração para rodar e mais um serviço para pagar ou hospedar, tudo para servir conteúdo que só muda quando eu publico. Não foi disciplina que evitou isso: quando a arquitetura chegou na fila, os requisitos já diziam que o conteúdo era arquivo e que nada externo podia ser obrigatório para renderizar página. A decisão veio pronta.

Requisitos funcionais do blog

Esta é a lista fechada, depois de reescrever a primeira. Ela é longa e é específica deste blog, então deixei recolhida: abra se quiser o contexto completo.

Os itens 10 e 11 parecem detalhe de conforto e foram os mais determinantes de todos, porque é a exigência de interface gráfica que define qual categoria de ferramenta pode entrar, tanto para post quanto para ferramenta.

Sobre prioridade, sendo honesto: eu não cortei nada, construí os dezoito antes de publicar o primeiro post. Se houvesse prazo, o mínimo seriam os itens 1, 4, 6, 10, 16 e 18, ou seja, home, listagem, tempo de leitura, escrita por interface, rascunho fora do ar e preview de link correto. O resto é o que transforma isso em blog, em vez de página com texto dentro.

E uma ressalva sobre a lista: eu conferi os dezoito na mão, rota por rota, porque o projeto ainda não tem teste automatizado. É dívida, e eu sei o tamanho dela, porque cada mudança futura me obriga a repetir a conferência inteira em vez de rodar um comando.

Requisitos não funcionais do blog

Aqui eu tentei não repetir o erro do exemplo do carro, então cada item tem como ser verificado.

O item 4 merece explicação, porque número sem origem é chute, e chute em requisito não funcional é o mesmo erro do freio sem distância.

Ele não mede a escrita. Eu escrevo direto no editor e salvo como rascunho quantas vezes eu quiser, e isso pode levar dias sem violar nada. O que os três minutos medem é o trecho mecânico depois que o texto está pronto: abrir a pull request, mesclar e esperar o build. O build sozinho não passa de um minuto, o resto é clique. Então três minutos não é meta otimista, é o tamanho real do caminho.

E é por isso que o número serve de alarme. Se um dia publicar passar disso, não foi o texto que ficou mais longo, foi um passo manual que entrou no meio sem eu perceber.

O que ficou de fora, de propósito

Requisito só vira decisão quando alguma coisa é recusada, então vale registrar o que eu deixei fora desta primeira versão:

• Comentário no post. Traz moderação, spam e dado de terceiro para dentro de um projeto que eu quero manter simples e sem cadastro.
• Curtida. Precisa guardar estado por visitante, o que puxa banco, e banco é o oposto do que os não funcionais pedem.
• Contador de acesso exibido no post. Eu acompanho acesso pelo painel da hospedagem, o que é diferente de mostrar número na página, porque mostrar exigiria escrita a cada visita.
• Medição de quem leu até o fim. Seria útil, e custa complexidade, então fica para quando existir volume que justifique.

Nada disso está descartado para sempre. Está fora da primeira versão, o que é diferente.

O que mudou entre a primeira lista e a última

Três mudanças, além da classificação errada que eu já contei, e nenhuma delas estava prevista quando eu comecei.

"Plano gratuito amplo" virou "gratuito sem limite que force migração para plano pago". Parece ajuste de palavra e é troca de critério. A primeira versão aceita qualquer ferramenta com limite generoso, o que inclui praticamente todo CMS de mercado. A segunda derruba as quatro que eu já conhecia, algumas delas por mais de um motivo, e abre a porta para uma categoria de ferramenta que eu ainda não conhecia quando escrevi a lista.

A ordem das ferramentas virou requisito. A concepção pedia "uma seção com as ferramentas", e ordem nenhuma. Quando a seção ficou pronta, a ordem que saiu não dizia nada sobre o blog, então ela passou a ser exigência: primeiro as ferramentas que sustentam o que eu escrevo aqui, depois as demais.

O estado vazio da listagem não existia em requisito nenhum. Quando a listagem não tinha nada para mostrar, ela dizia a mesma coisa em duas situações completamente diferentes: não existe post publicado, e o filtro não encontrou resultado. Quem chega no site precisa saber qual dos dois é, porque na primeira não tem o que fazer e na segunda basta limpar o filtro. Isso só apareceu quando eu vi a tela, e virou requisito depois.

Essa última é o tipo de coisa que eu queria registrar aqui. Ela não sai de planejamento nenhum, ela sai de usar.

Quando eu pesquiso e quando eu delego

Eu poderia ter aberto o Claude, usando Opus para o raciocínio mais longo, e pedido a comparação pronta com base nos meus critérios. Teria funcionado bem, e provavelmente com boa parte das mesmas ferramentas na mesa.

Escolhi pesquisar na mão por um motivo que só ficou claro no reencontro com o Prismic: a minha familiaridade estava velha. Eu conhecia as ferramentas de anos atrás, e uma delas tinha mudado o suficiente para eu não reconhecer. O assunto parecia conhecido e era novo, e essa é a situação em que a pesquisa paga mais, porque repertório desatualizado dá a falsa sensação de que a resposta já está na mão.

A escolha não é entre pesquisar e delegar, é entre delegar com repertório e delegar sem. Quanto mais você conhece o assunto, mais dá para entregar para a IA e mais longe dá para levar, porque fica claro o que pedir, fica rápido ler o que voltou e dá para perceber quando a resposta está boa no papel e ruim para o seu caso. E esse repertório se constrói devagar, testando ferramenta, quebrando projeto e lendo o que outras pessoas já resolveram. Por isso, quando o assunto é novo para mim, ou quando o que eu sei sobre ele está velho, eu pesquiso. Quando é conhecido de verdade, eu delego e vou muito mais rápido do que iria sozinho.

Cada pessoa tem seu contexto. Pode ser que comparar ferramenta não te interesse, ou que o objetivo do momento seja entregar e faturar, e não tem nada de errado nisso, porque o projeto entregue é o que vale.

O cuidado é com o que você aceita sem saber que aceitou. Imagine a mesma decisão numa empresa: entra uma ferramenta com limite gratuito por operação, o produto cresce, o limite estoura numa terça de manhã e a publicação de conteúdo para. Nesse ponto não existe mais escolha, existe fatura, negociada com o problema em produção e sem tempo de comparar alternativa. A decisão barata do começo virou a decisão caríssima do meio, e o que faltou não foi a ferramenta certa, foi alguém que soubesse qual pergunta fazer antes de assinar.

O mesmo cuidado, com preço diferente

Em algum momento você vai ser a pessoa do time que decide qual ferramenta entra, e nessa hora o que sustenta a decisão é repertório, porque a sua escolha vira a segurança de todo mundo. Se ela for ruim para o momento e ninguém questionar, o time vai junto, e meses depois alguém pergunta por que não foi feito de outro jeito. Essa resposta precisa existir, com o critério que você usou registrado em algum lugar.

Se eu tenho esse cuidado num blog, onde a pior consequência é eu não conseguir publicar um texto, num sistema bancário, num painel de operação ou num controle de acesso o método é o mesmo e só o preço do erro muda.

Então, tente sempre entender o momento em que você está e o que precisa alcançar. A partir disso, ajuste o caminho. Um prazo curto pede velocidade, um assunto novo pede pesquisa e um time maior pede critérios bem definidos. O que permanece em qualquer cenário é saber explicar o porquê de cada escolha.

Foi assim neste projeto. A lista de dezoito requisitos deixou de ser apenas uma lista e virou um site. O site está no ar e, como parte desse processo, este é o primeiro texto publicado nele.