|
| 1 | +# DeepCode CLI — Plano de Contribuição |
| 2 | + |
| 3 | +## Por que contribuir |
| 4 | + |
| 5 | +- Ferramenta artesanal, poucos devs, poucas skills bundled |
| 6 | +- O gap principal é de **prompt/guidelines**, não de runtime — e isso é meu forte |
| 7 | +- Já mapeei os internals: cada prompt, skill, template |
| 8 | +- Meus system prompts (AGENTS.md + skills) levaram output de 6.5/10 → 9/10 |
| 9 | +- Já uso a API DeepSeek que é o target principal da ferramenta |
| 10 | +- Contribuições teriam impacto desproporcional no projeto |
| 11 | + |
| 12 | +## Estado atual do built-in |
| 13 | + |
| 14 | +### O que o DeepCode tem (pouco) |
| 15 | + |
| 16 | +``` |
| 17 | +templates/ |
| 18 | +├── prompts/init_command.md.ejs → gera AGENTS.md inicial (45 linhas) |
| 19 | +├── tools/*.md → descrição das 6 tools (bash, read, write, edit, etc.) |
| 20 | +└── skills/karpathy-guidelines.md → 72 linhas, puramente comportamental |
| 21 | +
|
| 22 | +bundled/ |
| 23 | +├── plan/SKILL.md → 134 linhas, bom (3 fases, decision-complete) |
| 24 | +├── skill-writer/SKILL.md → 403 linhas, completo |
| 25 | +├── skill-digester/SKILL.md → review/install skills |
| 26 | +└── deepcode-self-refer/SKILL.md → auto-referência |
| 27 | +``` |
| 28 | + |
| 29 | +### O que falta (e eu já resolvi no userland) |
| 30 | + |
| 31 | +| Gap | Minha solução | Onde tá | |
| 32 | +|---|---|---| |
| 33 | +| Concurrency / locks | engineering-standards | `~/.agents/skills/` | |
| 34 | +| File I/O performance | engineering-standards | `~/.agents/skills/` | |
| 35 | +| Atomic writes | python-fastapi-patterns | `~/.deepcode/skills/` | |
| 36 | +| Testing enforcement | engineering-standards | `~/.agents/skills/` | |
| 37 | +| Pre-commit checklist | engineering-standards | `~/.agents/skills/` | |
| 38 | +| Plan adherence | engineering-standards | `~/.agents/skills/` | |
| 39 | +| Migration patterns | python-fastapi-patterns | `~/.deepcode/skills/` | |
| 40 | +| Config resolution isolation | python-fastapi-patterns | `~/.deepcode/skills/` | |
| 41 | +| Plan verification pós-impl | NÃO EXISTE AINDA | backlog | |
| 42 | + |
| 43 | +## Filosofia do Mantenedor e Perfil de Review |
| 44 | + |
| 45 | +Análise de PRs fechados/ignorados (como o PR #132 de temas e a recusa do PR de File Mention) revela a mentalidade do mantenedor (`lessweb`): |
| 46 | + |
| 47 | +1. **"Menos Framework, Mais LLM"**: Ele prefere manter o runtime (backend Node) o mais simples e burro possível. Exemplo: prefere que o frontend apenas ajude a autocompletar caminhos (`@`) e que a IA decida chamar a tool `Read` de forma autônoma, em vez de o framework ler e injetar o arquivo de forma "não inteligente" no contexto. |
| 48 | +2. **Aversão a Bloat de Código**: Ele rejeita PRs que introduzem muitas mudanças no backend por medo de aumentar a dívida de manutenção ("Read tool mudando de ferramenta do agente para dependência do framework"). |
| 49 | +3. **Foco em UX no Frontend**: Ele valoriza a TUI, mas é extremamente cauteloso com edge-cases de interação (ex: o que acontece se o usuário apagar caracteres no meio do caminho de um arquivo mention de forma dinâmica). |
| 50 | +4. **Perfil Altamente Seletivo (Lento)**: PRs simples e com testes demoram semanas/meses para serem analisados ou são reescritos por ele mesmo na branch `main`. |
| 51 | + |
| 52 | +### Implicação para a Estratégia: |
| 53 | +- **Upstream PRs**: Precisam ser ultra-minimalistas, sem mexer na lógica do core do backend. Foco em customizações que não impõem decisões dogmáticas ao mantenedor (como aliases no settings). |
| 54 | +- **Personal Fork**: Destinado a features que violam a regra de "simplicidade do framework" mas aumentam a sua produtividade pessoal (como o gatekeeper e a integração automática com o `agy` CLI). |
| 55 | + |
| 56 | +## Estratégia de Contribuição: Upstream vs. Personal Fork |
| 57 | + |
| 58 | +Dividido em duas trilhas: **Upstream PRs** (mudanças genéricas de alta aceitação) e **Personal Fork** (customizações profundas, integrações proprietárias e wrappers de agentes). |
| 59 | + |
| 60 | +--- |
| 61 | + |
| 62 | +## Trilha A — Upstream PRs (Mudanças de Alta Aceitação) |
| 63 | + |
| 64 | +Foco em UX simples e habilidades genéricas que complementam o que já existe sem impor decisões dogmáticas ao mantenedor. |
| 65 | + |
| 66 | +### PR 1 — UX & Keybindings |
| 67 | +- `exit` command no console da CLI para sair de forma limpa. |
| 68 | +- `Esc Esc` como atalho rápido para desfazer a última ação (`/undo`). |
| 69 | +- *Status*: Baixo risco, atrativo para novos usuários. |
| 70 | + |
| 71 | +### PR 2 — Melhorar a descrição da ferramenta `bash` |
| 72 | +- Atualizar a descrição da tool `bash` (em `templates/tools/bash.md`) injetando as boas práticas operacionais do seu `AGENTS.md`: |
| 73 | + - Instruir explicitamente o modelo a sempre capturar saídas (`set st $status` ou `; or report_error`). |
| 74 | + - Mapear para comandos silenciosos (`mv`, `mkdir`, `chmod`) o append de `&& echo ok` para confirmação de runtime. |
| 75 | +- *Status*: Corrige o comportamento padrão de execução cega de comandos. |
| 76 | + |
| 77 | +### PR 3 — `engineering-standards` como Skill Bundled |
| 78 | +- Propor uma versão genérica do seu `~/.agents/skills/engineering-standards/SKILL.md`. |
| 79 | +- Remover referências específicas a este projeto (`sessions.json`, `state_lock`). |
| 80 | +- Foco em: locks para concorrência de arquivos, evitar I/O em loops estáticos, e checklist pré-commit. |
| 81 | +- *Status*: Fica ao lado do Karpathy Guidelines como guia técnico (Karpathy = conceitual; este = engenharia). |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Trilha B — Personal Fork (Minha Customização de Liderança/Staff) |
| 86 | + |
| 87 | +Para o que o upstream recusar por ser muito específico, ou para integrações profundas com sua stack e fluxos locais. |
| 88 | + |
| 89 | +### Feature 1 — `python-tooling` e `fish-tooling` Skills |
| 90 | +- **`python-tooling`**: Skill bundled nativa para forçar o loop de validação (`ruff check .`, `mypy`, `pytest` via `uv` no `.venv/`). Evita erros de sintaxe ou imports que quebram o runtime silenciosamente. |
| 91 | +- **`fish-tooling`**: Configuração e escrita de scripts executáveis nativos em `.fish` em vez de `.sh`, alinhado com o shell padrão do ambiente. |
| 92 | +- *Status*: Muito específico do seu setup de desenvolvimento local. |
| 93 | + |
| 94 | +### Feature 2 — Gatekeeper Determinístico no Runtime (PR 5) |
| 95 | +- Modificação em TypeScript no runtime do DeepCode. |
| 96 | +- Quando o `UpdatePlan` marcar tudo `[x]`, o runtime intercepta a finalização: |
| 97 | + - Parseia o `<proposed_plan>` original usando regex. |
| 98 | + - Verifica no filesystem se os arquivos da seção "Implementation Changes" têm diff no git. |
| 99 | + - Verifica se arquivos de teste em "Test Plan" foram criados ou alterados. |
| 100 | + - Se faltar algo, aborta o commit e injeta: `[Gatekeeper] Itens não entregues: X. Corrija antes de prosseguir.` |
| 101 | +- *Status*: Transforma prompt (confiança) em código determinístico (enforcement). |
| 102 | + |
| 103 | +### Feature 3 — Wrapper Skill `antigravity-critic` (Integração com Claude/Gemini) |
| 104 | +- Criação de uma skill local que atua como ponte para a CLI do Antigravity (`agy`). |
| 105 | +- Permite ao DeepCode invocar de forma autônoma revisões do Opus/Gemini no meio do seu próprio loop de escrita: |
| 106 | + ```bash |
| 107 | + git diff | agy "Faça uma auditoria de segurança focada em concorrência neste diff." |
| 108 | + ``` |
| 109 | +- O DeepCode lê o output da auditoria e auto-corrige o código antes do seu commit final. |
| 110 | +- *Status*: Orquestração multi-agente local de baixo custo. |
| 111 | + |
| 112 | +--- |
| 113 | + |
| 114 | +## Design Patterns do meta_2028 aplicáveis |
| 115 | + |
| 116 | +Referência: `~/git/my/meta_2028/` — multi-agent Actor-Critic para otimização de CV com sandbox containerizado. |
| 117 | + |
| 118 | +### 1. "Fails silently → code, fails loudly → prose" |
| 119 | + |
| 120 | +Heurística central do meta_2028 para decidir o que vive em prose (runbooks .md) vs o que vive em código (Python determinístico): |
| 121 | + |
| 122 | +| Tipo de falha | Onde vive | Exemplo no DeepCode | |
| 123 | +|---|---|---| |
| 124 | +| **Fails loudly** (erro visível, agent self-heals) | Prose (skill) | "use locks" — se não usar, o bug aparece em testes | |
| 125 | +| **Fails silently** (completa sem erro, resultado errado) | Code (runtime) | Agente marca tudo `[x]` mas não escreveu os testes prometidos | |
| 126 | + |
| 127 | +O DeepCode hoje é 100% prose (skills). O gap é que falhas silenciosas (plano não cumprido, testes não escritos) passam despercebidas porque não tem código determinístico validando. |
| 128 | + |
| 129 | +### 2. Actor-Critic loop → plan-verify |
| 130 | + |
| 131 | +O meta_2028 usa Karen (critic) → Bill (editor) → loop até score atingir target. No DeepCode, o equivalente seria: |
| 132 | + |
| 133 | +``` |
| 134 | +Agente implementa → plan-verify (critic) audita deliverables |
| 135 | + → se faltou algo → injeta feedback → agente corrige → loop |
| 136 | + → se tudo OK → permite commit |
| 137 | +``` |
| 138 | + |
| 139 | +Hoje o DeepCode tem o Actor (agente implementa) mas não tem o Critic (ninguém valida se o plano foi cumprido). A skill `plan-verify` resolve em prose; a Feature 2 (gatekeeper) resolve em código. |
| 140 | + |
| 141 | +### 3. Gatekeeper com exit codes |
| 142 | + |
| 143 | +O `gatekeeper.py` do meta_2028 é um módulo Python puro que: |
| 144 | +- Parseia output do critic com regex robusto. |
| 145 | +- Retorna exit codes determinísticos (0=success, 1=max loops, 2=continue, 3=error). |
| 146 | +- O orchestrator nunca confia no modelo pra decidir se o loop continua. |
| 147 | + |
| 148 | +Aplicação no DeepCode: o runtime do seu fork pode ter um mini-gatekeeper que parseia o `<proposed_plan>` e valida com checagem de filesystem (git diff, file exists) antes de aceitar o "pronto" do agente. |
| 149 | + |
| 150 | +## Complexidade real |
| 151 | + |
| 152 | +- **Trilha Upstream (PRs 1-4)**: Baixa. Em sua maioria apenas alteração de arquivos de markdown (`bundled/` ou `templates/`). O PR 1 envolve poucas linhas no tratador de teclado do console Node. |
| 153 | +- **Trilha Fork (Features 1-3)**: Média/Alta. Envolve alterações no interpretador de estado do terminal da CLI (TypeScript/Node) para criar ganchos no `UpdatePlan` e interceptar o fluxo, além de scripts wrappers para o `agy`. |
| 154 | + |
| 155 | +## Referências |
| 156 | + |
| 157 | +- `~/.deepcode/AGENTS.md` — regras operacionais (a base) |
| 158 | +- `~/.deepcode/skills/python-fastapi-patterns/SKILL.md` — patterns específicos |
| 159 | +- `~/.agents/skills/engineering-standards/SKILL.md` — standards genéricos |
| 160 | +- `~/git/my/meta_2028/` — design patterns (Actor-Critic, prose vs code, gatekeeper) |
| 161 | +- Review que motivou tudo: commit 75fde122 no orchestrator (6.5/10 → 9/10) |
0 commit comments