Skip to content
mel — finance agent for couples

003 — Estratégia de documentação (scenarios / decisions / infrastructure specs)

Status: Aceita (2026-06-03)

Contexto

Section titled “Contexto”

O projeto já tem dois lugares onde “documentação executável” mora — scenarios/NNN-slug.{md,spec.ts} (doc Gherkin + BDD spec, 1:1) e ADRs em decisions/NNN-slug.md (decisões técnicas atemporais, ex: 001 stack, 002 test tiers/e2e). Conforme entram os cenários de infraestrutura (persistir budget, parsing de fatura, chat com agente), aparece uma terceira categoria de documento que não cabe bem em nenhum dos dois: spec de adapter (BudgetRepository, OpenRouterClient, NubankPDFParser) — comportamento mecânico de mapeamento, sem história do casal, sem decisão a registrar.

Forçar tudo em scenarios/ infla o índice com docs que ninguém do casal leria (“como adapter mapeia row ↔ aggregate”). Forçar tudo em ADR vira changelog disfarçado. Falta uma regra clara de qual doc mora aonde — antes que o primeiro adapter real apareça e a decisão saia por inércia.

Decisão

Section titled “Decisão”

Documentação vive em três lugares, cada um com propósito disjunto:

  1. scenarios/NNN-slug.{md,spec.ts} — fluxos behaviorais visíveis ao casal (UX-facing). Gherkin no .md, BDD no .spec.ts, sibling 1:1. Já estabelecido pra 000–006. Persistência reaparece aqui quando for cenário behavioral (“fecho o app, reabro, vejo o orçamento”) — NÃO como contrato de schema.

  2. decisions/NNN-slug.md — ADRs curtos pra escolhas técnicas atemporais (“usar drizzle vs prisma”, “polyfill Temporal”, “tier de testes”). Formato fixo: Contexto / Decisão / Consequências / Alternativas / Referências. Sem .spec.ts sibling — ADR é decisão escrita, não comportamento testável.

  3. src/contexts/<ctx>/infrastructure/*.spec.ts — specs colocated com adapter (BudgetRepository, OpenRouterClient, NubankPDFParser). Sem doc Gherkin sibling — código bem nomeado + spec descritivo se documentam. A mecânica de “como adapter X mapeia Y” não precisa de prosa adicional.

Regra prática de roteamento:

  • “O casal observa…” → scenarios/
  • “Decidimos usar X porque Y” → decisions/
  • “Esse adapter mapeia row ↔ aggregate” → spec colocated em infrastructure/

O que este ADR NÃO decide:

  • Não muda nada nos cenários 000–006 existentes.
  • Não introduz docs novos automáticos pra código já escrito — só estabelece convenção pra novos.
  • ADR não é changelog. Cada um é estado da decisão num ponto, congela quando aceito. Mudança = novo ADR superseding (status: Superseded by NNN).

Consequências

Section titled “Consequências”

Positivas:

  • Três lugares pra olhar, mas cada um óbvio quando estiver lá. Roteamento decidido na hora de escrever, não na hora de procurar.
  • scenarios/ não infla com prosa de infra — segue legível como índice de UX do casal.
  • Specs colocated de adapter dispensam Gherkin: código + teste + nome do arquivo já contam a história mecânica.
  • ADR fica reservado pra decisões técnicas — não vira lixeira de notas.

Negativas / Trade-offs:

  • Convenção depende de julgamento na fronteira (“isso é cenário ou adapter spec?”). Regra prática mitiga, mas casos limítrofes vão aparecer — resolver caso a caso e memorizar gotcha se virar padrão.
  • Cenário behavioral pode tocar infra real (ex: e2e via Playwright). Fica em scenarios/ se contar história do casal; vai pra e2e/ se for fluxo técnico cross-stack (ver ADR 002).
  • ADRs futuros sobre docs/conventions podem se sobrepor a gotchas do AGENTS.md — manter AGENTS.md como índice vivo; ADR é snapshot de decisão pontual.

Alternativas consideradas

Section titled “Alternativas consideradas”
  • Tudo em scenarios/ (forçar doc Gherkin pra adapter): infla índice com docs irrelevantes pro casal; “como BudgetRepo mapeia rows” não é cenário, é mecânica.
  • Tudo em ADRs (incluindo notas de design e adapter behavior): vira changelog disfarçado, perde a clareza de “decisão técnica atemporal”.
  • Pasta docs/ única plana: dilui contexto. Cada doc precisaria explicitar seu tipo no header. Roteamento por pasta é mais barato.
  • README.md por contexto: redundante com spec colocated + AGENTS.md como índice de gotchas. README envelhece e ninguém atualiza.

Referências

Section titled “Referências”
  • AGENTS.md — convenções “aggregate root names the context” (exceção: capability-named como planning/), “toda doc tem que ser testável” (aplica só a scenarios/, NÃO a ADRs), “sempre memorizar” (AGENTS.md é índice vivo de gotchas; ADRs são decisões pontuais — memória contínua vs snapshot).
  • ADR 001 — stack de infraestrutura (define adapters que farão uso de specs colocated).
  • ADR 002 — tier de testes / e2e (define quando cenário vira scenarios/ vs e2e/).