João HenriqueandClaude Opus 5
dcdd73edb5
A documentação descrevia um sistema que não existe mais: 62/73 ferramentas
(são 74), writer.py e models.py como arquivos (viraram pacotes), 1032 testes
(são 1454), models_api.py descrito como "API FastAPI" (é ponte JSON) e o app
SwiftUI ausente por completo — 5.500 linhas que o usuário opera todo dia sem
uma linha de documentação.
Cada arquivo passa a ter uma função específica, com cabeçalho de escopo
dizendo o que cobre e o que NÃO cobre (com a seta para quem cobre). O objetivo
é ler só o necessário: doc fora do assunto custa tempo e processamento sem
entregar nada.
01 arquitetura camadas, duas portas de entrada, regras transversais
02 módulos mapa do engine, incluindo o pipeline de voz
03 server/tools as 74 tools, helpers e como criar uma nova
08 app macOS NOVO — build por swiftc, telas, ponte, etapa 5
09 manutenção NOVO — por onde começar, o que está aberto, sintoma→arquivo
CLAUDE.md ganha a seção "Documentação (MANDATORY)": tabela de roteamento
(qual arquivo abrir para cada tarefa) e a regra de que toda alteração de
código atualiza a doc no mesmo commit, com o mapa de o-que-mexeu → o-que-
atualizar. Doc velha engana mais que doc ausente.
O índice do 05_EXPERIENCIAS subiu para o topo: consultar "isso já quebrou
antes?" custava carregar 1.281 linhas antes de chegar na tabela.
Dívidas levantadas na varredura e registradas em 09 §2: etapa 6 ainda ignora
o phrase_review.json, offset de ~400ms do Whisper, MacApp sem teste, admin/
fora do lint, confirmações visuais pendentes no FCP, submódulo WHISPERX sujo.
Também corrigidos dois links quebrados no Engine/README que apontavam um
nível acima do certo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
# 06 — Boas Práticas de Programação (G-ART)
|
|
|
|
> **Escopo:** Checklist de qualidade a aplicar antes de dar algo por pronto.
|
|
> **Não cobre:** Por onde começar uma tarefa (→ 09) · o que já quebrou (→ 05)
|
|
|
|
> **Propósito:** registrar as melhores práticas de programação a serem aplicadas
|
|
> **sempre** que qualquer alteração ou correção for feita neste programa.
|
|
> Servem de checklist obrigatório antes de concluir qualquer mudança.
|
|
|
|
**Regra:** antes de considerar uma alteração concluída, confira os itens abaixo.
|
|
Eles são o mesmo espírito do fluxo de validação pós-correção
|
|
(`Engine/run_after_fix.sh`), mas cobrem também **qualidade de código** e
|
|
**convenções do projeto**.
|
|
|
|
---
|
|
|
|
## 1. Correções de código
|
|
|
|
1. **Sempre valide após corrigir** — rode `./Engine/run_after_fix.sh` (lint +
|
|
testes). Nunca declare uma correção pronta sem que lint e a suíte passem.
|
|
2. **Toda correção já corrigida vira registro** — registre o problema em
|
|
`Engine/docs/05_EXPERIENCIAS.md` para que não se repita.
|
|
3. **Mude o mínimo necessário** — altere apenas o que resolve o problema; evite
|
|
refatorar código não relacionado na mesma mudança.
|
|
|
|
## 2. Tempo e FCPXML
|
|
|
|
4. **Nunca use `float` para tempo** — toda duração/offset é `TimeValue`
|
|
(fração racional `"600/2400s"`). Float introduz erro de arredondamento.
|
|
5. **`offset` é a posição na timeline; `start` é o in-point na origem** — não
|
|
confundir nas edições de clip.
|
|
6. **Markers são filhos dos clips, não irmãos** — e `<spine>` é a storyline
|
|
primária; connected clips penduram-se com atributo `lane`.
|
|
7. **Preserve sidecars em bundles `.fcpxmld`** — ao gravar um bundle, copie os
|
|
arquivos de dados; caso contrário destrói object-tracking/Cinematic.
|
|
|
|
## 3. Estrutura e arquitetura
|
|
|
|
8. **Mantenha o núcleo desacoplado** — `fcpxml/` não conhece o protocolo MCP;
|
|
`server.py` é a camada de transporte. Não vazem lógica MCP para o núcleo.
|
|
9. **Use o padrão de dispatch** — sem cadeias gigantes de `if/elif`; use
|
|
`TOOL_HANDLERS` (dicionário nome → handler assíncrono).
|
|
10. **Reaproveite os helpers centrais** — `_parse_project()`, `_resolve_io_paths()`,
|
|
`_setup_modifier()`, etc. Não duplique parse/validação de caminho.
|
|
11. **Nunca sobrescreva o original** — use `generate_output_path()` e crie
|
|
`_modified`, `_chapters`, etc.
|
|
12. **Mantenha o `MarkerType` como single source of truth** — a serialização
|
|
(parse/escrita) vive no enum, não espalhada por handlers.
|
|
|
|
## 4. Segurança
|
|
|
|
13. **Sempre use `safe_xml.py` (defusedxml)** — todos os entry points de parse;
|
|
jamais `xml.etree` cru com input não confiável.
|
|
14. **Valide caminhos com `_validate_filepath` / `_validate_output_path`** — o
|
|
sandbox de I/O existe para impedir escrita fora do permitido.
|
|
15. **Rejeite payloads excessivamente aninhados** — `_check_json_depth` protege
|
|
contra payloads além de 50 níveis.
|
|
16. **Nunca registre/commite segredos ou chaves** — nem em logs, nem em código.
|
|
|
|
## 5. Qualidade e clareza
|
|
|
|
17. **Sem comentários desnecessários** — código deve ser autoexplicativo;
|
|
comente o *porquê*, não o *o quê*.
|
|
18. **Mimice as convenções do projeto** — mesma estrutura de imports, nomes,
|
|
padrões e bibliotecas já usadas nas vizinhas.
|
|
19. **Lazy import de dependências opcionais** — `media_intel` (librosa) e
|
|
`transcribe` (Whisper) importam sob demanda e degradam com graça (`None`).
|
|
20. **Convenções de teste** — use `examples/sample.fcpxml` + fixtures XML inline;
|
|
`sample.fcpxml` NÃO é DTD-conformante, não o use como fixture de validade DTD.
|
|
|
|
## 6. Checklist final antes de concluir uma alteração
|
|
|
|
- [ ] `./Engine/run_after_fix.sh` passou (lint zero erros + todos os testes).
|
|
- [ ] Problema registrado em `Engine/docs/05_EXPERIENCIAS.md` (se aplicável).
|
|
- [ ] Nenhum `float` usado em matemática de tempo.
|
|
- [ ] Nenhum caminho original sobrescrito.
|
|
- [ ] `safe_xml.py` usado em todo parse de input não confiável.
|
|
- [ ] Nenhum segredo registrado ou commitado.
|
|
- [ ] Mudança mínima, sem refatoração não relacionada.
|
|
- [ ] Boa prática nova aprendida adicionada a esta lista.
|