Convenções de framework tornam aplicações mais fáceis de entender sem longos documentos. Aprenda o que as convenções cobrem, onde falham e como documentar somente as exceções.
As convenções de framework são as “maneiras padrão de fazer as coisas” que um framework incentiva — ou mesmo espera. Em vez de cada time inventar seu próprio layout de pastas, esquema de nomes ou fluxo de requisição/resposta, o framework fornece um padrão compartilhado. Se você o segue, outros desenvolvedores conseguem prever onde as coisas ficam e como se comportam sem precisar de uma explicação longa.
A maior parte da documentação não é escrita porque as pessoas adoram escrever docs. Ela existe para resolver alguns problemas recorrentes:
As convenções lidam especialmente bem com os dois primeiros. Quando “onde colocar X” e “como nomear Y” já estão decididos pelo framework, há menos a explicar e menos o que debater.
“Convenções substituem documentação” não significa que um projeto fica sem documentação. Significa que uma grande parte da orientação básica se move da prosa para uma estrutura previsível. Em vez de ler uma página na wiki para aprender onde ficam os controllers, você infere porque o framework espera controllers em um lugar específico (e ferramentas, geradores e exemplos reforçam isso).
O resultado é menos documentação sobre o óbvio e mais foco em documentar o que é realmente específico do projeto: regras de negócio, escolhas arquiteturais incomuns e exceções intencionais.
Este artigo é para desenvolvedores, tech leads e times orientados ao produto que querem bases de código mais claras e um onboarding mais rápido sem manter um site de documentação enorme.
Você verá como convenções de framework criam “documentação implícita”, que tipos de coisas as convenções normalmente padronizam, onde as convenções deixam de ajudar e o que ainda merece documentação explícita — assim a clareza aumenta mesmo com menos docs.
“Convenção sobre configuração” significa que um framework faz escolhas sensatas por você — desde que você siga suas regras acordadas. Em vez de escrever (e ler) páginas de instruções de setup, as equipes confiam em defaults compartilhados que todos reconhecem.
Pense como dirigir em um país onde todos concordam em dirigir pela direita, parar no sinal vermelho e seguir sinais padrão.
Você poderia escrever um manual detalhado para cada interseção (“Se vir um octógono vermelho, pare; se a luz estiver verde, vá…”), mas não precisa — porque a convenção já é conhecida e aplicada consistentemente.
As convenções de framework funcionam do mesmo jeito: transformam “como fazemos as coisas aqui” em comportamento previsível.
Quando um framework tem defaults, você não precisa documentar toda decisão pequena. O framework (e seu time) pode assumir padrões como:
User mapeia para dados users)Essa linha de base compartilhada encolhe a documentação de “aqui está cada passo para configurar X” para “seguimos os padrões do framework, exceto quando indicado”. Também reduz a carga mental no onboarding: novos desenvolvedores acertam mais vezes, porque o código bate com o que já viram em outros projetos.
Convenções não são de graça. O lado negativo é que às vezes você abre mão de estruturas de pastas incomuns, nomes customizados ou fluxos muito específicos.
O lado positivo é consistência: menos debates, menos surpresas, menos regras de “conhecimento tribal” que só os veteranos lembram. As equipes andam mais rápido porque gastam menos tempo explicando e mais tempo construindo.
Uma convenção só economiza documentação se as pessoas já a conhecem — ou podem aprendê-la uma vez e reaplicá-la em todo lugar.
Por isso frameworks populares são poderosos: suas convenções são ensinadas amplamente, usadas amplamente e repetidas em muitos codebases. Quando seu projeto fica próximo desses defaults compartilhados, seu código fica compreensível por padrão, com muito menos explicações escritas necessárias.
As convenções de framework são atalhos compartilhados. Elas padronizam as perguntas que todo novo colega faz no primeiro dia: “Onde isto vai?” e “Como devo nomear isto?” Quando essas respostas são previsíveis, você pode substituir páginas de docs por alguns defaults consistentes.
A maioria dos frameworks empurra uma estrutura de projeto reconhecível: um lugar para UI, um lugar para rotas, um lugar para acesso a dados, um lugar para testes. Essa consistência é importante porque as pessoas não precisam ler um guia para encontrar “a parte que renderiza uma página” versus “a parte que fala com o banco de dados”.
As melhores convenções fazem tarefas comuns parecerem memória muscular: adicionar uma nova tela, você já sabe em qual pasta ela pertence.
Regras de nomes reduzem a necessidade de explicações como “Nossos controllers ficam em X e devem ser ligados em Y.” Em vez disso, os nomes implicam papéis.
Exemplos comuns:
Muitos frameworks mapeiam arquivos para rotas (ou tornam as rotas fáceis de inferir). Se você consegue adivinhar a URL a partir do nome do arquivo — ou vice-versa — não precisa de um manual de roteamento para cada feature.
A convenção também define expectativas sobre rotas dinâmicas, rotas aninhadas e tratamento de 404, então “como adicionamos um endpoint novo?” tem uma resposta padrão.
Convenções frequentemente definem onde o “código de dados” vive: models, repositories, services, migrations, arquivos de schema. Mesmo que sua app seja pequena, ter uma casa acordada para acesso a dados evita chamadas de banco espalhadas pela UI.
Comandos padrão (rodar, testar, buildar, lintar, formatar) eliminam ambiguidade. Um novo desenvolvedor não deveria precisar de uma página na wiki para descobrir como iniciar o projeto — npm test (ou equivalente) deveria ser o passo óbvio.
Quando essas cinco áreas são consistentes, a própria base de código responde à maioria das perguntas “como fazemos as coisas aqui?”.
Uma wiki de “como tudo funciona” tenta descrever o sistema todo em prosa. Ela costuma começar útil e depois se desatualiza à medida que pastas mudam, nomes mudam e novas features aparecem. Convenções invertem essa ideia: em vez de ler uma explicação longa, você lê a estrutura.
Quando um framework (e seu time) concorda onde as coisas ficam, o repositório fica navegável como um mapa urbano.
Se você sabe que componentes de UI vão em components/, views de página em pages/ e handlers de API em api/, você para de perguntar “onde está X?” porque o primeiro palpite geralmente está certo. Mesmo quando não está, sua busca fica mais restrita: não é qualquer lugar — está em um pequeno número de locais esperados.
Convenções também fazem nomes de arquivos e símbolos carregarem significado. Um recém-chegado pode inferir comportamento a partir da localização e nomenclatura:
user.controller provavelmente lida com lógica de requisiçãoUserService provavelmente contém regras de negóciomigrations/ provavelmente contém mudanças ordenadas, executadas uma vezEssa inferência reduz perguntas longas do tipo “explique a arquitetura para mim” para perguntas menores e respondíveis (“Este service pode chamar o banco direto?”), que são muito mais fáceis de documentar.
A forma mais rápida de reforçar o mapa é scaffolding. Templates iniciais e geradores criam novas features no “formato certo” por padrão — pastas, nomes de arquivos, boilerplate e frequentemente testes.
Isso importa porque convenções só ajudam quando são aplicadas consistentemente. Um template é um guarda-rail: ele empurra cada nova rota, componente ou módulo para a estrutura esperada, então a base de código se mantém legível sem acrescentar mais páginas na wiki.
Se você mantém scaffolds internos, linke-os a uma página curta de onboarding (por exemplo, /docs/getting-started) e deixe a árvore de pastas fazer o resto.
Convenções de framework muitas vezes atuam como instruções silenciosas incorporadas. Em vez de escrever uma página que explica “onde as coisas ficam” ou “como ligar isto”, o framework já toma a decisão — e seu time aprende a ler a estrutura.
Rails é famoso por convenção sobre configuração. Um exemplo simples: se você criar um controller chamado OrdersController, o Rails assume que existe uma pasta de views correspondente em app/views/orders/.
Essa única convenção pode substituir parte da documentação que explicaria:
Resultado: novos colegas podem adicionar uma página seguindo o padrão de pastas, sem perguntar “onde este arquivo fica?”.
Django incentiva uma estrutura consistente de “app”. Quando alguém vê um app Django, espera encontrar models.py para estruturas de dados, views.py para tratamento de requisições e templates/ para HTML.
Você poderia escrever um guia longo descrevendo a anatomia do projeto, mas os defaults do Django já ensinam isso. Quando alguém quer mudar a aparência de uma página, sabe procurar em templates/. Quando precisa ajustar dados armazenados, começa em models.py.
Resultado: correções mais rápidas, menos tempo caçando, menos mensagens “qual arquivo controla isto?”.
Next.js reduz a documentação fazendo do roteamento um reflexo direto da estrutura de pastas. Crie um arquivo em app/about/page.tsx (ou pages/about.tsx em setups antigos) e você ganha automaticamente uma página /about.
Isso elimina a necessidade de docs que expliquem:
Resultado: o onboarding fica mais simples — as pessoas descobrem a forma do site escaneando diretórios.
Rails, Django e Next.js parecem distintos, mas o princípio é idêntico: defaults compartilhados transformam a estrutura do projeto em instruções. Quando todos confiam nas mesmas convenções, o próprio código responde a muitas perguntas “como fazemos isto aqui?” — sem outro documento para manter.
As convenções de framework parecem “invisíveis” quando funcionam. Você consegue adivinhar onde os arquivos ficam, como as coisas se chamam e como uma requisição percorre a app. A confusão volta quando uma base de código se afasta desses defaults compartilhados.
Alguns padrões aparecem cedo:
UserService, outra UsersManager, outra user_serviceNada disso é automaticamente errado — mas significa que um novo colega não pode confiar mais no “mapa” do framework.
A maioria dos rompimentos começa com uma otimização local razoável: “Esta feature é especial, então vamos colocá-la aqui” ou “este nome fica melhor”. O problema é que exceções são contagiosas. Quando a primeira exceção é lançada, o próximo dev a usa como precedente:
A partir daí, a convenção deixa de ser convenção — vira conhecimento tribal.
Quando as convenções ficam borradas, o onboarding desacelera porque as pessoas não conseguem prever onde procurar. Tarefas do dia a dia demoram mais (“qual dessas pastas é a verdadeira?”), e erros aumentam (ligar o módulo errado, usar o padrão de nomes errado, duplicar lógica). As equipes compensam marcando mais syncs, escrevendo descrições longas em PRs e adicionando “docs rápidos” que ficam obsoletos.
Customize só quando houver uma razão clara — e deixe uma nota escrita.
Essa nota pode ser leve: um comentário perto da estrutura incomum, ou uma breve entrada em uma página /docs/decisions explicando o que mudou, por que valeu a pena e qual deve ser a abordagem padrão no futuro.
Convenções de framework podem eliminar páginas de explicação, mas não tiram responsabilidades. As partes que ainda precisam de documentação são as onde seu projeto diferentemente intencionalmente do que a maioria dos desenvolvedores assumiria.
Pule a reexplicação do comportamento padrão do framework. Capture decisões que afetam o trabalho diário:
Exemplo: “Usamos feature folders em /src/features em vez de pastas por camada (/src/components, /src/services) porque a propriedade mapeia para times e reduz acoplamento entre equipes.” Essa única frase evita semanas de deriva lenta.
Quando uma exceção importa localmente, coloque a nota localmente. Um pequeno README.md dentro de uma pasta, ou um cabeçalho curto no topo de um arquivo, muitas vezes ganha do wiki central que ninguém checa.
Bons candidatos:
Mantenha essas notas curtas e acionáveis: o que é diferente, por que é diferente e o que fazer a seguir.
Tenha uma página leve (normalmente em /docs/project-rules.md ou no README na raiz) que liste apenas 5–10 escolhas chave que as pessoas tropeçam:
Isso não é um manual completo — apenas um conjunto compartilhado de guardrails.
Mesmo com convenções, o onboarding trava quando as pessoas não conseguem rodar a app. Adicione uma seção curta “Como rodar/testar” que combine comandos padrão e sua configuração real.
Se o comando convencional for npm test mas seu projeto exigir npm run test:unit, documente isso explicitamente.
A documentação permanece precisa quando é tratada como parte da mudança. Em reviews, pergunte: “Isto introduziu uma nova exceção?” Se sim, exija a nota correspondente (README local, Project Rules ou quickstart) no mesmo pull request.
Se convenções são os “defaults compartilhados” da sua base de código, automação é o que as torna reais. Em vez de pedir para cada desenvolvedor lembrar regras de uma wiki, faça as regras executáveis — assim o projeto se aplica sozinho.
Uma boa configuração pega a deriva cedo e silenciosamente:
default export se esse for seu padrão).*.spec.ts, escrita describe/it ou asserções obrigatórias para que os testes sejam consistentes.Essas checagens substituem parágrafos de “por favor, lembre-se de…” por um simples resultado: o código ou está conforme a convenção, ou não está.
Automação brilha porque falha rápido:
Os melhores conjuntos de regras são pequenos e sem graça. Comece pelos defaults do framework e adicione somente o que protege clareza (nomenclatura, estrutura e limites). Cada regra extra é mais uma coisa que as pessoas precisam entender, então trate novas checagens como código: adicione quando resolver um problema recorrente e remova quando pararem de ajudar.
Quando uma base de código segue convenções de framework, testes podem fazer mais do que “provar que funciona”. Podem explicar o que o sistema deve fazer, em linguagem clara, ao lado da implementação.
Uma regra útil: um teste deve descrever um comportamento de ponta a ponta. Se alguém consegue entender a promessa do sistema só lendo o nome do teste, você reduziu a necessidade de documentação separada.
Bons testes tendem a seguir um ritmo simples:
Melhor ainda é um nome que espelha a intenção do usuário:
signing_in_with_valid_credentials_redirects_to_dashboardcheckout_fails_when_shipping_address_is_missingEsses nomes são “documentação” que você não esquece de atualizar — porque testes falhos forçam a conversa.
Testes de aceitação documentam como o produto se comporta do ponto de vista do usuário.
Exemplos de comportamentos que testes de aceitação descrevem:
Esses testes respondem “O que acontece quando eu faço X?” — frequentemente a primeira coisa que um novo colega precisa.
Unit tests brilham quando é preciso documentar regras pequenas, porém importantes:
Eles são especialmente valiosos quando a regra não é óbvia a partir das convenções do framework.
Dados de exemplo podem ser documentação viva também. Uma fixture pequena e bem nomeada (ex.: user_with_expired_subscription) ensina o domínio mais rápido que um parágrafo na wiki.
A chave é restrição: mantenha fixtures mínimas, legíveis e ligadas a uma única ideia, para que continuem sendo exemplos confiáveis e não um segundo sistema a manter.
Templates iniciais (e os geradores por trás deles) são a maneira mais rápida de transformar “como fazemos aqui” em algo que as pessoas realmente seguem. Em vez de pedir a cada membro da equipe para lembrar pastas, scripts e tooling, você codifica essas decisões em um repositório que já começa correto.
Os três reduzem a “dívida de documentação” porque a convenção está codificada no ponto de partida, não numa wiki que deriva.
Na prática, é também onde ferramentas como Koder.ai podem ajudar: ao gerar uma nova app React, backend em Go, schema PostgreSQL ou cliente Flutter via workflow orientado por chat, você mantém times numa “golden path” ao fazer a saída padrão coincidir com suas convenções (e depois exportar o código-fonte para o repo).
A maior parte da confusão no onboarding não é sobre lógica de negócio — é sobre onde as coisas vivem e como rodá-las. Um bom template torna tarefas comuns idênticas entre repositórios: mesmos scripts, mesmos nomes de pastas, mesmos comandos de checagem, mesma expectativa de PR.
Se fizer apenas isto, alinhe em:
/src, /test, /docs apenas para exceções)Mantenha pequeno para que times não pulem:
install + dev)test, lint e formatO maior risco é copiar um template antigo “porque funcionou no ano passado”. Dependências desatualizadas, scripts legados ou padrões abandonados se espalham rápido quando estão num starter.
Trate templates como produtos: versione-os, revise-os periodicamente e atualize-os quando suas convenções mudarem. (Se sua plataforma suporta snapshots e rollback — Koder.ai faz — use isso para iterar com segurança em starters sem quebrar a baseline de todo mundo.)
Reduzir documentação não significa deixar as pessoas adivinharem. Significa tornar o “caminho feliz” tão consistente que a maioria das perguntas se responde sozinha, e só as partes realmente incomuns precisam ser escritas.
Procure lugares onde pessoas repetidamente fazem as mesmas perguntas no Slack, comentários de PR, standups ou sessões de onboarding. Alguns prompts:
Se você ouvir a mesma pergunta duas vezes, provavelmente não precisa de mais prosa — precisa de uma convenção.
Para cada pergunta recorrente, decida:
Uma regra útil: se um desvio não está economizando tempo real ou prevenindo risco real, provavelmente não vale a confusão contínua.
Mantenha uma página curta (ex.: /docs/conventions) que liste:
Limite ao que alguém precisa na primeira semana. Se começar a crescer, muitas vezes é sinal de que você deveria simplificar a base de código em vez de documentá-la.
Apps evoluem. Agende uma revisão leve a cada trimestre:
Prefira os defaults do framework sempre que possível, e documente apenas o que difere — de forma clara, breve e num único lugar.
As convenções de framework são os padrões padrões que o framework espera que você siga — estrutura de pastas, nomenclatura, roteamento, acesso a dados e comandos comuns. Quando você se mantém nelas, outros desenvolvedores conseguem inferir onde as coisas ficam e como funcionam sem ler documentação específica do projeto.
Porque é difícil manter a prosa precisa à medida que o código muda. A documentação existe principalmente para:
As convenções cobrem bem os dois primeiros pontos ao tornar a estrutura previsível.
Não. Convenções reduzem a necessidade de documentar o óbvio (onde os arquivos ficam, como as rotas são ligadas), mas ainda é preciso documentar o que é específico do projeto: regras de negócio, desvios intencionais e decisões-chave. Pense em “menos documentação, documentação de maior valor”.
Elas padronizam as perguntas recorrentes do “primeiro dia”:
Quando o código segue um padrão conhecido, a árvore de diretórios e os nomes de arquivos funcionam como placas de sinalização. Um novo membro navega por expectativa (por exemplo, “templates ficam em templates/”, “migrations ficam em migrations/”) em vez de ler uma longa página de arquitetura que pode estar desatualizada.
Elas codificam as convenções nas opções padrão para que as pessoas não dependam da memória. Bons scaffolds geram:
Isso evita deriva e mantém o “mapa” consistente entre features.
Você percebe quando desenvolvedores não conseguem prever onde algo fica ou como se chama. Sinais comuns:
UserService vs UsersManager vs user_service)A partir daí a equipe compensa com explicações no Slack, PRs mais longos e docs rápidos que ficam obsoletos.
Customize apenas quando houver ganho claro e, então, deixe uma nota leve explicando o desvio:
README.md dentro da pasta incomum/docs/decisions ou similarCapture o que mudou, por quê e qual deve ser a abordagem padrão daqui em diante.
Comece com uma base prática e curta:
Mantenha enxuto e exija a atualização durante a revisão de código quando uma mudança introduzir uma nova exceção.
Use automação para tornar as convenções executáveis:
Quando verificações falham no dev local ou em PRs, os desenvolvedores aprendem as regras imediatamente — e os revisores gastam menos tempo policiando estilo.
Quando isso é previsível, o repositório se torna autoexplicativo.