# Workshop: Trabalhando com Claude Code no Cereus

> Roteiro para apresentação ao time de dev. Duração alvo: ~1h45-2h (conceitos + demo + prática + bootstrap
> em outro projeto). A Parte 6 é a mais longa de cortar se o tempo apertar — pode virar uma segunda sessão.
> Formato sugerido: compartilhar tela, abrir os arquivos reais mencionados ao vivo (não só ler slides).

---

## Objetivo do workshop

Mostrar que Claude Code, no Cereus, não é "um chat que escreve código" — é uma ferramenta configurada com
**regras, playbooks e memória específicos do nosso projeto**, que já geraram resultado real em produção
(as integrações CNAB Sicoob e Bradesco). O objetivo é que todo o time saia sabendo:

1. Os modos de uso essenciais (normal vs. Plan Mode).
2. Onde vivem as regras do projeto (`CLAUDE.md`, `.claude/rules/`) e por que elas existem.
3. Como e quando usar as *skills* `cereus-module` e `cereus-integration`.
4. Um caso real de sucesso — e por que ele funcionou mesmo com um dev com menos experiência em PHP.
5. Sair daqui tendo *efetivamente rodado* uma skill numa tarefa real (exercício prático).
6. **Saber montar esse mesmo tipo de ambiente do zero**, em qualquer stack — inclusive PHP puro sem
   framework — porque o mecanismo (`CLAUDE.md` + `rules/` + `skills/`) não é específico do Cereus nem de
   Laravel.

---

## Parte 1 — O que é Claude Code, na prática (≈15 min)

Conceitos essenciais, sem aprofundar no que é genérico demais:

- É um agente de terminal/IDE que lê e edita arquivos do projeto, roda comandos (com sua permissão) e mantém
  contexto sobre o repositório entre uma tarefa e outra.
- **Ele lê automaticamente** o `CLAUDE.md` do projeto a cada sessão — não é preciso colar regras no prompt
  toda vez. Isso é o que torna possível ter comportamento consistente entre diferentes devs usando a
  ferramenta no mesmo repo.
- **Modos de execução:**
  - **Modo normal** — Claude já faz as edições diretamente, pedindo aprovação pontual para ações
    sensíveis (rodar comando, editar arquivo fora do escopo, etc., dependendo da política de permissão).
  - **Plan Mode** — Claude **não edita nada**; ele investiga o código, monta um plano de implementação
    passo a passo e só executa depois que o dev aprova o plano. Essencial para tarefas grandes/ambíguas,
    onde você quer alinhar a abordagem *antes* de qualquer arquivo ser tocado.
  - **Skills** — playbooks reutilizáveis, acionados por nome (`/nome-da-skill`) ou automaticamente quando o
    pedido do dev casa com a descrição da skill. É o mecanismo central que o Cereus usa (ver Parte 3).
- **Memória entre sessões** — além do `CLAUDE.md` (sempre carregado), Claude pode guardar aprendizados
  específicos (preferências do time, decisões de arquitetura) que persistem entre conversas — vale mostrar
  rapidamente que isso existe, sem entrar em detalhes de implementação.

**Demo ao vivo sugerida:** abrir uma tarefa simples, mostrar o Claude entrando em Plan Mode, apresentar um
plano, e só então aprovar a execução — para o time visualizar a diferença entre "ele decide sozinho" e
"ele propõe, eu decido".

---

## Parte 2 — A estrutura `.claude/` do Cereus (≈15 min)

Tour guiado pela estrutura real do repositório (abrir os arquivos ao vivo):

```
.claude/
├── CLAUDE.md                 → regras globais, sempre carregadas
├── settings.local.json       → permissões (o que Claude pode rodar sem perguntar)
├── rules/                    → regras que só entram em contexto quando você mexe em paths específicos
│   ├── backend.md            (paths: app/**, resources/lang/**, database/**)
│   ├── auth.md                (paths: app/**, resources/views/**)
│   └── frontend.md           (paths: resources/js/**, resources/views/**)
└── skills/                   → playbooks sob demanda, para tarefas específicas
    ├── cereus-module/
    └── cereus-integration/
```

