Antes da primeira linha de código: como usar o Project Readiness Framework
Antes da primeira linha de código
Quase todo projeto encrencado que cruzou meu caminho tinha a mesma certidão de nascimento: alguém abriu o editor antes de o time combinar o que ia ser construído. Requisito na cabeça de uma pessoa só. Decisão técnica sem dono. E “pronto”? Pro negócio queria dizer uma coisa, pra quem codava, outra bem diferente. Meses na frente chegava a conta. Sempre na mesma moeda: retrabalho, mais dedo apontado de cá pra lá.
O Project Readiness Framework, na Seção 1 batizada de “Antes de Começar”, nasceu pra matar isso no berço. Código não é o assunto dele. Ou melhor: código é a consequência, e o assunto é tudo o que precisa estar escrito, aprovado e versionado antes da primeira linha, do levantamento de negócio até o gate que libera (ou trava) o desenvolvimento. Daqui pra baixo, o guia de uso. Te levo etapa por etapa, mostro o que cada documento cobra e aponto onde a coisa costuma estourar.
As três ideias que seguram o resto
Oito princípios numerados, de P1 a P8. Só que o prédio inteiro se apoia em três, e o resto vira detalhe a serviço deles.
Primeira ideia: o gate objetivo (P5). Cada etapa tem critério de entrada, o DoR (Definition of Ready), e de saída, o DoD (Definition of Done). Os dois verificáveis. “Tá bom assim” não carimba nada. Quem carimba é a lista batida item a item.
Segunda: a segregação de funções (P1). Quem produz um artefato jamais é quem o aprova. Parece firula burocrática. Não é. Serve pra cortar o autoengano de quem revisa o próprio trabalho e enxerga só o que quer enxergar.
Terceira, e a mais bonita na minha leitura: o handoff autossuficiente (P2). O que cada etapa entrega tem que bastar pra um time que não escreveu aquilo tocar o passo seguinte sem ligar pra ninguém. O teste é cruel e honesto. Dá pra produzir a próxima fase só com isto na mão? Pois essa régua é que deixa você trocar gente interna, contratada e parceira pelo caminho sem o trabalho desabar no meio.
Os outros cinco orbitam essas três: rastreabilidade ponta a ponta (P3), operabilidade e risco decididos cedo e não no fim (P4), ADR registrado no instante da decisão (P6), SAD tratado como documento vivo (P7) e rigor que escala com a criticidade (P8).
O mapa do fluxo
Sete etapas, de 0 a 6. Cada uma só arranca depois que a anterior passou. Fora uma exceção, e já chego nela. Olha o desenho.
Etapa 0: Discovery / Spike (opcional)
|
| alimenta
v
Etapa 1: BRD ------> ( gate ) --reprova--> volta pro BRD
|
aprova
v
Etapa 2: HLD --------> ( gate ) --reprova--> rework
(C4 L1/L2) |
aprova
+----------------+-----------------+
| |
v v
Etapa 3: LLD/TDD Etapa 5: Bootstrap Tecnico
(C4 L3) (roda em PARALELO, comeca
| logo que o HLD passa)
v |
Etapa 4: SAD (consolida) |
| |
+----------------+-----------------+
v
Etapa 6: Go / No-Go
|
+------------+------------+
| |
falta item tudo OK
v v
[ BLOQUEADO ] [ INICIO DO DESENVOLVIMENTO ]Dois pontos pedem atenção no desenho. Discovery é opcional, e só alimenta o BRD quando existe incerteza de verdade pra resolver. Já o Bootstrap Técnico não espera na fila atrás do LLD e do SAD: passou o HLD, ele roda em paralelo, porque montar repositório e pipeline independe de o design fino estar fechado.
Quem produz, quem aprova
Antes de mergulhar nas etapas, vale fixar o elenco. Quem escreve e quem carimba troca conforme o passo, e a matriz RACI bota tudo às claras. R produz, A aprova, C é consultado, I é informado.
| Etapa | Solicitante | PM | Produtor (Arq./Dev Lead) | Tech Lead Aprovador | Segurança/DPO |
|---|---|---|---|---|---|
| 0. Discovery/Spike | C | C | R | A | C |
| 1. BRD | R/A | A | C | C | C |
| 2. HLD | I | I | R | A | C |
| 3. LLD/TDD | I | I | R | A | C |
| 4. SAD | I | C | R | A | C |
| 5. Bootstrap | I | C | R | A | C |
| 6. Go/No-Go | A | R | C | A | A |
No centro de tudo, o Tech Lead Aprovador, designado pela organização. Autoridade técnica das Etapas 0 a 5, guardião do processo, com um limite sagrado: nunca aprova um artefato que ele mesmo produziu. No BRD a régua se inverte. Ali quem manda é o negócio, então o Solicitante produz e aprova. E o gate final? Decisão de três cabeças. Ninguém solta o desenvolvimento sozinho.
Etapa 0: Discovery / Spike
Opcional, timeboxed, feita pra derrubar incerteza antes de comprometer arquitetura e orçamento. Gera aprendizado, não código de produção. O que sai do spike é descartável por princípio, e isso liberta: dá pra experimentar sem dó.
Quando acionar? Só com motivo concreto na mesa: tecnologia nova que o time não domina (tipo a primeira vez que botei a mão numa fila de mensageria e descobri, no susto, que ordem de entrega não vinha de graça), viabilidade em dúvida, integração externa sem contrato conhecido, risco técnico classificado como Alto lá no levantamento inicial. Faltou tudo isso? Pula direto pro BRD.
O artefato é o Spike / PoC Report. Ele responde a uma pergunta de viabilidade com critério objetivo de sucesso ou fracasso, e anota o timebox (uns 3 a 5 dias), o experimento construído, o resultado (validado, invalidado ou inconclusivo, sempre com evidência) e a recomendação: seguir, pivotar ou abortar. DoD? Pergunta respondida com prova na mesa, e premissas prontas pra alimentar BRD e HLD.
Etapa 1: o BRD
Aqui o projeto de fato começa. O Business Requirements Document escreve preto no branco o problema de negócio, e quem o produz e aprova é o Solicitante, antes de qualquer movimento técnico. Quando quem vai construir começa a opinar sobre o que construir, a régua já saiu do lugar.
Conteúdo denso, e por bom motivo. Contexto e problema, a dor, o porquê agora. Objetivo de negócio mensurável, do tipo “cortar o tempo do processo em X%”. Escopo, com o que fica de fora dito em voz alta. As partes interessadas. Requisitos funcionais codificados (RF-001, RF-002…) e não-funcionais, cada um mensurável (RNF-001…), porque “tem que ser rápido” não é requisito, é desejo. E mais: critérios de aceite, processo as-is e to-be, restrições, premissas, a primeira versão do registro de riscos e a justificativa de negócio assinada.
Custo entra em duas parcelas que muita gente esquece de separar: a construção (desenvolvimento mais infra de projeto) e o recorrente anual, o TCO de manter aquilo de pé, com infra, licença e suporte. Barato de erguer e caro de operar é cilada clássica.
Tem ainda um bloco de definições obrigatórias que decide muita coisa lá na frente:
| Dimensão | Por que ela decide o projeto |
|---|---|
| Criticidade (Baixa/Média/Alta/Crítica) | Define SLA, monitoramento, deploy, nível de testes e o tailoring do processo. |
| Nº de usuários | Dimensiona infra, cache e autoscaling. |
| Multi-idioma | Exige i18n desde a concepção; não dá pra enfiar depois. |
| Dados pessoais (LGPD) | Obriga avaliação de impacto antes do desenvolvimento. |
| Classificação de dados | Define criptografia, controle de acesso e retenção. |
| Compliance | Define controles, trilhas de auditoria e gates aplicáveis ao domínio. |
| Integrações externas | Define dependências, riscos e prazo de homologação com terceiros. |
| Disponibilidade / DR | RTO e RPO ditam backup, redundância e recuperação. |
| Tem UI? | Se sim, exige protótipo aprovado pelo Solicitante antes do LLD. |
| Usa IA? | Se sim, exige avaliação de risco de IA antes do Go/No-Go. |
O DoD do BRD é o teste do handoff puro. O pessoal da Etapa 2 desenha a arquitetura só com esse documento? Não desenha? Então ele ainda não nasceu.
Etapa 2: o HLD
O High-Level Design pega os requisitos de negócio e traduz numa visão técnica de alto nível. Entra com o BRD aprovado e devolve a arquitetura macro: estilo escolhido com justificativa (monolito modular, microsserviços, serverless), stack com o porquê de cada peça, topologia de infra, fluxo de dados principal, integrações e APIs externas, mais as estratégias macro de segurança, escalabilidade, deploy, observabilidade e DR.
Um item desse pacote economiza dinheiro quando vai a sério: a análise build vs buy vs open source dos componentes principais, com critério objetivo (TCO, prazo, aderência, lock-in, maturidade) e a escolha fincada num ADR. Construir o que dava pra comprar é jeito caro de aprender a lição (e essa matrícula eu já paguei mais de uma vez).
É no HLD que o Modelo C4 entra em cena, o padrão de diagramação adotado pelo PRF. Quatro níveis de zoom, cada um respondendo uma pergunta:
/\
/L4\ Code "como e o codigo?" -> opcional
/----\
/ L3 \ Components "o que tem dentro?" -> Etapa 3 (LLD)
/--------\
/ L2 \ Containers "como e construido?" -> Etapa 2 (HLD)
/------------\
/ L1 \ Context "o que e o sistema?" -> Etapa 2 (HLD)
/----------------\| Nível | Mostra | Onde entra |
|---|---|---|
| L1 Context | O sistema, usuários e sistemas externos. | HLD |
| L2 Containers | Apps, APIs, bancos, filas. | HLD |
| L3 Components | Módulos e serviços dentro de cada contêiner. | LLD |
| L4 Code | Classes e interfaces (UML). | Opcional |
No HLD, L1 e L2 são obrigatórios. Pro DoD: estratégias de segurança, deploy, observabilidade e DR definidas no macro, ADRs registrados, riscos técnicos atualizados, reestimativa feita. E o teste de sempre, a Etapa 3 detalha o LLD só com isso na mão.
Etapa 3: o LLD/TDD
Um aviso pra você não tropeçar na sigla. O TDD daqui é Technical Design Document, o documento de design técnico, e não o Test-Driven Development do dia a dia de código. Letras iguais, bichos diferentes.
O Low-Level Design desce ao chão de fábrica: como cada componente vai ser construído. É a referência que o desenvolvedor abre enquanto codifica. Entra com o HLD aprovado, e traz mais uma trava. Tem interface no projeto? Então protótipos e wireframes precisam estar aprovados pelo Solicitante antes daqui.
O detalhamento não economiza. Diagrama de componentes C4 L3. Modelo de dados com ER, schema, índices e constraints. Contratos de API em OpenAPI/Swagger pra todos os endpoints, com payloads, respostas e erros. Fluxos em diagramas de sequência. Tratamento de erros, cache (com TTL e invalidação), rollback e feature flags, migrations e versionamento de schema. Instrumentação de observabilidade por componente, amarrada nos SLIs e SLOs vindos do HLD. Estratégia de testes, com dados e ambientes de teste. Dependências com versão e licença. E os pontos críticos de performance.
Aqui a matriz de rastreabilidade fecha e a reestimativa de esforço é registrada. O DoD não admite meio-termo: um desenvolvedor codifica só com o LLD.
Etapa 4: o SAD
O Solution Architecture Document é o documento vivo do projeto. “Vivo” no sentido literal: ninguém o escreve do zero nesta etapa. Vem sendo mantido ao longo das Etapas 2 a 4 e só é fechado agora, e a aprovação aqui é revisão de consistência e completude, não reescrita. Está reescrevendo o SAD do nada? Sinal de que algum passo anterior foi mal feito.
Doze seções consolidam tudo num registro único: visão geral, requisitos e restrições, decisões arquiteturais, visão arquitetural com C4 L1/L2/L3, infraestrutura e deploy, segurança, observabilidade, estratégia de dados, riscos e mitigações, cronograma, glossário, histórico de revisões. Cada uma puxa de um artefato anterior. Nenhuma pode brigar com a outra.
O coração do SAD são os ADRs, os Architecture Decision Records. Cada decisão arquitetural que pesa vira um ADR no instante em que é tomada, lá da Etapa 2 em diante (princípio P6). Curto e imutável: título, status, contexto, a decisão, as alternativas que ficaram pelo caminho e as consequências, os trade-offs que você topou pagar. Decisão não se apaga. Quando muda, um ADR novo supersede o antigo, e o rastro permanece. Daqui a um ano, quando alguém perguntar “por que cargas d’água escolheram isso?”, a resposta está escrita.
Etapa 5: o Bootstrap Técnico
Esta etapa transforma a arquitetura aprovada num ambiente onde dá pra começar a desenvolver. Ela recolhe os itens de prontidão que antes ficavam órfãos, sem etapa de origem, e por isso só apareciam quando já era tarde demais.
A jogada de cronograma merece repetição: o Bootstrap pode arrancar logo que o HLD (Etapa 2) é aprovado, em paralelo com LLD e SAD. Segurar a criação do repositório esperando o design fino fechar não faz sentido nenhum.
A linha do tempo desenha mais ou menos assim:
tempo ------------------------------------------>
Etapa 2 HLD [====]
Etapa 3 LLD [=======]
Etapa 4 SAD [=========]
Etapa 5 Boot [=============] arranca apos o HLD
|
v
Etapa 6: Go / No-GoA entrega é grande: repositório com README, estrutura de pastas e CODEOWNERS; estratégia de branches conforme o Gitflow da organização; pipeline CI/CD com build, secrets scan, lint e testes; gestão de segredos num cofre dedicado, com a regra inegociável de nenhum segredo no repositório ou na imagem; análise de segurança no pipeline (SAST, SCA e, quando há superfície web exposta, DAST); ambientes dev, staging e prod provisionados ou planejados, com tagging de custo pro FinOps. O DoD confere que o pipeline roda build mais secrets scan mais SAST/SCA, e que segredo nenhum vazou pro código.
Etapa 6: o Go/No-Go
O gate final. Entram as Etapas 1 a 5 concluídas, e PM, Tech Lead Aprovador e Segurança/DPO sentam pra bater um checklist de 26 itens. A maioria é obrigatória. Uns poucos são condicionais, cobrados só quando a dimensão correspondente do BRD se aplica (protótipo de UX quando há interface, avaliação de risco de IA quando há IA). Outros são recomendados, que não travam mas pedem prazo.
A regra é dura de propósito. Todo item obrigatório, mais os condicionais que se aplicam, precisa estar “Concluído”, com evidência. Um pendente bloqueia o início do desenvolvimento. Não existe “a gente resolve depois”. A aprovação final exige a tríade inteira, Solicitante mais Tech Lead Aprovador mais Segurança/DPO, e é ela que vira a chave entre o time parado e o desenvolvimento começando pra valer.
Dois artefatos que atravessam tudo
Fora da fila das etapas, dois documentos não param de crescer.
O Registro de Riscos não nasce pronto. Ele se acumula. Começa no BRD com os riscos de negócio, ganha corpo no HLD e no LLD com os riscos técnicos e de arquitetura, e termina consolidado no SAD. Cada risco carrega ID (RISK-NNN), categoria, probabilidade, impacto, mitigação e um responsável que monitora.
BRD HLD / LLD SAD
(inicia) ----> (enriquece) ----> (consolida)
riscos de riscos tecnicos registro final,
negocio e de arquitetura com mitigacoesJá a Matriz de Rastreabilidade é a cara do princípio P3. Ideia simples e implacável: todo requisito, funcional ou não, tem que ser rastreável até um componente de design e até um caso de teste. Você lê uma linha e segue do RF-001 ao componente que o atende, ao endpoint, ao caso de teste, ao critério de aceite. Requisito que não chega num teste é requisito que ninguém vai verificar. Ela se preenche ao longo do HLD e do LLD, e é conferida no gate final.
As regras que impedem o fluxo de travar
Processo com gate corre um perigo óbvio: virar gargalo, com aprovador sumido e produtor de braços cruzados esperando. Tem amortecedores pra isso, e eles moram dentro do ciclo de cada gate.
produtor submete o artefato
|
v
aprovador revisa (SLA: 3 dias uteis)
|
+-----+--------------------+
| |
aprovado reprovado
| (motivos objetivos,
v contra o criterio)
libera a |
proxima etapa v
produtor corrige e ressubmete
|
v
3 reprovacoes na mesma etapa?
|
sim
v
escala pro Time de Arquitetura
(replanejar, trocar abordagem
ou cancelar)São 3 dias úteis pra revisar cada submissão, e todo aprovador precisa de um suplente designado, pra que férias ou agenda lotada não congelem o projeto. Reprovar não é vetar por birra: anotam-se motivos objetivos, sempre contra o critério de aceite da etapa. E existe freio pro pingue-pongue infinito. Depois de 3 ciclos de reprovação no mesmo passo, o caso sobe pro Time de Arquitetura, que decide se replaneja, muda de rota ou cancela.
Tem ainda a estimativa progressiva, na minha opinião uma das partes mais sãs de tudo. Custo não é número chutado uma vez e cravado pra sempre. Nasce como ordem de grandeza no BRD e é refeito por obrigação em dois pontos: depois do HLD (arquitetura e infra) e depois do LLD (esforço de desenvolvimento). Variação acima de ±25% entre estimativas exige ciência formal do Solicitante. Mudou o escopo depois de uma aprovação? Também não sai de graça: obriga atualizar os artefatos afetados, reavaliar risco e estimativa, e re-aprovar com os mesmos aprovadores dos passos mexidos.
E a burocracia?
É a primeira coisa que escuto de quem olha de fora, e é pergunta justa. Rodar tudo isso num projetinho de duas semanas seria peso morto. O PRF sabe disso. A resposta atende pelo nome de tailoring por criticidade (P8): o rigor sobe junto com o tamanho do estrago que o projeto causa se desandar.
| Artefato | Baixa | Média | Alta | Crítica |
|---|---|---|---|---|
| Etapa 0 (Discovery) | Opcional | Opcional | Recomendado | Recomendado |
| BRD | ✔ | ✔ | ✔ | ✔ |
| HLD (C4 L1/L2) | Simplificado | ✔ | ✔ | ✔ |
| Protótipo UX (se há UI) | Wireframe simples | ✔ | ✔ | ✔ |
| LLD/TDD (C4 L3) | Opcional | ✔ | ✔ | ✔ |
| SAD | Opcional | Simplificado | ✔ | ✔ |
| Bootstrap Técnico | ✔ | ✔ | ✔ | ✔ |
| Threat modeling formal | - | Recomendado | ✔ | ✔ |
| Go/No-Go | ✔ | ✔ | ✔ | ✔ |
Criticidade Baixa ganha uma Trilha Leve: o BRD e um HLD simplificado podem virar um documento só, estilo one-pager, contanto que preserve o essencial (problema, objetivo mensurável, escopo, RF/RNF, as dimensões obrigatórias do BRD, o C4 L1 e a stack justificada). LLD e SAD ficam opcionais. Onde exatamente cai a linha entre Baixa e Média? Aí eu titubeio de verdade, e já vi reunião inteira queimar nessa discussão sem fechar consenso. Duas coisas, porém, jamais caem, em criticidade nenhuma: o BRD e o Go/No-Go. E toda simplificação vai registrada pelo Tech Lead Aprovador, porque cortar caminho também é decisão. E decisão tem dono.
Vale a pena?
Quando montei essa régua, confesso, não sabia se ela estava calibrada. Sinceramente, ainda não sei de pedra e cal. Foi justo por isso que o PRF foi feito pra medir a si mesmo: lead time por etapa, ciclos de reprovação, variação de estimativa do BRD ao LLD, e o indicador que não mente, o retrabalho que dá as caras depois do Go. A cada trimestre o documento para na frente desses números e se revisa. Régua torta, os próprios dados entregam.
Nada disso vale pro projeto solo de fim de semana. Mas no minuto em que mais de um time encosta no mesmo código, interno, contratado, parceiro, a conversa muda de figura. É aí que ter o combinado escrito, aprovado e com dono deixa de ser papelada e vira a fronteira entre entregar e apontar dedo. O repositório está aberto em github.com/uesleinasch/project-readiness-framework. Se o seu próximo projeto junta gente de mais de um lado, vale o clone.
Glossário rápido
| Sigla | Significado |
|---|---|
| BRD | Business Requirements Document, requisitos de negócio. |
| HLD / LLD | High-Level e Low-Level Design, design de alto e de baixo nível. |
| TDD | Technical Design Document (aqui não é Test-Driven Development). |
| SAD | Solution Architecture Document, documento de arquitetura. |
| ADR | Architecture Decision Record, registro de decisão arquitetural. |
| C4 | Modelo de diagramação em 4 níveis: Context, Containers, Components, Code. |
| DoR / DoD | Definition of Ready / Done, critérios de entrada e de saída de uma etapa. |
| RACI | Responsible, Accountable, Consulted, Informed. |
| RTO / RPO | Recovery Time / Point Objective, metas de recuperação de desastre. |
| SAST / SCA / DAST | Análise de segurança estática, de dependências e dinâmica. |
| TCO | Total Cost of Ownership, custo de construir mais operar. |
| LGPD | Lei Geral de Proteção de Dados. |