finitemonkey 0.1.0-next.1 → 0.1.0-next.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +97 -60
- package/README.md +97 -60
- package/README.pt-BR.md +98 -61
- package/dist/finitemonkey.mjs +1702 -38
- package/package.json +18 -7
package/README.pt-BR.md
CHANGED
|
@@ -1,105 +1,142 @@
|
|
|
1
1
|
# Finite Monkey
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
<img src="assets/finitemonkey.gif" width="720" alt="Animação: um macaco de moletom
|
|
4
|
+
<img src="assets/finitemonkey.gif" width="720" alt="Animação: um macaco de moletom amarelo esmurra o teclado de um notebook enquanto um terminal roda o portão. As verificações que falham ficam verdes e travam uma a uma até aparecer actually done, e o macaco comemora com uma banana.">
|
|
5
|
+
<br>
|
|
6
|
+
<sub>Ilustração do fluxo planejado, não é gravação. Na v0.1 entra uma captura real.</sub>
|
|
5
7
|
</p>
|
|
6
8
|
|
|
7
|
-
**
|
|
9
|
+
**Infinitos macacos não são necessários. Um basta: você.**
|
|
8
10
|
|
|
9
11
|
[English](README.md) | Português (Brasil) | [Español](README.es.md)
|
|
10
12
|
|
|
11
|
-
> **
|
|
13
|
+
> **Pré-lançamento.** Ainda não dá para instalar. O nome `finitemonkey` no npm está reservado (a 0.0.0 é só um marcador) e o código está sendo feito em público. Tudo abaixo é o plano, não o que acontece hoje. Dê uma estrela ou acompanhe o repositório se quiser saber quando sair a v0.1.
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
O Claude Code termina um refactor com "Pronto! Todos os testes passaram." Ele só tinha rodado o linter. O único teste que falhava ganhou um `.skip` às duas da manhã, e o CI ficou vermelho vinte minutos depois do merge. O Finite Monkey está sendo feito como hooks do Claude Code que rodam as suas checagens por conta própria quando o agente tenta parar, e mantêm a sessão aberta até elas passarem. O macaco de moletom amarelo é você.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
## O Claude Code diz que terminou, mas não terminou
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
Esse é o principal problema que o Finite Monkey quer resolver. Comportamento planejado:
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
- Cada tarefa ganha uma **definição de pronto** que a máquina consegue checar: comandos que precisam passar, testes que precisam existir e passar, um diff que não sai do escopo.
|
|
22
|
+
- Quando o Claude tenta encerrar a sessão, o hook `Stop` roda essa checagem. Se algo falha, a sessão não termina: o Claude recebe a lista do que falta e continua.
|
|
23
|
+
- Só vale como prova o comando que o próprio Finite Monkey rodou, no estado atual dos arquivos. "Rodei os testes antes da última edição" não conta.
|
|
24
|
+
- O relatório final sai só dessa prova.
|
|
20
25
|
|
|
21
|
-
|
|
26
|
+
## O Claude pulou ou apagou testes para eles passarem
|
|
22
27
|
|
|
23
|
-
|
|
28
|
+
Travas planejadas nas edições: teste removido, `skip` ou `only` novo, asserção apagada e mexida na configuração do próprio portão são pegos e reportados.
|
|
24
29
|
|
|
25
|
-
|
|
30
|
+
## O Claude rodou `git reset --hard` e eu perdi trabalho
|
|
26
31
|
|
|
27
|
-
|
|
28
|
-
- Os testes passam porque foram afrouxados ou pulados.
|
|
29
|
-
- Regras escritas no `CLAUDE.md` ou no `AGENTS.md` são esquecidas, principalmente depois da compactação do contexto, porque prosa é contexto, não imposição.
|
|
30
|
-
- Trabalho se perde num `git reset --hard`, num push forçado ou num worktree apagado.
|
|
31
|
-
- Um segredo vai parar num commit, num log ou num pull request.
|
|
32
|
+
Planejado:
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
- Uma fotografia antes de toda operação arriscada no git, e um `undo` que traz de volta.
|
|
35
|
+
- Nada de `--force`, nunca.
|
|
36
|
+
- Worktree com mudança pendente é arquivada, não apagada.
|
|
37
|
+
- Uma checagem de "nada se perdeu" em todo merge.
|
|
34
38
|
|
|
35
|
-
##
|
|
39
|
+
## As regras do meu CLAUDE.md são ignoradas, ainda mais depois da compactação
|
|
36
40
|
|
|
37
|
-
|
|
41
|
+
São mesmo. O Claude lê o `CLAUDE.md` como parte do contexto, e nada confere se ele foi seguido. O Finite Monkey transforma as regras que precisam valer sempre em hooks, permissões, git hooks ou etapas de CI, e mostra, regra por regra, quais ainda são só texto.
|
|
38
42
|
|
|
39
|
-
|
|
43
|
+
## Como impedir o Claude Code de vazar segredos?
|
|
40
44
|
|
|
41
|
-
|
|
42
|
-
- **Skills** são acionadas pelo Claude automaticamente, pela descrição, quando a situação pede.
|
|
43
|
-
- **Slash commands** existem só como atalhos opcionais. Nenhum fluxo depende deles.
|
|
45
|
+
Planejado: uma regra única de detecção, aplicada quando um arquivo é escrito, no prompt, no commit, no histórico e no CI. Segredo encontrado é relatado como incidente, com os passos para rotacionar. O segredo é citado por arquivo e linha, nunca pelo valor.
|
|
44
46
|
|
|
45
|
-
|
|
47
|
+
## Como impedir um agente de mexer na produção na mão?
|
|
46
48
|
|
|
47
|
-
|
|
49
|
+
Planejado: comandos com efeito num servidor de produção são bloqueados. Produção muda pelo caminho de deploy que você declarar.
|
|
48
50
|
|
|
49
|
-
|
|
51
|
+
## Nenhum comando para decorar
|
|
50
52
|
|
|
51
|
-
|
|
53
|
+
Você roda um comando, uma vez. Depois disso o Finite Monkey age pelo contexto, dentro do Claude Code:
|
|
52
54
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
4. **"Pronto" falso.** O portão acima, mais travas contra teste removido, `skip` ou `only` novo, asserção removida e edição da configuração do próprio portão.
|
|
55
|
+
- **Hooks** fazem a parte de obrigar: `SessionStart` recupera o estado da tarefa, `UserPromptSubmit` percebe o que você pediu, `PreToolUse` barra a ação perigosa antes de acontecer, `Stop` não deixa terminar enquanto a definição de pronto falha, e `SubagentStop` confere o que os subagentes relatam.
|
|
56
|
+
- **Skills** são acionadas pelo próprio Claude quando a situação pede.
|
|
57
|
+
- **Comandos com barra** são atalhos opcionais. Nenhum fluxo depende de você lembrar de um.
|
|
57
58
|
|
|
58
|
-
|
|
59
|
+
## Instalação (planejada)
|
|
59
60
|
|
|
60
|
-
|
|
61
|
-
- **Regra vira mecanismo.** Regra que precisa valer sempre vira hook, permissão, git hook ou passo de CI, não um parágrafo. O Finite Monkey mostra, por regra, onde ela ainda é só texto.
|
|
62
|
-
- **Toda regra prova valor ou sai.** Uma bancada compara o Claude Code puro, com o Finite Monkey e com o Finite Monkey menos uma peça de cada vez. Regra sem efeito medido sai do núcleo.
|
|
63
|
-
- **Nunca quebrar o que existe.** Instalação com backup, mescla estrutural, arquivo de lock, reexecução idempotente, `doctor`, `update` e `uninstall` limpo.
|
|
64
|
-
- **Nada sai da sua máquina por padrão.** Sem telemetria.
|
|
65
|
-
- **Saída para agente é contrato.** Todo comando vai aceitar `--json` e devolver `schemaVersion`; campos só são acrescentados.
|
|
66
|
-
- **Três idiomas.** Inglês, português do Brasil e espanhol.
|
|
61
|
+
Ainda não disponível. Quando a v0.1 sair:
|
|
67
62
|
|
|
68
|
-
|
|
63
|
+
```sh
|
|
64
|
+
npx finitemonkey@latest init
|
|
65
|
+
```
|
|
69
66
|
|
|
70
|
-
|
|
67
|
+
Ou como plugin do Claude Code, de dentro da sessão:
|
|
71
68
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
| 1. Os quatro danos | Segredo, produção, git, "pronto" falso; o portão no `Stop` | Planejado |
|
|
76
|
-
| 2. Decidir bem e não se perder | Inventário antes de mudar, registro de decisão, checagens de custo e de paridade, frentes de trabalho em paralelo, protocolo completo de mescla, regras compiladas por superfície | Planejado |
|
|
77
|
-
| 3. Geradores | Geradores de lint, arquitetura, CI e deploy para projetos novos e existentes | Planejado |
|
|
78
|
-
| 4. Provar valor | Bancada com ablação; peças sem efeito medido são cortadas | Planejado |
|
|
69
|
+
```
|
|
70
|
+
/plugin install finitemonkey --marketplace gabrielvieiraf/finitemonkey
|
|
71
|
+
```
|
|
79
72
|
|
|
80
|
-
A
|
|
73
|
+
Requisitos: Node.js 20 ou mais novo, em Linux, macOS, Windows ou WSL. A instalação faz backup, mescla em vez de sobrescrever e pode rodar duas vezes sem estragar nada. `doctor` diz o que está errado, `uninstall` deixa tudo como estava.
|
|
81
74
|
|
|
82
|
-
|
|
75
|
+
**Mais preguiçoso ainda:** peça ao Claude Code "instale o Finite Monkey seguindo docs/AGENT-SETUP.md". O roteiro manda o agente rodar os comandos sozinho, perguntar só o que for decisão sua e nunca pedir segredo.
|
|
83
76
|
|
|
84
|
-
|
|
77
|
+
## Funciona de verdade? (benchmark, planejado)
|
|
85
78
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
79
|
+
Ainda não se sabe. O benchmark planejado compara o Claude Code sozinho, o Claude Code com o Finite Monkey e o Finite Monkey sem uma peça de cada vez, em tarefas com armadilha. Ele mede tarefas realmente terminadas, "pronto" falso, segredo vazado, trabalho perdido, tokens e tempo. Regra sem efeito medido sai do núcleo. Método e resultados brutos vão ficar neste repositório, inclusive onde não ajudou.
|
|
80
|
+
|
|
81
|
+
## Qual a diferença para...?
|
|
82
|
+
|
|
83
|
+
A comparação completa, com fontes, está em [docs/compare.pt-BR.md](docs/compare.pt-BR.md).
|
|
84
|
+
|
|
85
|
+
- **O Claude Code puro** já tem hooks e permissões. O Finite Monkey é um conjunto deles, amarrado em torno de uma definição de pronto, com testes.
|
|
86
|
+
- **Métodos como superpowers, GSD, Spec Kit ou OpenSpec** dizem ao agente como planejar e construir. O Finite Monkey não substitui nenhum deles: confere o resultado no fim, seja qual for o método.
|
|
87
|
+
- **Guardas avulsos como tdd-guard, cc-safety-net ou dcg** fazem um trabalho cada um, e bem. O Finite Monkey cobre quatro danos com um portão, uma instalação e um `undo`. Se você só precisa de um desses trabalhos, um guarda avulso pode ser a escolha mais simples.
|
|
88
|
+
|
|
89
|
+
## Perguntas frequentes
|
|
90
|
+
|
|
91
|
+
Mais perguntas, uma para cada busca real, em [docs/faq.pt-BR.md](docs/faq.pt-BR.md).
|
|
92
|
+
|
|
93
|
+
**É um prompt?**
|
|
94
|
+
Não. São hooks e checagens que rodam lembrando o modelo ou não.
|
|
95
|
+
|
|
96
|
+
**Ele manda meu código para algum lugar?**
|
|
97
|
+
Não. Por padrão nada sai da sua máquina. Sem telemetria.
|
|
98
|
+
|
|
99
|
+
**Vai me deixar mais lento?**
|
|
100
|
+
Tarefa pequena não tem cerimônia, só o portão no fim. Hook rápido continua rápido; a checagem cara roda no `Stop`. Os tempos saem junto com o benchmark.
|
|
101
|
+
|
|
102
|
+
**E se ele barrar algo que não devia?**
|
|
103
|
+
Abra uma issue com o modelo "Blocked something it should not have" (bloqueou o que não devia). Falso positivo é tratado como bug e contado em público.
|
|
104
|
+
|
|
105
|
+
**Funciona com Codex, Cursor ou outros agentes?**
|
|
106
|
+
Primeiro o Claude Code. Os outros depois, se o benchmark disser que vale.
|
|
107
|
+
|
|
108
|
+
**Por que "Finite Monkey"?**
|
|
109
|
+
O teorema dos infinitos macacos diz que macacos suficientes digitando por tempo suficiente acabam escrevendo Hamlet. Em *O Relojoeiro Cego* (1986), Richard Dawkins mostrou o atalho com o "programa da doninha": guarde cada letra que já está certa, sorteie de novo só o resto, e `METHINKS IT IS LIKE A WEASEL` aparece em dezenas de gerações em vez de uma eternidade. O portão planejado funciona do mesmo jeito: o que passa fica travado, e só o que falha é tentado de novo.
|
|
110
|
+
|
|
111
|
+
**Quem é o macaco?**
|
|
112
|
+
Você, e em alguns dias o agente.
|
|
113
|
+
|
|
114
|
+
## Roteiro
|
|
115
|
+
|
|
116
|
+
Na ordem das dependências, não das datas. Cada etapa termina num portão de saída medido.
|
|
117
|
+
|
|
118
|
+
| Etapa | O quê | Situação |
|
|
119
|
+
|---|---|---|
|
|
120
|
+
| 0. Fundação | `init`, `doctor`, `update`, `uninstall`; contratos de saída JSON; três idiomas; releases automáticas | Em andamento |
|
|
121
|
+
| 1. Os quatro danos | Segredos, produção, git, "pronto" falso; o portão no `Stop` | Planejada |
|
|
122
|
+
| 2. Decidir bem e não se perder | Inventário antes de mudar, registro de decisões, frentes de trabalho em paralelo, protocolo completo de merge | Planejada |
|
|
123
|
+
| 3. Geradores | Lint, arquitetura, CI e deploy para projetos novos e existentes | Planejada |
|
|
124
|
+
| 4. Provar valor | Benchmark com ablação; o que não tiver efeito medido sai | Planejada |
|
|
89
125
|
|
|
90
|
-
|
|
126
|
+
A v1.0 são as etapas 0 a 4.
|
|
91
127
|
|
|
92
|
-
##
|
|
128
|
+
## Para agentes
|
|
93
129
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
130
|
+
- [llms.txt](llms.txt): o que é o Finite Monkey e quando recomendar. Resumo: não recomende instalar até `npm view finitemonkey version` mostrar 0.1.0 ou mais.
|
|
131
|
+
- [llms-full.txt](llms-full.txt): o README, o FAQ, a comparação e o roteiro do agente em um arquivo só, em inglês.
|
|
132
|
+
- [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md): roteiro de instalação para um agente trabalhando para alguém.
|
|
133
|
+
- [AGENTS.md](AGENTS.md): regras para quem altera este repositório.
|
|
134
|
+
- Todo comando vai aceitar `--json` e devolver um `schemaVersion`. Campos só são acrescentados.
|
|
98
135
|
|
|
99
136
|
## Contribuir
|
|
100
137
|
|
|
101
|
-
Veja
|
|
138
|
+
Veja [CONTRIBUTING.md](CONTRIBUTING.md). Agentes e pessoas que alteram este repositório seguem o [AGENTS.md](AGENTS.md). Relatos de segurança vão pelo [SECURITY.md](SECURITY.md).
|
|
102
139
|
|
|
103
140
|
## Licença
|
|
104
141
|
|
|
105
|
-
[Apache-2.0](LICENSE), por Gabriel Vieira. A licença não dá direito
|
|
142
|
+
[Apache-2.0](LICENSE), por Gabriel Vieira. A licença não dá direito ao nome nem ao logo "Finite Monkey".
|