Esse é o ponto-chave para o time entender: **três camadas de contexto, cada uma com sua granularidade**.

| Camada | Quando carrega | Conteúdo |
|---|---|---|
| `CLAUDE.md` | Sempre, toda sessão | Comportamento geral, stack, arquitetura multi-tenant |
| `.claude/rules/*.md` | Só quando o arquivo tocado casa com o `paths:` do frontmatter | Convenções técnicas detalhadas por camada (backend, auth, frontend) |
| `.claude/skills/*/SKILL.md` | Sob demanda, quando a tarefa casa com a descrição da skill | Playbook completo passo a passo para um tipo de tarefa |

### O que tem em `CLAUDE.md` (abrir o arquivo ao vivo)

- **Comportamento:** nunca `git add/commit/push` (commit é do programador), nunca `npm run build` (o dev
  mantém `npm run dev` rodando), todo comando PHP/Artisan/Composer via `docker compose exec app <cmd>`
  (nunca no host), respostas concisas, e a regra mais importante para qualidade — **antes de implementar
  algo novo, perguntar se existe uma referência de implementação similar** (caminho absoluto de outro
  projeto, subpasta, ou arquivos passados pelo P.O.) e ler esses arquivos antes de começar.
- **Stack:** PHP 8.2+/Laravel 11, JS vanilla com `axios` global (nunca importar manualmente), Node
  v24.13.1 (sempre `nvm use`), MySQL strict mode.
- **Arquitetura multi-tenant:** `Person` como identidade central, `condominium_person.role` como fonte de
  verdade de acesso (staff/owner/tenant) — `users.user_type` foi removido, não deve ser referenciado.

### O que tem em `.claude/rules/` (path-scoped)

Vale mostrar rapidamente que essas regras só "aparecem" quando o dev está mexendo em arquivos daquele
tipo — é contexto sob demanda, não ruído o tempo todo:

- **`backend.md`** — GlobalScopes (`ClientScope`/`CondominiumScope`, sempre bypass por classe, nunca por
  string), padrão de paginação para Grid.js, convenção de rotas usando `{code}` (nunca `id` cru).
- **`auth.md`** — diferença entre `condominium_person.role` (GlobalScopes) e a tabela `Roles` (permissões de
  módulo via `Groups`), uso de `is_master`, e um alerta real de segurança: `PersonEmployee` não tem
  `ClientScope`/`CondominiumScope`, então query sem filtro vaza dados entre clientes.
- **`frontend.md`** — nunca `@vite()`/`@push('scripts')` em Blade (JS carrega via `switch` em `app.js`),
  `window.grid = grid` obrigatório, `FormHandler` obrigatório para forms, nunca `fetch()` nativo.

### `settings.local.json`

Mostrar rapidamente que é aqui que ficam as permissões (o que Claude pode rodar sem perguntar). No Cereus
hoje não há `.claude/agents/`, `.claude/commands/` nem hooks configurados — é uma estrutura **enxuta e
disciplinada**: toda a "inteligência" está concentrada em `CLAUDE.md` + `rules/` + `skills/`, não em
automações adicionais. Vale deixar claro para o time que isso é uma escolha, não uma limitação — dá pra
crescer para agents/commands/hooks depois, se fizer sentido.

---

## Parte 3 — As Skills na prática: `cereus-module` e `cereus-integration` (≈20 min)

### Por que skills, e não só pedir no chat?

Sem uma skill, cada dev (e cada sessão do Claude) reinventa a abordagem: esquece de perguntar sobre
multi-tenancy, esquece traduções, esquece de registrar o módulo no `app.js`. A skill fixa um **checklist e
uma sequência de perguntas obrigatórias** — o resultado fica consistente independente de quem está
pilotando o Claude.

### `cereus-module` — playbook para qualquer módulo (CRUD, read-only, modal-driven, wizard, relatório)

Antes de escrever qualquer código, a skill obriga o Claude a perguntar:

