chshzh/charlie-claude

Fluxo de Trabalho de Commits Git

Regras Críticas

1. Inspecione antes de commitar: Sempre execute git diff . para revisar toda a árvore de trabalho antes de propor ou criar qualquer commit.
2. Planeje primeiro, commite depois: Apresente um plano de commits (arquivos agrupados, justificativa, mensagens sugeridas) e aguarde a aprovação explícita do usuário antes de executar git commit.
3. Divida por alteração lógica: Separe os commits por assunto — não misture correções não relacionadas, refatorações, documentação, alterações apenas de formatação ou arquivos gerados, a menos que o usuário solicite explicitamente.
4. Sem comandos interativos: Use apenas comandos Git não interativos.
5. Nunca presuma permissão: Trate qualquer solicitação de "commitar alterações" como permissão para inspecionar e planejar, não como permissão para executar git commit.

Fluxo de Trabalho

Etapa 1 — Inspecione a árvore de trabalho

git diff .
git status --short
git diff --cached   # apenas se houver alterações em staged

Etapa 2 — Proponha um plano de commits

Apresente uma tabela ou lista mostrando:

• Grupo: o conjunto de arquivos para cada commit proposto
• Justificativa: por que esses arquivos pertencem juntos
• Mensagem de commit sugerida: use o estilo correto para o repositório (veja Formatos de Mensagem de Commit abaixo)

Etapa 3 — Aguarde aprovação

Após apresentar o plano, use a ferramenta AskQuestion para coletar a aprovação. Sempre ofereça estas opções:

Pergunta: "Prosseguir com este plano de commits?"
Opções:
  - "Aprovar — commitar conforme planejado"
  - "Editar mensagens de commit primeiro"
  - "Reagrupar os commits"
  - "Cancelar"

Não execute git commit até que o usuário selecione Aprovar. Trate qualquer outra seleção como uma solicitação para revisar o plano.

Etapa 4 — Execute os commits aprovados

Para cada commit aprovado, adicione ao stage apenas os arquivos relevantes e faça o commit:

git add <arquivo1> <arquivo2> ...
git commit -s -m "tipo(escopo): descrição"

Use um HEREDOC para mensagens com múltiplas linhas quando necessário:

git commit -s -m "$(cat <<'EOF'
tipo(escopo): resumo curto

- detalhe linha 1
- detalhe linha 2
EOF
)"```

## Formatos de Mensagem de Commit

### Detecte o tipo de repositório primeiro

| Repositório | Estilo |
|---|---|
| Repositório de aplicativo do usuário (projeto próprio) | Conventional Commits |
| `zephyr/`, `nrf/`, `nrfxlib/`, `modules/` | Estilo Zephyr |

### Repositórios de Aplicativo do Usuário — Conventional Commits

tipo(escopo): resumo curto

