my-code-codex

Comunicação escrita

Em time remoto, a maior parte do trabalho acontece por escrito: o PR, o ticket, a mensagem no chat, o documento de decisão. Escrever bem é a habilidade que mais multiplica o resto.

Descrição de pull request

## O que muda
Aprovação de pedidos passa a exigir a permissão `pedidos:aprovar`.

## Por quê
Hoje qualquer usuário autenticado aprova pedidos (incidente INC-412).

## Como testar
1. `dotnet test` cobre os casos novos em `PedidosEndpointsTests`.
2. Em homologação, um usuário sem a permissão recebe 403 em `POST /pedidos/{id}/aprovacao`.

## Riscos
O app de backoffice precisa enviar o token com a nova claim. Combinado com o time de identidade para liberar antes do deploy.

O revisor lê em dois minutos e sabe onde olhar. Daqui a um ano, quem rodar git blame entende a decisão.

ADR (Architecture Decision Record)

Uma página por decisão difícil de desfazer, guardada no repositório (docs/adr/0007-kafka-para-eventos-de-pedido.md):

# 7. Kafka para os eventos de pedido

Status: aceita (2026-03-10)

## Contexto
Três serviços precisam reagir à criação de pedidos, e o volume de pico é de 2 mil por segundo.

## Decisão
Publicar os eventos de pedido no Kafka, tópico `pedidos.eventos`, chave = id do pedido.

## Alternativas consideradas
- RabbitMQ: atende o volume, mas não permite reprocessar o histórico quando um serviço novo chega.
- Chamada HTTP direta: acopla os serviços e perde eventos quando um deles está fora.

## Consequências
O time passa a operar Kafka (ou contratar gerenciado). Consumidores precisam ser idempotentes.

Mensagem assíncrona

Escreva para quem vai ler sem poder te perguntar nada.

Ruim:
  oi, tem um minuto?

Bom:
  Oi! O endpoint de pedidos está devolvendo 500 em homologação desde as 14h
  quando o cliente não tem endereço (trace no link). Acho que é a migration de ontem.
  Consegue olhar até amanhã? Se for urgente pro seu lado, eu reverto a migration.

Contexto, o que você precisa, até quando e o que você já tentou. Uma mensagem completa economiza três idas e voltas e uma reunião.

Post-mortem sem culpados

Depois de um incidente: linha do tempo, impacto (quantos usuários, por quanto tempo), causa raiz, o que funcionou, o que não funcionou e ações com dono e prazo. O foco é o sistema que permitiu o erro, não a pessoa que apertou o botão. Time que pune o erro aprende a esconder erro.

Documentação que alguém lê

  • O README responde: o que é, como rodar local em cinco minutos, como testar, como publicar.
  • Documente o porquê e o que não é óbvio; o “como” o código já mostra.
  • Diagrama simples (caixas e setas) vale mais que dez parágrafos. Mermaid no próprio Markdown fica versionado junto do código.

O que perguntam em entrevista

  • Como você documenta uma decisão técnica.
  • Como você explicaria um problema técnico para alguém de negócio.
  • Como você comunica um atraso.
  • Conte de um incidente e como foi a comunicação durante ele.