1. **Tipo de módulo** — CRUD completo, read-only, modal-driven, wizard ou relatório?
2. **Escopo do auto-código** — o dado é por condomínio (`condominium_id`) ou compartilhado por toda a
   administradora (`client_id`)? Isso muda migration, GlobalScopes e geração de sequência.
3. **Precisa de API** — endpoints REST (grid/create/update/delete) ou só rotas web?
4. **Campos especiais** — moeda, CPF/CNPJ/RUC, telefone internacional, upload de imagem?

A partir das respostas, aplica um checklist de 13 passos (migration → model → service → controller web →
controller API → rotas → blade index → blade form → JS list → JS form → registro em `app.js` →
traduções → `RolesSeeder`/sidebar) — **pulando os passos que não se aplicam** (ex.: read-only pula form e
toggle; modal-driven pula as páginas de form dedicadas).

O ponto mais importante para o time: a skill aponta para **implementações maduras já existentes no
código** como referência obrigatória — `DynamicReportService` (service), `banks-form.js`/`people-form.js`
(JS form), `banks-list.js` (JS list), `error-handlers.js` (tratamento de erro), `FormHandler` (submit). Ou
seja: a skill não inventa padrão do zero, ela **aponta para o melhor exemplo real do próprio Cereus**.

### `cereus-integration` — playbook para integrar um banco (REST API ou CNAB 240)

Mesma lógica de perguntas obrigatórias antes de codar:

1. Método — API REST ou CNAB 240?
2. Se API — tipo de autenticação (OAuth, `client_credentials`, API key)?
3. Se CNAB — remessa completa ou boleto avulso?
4. Existe sandbox/homologação?
5. **Como a documentação do banco será fornecida** — a skill oferece 3 opções explícitas: `.md` (recomendado,
   leitura confiável), `.pdf` (aceito, mas alerta que tabelas podem sair deformadas) ou nenhuma
   documentação (Claude pergunta campo a campo).

Depois disso, um checklist de 7 passos: enum do banco (`app/Enums/Bank.php`) → service em
`Api/` ou `Cnab/` → registrar no `match()` de `ConsolidatedBoletoService::getIntegrationService()` →
registro em `layouts` → credenciais sandbox via UI → caso de teste em `testBankIntegration()` → validar via
UI.

O ponto-chave de arquitetura que vale explicar ao vivo: **um único ponto de resolução** decide qual classe
trata qual banco — adicionar um banco novo é só somar um `case` no `match()`, nunca espalhar `if`s pelo
código. CNAB usa Template Method (`BaseCnabService`; um banco novo só sobrescreve `calcularCampoLivre()`),
API usa um contrato próprio com token cacheado por banco.

---

## Parte 4 — Caso real de sucesso: Sicoob → Bradesco (≈10 min)

Esse é o argumento mais forte do workshop: **a estrutura não é teoria, ela já entregou em produção — e
permitiu que um dev com menos experiência em PHP replicasse o resultado sozinho.**

### Linha do tempo (verificada no histórico do git)

| Data | O quê | Ticket |
|---|---|---|
| 2026-04-20 → 2026-05-12 | CNAB Sicoob: serviço CNAB, cálculo de campo livre, e o módulo de **Remessas** (geração de arquivo CNAB 240) — a entrega "flagship" | `cereus-203` (retornos) + `cereus-222` (remessa) |
| 2026-06-30 | CNAB **Bradesco**, integração completa, em **um único commit**, no **mesmo dia** em que a PR foi aberta e mergeada | `cereus-244` |

A integração do Bradesco foi feita por um dev com menos experiência em PHP, **usando a mesma skill
(`cereus-integration`), as mesmas rules e a mesma estrutura `.claude/`** já preparadas a partir da
experiência com o Sicoob.

### A prova mais forte: o padrão se repetiu, literalmente

O próprio código institucionalizou o padrão que a skill ensina. `ConsolidatedBoletoService.php` documenta
isso em um docblock (mostrar ao vivo):