Tipos comuns: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`, `build`. Título ≤ 72 caracteres. Corpo opcional, mas útil para alterações não triviais.

### Repositórios NCS / Zephyr — Estilo Zephyr

[tag nrf] área: subárea: resumo curto

Corpo explicando o quê, por quê, suposições e como foi verificado.

PR upstream #: NNNNN (se portado do upstream) Ref: NCSDK-XXXXX (se rastreando um ticket interno) Assisted-by: Claude:claude-sonnet-4.6 (se assistido por IA) Signed-off-by: Nome Completo

- Título ≤ 72 caracteres; **corpo é obrigatório** (não vazio) para qualquer contribuição upstream
- Linhas do corpo ≤ 75 caracteres
- `Signed-off-by:` obrigatório (DCO) — use `git commit -s`
- Tags de prefixo NRF: `[nrf fromlist]` (para upstream), `[nrf fromtree]` (do upstream), `[nrf noup]` (apenas NCS), `[nrf ncsdk]` (apenas SDK)
- Adicione `Assisted-by:` quando a IA escreveu código substancial

**Exemplos:**

[nrf fromlist] drivers: nrf_wifi: adicionar tipo de segurança WPA3-AUTO

O wpa_supplicant requer um valor de enumeração key_mgmt dedicado para modo WPA3-AUTO. Sem isso, estações anunciando ambos WPA2 e WPA3 falham na troca de chaves.

PR upstream #: 106674 Signed-off-by: Seu Nome [email protected]

[nrf noup] testes: my_module: adicionar teste unitário para buffer de tamanho zero

Testa a condição de contorno onde o comprimento do buffer de entrada é igual a zero, que anteriormente disparava uma asserção no analisador.

Ref: NCSDK-12345 Signed-off-by: Seu Nome [email protected]

## Diretrizes de Agrupamento

| Tipo de alteração | Commit separado? |
|---|---|
| Novo código de funcionalidade | Sim |
| Correção de bug | Sim |
| Refatoração (sem mudança de comportamento) | Sim |
| Alterações de configuração / Kconfig | Sim (ou com a funcionalidade relacionada) |
| Documentação / README | Sim (a menos que esteja fortemente acoplado a uma funcionalidade) |
| Apenas formatação / espaços em branco | Sim |
| Arquivos gerados / atualizados automaticamente | Sim |
| Overlay de placa + prj.conf correspondente | Pode agrupar juntos |
| Arquivos Sysbuild | Agrupar por propósito lógico |

## Notas Específicas do NCS

**Agrupamento de arquivos:**
- `prj.conf`, `boards/*.conf`, `overlay-*.conf` — agrupar com a funcionalidade que habilitam
- Alterações em `CMakeLists.txt` — commit separado, a menos que faça parte trivial de uma adição de funcionalidade
- Alterações em `west.yml` — sempre um commit separado com uma justificativa clara
- Arquivos `sysbuild/` — agrupar por propósito lógico (ex.: alterações de configuração do mcuboot juntas)
- Arquivos gerados pelo gerenciador de partição (`pm/`, `*.map`) — commit separado do tipo `chore` ou omitir se não forem significativos

**Em repositórios NCS/Zephyr (`zephyr/`, `nrf/`, `nrfxlib/`):**
- Use o estilo Zephyr (veja acima), não Conventional Commits
- Sempre inclua um corpo não vazio — a CI rejeitará corpos vazios para PRs upstream
- Execute `git log -- <arquivo>` para ver como outros formataram commits para o mesmo subsistema

## Dividindo Alterações Dentro de um Único Arquivo

Quando um arquivo contém duas ou mais alterações logicamente distintas que pertencem a commits separados (ex.: uma correção de bug + uma nova seção de política), divida-as sem staging interativo:

1. Remova temporariamente a seção *posterior* do arquivo (Python ou StrReplace)
2. Adicione ao stage e commit a *primeira* alteração
3. Restaure a seção removida
4. Adicione ao stage e commit a *segunda* alteração

```python
MARCADOR = "\n## Política de Autoatualização\n"
texto = path.read_text()
path.write_text(texto[:texto.find(MARCADOR)])  # remove seção posterior
# → git add + commit "fix: ..."
path.write_text(texto)                          # restaura conteúdo completo
# → git add + commit "feat: ..."

Por quê: git log -p <arquivo> então mostra cada alteração lógica em seu próprio commit — mais fácil de bisectar, revisar ou reverter independentemente.

Armadilha: Sempre verifique se o marcador está antes das linhas de fechamento da função/bloco. Se o marcador for a última instrução em uma função, o arquivo removido estará sem return e }, causando erros expected declaration or statement at end of input.

Política de Autoatualização

Ao final de cada conversa, revise o que foi descoberto e verifique se algum fato nesta habilidade é novo, corrigido ou desatualizado (ex.: novos padrões de agrupamento, convenções específicas de arquivos do NCS, convenções de mensagens de commit).

Se atualizações forem necessárias:

1. Colete todas as alterações propostas com uma breve justificativa para cada.
2. Apresente um resumo ao usuário e peça aprovação usando AskQuestion.
3. Aplique as atualizações aprovadas neste arquivo imediatamente.

Não modifique esta habilidade no meio da conversa, a menos que o usuário solicite explicitamente.