finitemonkey 0.1.0-next.1 → 0.1.0-next.3
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 +123 -57
- package/README.md +122 -56
- package/README.pt-BR.md +123 -57
- package/dist/finitemonkey.mjs +2960 -86
- package/package.json +21 -7
package/README.pt-BR.md
CHANGED
|
@@ -1,105 +1,171 @@
|
|
|
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
|
+
Eu sei como é. Com o advento da IA, muita coisa mudou.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
Uns batem a cabeça no teclado esperando que o Claude cuspa magicamente o próximo SaaS bilionário. Outros já cansaram de digitar código. E tem quem precise entregar, em dias, o que antes exigiria equipes inteiras trabalhando por meses.
|
|
16
18
|
|
|
17
|
-
O
|
|
19
|
+
O resultado é quase sempre o mesmo: você vira um macaco na frente do computador, soterrado por tanta coisa para fazer que já não sabe por onde começar, muito menos como terminar.
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
O Finite Monkey foi criado para ser o portão entre esse macaco e a `main`.
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
Digite do jeito que quiser. Trabalhe com a IA que preferir. Produza código na velocidade que conseguir.
|
|
22
24
|
|
|
23
|
-
|
|
25
|
+
O Finite Monkey cuida primeiro do que não pode ficar na base da confiança: as verificações.
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Cada verificação aprovada fica registrada. Cada falha continua visível até ser resolvida. E nada é considerado pronto sem evidências de que realmente funciona.
|
|
26
28
|
|
|
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.
|
|
29
|
+
Não importa quanto código foi gerado, quantos agentes trabalharam ou quão convincente parece a resposta da IA. Se não passou pelas verificações, não está pronto.
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
E o portão é só o começo: o Finite Monkey também percebe quando você está dando voltas, mostra o que falta num projeto maior que você, segura as rédeas de vários agentes ao mesmo tempo e leva tudo até produção sem quebrar nada pelo caminho.
|
|
34
32
|
|
|
35
|
-
|
|
33
|
+
Um macaco. Tempo finito. Trabalho que sai de verdade.
|
|
36
34
|
|
|
37
|
-
|
|
35
|
+
## O Claude Code diz que terminou, mas não terminou
|
|
38
36
|
|
|
39
|
-
|
|
37
|
+
Esse é o principal problema que o Finite Monkey quer resolver. Comportamento planejado:
|
|
40
38
|
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
39
|
+
- 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.
|
|
40
|
+
- 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.
|
|
41
|
+
- 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.
|
|
42
|
+
- O relatório final sai só dessa prova.
|
|
44
43
|
|
|
45
|
-
|
|
44
|
+
## O Claude pulou ou apagou testes para eles passarem
|
|
46
45
|
|
|
47
|
-
|
|
46
|
+
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.
|
|
48
47
|
|
|
49
|
-
|
|
48
|
+
## O Claude rodou `git reset --hard` e eu perdi trabalho
|
|
50
49
|
|
|
51
|
-
|
|
50
|
+
Planejado:
|
|
52
51
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
52
|
+
- Uma fotografia antes de toda operação arriscada no git, e um `undo` que traz de volta.
|
|
53
|
+
- Nada de `--force`, nunca.
|
|
54
|
+
- Worktree com mudança pendente é arquivada, não apagada.
|
|
55
|
+
- Uma checagem de "nada se perdeu" em todo merge.
|
|
57
56
|
|
|
58
|
-
|
|
57
|
+
## As regras do meu CLAUDE.md são ignoradas, ainda mais depois da compactação
|
|
59
58
|
|
|
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.
|
|
59
|
+
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.
|
|
67
60
|
|
|
68
|
-
##
|
|
61
|
+
## Como impedir o Claude Code de vazar segredos?
|
|
69
62
|
|
|
70
|
-
|
|
63
|
+
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.
|
|
71
64
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
65
|
+
## Como impedir um agente de mexer na produção na mão?
|
|
66
|
+
|
|
67
|
+
Planejado: comandos com efeito num servidor de produção são bloqueados. Produção muda pelo caminho de deploy que você declarar.
|
|
68
|
+
|
|
69
|
+
## Mais que um portão (planejado)
|
|
70
|
+
|
|
71
|
+
O portão vem primeiro porque nada mais importa se o "pronto" pode ser mentira. O resto do plano é sobre quem está digitando:
|
|
79
72
|
|
|
80
|
-
A
|
|
73
|
+
- **Quando você está dando voltas.** A quarta correção para o mesmo erro, o mesmo arquivo editado para lá e para cá, um bug colado de uma IA para outra e de volta: o Finite Monkey percebe a volta e diz isso com todas as letras, com o que tentar no lugar.
|
|
74
|
+
- **Quando o projeto é maior que você, por enquanto.** Quem nunca colocou um SaaS no ar não sabe que ele precisa de login, cobrança, backup e um jeito de voltar atrás. As plantas de projeto mostram o que uma versão de verdade precisa e o que ainda falta, para uma tela de login não ser chamada de produto. As explicações acompanham o que você já sabe e vão sumindo conforme você aprende.
|
|
75
|
+
- **Quando uma decisão pesa.** Antes de trocar uma biblioteca ou um fornecedor: o que existe hoje, quais as opções, os critérios escritos antes dos candidatos, o custo e como voltar.
|
|
76
|
+
- **Quando você roda vários agentes ao mesmo tempo.** Frentes de trabalho em paralelo, cada uma na sua branch, um merge que confere que nada se perdeu e uma tela com o que cada frente está fazendo.
|
|
77
|
+
- **Quando uma regra precisa valer em todo lugar.** A regra que você escreve uma vez vira hook, permissão, git hook e passo de CI, e você vê onde ela ainda é só texto.
|
|
78
|
+
- **Quando vai para produção.** CI, deploy e infraestrutura no tamanho do projeto, e checagens de organização de código para bases que cresceram rápido demais.
|
|
79
|
+
|
|
80
|
+
## Nenhum comando para decorar
|
|
81
|
+
|
|
82
|
+
Você roda um comando, uma vez. Depois disso o Finite Monkey age pelo contexto, dentro do Claude Code:
|
|
83
|
+
|
|
84
|
+
- **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.
|
|
85
|
+
- **Skills** são acionadas pelo próprio Claude quando a situação pede.
|
|
86
|
+
- **Comandos com barra** são atalhos opcionais. Nenhum fluxo depende de você lembrar de um.
|
|
81
87
|
|
|
82
88
|
## Instalação (planejada)
|
|
83
89
|
|
|
84
|
-
Ainda não disponível. Quando a
|
|
90
|
+
Ainda não disponível. Quando a v0.1 sair:
|
|
85
91
|
|
|
86
92
|
```sh
|
|
87
93
|
npx finitemonkey@latest init
|
|
88
94
|
```
|
|
89
95
|
|
|
90
|
-
|
|
96
|
+
Ou como plugin do Claude Code, de dentro da sessão:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
/plugin install finitemonkey --marketplace gabrielvieiraf/finitemonkey
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
**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.
|
|
105
|
+
|
|
106
|
+
## Funciona de verdade? (benchmark, planejado)
|
|
107
|
+
|
|
108
|
+
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.
|
|
109
|
+
|
|
110
|
+
## Qual a diferença para...?
|
|
111
|
+
|
|
112
|
+
A comparação completa, com fontes, está em [docs/compare.pt-BR.md](docs/compare.pt-BR.md).
|
|
113
|
+
|
|
114
|
+
- **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.
|
|
115
|
+
- **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.
|
|
116
|
+
- **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.
|
|
117
|
+
|
|
118
|
+
## Perguntas frequentes
|
|
119
|
+
|
|
120
|
+
Mais perguntas, uma para cada busca real, em [docs/faq.pt-BR.md](docs/faq.pt-BR.md).
|
|
121
|
+
|
|
122
|
+
**É um prompt?**
|
|
123
|
+
Não. São hooks e checagens que rodam lembrando o modelo ou não.
|
|
124
|
+
|
|
125
|
+
**Ele manda meu código para algum lugar?**
|
|
126
|
+
Não. Por padrão nada sai da sua máquina. Sem telemetria.
|
|
127
|
+
|
|
128
|
+
**Vai me deixar mais lento?**
|
|
129
|
+
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.
|
|
130
|
+
|
|
131
|
+
**E se ele barrar algo que não devia?**
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
**Funciona com Codex, Cursor ou outros agentes?**
|
|
135
|
+
Primeiro o Claude Code. Os outros depois, se o benchmark disser que vale.
|
|
136
|
+
|
|
137
|
+
**Por que "Finite Monkey"?**
|
|
138
|
+
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.
|
|
139
|
+
|
|
140
|
+
**Quem é o macaco?**
|
|
141
|
+
Você, e em alguns dias o agente.
|
|
142
|
+
|
|
143
|
+
## Roteiro
|
|
144
|
+
|
|
145
|
+
Na ordem das dependências, não das datas. Cada etapa termina num portão de saída medido.
|
|
146
|
+
|
|
147
|
+
| Etapa | O quê | Situação |
|
|
148
|
+
|---|---|---|
|
|
149
|
+
| 0. Fundação | `init`, `doctor`, `update`, `uninstall`; contratos de saída JSON; três idiomas; releases automáticas | Em andamento |
|
|
150
|
+
| 1. Os quatro danos | Segredos, produção, git, "pronto" falso; o portão no `Stop` | Planejada |
|
|
151
|
+
| 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 |
|
|
152
|
+
| 3. Geradores | Lint, arquitetura, CI e deploy para projetos novos e existentes | Planejada |
|
|
153
|
+
| 4. Provar valor | Benchmark com ablação; o que não tiver efeito medido sai | Planejada |
|
|
154
|
+
|
|
155
|
+
A v1.0 são as etapas 0 a 4.
|
|
91
156
|
|
|
92
|
-
##
|
|
157
|
+
## Para agentes
|
|
93
158
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
159
|
+
- [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.
|
|
160
|
+
- [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.
|
|
161
|
+
- [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md): roteiro de instalação para um agente trabalhando para alguém.
|
|
162
|
+
- [AGENTS.md](AGENTS.md): regras para quem altera este repositório.
|
|
163
|
+
- Todo comando vai aceitar `--json` e devolver um `schemaVersion`. Campos só são acrescentados.
|
|
98
164
|
|
|
99
165
|
## Contribuir
|
|
100
166
|
|
|
101
|
-
Veja
|
|
167
|
+
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
168
|
|
|
103
169
|
## Licença
|
|
104
170
|
|
|
105
|
-
[Apache-2.0](LICENSE), por Gabriel Vieira. A licença não dá direito
|
|
171
|
+
[Apache-2.0](LICENSE), por Gabriel Vieira. A licença não dá direito ao nome nem ao logo "Finite Monkey".
|