```php
/**
 * Resolve o serviço de integração baseado no método (api/cnab) e no banco.
 *
 * Para adicionar suporte a um novo banco:
 *   API : crie Api/{Banco}ApiService   e adicione o case no match de API abaixo.
 *   CNAB: crie Cnab/{Banco}CnabService e adicione o case no match de CNAB abaixo.
 */
```

E o `match()` recebeu o Bradesco exatamente como documentado, no mesmo formato usado para o Sicoob — e essa
mesma adição de `case` se repete **em três arquivos diferentes** (`ConsolidatedBoletoService`,
`BoletosService`, `APIConsolidatedBoletosController`), sempre no mesmo padrão:

```php
return match ($type) {
    'SICOOB'   => new SicoobCnabService(),
    'BRADESCO' => new BradescoCnabService(),
    default    => new BaseCnabService(),
};
```

`BradescoRemessaService` (462 linhas) segue **método a método** a mesma estrutura de
`SicoobRemessaService` (451 linhas) — só o conteúdo específico dos segmentos CNAB 240 muda. Ou seja: o dev
com menos experiência em PHP não teve que decidir arquitetura nenhuma — a skill + o exemplo do Sicoob já definiam exatamente o
que copiar e o que adaptar.

### E foi além: a integração do Bradesco superou a do Sicoob

Ponto interessante para reforçar a mensagem de que a estrutura *não* limita a um "copiar e colar cego":
o dev do Bradesco implementou `BradescoReturnService.php`, que processa automaticamente o arquivo de
retorno (baixa automática de título). **O Sicoob, até hoje, não tem esse serviço** — o comentário no código
diz explicitamente que retornos de outros bancos CNAB "aguardam implementação futura". Ou seja: o dev
com menos experiência em PHP não só replicou o padrão, como **estendeu a funcionalidade além do que já existia**, com segurança,
porque a skill e as rules já garantiam o alicerce (interface comum, error flow, GlobalScopes) — ele só
precisou focar na parte realmente nova.

**Mensagem para o time:** a estrutura `.claude/` não é sobre "deixar o Claude fazer sozinho" — é sobre
codificar o conhecimento de quem já fez a primeira integração difícil, para que a segunda (e a terceira)
sejam rápidas e seguras mesmo para quem tem menos experiência no projeto.

---

## Parte 5 — Exercício prático guiado (≈25-30 min)

**Regra de ouro do exercício:** ninguém commita nada. O `CLAUDE.md` já impede o Claude de rodar
`git add/commit/push`, mas por segurança faça todo o exercício numa branch descartável
(`git checkout -b workshop-exercicio-<seu-nome>`) que ninguém vai dar merge.

### Opção A — Rodar a skill `cereus-module` num módulo fictício

Peça para o Claude, no seu próprio checkout, algo como:

> "Preciso criar um módulo de read-only para listar 'Ocorrências de Portaria' por condomínio, sem API."

Objetivo do exercício: observar o Claude **fazendo as 4 perguntas de clarificação antes de codar** — se ele
pular direto para o código sem perguntar, é sinal de que algo no contexto não carregou (bom gancho para
debug ao vivo). Depois, comparar o plano/checklist gerado com a tabela de referências maduras do
`cereus-module/SKILL.md`.

### Opção B — Simular a chegada de "mais um banco" via `cereus-integration`

Peça para o Claude:

> "Quero integrar o banco Itaú via CNAB 240, tenho um manual em PDF, ainda não sei se tem sandbox."

Objetivo: ver a skill perguntar sobre método/autenticação/documentação **antes** de tocar em qualquer
arquivo, e apontar para `SicoobCnabService`/`SicoobRemessaService` como referência — a mesma referência que
guiou o Bradesco.

### Debrief (5 min)

Perguntas para abrir a discussão com o time:
- Em algum momento o Claude tentou pular uma pergunta de clarificação ou inventar um padrão em vez de
  apontar para um arquivo real do projeto?
