Dossiê do sistema
O escriba mantém o mapa da plataforma, o acesso, o banco, o domínio, o deploy e os achados, atualizados a cada atividade.
Entrega: dossiê em diaOcto para documentação · braço escriba
O que o time aprende fica escrito.
Para o DORA, a qualidade da documentação impulsiona todas as práticas técnicas que ele estudou, e documentação precisa ser criada e mantida ativamente. Nesta etapa atua o braço escriba do Octo: mantém o dossiê do sistema (mapa da plataforma, acesso, banco, domínio, deploy e achados), o estado e as decisões do projeto, separando regra, conhecimento e estado. O que vira regra do projeto é aprovado pelo líder técnico.
BraçoEscribaatua nesta etapa
Conventional Commits1.0.0tipo, escopo e descrição
Fontes6listadas no fim da página
01
O que o Octo faz na documentação.
Quatro entregas possíveis. O que vira regra do projeto e o padrão do time são decididos pelo líder técnico.
Estado e decisões
Registra o estado do projeto e as decisões com data, separando o que é regra, o que é conhecimento e o que é só estado do dia.
Entrega: decisões registradas com dataRegra que vale sempre
O que tem de acontecer sempre vira hook, regra de negação ou configuração gerenciada; o arquivo de instruções do projeto fica para orientação.
Entrega: proposta de regra para aprovaçãoCommits com motivo
Commits pequenos, com linha curta de resumo e o motivo da mudança, no padrão que o time escolher, como Conventional Commits.
Entrega: histórico do Git legível
02
Oito braços, um dossiê.
O mesmo ciclo do Octo, aplicado a esta etapa. Cada braço tem um papel estreito; quem comanda e aprova é o líder técnico da sua empresa.
-
Descoberta
Entrega o mapa
O que a descoberta levantou vira o mapa da plataforma no dossiê.
-
Dados
Entrega o modelo
O estudo do banco vira a página de banco do dossiê.
-
Segurança
Entrega os achados
Achados de segurança e riscos aceitos ficam registrados.
-
Arquitetura
Entrega as decisões
Cada decisão de arquitetura entra com data e motivo.
-
Desenvolvimento
Escreve commits claros
Mensagem com o resumo, o motivo e a referência da atividade.
-
Revisão
Confere a documentação
A documentação da entrega também passa pela revisão.
-
Publicação
Registra o deploy
Como se publica e como se confere fica no dossiê.
-
Documentação
Mantém o dossiê
Separa regra, conhecimento e estado, e atualiza o estado no fim do dia.
O Octo escreve e mantém; aprovar o que vira regra do projeto, definir o padrão de commit do time e validar a documentação entregue a terceiros é do líder técnico.
03
Quem faz o quê na documentação.
O que o escriba mantém e o que continua sendo decisão da sua equipe.
| Documento | Braço do Octo | Fica com o líder técnico |
|---|---|---|
| Dossiê do sistema | Escriba | Ler e corrigir |
| Decisões do projeto | Escriba | Aprovar o que vira regra |
| Mensagens de commit | Dev | Definir o padrão do time |
| Documentação da API | Dev, a partir da descrição OpenAPI | Validar o que vai para terceiros |
04
Do pedido à rotina.
Três degraus. Cada um só faz sentido depois que o anterior mostrou resultado na sua equipe.
Proposta, não promessa
Dossiê inicial
O escriba monta o dossiê a partir do que a descoberta levantou.
- Mapa da plataforma
- Banco e deploy
- Achados
Decisões com data
Cada decisão do projeto passa a ser registrada com data e motivo.
- Decisões registradas
- Estado do fim do dia
Regras que valem sempre
O que precisa acontecer sempre sai do texto e vira regra da ferramenta.
- Hooks e regras de negação
- Revisão periódica do dossiê
05
Confirmado em fonte.
Cada ponto abaixo tem fonte publicada pela organização responsável pela norma, pela especificação ou pela ferramenta, ou em lei federal. As fontes estão na seção seguinte.
7
pontos com fonte publicada, cada um com a referência indicada ao lado.
- ConfirmadoQualidade da documentação
- O DORA vê a qualidade da documentação impulsionando a adoção de cada uma das práticas técnicas que estudou.Fonte: DORA, qualidade da documentação
- ConfirmadoTrabalho contínuo
- Documentação precisa ser criada e mantida ativamente, e isso dá trabalho.Fonte: DORA, qualidade da documentação
- ConfirmadoArquivo de instruções
- O CLAUDE.md é um arquivo em markdown na raiz do projeto que o Claude Code lê no início de toda sessão.Fonte: Claude Code, visão geral
- ConfirmadoOrientação e regra
- O que precisa acontecer toda vez deve virar hook, regra de negação ou configuração gerenciada.Fonte: Claude Code, boas práticas
- ConfirmadoConventional Commits
- Conventional Commits 1.0.0 é uma especificação para dar significado legível por pessoas e por máquinas às mensagens de commit, no formato tipo, escopo opcional e descrição; fix casa com PATCH, feat com MINOR e BREAKING CHANGE com MAJOR, do SemVer.Fonte: Conventional Commits 1.0.0
- ConfirmadoMensagem de commit
- A documentação do Git sugere, sem exigir, começar a mensagem com uma linha curta de até 50 caracteres, uma linha em branco e a descrição.Fonte: Git, git-commit
- ConfirmadoOpenAPI e documentação
- A descrição OpenAPI pode ser usada por ferramentas de geração de documentação para mostrar a API.Fonte: OpenAPI Initiative, OAS 3.2.1
06
O que o Octo faz e o que fica com vocês.
O Octo prepara tudo, mas não assina. O documento que vale continua com quem responde por ele.
O Octo prepara
Mapeia, planeja, programa na branch da atividade, revisa com evidência e prepara a publicação: planos, código, revisões, relatórios de segurança e o dossiê do sistema.
Entrega: material pronto para conferirA sua equipe confere
Quem comanda é o líder técnico ou o desenvolvedor sênior da empresa: aprova o plano, revisa o PR e faz o merge. Nada vai para produção sem a aprovação de quem comanda.
Etapa: aprovação por quem comandaQuem assina e responde
O Octo não assina e não responde pelo sistema. Quem aceita o risco e responde pelo sistema em produção é o líder técnico; laudo ou parecer de segurança é assinado por profissional da empresa.
Responsável: líder técnico da empresa
07
Fontes.
DORA, documentação do Claude Code, Conventional Commits, documentação do Git e OpenAPI Initiative. Consultadas em 31/10/2026.
- DORA: qualidade da documentaçãoImpacto nas práticas técnicas
- Claude Code: visão geralCLAUDE.md lido no início da sessão
- Claude Code: boas práticasHook, regra de negação e configuração gerenciada
- Conventional Commits 1.0.0Formato da mensagem e relação com o SemVer
- Git: git-commitLinha de resumo da mensagem
- OpenAPI Initiative: OAS 3.2.1Uso por geradores de documentação
O sistema descrito e em dia.
O diagnóstico começa pelo que já está documentado na sua equipe, sem alterar nada. Você recebe a proposta do dossiê e decide com ela na mão.