Organização dos documentos — uma definição, um lugar
Este documento define onde cada tipo de informação deve ser registrada, para que nada fique definido em mais de um lugar e haja uma única fonte de verdade por tema.
Regra de ouro
Cada “coisa” tem um único lugar onde é definida. Os outros documentos referenciam (link, número de documento) em vez de repetir a definição.
Onde definir cada tipo de informação
| Se você quer definir… | Documento / pasta | Exemplo |
|---|---|---|
| Para que existe o produto; direção estratégica; princípios de alto nível | Vision (vision/) | “A plataforma existe para gestão da EBD com privacidade e multi-igreja.” |
| Requisito de negócio; regra que o negócio exige; processo de negócio | BRD (brd/) | “O negócio exige que cada participante tenha um único perfil de usuário, onde se saiba tudo sobre ele em um só lugar.” |
| O que o produto faz; comportamento; telas; critérios de aceite; user stories | PRD (prd/) | “O produto terá uma tela de Perfil do usuário que exibe nome, cargo, igreja, avatar e permite editar X, Y, Z.” |
| Decisão arquitetural; por que escolhemos esta tecnologia/estrutura | ADR (architecture/adrs/) | “O perfil do usuário é armazenado em Firestore; o backend é a autoridade; dados em platform/users.” |
| Estrutura dos dados; entidades; campos; relacionamentos; ERD | Data Model / ERD (architecture/data-model/) | “Entidade User: id, ministry_id, unit_id, name, email, activeRole, roleAssignments[], …” |
| Contratos de API; fluxos técnicos; integrações; detalhes de implementação | TDD (architecture/tdd/) | “Endpoint GET /myProfile retorna payload (objeto); DTO UserProfile; regras de cache e etag.” |
Exemplo: “Perfil de usuário em um único lugar”
| O quê | Onde fica | Documento sugerido |
|---|---|---|
| Necessidade de negócio (“preciso saber tudo sobre o usuário em um lugar”) | BRD | brd/brd-001-perfil-e-identidade-usuario.md |
| Comportamento do produto (o que a tela mostra, o que o usuário pode fazer) | PRD | prd/prd-001-perfil-usuario.md |
| Decisões (onde guardar, quem é autoridade, ciclo de vida) | ADR | Já existe: adrs/adr-0013-perfil-de-usuario-e-ciclo-de-vida.md |
| Estrutura dos dados (campos da entidade User, relacionamentos) | Data Model | architecture/data-model/data-model-ebdbe.md (ou data-model-usuario.md) |
| APIs e contratos (myProfileHttp, payload, validações) | TDD | architecture/tdd/tdd-001-api-perfil-usuario.md |
Assim, a existência do conceito “perfil único” está no BRD; o desenho dos dados no Data Model; o comportamento na interface no PRD; o porquê técnico no ADR; e o detalhe de API no TDD. Nada fica definido duas vezes.
Fluxo recomendado (ordem de criação)
- Vision — já existe; direção geral.
- BRD — requisitos de negócio (ex.: “perfil único por usuário”).
- PRD — o que o produto faz a partir do BRD (telas, fluxos, aceite).
- ADR — decisões de arquitetura que impactam o desenho (onde guardar, autoridade).
- Data Model — entidades, campos, relacionamentos (uma vez só).
- TDD — detalhes técnicos (APIs, DTOs, regras de implementação).
Quando algo mudar (ex.: novo campo no perfil), altere só o documento dono (ex.: Data Model para estrutura; PRD para comportamento). Os outros apenas referenciam.
Resumo visual
Vision → "Para que existe"
BRD → "O negócio exige que…" (ex.: perfil único por usuário)
PRD → "O produto faz…" (ex.: tela de perfil com X, Y, Z)
ADR → "Decidimos que…" (ex.: backend autoridade, Firestore)
Data Model → "Estrutura dos dados…" (ex.: entidade User, campos)
TDD → "Como implementar…" (ex.: GET /myProfile, DTO)
Com isso, cada definição fica em apenas um lugar e é referenciada nos demais.