- O plano proposto (Plan Mode) bateu com o checklist da skill?
- Que outras skills fariam sentido documentar (ex.: um playbook para relatórios, ou para a criação de
  wizards multi-step)?

---

## Parte 6 — Como montar esse ambiente do zero em outro projeto (≈20-25 min)

Até aqui o workshop mostrou como **usar** uma estrutura já pronta. Esta parte é sobre como **construir**
essa mesma estrutura em um projeto novo — inclusive um projeto **PHP puro, sem framework**, onde não existe
Eloquent, Blade nem nada parecido. O mecanismo (`CLAUDE.md` + `rules/` + `skills/`) não é específico do
Cereus nem de Laravel — só o *conteúdo* muda.

### O Cereus não nasceu assim — e a própria história dele é a melhor aula

Antes de ensinar o método, vale mostrar ao vivo (`git log --follow --oneline -- GEMINI.md` e
`-- .claude/CLAUDE.md`) que essa estrutura em 3 camadas foi o resultado de **~4 meses de iteração**, não de
um planejamento inicial perfeito:

| Quando | O que aconteceu |
|---|---|
| 2026-02-26 | Primeira peça, um mês *antes* de existir qualquer arquivo de regras: um manual em PDF de um banco (Sicredi) foi convertido em markdown por tópico (`docs/sicredi-api-documentation-llm-optimized/`) — "documentação em estrutura md para consumo de agents". |
| 2026-03-26 | Nasce um arquivo único de regras (na época, `GEMINI.md`, em inglês, para uma ferramenta de agente diferente) — persona, stack, arquitetura multi-tenant, convenções de banco. |
| 2026-04-15 | Maior salto de conteúdo (+848 linhas numa única alteração) — introduz o playbook de criação de módulo **e** uma tabela de "implementações de referência por maturidade" (bom exemplo vs. anti-padrão), com o próprio commit avisando: *"Não testado, usar com cautela em pequenos ajustes... para validar se as rules estão maduras."* |
| 2026-05-31 | O arquivo tinha passado de **1300 linhas** — inchado demais para ser confiável. Purga completa: reescrito do zero, compacto, em português. No mesmo dia, esse conteúdo é bifurcado para `.claude/CLAUDE.md` (a estrutura do Claude Code) e a parte mais processual (o playbook de módulo) vira a primeira skill, `cereus-module`. |
| 2026-06-22 | Só **22 dias depois**, quando `CLAUDE.md` cresceu de novo, o conteúdo "sempre relevante mas grande" foi separado em `.claude/rules/*.md` (path-scoped) — e nasce a segunda skill, `cereus-integration`. |
| até 2026-06-30 | `.claude/CLAUDE.md`/`rules/` seguem recebendo ajustes — sempre **junto** com um commit de código real (nunca uma sessão de "documentação" isolada). |

O arquivo antigo (`GEMINI.md`) ficou congelado como um stub de poucas linhas por quase 50 dias até ser
apagado — **literalmente durante a preparação deste workshop**, quando reparamos nele e confirmamos que
não tinha mais dono. É um exemplo real e recente do que acontece quando você não limpa depois de trocar de
ferramenta: documentação órfã que ninguém sabe se ainda vale.

### O método, generalizado (o que replicar em um projeto novo)

1. **Docs externas primeiro, sempre.** Se existe documentação de terceiros que o agente vai precisar
   (manual de API, RFC, especificação de integração), transforme em markdown por tópico *antes* de escrever
   qualquer regra — não jogue um PDF cru para o agente interpretar toda vez.
2. **Não escreva o arquivo de regras sozinho — peça para o Claude extrair.** Em vez de digitar as
   convenções de memória, mostre 2-3 implementações reais já existentes (ou, num projeto novo, o padrão que
   você quer estabelecer) e peça para o Claude ler e resumir os padrões em um rascunho de `CLAUDE.md`. Você
   revisa e corrige — mas o primeiro rascunho sai muito mais fiel ao código real assim do que escrito do
   zero.
