Como um developer sábio trabalha em um novo projeto

Um developer sábio não «começa a programar e espera.» Ele conduz um novo projeto por brainstorming, discussão com a equipe, prototipagem, diagramas, propostas, ADR, MR/PR e GitOps — com Review Bots que geram automaticamente comentários em PR para que humanos gastem tempo no que importa. Este é o playbook de nível produção. Um FDE pode levantar o sistema; a Claude Architect Certification vale a pena se você quiser projetá-lo e defendê-lo.

1. O que «sábio» significa em um novo projeto

Sabedoria não é mais reuniões. É aprendizado barato cedo e erros caros tarde tornados raros. A sequência abaixo é ordenada para que cada passo reduza o raio de explosão do próximo:

Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
        → Implement in small slices → MR/PR + Review Bot → Merge
        → GitOps promote (dev → staging → prod) → Observe → Iterate

Pule etapas só com intenção (ex.: correção de config de uma linha). Nunca pule Review Bot + CI em qualquer coisa que possa chegar à produção.

2. Brainstorming (solo primeiro, depois estruturado)

Antes de pedir tempo a alguém, gaste 30–90 minutos sozinho:

• Resultado: qual mudança de usuário/negócio deve ser verdadeira quando terminarmos?
• Restrições: tempo, orçamento, compliance, plataformas existentes, skills da equipe.
• Não-objetivos: o que não construiremos na v1 (protege o escopo).
• Riscos: dados, segurança, performance, vendor lock-in, carga operacional.
• Métricas de sucesso: latência, taxa de erro, adoção, custo — escolha duas que importam.

Capture isso em uma nota curta (Notion/Confluence/markdown no repo em docs/ideas/). Brainstorming sem artefato escrito é só conversa que evapora.

3. Discussões com colegas

Convide o menor círculo útil: um par que implementará com você, alguém que possui o sistema adjacente e (quando necessário) segurança ou SRE. Regras que mantêm a sabedoria:

• Time-box (25–45 minutos). Termine com decisões ou perguntas abertas — não vibes.
• Discorde de opções, não de pessoas. Force «opção A vs B vs adiar.»
• Designe um scribe. A nota vira a semente da proposta.
• Sem vetos silenciosos. Se alguém estiver desconfortável, escreva a preocupação como risco no ADR depois.

Async também funciona: um fio curto de comentários RFC muitas vezes supera uma reunião — mas alguém ainda deve fechar o loop.

4. Prototipagem (spikes com data de validade)

Prototipe quando a incerteza for alta: uma nova API, um serviço cloud pouco familiar, uma questão de performance ou comportamento de IA/agente. Regras sábias:

1. Nomeie como spike no ticket; defina uma parada no calendário (1–3 dias típicos).
2. Mantenha o código em um branch descartável ou pasta spikes/; não polir.
3. Anote o que aprendeu em 10 bullets — especialmente o que falhou.
4. Decida: promover (refatorar para o produto), reescrever ou abandonar.

Protótipos que viram produção em silêncio sem ADR são como equipes herdam arquitetura acidental.

5. Diagramas (o suficiente para discutir)

Você não precisa de um romance UML. Prefira três esboços que caibam em uma tela cada:

Diagrama	Responde
Contexto (C4 L1)	Quem fala com o quê? Limites de confiança?
Sequência	Happy path + um caminho de falha
Deployment	Onde roda; como config e secrets fluem

Guarde Mermaid ou imagens ao lado da proposta (docs/architecture/). Atualize diagramas quando ADRs mudarem — imagens obsoletas são piores que nenhuma.

6. Propostas (RFC leve)

Uma boa proposta tem de uma a três páginas:

1. Problema e por que agora
2. Opções consideradas (pelo menos duas)
3. Recomendação e por quê
4. Impacto: segurança, custo, ops, migração
5. Rollout e rollback
6. Perguntas abertas

Peça review com prazo claro. Quando aprovada (ou com emendas), transforme a decisão em ADR — não deixe a «fonte da verdade» no chat.

7. ADR — Architecture Decision Records

Um ADR é um registro curto, imutável por convenção, de uma decisão. Template:

# ADR-00XX: Title

