# AGENTS.md

## Project Skills

## Convenções obrigatórias de Python / OO

Todo código Python em `code/engine/` deve seguir a skill **`.agents/skills/boas-praticas-oo/SKILL.md`** (boas práticas de programação orientada a objetos) — obrigatória, aplicada automaticamente, não apenas quando solicitada. Leia-a antes de criar, modificar, corrigir, revisar, refatorar ou ampliar qualquer sistema Python.

Resumo das regras vinculantes:

- **PT-BR obrigatório** em todos os identificadores internos (classes, métodos, variáveis, atributos, parâmetros, constantes, arquivos, pastas, módulos), docstrings, comentários, logs, mensagens de erro e documentação. Identificadores externos (bibliotecas, APIs, contratos) são preservados e isolados em adaptadores/integrações.
- **Nomenclatura**: classes `PascalCase`; métodos, funções, variáveis e arquivos `snake_case`; constantes `MAIÚSCULAS_COM_SUBLINHADO`. Evitar nomes genéricos (`Util`, `Helper`, `Manager`, `Data`).
- **Documentação obrigatória**: docstring no topo de todo módulo, classe e método público, mantida coerente com o comportamento real (documentação viva).
- **Arquitetura**: responsabilidade única, alta coesão, baixo acoplamento, composição antes de herança, herança só com especialização real, encapsulamento, interfaces pequenas, injeção de dependências, métodos pequenos e objetivos.
- **Domínio**: regras de negócio ficam no domínio/aplicação, nunca misturadas com interface, SQL, HTTP ou apresentação. Integrações externas isoladas em módulos próprios.
- **Erros e segurança**: tratar erros com exceções específicas (nunca `except Exception: pass`), validar toda entrada externa, não registrar credenciais, não duplicar regras, retornos previsíveis.
- **Testes**: toda funcionalidade relevante deve ter testes (unitário, integração, regressão); criar/atualizar teste ao corrigir bug.
- Seguir o **checklist obrigatório** (seção 41 da skill) antes de finalizar qualquer implementação.

## Interface do painel

Quando o usuário pedir uma implementação “na tela”, “no painel” ou “na interface do MCP”, use o painel CEP em `code/cep-plugin/`, identificado por **MCP for Adobe Premiere Pro** e pelas abas **Editar vídeo**, **Scanner**, **Conexão**, **Modelos** e **Ajustes**. Essa é a interface de produto; não criar fluxos de interface alternativos em `code/uxp-plugin/`.

Este projeto usa skills do mattpocock/skills para manter integridade e organização do código.

### Skills disponíveis

| Skill | Trigger | Descrição |
|-------|---------|-----------|
| `improve-codebase-architecture` | `/improve-codebase-architecture` | Escaneia oportunidades de melhoria no codebase |
| `codebase-design` | `/codebase-design` | Projetar módulos profundos (muita funcionalidade, interface simples) |
| `domain-modeling` | `/domain-modeling` | Constrói vocabulário compartilhado no projeto |
| `tdd` | `/tdd` | Test-driven development - garante que código funciona antes de commitar |
| `code-review` | `/code-review` | Revisão automática de diffs (Standards + Spec) |
| `diagnosing-bugs` | `/diagnosing-bugs` | Loop disciplinado para debugar bugs complexos |
| `resolving-merge-conflicts` | `/resolving-merge-conflicts` | Resolve conflitos git hunk por hunk |

### Uso

- Para escanear melhorias: `/improve-codebase-architecture`
- Para projetar módulos: `/codebase-design`
- Para modelar domínio: `/domain-modeling`
- Para TDD: `/tdd`
- Para revisão de código: `/code-review`
- Para debugar bugs: `/diagnosing-bugs`
- Para resolver conflitos: `/resolving-merge-conflicts`

### Skills globais

Skills adicionais estão disponíveis globalmente em `~/.agents/skills/` (outras 29 skills)...