3. **Diga explicitamente onde ficam as coisas transversais**: traduções/i18n, tratamento de erro,
   autenticação, convenção de rotas. Isso é o que virou as seções "Global Scopes", "Identificação & Rotas" e
   "Frontend" no Cereus — sem isso, cada sessão do Claude reinventa o próprio jeito de fazer.
4. **Assim que houver módulos suficientes para comparar, curadoria de "referência madura" vs.
   anti-padrão.** Não é opcional — o próprio Cereus perdeu tempo com isso quando uma versão antiga da
   documentação apontava para um controller de baixa qualidade como exemplo, e agentes replicaram o padrão
   ruim em módulos novos até alguém perceber e corrigir.
5. **Comece já separando por granularidade — não espere o arquivo passar de 1300 linhas para descobrir
   isso da forma difícil:**
   - `CLAUDE.md` → só o que é relevante em **toda** sessão (persona, stack, arquitetura central).
   - `.claude/rules/*.md` (com `paths:` no frontmatter) → convenções detalhadas que só importam quando se
     mexe naquela camada (ex.: regras de frontend só carregam ao editar `resources/js/**`).
   - `.claude/skills/*/SKILL.md` → playbooks de várias etapas para um tipo de tarefa recorrente (criar um
     módulo, integrar um serviço externo) — com perguntas de clarificação obrigatórias antes de codar.
6. **Valide em algo pequeno antes de confiar.** Peça para o Claude usar a skill recém-criada num módulo de
   teste, sem risco, antes de aplicar em uma feature real — exatamente a cautela que o próprio Cereus
   registrou no commit que introduziu o playbook de módulos.
7. **Mantenha a documentação viva junto do código, nunca isolada.** No histórico do Cereus, toda atualização
   relevante de `CLAUDE.md`/`rules`/`skills` aconteceu no mesmo commit de uma mudança de código real (ex.:
   ao trocar o padrão de import do axios, ou ao remover `users.user_type`) — nunca como uma tarefa de
   "documentação" à parte, que tende a ficar pra depois e nunca sair.
8. **Se trocar de ferramenta, não deixe o arquivo antigo órfão.** Migre o conteúdo e apague o antigo (ou
   deixe um único ponteiro claro) — não deixe dois arquivos de regras coexistindo silenciosamente por
   semanas, como aconteceu aqui.

### E se o novo projeto for PHP puro, sem framework?

A mecânica não muda — só o conteúdo do passo 2/3 muda:
- Sem Eloquent/Blade, as seções vão descrever **os padrões que existem de fato no seu código**: como você
  conecta no banco (PDO puro? um wrapper próprio?), onde ficam as classes de validação, como o roteamento é
  feito (um front controller manual? `.htaccess` + switch?), onde estão as strings traduzíveis.
- Se o projeto for pequeno o suficiente para não ter "camadas" bem definidas ainda, **isso é ok** —
  comece só com `CLAUDE.md` (sem `rules/` nem `skills/`) e adicione as outras camadas quando sentir a dor
  real de arquivo grande demais ou tarefa repetitiva demais, do jeito que o Cereus fez.

---

## Referência rápida (deixar fixado/compartilhado após o workshop)

- Regras sempre carregadas: `.claude/CLAUDE.md`
- Regras por contexto (path-scoped): `.claude/rules/{backend,auth,frontend}.md`
- Skill de módulos: `.claude/skills/cereus-module/SKILL.md` (+ `references/`)
- Skill de integrações bancárias: `.claude/skills/cereus-integration/SKILL.md` (+ `references/`)
- Caso de sucesso para citar sempre que alguém duvidar do processo: **Sicoob → Bradesco**
  (`app/Services/Bank/BankIntegration/Cnab/{Sicoob,Bradesco}*.php`, e o `match()` em
  `ConsolidatedBoletoService.php`).
- Histórico completo da evolução do próprio ambiente de agente (útil pra citar/mostrar ao vivo na Parte 6):
  `git log --follow --oneline -- .claude/CLAUDE.md` e `git log --follow --oneline -- GEMINI.md` (arquivo já
  removido do repo, mas o histórico continua acessível via git).