Status: Proposed | Accepted | Superseded by ADR-00YY
Date: YYYY-MM-DD
Deciders: @alice @bob

## Context
What forces are in play?

## Decision
What we will do.

## Consequences
Positive, negative, and follow-ups.

## Alternatives considered
Option A — why not
Option B — why not

Mantenha ADRs no git (docs/adr/). Linke-os a partir de PRs. Substitua em vez de reescrever a história — seu eu futuro precisa do rastro.

8. MR e PR — a unidade de entrega

MR (Merge Request, GitLab) e PR (Pull Request, GitHub/Bitbucket) são a mesma ideia: um conjunto de mudanças revisável. Hábitos sábios:

• Pequeno: idealmente <400 linhas de diff significativo; divida em slices verticais.
• Uma intenção: uma feature, fix ou chore — não «misc.»
• Descrição: por quê, como testar, screenshots/logs, risco, rollback.
• Links: ticket + ADR + diagrama de design.
• Draft primeiro quando quiser feedback antecipado sem implicar «pronto para merge.»
• Nunca force-merge em torno de CI vermelho ou findings de bot de alta severidade sem exceção escrita.

Exemplo de checklist do corpo da PR

## Summary
- …

## Test plan
- [ ] Unit tests
- [ ] Manual path …
- [ ] Feature flag / config …

## Risk & rollback
- Risk: …
- Rollback: revert this PR / GitOps revert commit …

## References
- ADR-00XX
- Ticket ABC-123

9. Uso do Review Bot — comentários PR auto-gerados

Um Review Bot é um revisor automatizado que publica comentários inline e resumos em cada MR/PR. Não substitui humanos; antecipa o entediante e o perigoso.

9.1 Sobre o que o bot deve comentar

• Segurança: injection, lacunas de authz, vazamento de secrets, defaults inseguros
• Correctness: caminhos null, race conditions, migrations quebradas
• Tests: cobertura faltando em novos branches, abuso de snapshots
• API/contrato: breaking changes sem version bump
• Ops: timeouts faltando, sem idempotência, retries ilimitados
• Style só quando escapou do formatter/linter (evitar ruído)

9.2 Como simplifica a vida do developer

1. Autor abre a PR → bot roda em segundos a minutos.
2. Autor corrige ou responde threads do bot antes de pedir humanos.
3. Revisor humano lê o resumo do bot + foca em design e risco de produto.
4. Menos rodadas de «nits»; merge mais rápido; menos incidentes de sexta à noite por footguns perdidos.

9.3 Opções típicas de setup

Abordagem	Notas
SaaS Review Bot (ex. CodeRabbit, bots de vendor)	Rápido de ativar; ajuste severidade e filtros de path
Cursor Bugbot / review ligada ao IDE	Forte em diffs de PR em times centrados em Cursor
GitHub Action custom + Claude / LLM	Controle total; precisa de prompt + política + tetos de custo
Pipeline em camadas (lint → SAST → LLM)	Melhor postura de produção — veja o guia de pipeline de revisão de código IA

9.4 Política que mantém o bot útil

• Labels de severidade: blocker / should-fix / nit — nits não devem bloquear o merge.
• Ignorar paths gerados (vendor/, ruído de lockfiles, dumps protobuf).
• Exigir aprovação humana para paths sensíveis de segurança (auth/, infra/, IAM).
• Registrar falsos positivos; reinyetá-los nas regras de ignore mensalmente.
• Nunca deixe o bot ser o único revisor em serviços críticos de produção.

9.5 Esboço mínimo de GitHub Action

# .github/workflows/review-bot.yml
name: review-bot
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run Review Bot
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: |
          # Fetch diff, call your review CLI, post review comments via gh api
          ./scripts/review-bot.sh

Implemente review-bot.sh para: calcular o diff da PR, chamar seu modelo com um system prompt estrito (segurança + correctness primeiro) e postar comentários via API GitHub/GitLab. Limite tokens e pule drafts se o custo for preocupação.

10. Melhores práticas GitOps para qualidade production-grade

GitOps significa: o estado desejado vive no git; um reconciler (Argo CD, Flux, etc.) faz o cluster corresponder; promoção é um merge; rollback é um revert.

• Separar código da app e config de env (ou pastas claras: apps/ vs envs/dev|staging|prod).
• Sem kubectl apply em prod como happy path — só break-glass, auditado.
• Entrega progressiva: auto-sync em dev; sync manual ou gated para prod.
• Digests de imagem em vez de tags mutáveis em manifests de prod.
• Policy as code: OPA/Kyverno para privilégios, registries, limites de recursos.
• Commits assinados / provenance onde seu threat model exigir.
• Observar após sync: health checks, error budgets, hooks de rollback automático quando prontos.

Qualidade de código não é só «funções limpas.» Também é como a mudança entra em produção. GitOps torna esse caminho revisável, reversível e repetível.

11. Gates de qualidade ponta a ponta (otimizados para produção)

Local:     pre-commit (fmt, lint, secrets) + unit tests
PR open:   CI (build, test, SAST) + Review Bot comments
PR merge:  human approve + branch protection + required checks
Main:      build immutable artifact (image digest)
GitOps:    update env repo / overlay → sync → verify
Prod:      SLOs + alerts + runbook linked from ADR/PR

12. Papel do FDE — quem monta este sistema

Um Forward Deployed Engineer é ideal para instalar o sistema do developer sábio dentro de uma equipe real:

• Templates de repo: docs/adr/, template de PR, CODEOWNERS, branch protection
• Review Bot + secrets + controles de custo
• Checks CI obrigatórios e proteções de ambiente
• Apps GitOps (dev/staging/prod) e docs de promoção
• Coaching de duas semanas: primeiro ADR, primeira PR afinada pelo bot, primeiro drill de rollback GitOps

Calendário indicativo para enablement liderado por FDE em um repo de produto: 1–2 semanas para scaffolding e política do bot; +1–2 semanas para o caminho de promoção GitOps e um rollback a seco. Mudança cultural demora mais — meça tempo de merge e defects escapados, não installs de ferramentas.

13. Claude Architect Certification — vale a pena

Se você projeta sistemas onde humanos e agentes de IA coescrevem código, a Claude Architect Certification vale a pena. Sinaliza que você pode:

• Arquitetar entrega assistida por IA sem tratar o modelo como infalível
• Especificar políticas de review, guardrails e avaliação para workflows agenticos
• Comunicar trade-offs (latência, custo, privacidade, precisão) a stakeholders
• Treinar equipes em ADRs, disciplina de PR e gates de produção ao lado de ferramentas de IA

Combine a credencial com entrega real: levante um Review Bot, escreva três ADRs e execute um drill de rollback GitOps. Papel sem prática não o torna sábio; prática mais uma linguagem compartilhada, sim.

14. Anti-padrões (como a imprudência parece)

• PR gigante com «WIP please approve ASAP»
• Arquitetura decidida só no Slack, nunca em ADR
• Protótipo mergeado como prod sem testes
• Desativar Review Bot porque «ele enche»
• Hotfix em prod fora do GitOps sem plano de revert
• Humanos repetindo nits de formatter que o bot já pegou

15. Checklist starter copy-paste para um novo projeto

1. Criar docs/ideas/, docs/architecture/, docs/adr/
2. Adicionar template PR/MR + CODEOWNERS
3. Ativar pre-commit + checks CI obrigatórios
4. Instalar Review Bot; ajustar filtros de path e severidades
5. Escrever ADR-0001: «We use GitOps for deploy»
6. Definir ambientes e regras de promoção
7. Agendar um game day de rollback de 30 minutos
8. Reservar tempo FDE para coaching do primeiro mês; considerar Claude Architect Certification para leads

16. Encerramento

Um developer sábio trata um novo projeto como uma sequência de artefatos de aprendizado — notas, diagramas, propostas, ADRs — e então entrega via MR/PR pequenos vigiados por um Review Bot e promovidos por GitOps. É assim que a qualidade do código é otimizada para production grade sem queimar a equipe em nits intermináveis. Deixe um FDE instalar os trilhos; deixe arquitetos certificados manterem o sistema honesto enquanto a IA acelera quão rápido você pode escrever código.

Publicado por Workstation.