@fullchico/harness 0.1.4 → 0.1.5
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.md
CHANGED
|
@@ -11,46 +11,413 @@
|
|
|
11
11
|
npx @fullchico/harness install .
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
14
|
+
Um plugin para o Claude Code que troca instrução por trilhos e portões (hooks, guards e
|
|
15
|
+
scripts), para que agentes levem uma mudança da entrevista ao pull request sem que nada
|
|
16
|
+
chegue ao remoto sem revisão independente.
|
|
17
|
+
|
|
18
|
+
## Sumário
|
|
19
|
+
|
|
20
|
+
- [O conceito](#o-conceito)
|
|
21
|
+
- [Como é usar](#como-é-usar)
|
|
22
|
+
- [A entrevista](#a-entrevista)
|
|
23
|
+
- [Quem faz o quê](#quem-faz-o-quê)
|
|
24
|
+
- [Os portões](#os-portões)
|
|
25
|
+
- [O que é recusado por máquina](#o-que-é-recusado-por-máquina)
|
|
26
|
+
- [O que é instalado e o que é exigido](#o-que-é-instalado-e-o-que-é-exigido)
|
|
27
|
+
- [Instalar num projeto](#instalar-num-projeto)
|
|
28
|
+
- [Comandos](#comandos)
|
|
29
|
+
- [Configuração](#configuração)
|
|
30
|
+
- [Arquitetura que o harness espera](#arquitetura-que-o-harness-espera)
|
|
31
|
+
- [Ambiente por feature](#ambiente-por-feature)
|
|
32
|
+
- [Memória do projeto](#memória-do-projeto)
|
|
33
|
+
- [Projeto sem remoto](#projeto-sem-remoto)
|
|
34
|
+
- [Atualizar o harness](#atualizar-o-harness)
|
|
35
|
+
- [O que já foi provado e o que ainda não](#o-que-já-foi-provado-e-o-que-ainda-não)
|
|
36
|
+
- [Desenvolver o harness](#desenvolver-o-harness)
|
|
37
|
+
- [Licença](#licença)
|
|
38
|
+
|
|
39
|
+
## O conceito
|
|
40
|
+
|
|
41
|
+
Uma instrução escrita num arquivo é texto, e texto o agente interpreta: ele pode ler de outro
|
|
42
|
+
jeito, esquecer no meio de uma sessão longa ou decidir que aquele caso é exceção. Um trilho
|
|
43
|
+
é diferente: é um hook, um guard ou um script que confere a regra e recusa o que não passa.
|
|
44
|
+
O agente não precisa concordar com ele, e não tem como atravessá-lo.
|
|
45
|
+
|
|
46
|
+
O harness aplica essa ideia ao ciclo inteiro de uma mudança. O que pode ser conferido por
|
|
47
|
+
máquina é conferido por máquina; o texto fica só para o que exige julgamento.
|
|
48
|
+
|
|
49
|
+
<img src="site/img/fluxo.svg" alt="Fluxo de uma entrega: pedido, entrevista, spec, revisão da spec, tickets, implementação em paralelo, integração, checagem, revisão e envio, com os portões entre as etapas">
|
|
50
|
+
|
|
51
|
+
São três princípios:
|
|
52
|
+
|
|
53
|
+
1. **Quem escreve não aprova.** Revisão no mesmo contexto não é revisão. Todo revisor é um
|
|
54
|
+
subagente de contexto novo, que recebe só ponteiros para os documentos e para o diff, sem
|
|
55
|
+
a conversa nem a opinião de quem escreveu. A aprovação é gravada por um hook, a partir do
|
|
56
|
+
veredito do revisor, num lugar onde o agente não escreve.
|
|
57
|
+
2. **Nada sai sem os portões.** O shell do agente roda no sandbox do Claude Code, sem rede
|
|
58
|
+
para o servidor de git. O único caminho até o remoto é `.harness/push`, que exige quatro
|
|
59
|
+
vereditos sobre o commit do topo da branch.
|
|
60
|
+
3. **Paralelismo por contrato e posse de arquivo.** Cada ticket é dono de pastas (`Owns:`).
|
|
61
|
+
Dois tickets que rodam ao mesmo tempo nunca possuem o mesmo caminho, o ticket de contrato
|
|
62
|
+
fecha antes de todos os outros, e a integração recusa a branch que mexer fora da posse.
|
|
63
|
+
|
|
64
|
+
## Como é usar
|
|
65
|
+
|
|
66
|
+
O loop é: pedido curto, entrevista, pronto. Você abre um worktree para a feature, faz o
|
|
67
|
+
pedido numa sessão do Claude Code dentro dele e responde à entrevista. O resto corre sem você.
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
/harness:entregar quero um sistema de agendamento para uma barbearia
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
O que acontece em cada etapa:
|
|
74
|
+
|
|
75
|
+
| Passo | O que acontece | Quem faz |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| 1. Entrevistar | perguntas até não sobrar decisão em aberto; o vocabulário vai para o `GLOSSARY.md` e as decisões difíceis de reverter viram ADRs | a sua sessão, com você |
|
|
78
|
+
| 2. Especificar | a spec é escrita em `docs/specs/<slug>/spec.md` e entra em commit | a sua sessão |
|
|
79
|
+
| 3. Revisar a spec | um revisor de contexto novo lê a spec como quem vai implementá-la sem poder perguntar, e aponta o que falta | `revisor-spec` |
|
|
80
|
+
| 4. Fatiar | um arquivo por ticket em `docs/specs/<slug>/issues/`, com o que o bloqueia e o que ele possui | `orquestrador` |
|
|
81
|
+
| 5. Implementar | os tickets da fronteira do grafo rodam em paralelo, cada um num worktree próprio, com TDD | `implementador` |
|
|
82
|
+
| 6. Integrar | cada ticket passa pela caça a bugs e só então é juntado à branch da feature, um por vez | `revisor-bugs` e `.harness/integrate` |
|
|
83
|
+
| 7. Checar | a checagem completa do projeto, sem custo de IA | `.harness/validate` |
|
|
84
|
+
| 8. Revisar | quatro vereditos, em paralelo, sobre o mesmo commit | `seguranca`, `revisor`, `revisor-bugs`, `qualidade` |
|
|
85
|
+
| 9. Enviar | push, pull request, e o aplicativo deixado de pé | `.harness/push` e `.harness/pr` |
|
|
86
|
+
|
|
87
|
+
A entrega tem duas metades de propósito. O **desenho** (passos 1 a 3) acontece na sua sessão,
|
|
88
|
+
onde o raciocínio mais caro paga e onde você participa. A **execução** (passos 4 em diante) é
|
|
89
|
+
entregue a um subagente `orquestrador`, em modelo mais barato, que recebe só o caminho da
|
|
90
|
+
spec: o que ficou só na conversa não chega até ele.
|
|
91
|
+
|
|
92
|
+
No fim, o relato traz o link do pull request, o endereço do aplicativo que ficou rodando (com
|
|
93
|
+
o usuário de teste e como parar), o que entrou, o que ficou de fora, quantas rodadas de
|
|
94
|
+
correção houve e as decisões tomadas sem você. Depois do merge, `/harness:aprender` fecha o
|
|
95
|
+
ciclo.
|
|
96
|
+
|
|
97
|
+
### Quando você é chamado
|
|
98
|
+
|
|
99
|
+
| Parada | Quando |
|
|
100
|
+
|---|---|
|
|
101
|
+
| A entrevista | sempre, no começo |
|
|
102
|
+
| Aprovar a spec (PARADA 1) | depois da revisão da spec: você resolve cada achado e aprova |
|
|
103
|
+
| Um ticket que não fecha (PARADA 2) | só se um ticket não fechar em 3 rodadas de correção |
|
|
104
|
+
| Remover um ambiente | `.harness/destroy` apaga dados, então sempre pergunta |
|
|
105
|
+
| Instalar uma skill nova | `.harness/skills-add` pergunta a cada skill |
|
|
106
|
+
| O merge | sempre seu, preservando os commits, sem squash |
|
|
107
|
+
|
|
108
|
+
Todo o resto roda sem pergunta: os comandos dentro do sandbox e os scripts do harness. Se
|
|
109
|
+
quiser alguma pergunta de volta, acrescente a regra em `permissions.ask` num fragmento do
|
|
110
|
+
projeto (`harness.d/settings.json`); pergunta vence liberação.
|
|
111
|
+
|
|
112
|
+
### Seguir sem você
|
|
113
|
+
|
|
114
|
+
Se você disser "segue até o fim" (ou "pode seguir com o recomendado", "confio na sua análise"),
|
|
115
|
+
a entrega passa a correr em modo autônomo, e continua assim até você dizer o contrário:
|
|
116
|
+
|
|
117
|
+
- toda pergunta recebe a resposta recomendada, na entrevista e nos achados do revisor da spec;
|
|
118
|
+
- a aprovação da spec deixa de ser uma parada;
|
|
119
|
+
- cada decisão tomada sem você fica escrita na spec, na seção "Decisões tomadas sem o dono",
|
|
120
|
+
com o que foi escolhido, a alternativa descartada e o motivo.
|
|
121
|
+
|
|
122
|
+
O que continua parando: remover um ambiente, um ticket que não fecha em 3 rodadas, uma
|
|
123
|
+
decisão que depende de um dado que só você tem, e o merge. O modo autônomo não muda os
|
|
124
|
+
portões, as revisões nem o sandbox.
|
|
125
|
+
|
|
126
|
+
### Quando o pedido é um bug
|
|
127
|
+
|
|
128
|
+
Bug entra pela skill `diagnosing-bugs` no lugar da entrevista. Não há spec nem tickets: a
|
|
129
|
+
própria sessão corrige, com teste, em commits `fix`, e depois passa pela mesma checagem,
|
|
130
|
+
pelos mesmos revisores e pelo mesmo envio.
|
|
131
|
+
|
|
132
|
+
## A entrevista
|
|
133
|
+
|
|
134
|
+
A entrevista (grilling) é uma sequência de perguntas ao dono, até não sobrar decisão em
|
|
135
|
+
aberto. Ela vem antes de qualquer código porque quem executa não tem a quem perguntar: o
|
|
136
|
+
orquestrador e os implementadores nascem sem a conversa e trabalham só com o que está nos
|
|
137
|
+
documentos. Uma decisão que ficou de fora da spec vira um ticket reaberto no meio da entrega,
|
|
138
|
+
e uma rodada perdida para todos os que dependem dele.
|
|
139
|
+
|
|
140
|
+
<img src="site/img/entrevista.svg" alt="A entrevista: o pedido curto vira perguntas ao dono, e delas saem o glossário, os ADRs e a spec, que é revisada antes da execução">
|
|
141
|
+
|
|
142
|
+
Quem faz são skills do plugin de terceiros `mattpocock-skills`:
|
|
143
|
+
|
|
144
|
+
| Skill | Para quê |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `grilling` | conduz a entrevista com o dono |
|
|
147
|
+
| `domain-modeling` | registra o vocabulário no `GLOSSARY.md` e as decisões difíceis de reverter em ADRs (`docs/adr/`) |
|
|
148
|
+
| `diagnosing-bugs` | substitui a entrevista quando o pedido é um bug |
|
|
149
|
+
|
|
150
|
+
O que sai da entrevista é a spec, escrita para alguém que vai implementar sem ter visto a
|
|
151
|
+
conversa. As seções dela:
|
|
152
|
+
|
|
153
|
+
| Seção | O que traz |
|
|
154
|
+
|---|---|
|
|
155
|
+
| Problema e Solução | o que incomoda hoje e o que passa a acontecer, do ponto de vista de quem usa |
|
|
156
|
+
| Histórias | lista numerada, cobrindo casos de erro e estados vazios, não só o caminho feliz |
|
|
157
|
+
| Decisões de implementação | módulos que nascem ou mudam, contratos, mudanças de esquema, e cada escolha da entrevista com o motivo |
|
|
158
|
+
| Decisões de teste | os pontos de costura: por onde cada comportamento é testado |
|
|
159
|
+
| Critérios de aceite | numerados; cada um vira um teste de ponta a ponta |
|
|
160
|
+
| Módulos e contrato | os módulos do back e as fatias do front, cada um com a sua pasta (daqui sai a posse de cada ticket); as operações entre front e back; o que cada módulo oferece e consome dos outros |
|
|
161
|
+
| Ambiente e execução | os serviços de que os testes dependem, como os implementadores se isolam e, em projeto novo, o conteúdo do `harness.conf` |
|
|
162
|
+
| Fora de escopo | o que não entra, dito com todas as letras |
|
|
163
|
+
|
|
164
|
+
Antes da execução, a spec é revisada pelo `revisor-spec`, um subagente que não recebe nada da
|
|
165
|
+
conversa. Ele procura premissa não declarada, requisito ambíguo, decisão que falta, módulo
|
|
166
|
+
que depende de outro sem contrato, nome fora da língua do código, teste sem ponto de costura,
|
|
167
|
+
conflito com o glossário ou com um ADR, e risco de implementação. Ele não dá veredito nem
|
|
168
|
+
reescreve a spec: quem resolve os achados e aprova é o dono (ou a própria sessão, no modo
|
|
169
|
+
autônomo).
|
|
170
|
+
|
|
171
|
+
## Quem faz o quê
|
|
172
|
+
|
|
173
|
+
Três papéis:
|
|
174
|
+
|
|
175
|
+
- **Elefante:** o agente raiz da sessão. Carrega o contexto e desenha com o dono: entrevista
|
|
176
|
+
e spec. Entrega a execução ao orquestrador e não revisa o que orquestrou.
|
|
177
|
+
- **Goldfish:** todo subagente. Nasce sem a conversa, entrega o trabalho e não valida o
|
|
178
|
+
próprio resultado.
|
|
179
|
+
- **Dono:** você. Aprova a spec e faz o merge.
|
|
180
|
+
|
|
181
|
+
<img src="site/img/papeis.svg" alt="Os papéis: o dono e a sessão desenham; o orquestrador conduz a execução; implementadores escrevem; revisores de contexto novo dão os vereditos">
|
|
182
|
+
|
|
183
|
+
Os oito agentes do plugin:
|
|
184
|
+
|
|
185
|
+
| Agente | Modelo | O que faz | O que recebe | O que não pode |
|
|
186
|
+
|---|---|---|---|---|
|
|
187
|
+
| `orquestrador` | Sonnet | executa a spec aprovada: fatia, despacha, integra, checa, passa pelos revisores e envia | `spec`, `leitura` | escrever o código da feature, revisar o que orquestrou, juntar branch à mão, perguntar ao dono |
|
|
188
|
+
| `implementador` | Haiku (Sonnet no ticket de contrato) | implementa um ticket, com TDD, num worktree próprio | `spec`, `ticket`, `leitura`, `achado` | mexer fora do `Owns:`, subir ou parar ambiente, enviar, abrir pull request |
|
|
189
|
+
| `revisor-spec` | o da sua sessão | lê a spec como quem vai implementá-la sem poder perguntar | `spec`, `leitura` | editar arquivos, dar veredito, propor a solução |
|
|
190
|
+
| `revisor-bugs` | Sonnet | caça defeito: por ticket antes de integrar, e na branch inteira antes do push | `spec`, `ticket`, `diff`, `commit`, `leitura`, `achado` | editar, corrigir, trocar o commit do worktree |
|
|
191
|
+
| `revisor-ambiente` | Opus | só no ticket de contrato: confere que o que ele monta funciona numa cópia limpa | `spec`, `ticket`, `diff`, `commit`, `leitura`, `achado` | editar, corrigir, trocar o commit do worktree |
|
|
192
|
+
| `seguranca` | Sonnet | revisão de segurança da branch inteira | `diff`, `commit`, `spec`, `leitura` | editar, corrigir, reprovar por estilo ou risco hipotético |
|
|
193
|
+
| `revisor` | Sonnet | revisão de código: padrões do repositório, aderência à spec, arquitetura e clareza | `diff`, `commit`, `spec`, `leitura` | editar, corrigir |
|
|
194
|
+
| `qualidade` | Haiku | roda a checagem completa no commit e atesta o resultado | `commit` | revisar, opinar, consertar, rodar de novo "para ver se passa" |
|
|
195
|
+
|
|
196
|
+
Uma rodada de correção de um ticket sobe de modelo: vai em Sonnet e, depois de duas
|
|
197
|
+
reprovações, em Opus. Se o projeto tem um agente próprio em `.claude/agents/` cuja descrição
|
|
198
|
+
cobre a área do ticket, ele é usado no lugar do `implementador`.
|
|
199
|
+
|
|
200
|
+
O pedido a qualquer um desses agentes só aponta, uma chave por linha (`spec:`, `ticket:`,
|
|
201
|
+
`diff:`, `commit:`, `leitura:`, `achado:`). Narrativa e opinião são recusadas por um hook: o
|
|
202
|
+
documento é a única interface, e uma lacuna se corrige no documento, não por fora.
|
|
203
|
+
|
|
204
|
+
```mermaid
|
|
205
|
+
sequenceDiagram
|
|
206
|
+
actor Dono
|
|
207
|
+
participant Sessao as Sessão (elefante)
|
|
208
|
+
participant RS as revisor-spec
|
|
209
|
+
participant Orq as orquestrador
|
|
210
|
+
participant Impl as implementadores
|
|
211
|
+
participant Rev as revisores
|
|
212
|
+
participant Remoto
|
|
213
|
+
|
|
214
|
+
Dono->>Sessao: /harness:entregar pedido
|
|
215
|
+
Sessao->>Dono: entrevista (grilling)
|
|
216
|
+
Sessao->>Sessao: spec em commit
|
|
217
|
+
Sessao->>RS: spec
|
|
218
|
+
RS-->>Sessao: achados
|
|
219
|
+
Sessao->>Dono: PARADA 1, aprovar a spec
|
|
220
|
+
Sessao->>Orq: spec aprovada
|
|
221
|
+
Orq->>Orq: fatia em tickets e valida o grafo
|
|
222
|
+
loop cada onda do grafo
|
|
223
|
+
Orq->>Impl: tickets da fronteira, em paralelo
|
|
224
|
+
Impl-->>Orq: branch de cada ticket
|
|
225
|
+
Orq->>Rev: revisor-bugs por ticket
|
|
226
|
+
Rev-->>Orq: veredito
|
|
227
|
+
Orq->>Orq: .harness/integrate, um ticket por vez
|
|
228
|
+
end
|
|
229
|
+
Orq->>Orq: .harness/validate --profile merge
|
|
230
|
+
Orq->>Rev: seguranca, revisor, revisor-bugs e qualidade
|
|
231
|
+
Rev-->>Orq: quatro vereditos sobre o mesmo commit
|
|
232
|
+
Orq->>Remoto: .harness/push e .harness/pr
|
|
233
|
+
Orq-->>Sessao: relato
|
|
234
|
+
Sessao-->>Dono: link do PR e endereço do aplicativo
|
|
235
|
+
Dono->>Remoto: merge
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Os portões
|
|
239
|
+
|
|
240
|
+
<img src="site/img/portoes.svg" alt="Os portões: revisão por ticket antes de integrar, checagem completa, e os quatro vereditos sobre o commit do topo antes do push">
|
|
241
|
+
|
|
242
|
+
### Os quatro vereditos sobre o commit
|
|
243
|
+
|
|
244
|
+
Nada sai da máquina sem quatro aprovações sobre o commit do topo da branch:
|
|
245
|
+
|
|
246
|
+
| Veredito | Quem dá | O que atesta |
|
|
247
|
+
|---|---|---|
|
|
248
|
+
| segurança | `seguranca` | sem segredo, injeção, autorização ausente, dado sensível exposto, dependência duvidosa ou guardrail desligado no diff da branch |
|
|
249
|
+
| revisão de código | `revisor` | o código segue os padrões do repositório, a spec e a arquitetura |
|
|
250
|
+
| caça a bugs | `revisor-bugs` | o passe final sobre a branch inteira: o que só aparece olhando os módulos juntos |
|
|
251
|
+
| qualidade | `qualidade` | a checagem completa do projeto (testes, fronteiras, build, ponta a ponta) passou naquele commit |
|
|
252
|
+
|
|
253
|
+
Todo revisor termina a resposta com um bloco fixo:
|
|
254
|
+
|
|
255
|
+
```text
|
|
256
|
+
VEREDITO: APPROVED (ou REJECTED)
|
|
257
|
+
COMMIT: <hash completo do commit revisado>
|
|
258
|
+
RESUMO: <uma linha>
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Um hook lê esse bloco e grava a aprovação, e só quando o commit revisado é o topo atual.
|
|
262
|
+
Nenhum agente carimba aprovação. Commit local é livre; entrou commit novo, a validação é
|
|
263
|
+
refeita. Além dos vereditos, uma branch com commit `feat` precisa trazer a spec da mudança em
|
|
264
|
+
`docs/specs/<slug>/spec.md`. O carimbo manual, `.harness/approve`, é do dono e exige terminal.
|
|
265
|
+
|
|
266
|
+
### A revisão por ticket, antes de integrar
|
|
267
|
+
|
|
268
|
+
Cada ticket passa pela caça a bugs antes de ser juntado: um `revisor-bugs` por ticket, sobre a
|
|
269
|
+
ponta da branch do implementador. O diff de um ticket é pequeno, e é aí que a revisão funda
|
|
270
|
+
funciona: o defeito não chega aos tickets que dependem dele. O `.harness/integrate` recusa a
|
|
271
|
+
branch que não foi aprovada naquele commit exato.
|
|
272
|
+
|
|
273
|
+
O ticket de contrato tem duas leituras, juntas, porque é a base de todos os outros:
|
|
274
|
+
|
|
275
|
+
- o `revisor-bugs` procura defeito de comportamento e o que falta no contrato (cada porta que
|
|
276
|
+
um módulo consome, as respostas de erro comuns, as constantes de regra);
|
|
277
|
+
- o `revisor-ambiente` procura o que só funciona na pasta de quem escreveu: dependência fora
|
|
278
|
+
do commit, checagem que depende da ordem, valor fixo onde devia vir do ambiente, instalação
|
|
279
|
+
não reproduzível.
|
|
280
|
+
|
|
281
|
+
A integração exige as duas aprovações nesse commit.
|
|
282
|
+
|
|
283
|
+
### Pendências
|
|
284
|
+
|
|
285
|
+
Achado simples não reprova. Um achado é severo quando quem usa recebe resultado errado, um
|
|
286
|
+
dado se perde ou fica inconsistente, uma proteção não protege, uma falha some, ou um teste
|
|
287
|
+
passa sem exercitar o que diz. O que sobra é simples: o revisor aprova com linhas
|
|
288
|
+
`PENDENCIA:`, o hook as registra, e o ticket segue.
|
|
289
|
+
|
|
290
|
+
- O teto é de duas pendências abertas por ticket. Passou disso, a aprovação não é gravada,
|
|
291
|
+
mesmo que o revisor tenha escrito `APPROVED`.
|
|
292
|
+
- As pendências são corrigidas no fechamento, cada uma com o teste que a pegaria.
|
|
293
|
+
- Só um revisor fecha uma pendência: o `revisor-bugs`, no passe final, responde
|
|
294
|
+
`RESOLVIDA: <id>` depois de conferir a correção no código.
|
|
295
|
+
- O push é recusado enquanto houver uma aberta. `.harness/pendings` lista.
|
|
296
|
+
|
|
297
|
+
### Teto de rodadas
|
|
298
|
+
|
|
299
|
+
Quando a checagem ou um revisor reprova, o achado é gravado em
|
|
300
|
+
`docs/specs/<slug>/achados/`, o ticket é reaberto e despachado de novo, e o revisor que
|
|
301
|
+
reprovou confere a correção. As rodadas são contadas por ticket, e só reprovação conta. Cada
|
|
302
|
+
ticket tem limite de 3 rodadas de correção: na quarta, o orquestrador para e devolve o relato
|
|
303
|
+
do que travou. Os outros tickets continuam andando enquanto um está em correção.
|
|
304
|
+
|
|
305
|
+
## O que é recusado por máquina
|
|
306
|
+
|
|
307
|
+
| Regra | Quem recusa |
|
|
308
|
+
|---|---|
|
|
309
|
+
| `git push`, `git fetch` e `gh` diretos | sandbox do Claude Code: a rede para o servidor de git é negada |
|
|
310
|
+
| Gravar em `.harness/`, `harness.conf`, `harness.d/`, `.claude/skills/`, `skills-lock.json`, `CLAUDE.md`, `docs/agents/` | sandbox (`filesystem.denyWrite`) e `permissions.deny` |
|
|
311
|
+
| Desligar o sandbox num comando | `allowUnsandboxedCommands: false` nas configurações geradas |
|
|
312
|
+
| Editar a região gerenciada do `AGENTS.md` | hook `managed_guard` |
|
|
313
|
+
| Pular hooks de git (`--no-verify`, `core.hooksPath`) | hook `service_guard` |
|
|
314
|
+
| Encadear ou embrulhar um script que sai do sandbox (`.harness/up && ...`) | hook `service_guard` |
|
|
315
|
+
| Implementador ou revisor subir, parar ou remover ambiente, rodar o aplicativo, enviar ou abrir pull request | hook `service_guard` |
|
|
316
|
+
| Revisor trocar o commit do worktree (`git checkout`, `switch`, `reset`, `restore`, `stash`, `clean`) | hook `service_guard` |
|
|
317
|
+
| Orquestrador juntar branch à mão (`git merge`, `rebase`, `cherry-pick`) | hook `service_guard` |
|
|
318
|
+
| Proposta de `harness.conf` fora do formato, ou que remove uma checagem já gravada | hook `service_guard`, ao rodar `.harness/conf-apply` |
|
|
319
|
+
| Pedido a um agente do harness com narrativa, chave que ele não recebe ou caminho que não existe | hook `dispatch_guard` |
|
|
320
|
+
| Pedido de revisão cujo `commit` não é o topo ou cujo `diff` não cobre a branch inteira | hook `dispatch_guard` |
|
|
321
|
+
| Implementador despachado por quem não é o orquestrador, ou sem worktree isolado | hook `dispatch_guard` |
|
|
322
|
+
| Orquestrador despachado com a spec fora de commit, ou sem `harness.conf` no projeto nem na spec | hook `dispatch_guard` |
|
|
323
|
+
| Aprovação sem veredito `APPROVED` de um revisor sobre o commit do topo, ou com mais de duas pendências no ticket | hook `gate_stamp`, que só então grava |
|
|
324
|
+
| Grafo de tickets com ciclo, referência inexistente, cabeçalho faltando, posse sobreposta entre paralelos ou ticket que não espera o contrato | `.harness/tickets_check.py` |
|
|
325
|
+
| Integrar branch sem a caça a bugs naquele commit (e, no ticket de contrato, sem a conferência de ambiente) | `.harness/integrate` |
|
|
326
|
+
| Integrar branch que mexeu fora do `Owns:` do ticket, ou que conflita | `.harness/integrate` |
|
|
327
|
+
| Integrar branch que quebra a checagem do projeto | `.harness/integrate`, que desfaz a junção |
|
|
328
|
+
| Marcar um ticket como `Status: done` num commit em que a checagem não passa | hook de git `pre-commit` |
|
|
329
|
+
| Assunto de commit fora de `tipo(escopo): descrição`, com mais de 80 caracteres, ou com co-autoria ou assinatura de IA | hook de git `commit-msg` |
|
|
330
|
+
| Módulo do back importando por dentro de outro módulo | `.harness/arch_check.py`, dentro do `.harness/validate` |
|
|
331
|
+
| Arquivo gerenciado alterado fora da atualização | `.harness/manifest_check.py`, dentro do `.harness/validate` |
|
|
332
|
+
| Push sem os quatro vereditos sobre o commit do topo | `.harness/gate-check`, chamado pelo `.harness/push` e pelo hook `pre-push` |
|
|
333
|
+
| Push de branch com commit `feat` e sem spec | `.harness/gate-check` |
|
|
334
|
+
| Push com pendência aberta | `.harness/gate-check` |
|
|
335
|
+
| Pull request com título fora do formato, sem o parágrafo de abertura, sem as seções "Critérios de aceite" e "Validação", com assinatura de IA, ou de branch que não passou pelo push | `.harness/pr` |
|
|
336
|
+
| Compose que dá a um contêiner acesso a algo fora da pasta do projeto | `.harness/compose_check.py`, dentro do `.harness/up` |
|
|
337
|
+
| Carimbo manual de aprovação por um agente | sandbox e exigência de terminal no `.harness/approve` |
|
|
338
|
+
|
|
339
|
+
Um erro interno de um guard vira negação, nunca liberação.
|
|
340
|
+
|
|
341
|
+
## O que é instalado e o que é exigido
|
|
342
|
+
|
|
343
|
+
### Pré-requisitos da máquina
|
|
344
|
+
|
|
345
|
+
| Item | Para quê |
|
|
346
|
+
|---|---|
|
|
347
|
+
| macOS ou Linux | os scripts são shell e Python |
|
|
348
|
+
| `git` | o projeto precisa ser um repositório git; o remoto, quando houver, por HTTPS |
|
|
349
|
+
| `python3` 3.9 ou mais novo | hooks, guards e validadores |
|
|
350
|
+
| Node.js 18 ou mais novo | o `npx` do instalador e da instalação das skills |
|
|
351
|
+
| Docker com Compose v2 | o ambiente por feature |
|
|
352
|
+
| Claude Code com sandbox disponível | a barreira de escrita e de rede |
|
|
353
|
+
| `gh` | abrir o pull request (`.harness/pr`) |
|
|
354
|
+
| `rtk` (recomendado) | comprime a saída de git e de testes; sem ele, o hook é ignorado |
|
|
355
|
+
|
|
356
|
+
### Plugins de terceiros
|
|
357
|
+
|
|
358
|
+
O instalador registra os marketplaces e instala, no escopo do projeto, o plugin do harness e
|
|
359
|
+
estes:
|
|
360
|
+
|
|
361
|
+
| Plugin | Origem | Para que serve aqui |
|
|
362
|
+
|---|---|---|
|
|
363
|
+
| `mattpocock-skills` | marketplace oficial `claude-plugins-official` | `grilling` e `domain-modeling` na entrevista, `tdd` na implementação, `diagnosing-bugs` para bugs; traz também skills avulsas, como `code-review`, `prototype`, `research` e `codebase-design` |
|
|
364
|
+
| `ponytail` | `DietrichGebert/ponytail` | sempre ligado: segura o tamanho do código que o agente escreve; a `ponytail-review` dá ao revisor os critérios de duplicação e enxugamento |
|
|
365
|
+
| `frontend-design` | marketplace oficial `claude-plugins-official` | direção visual das telas, para o implementador de front |
|
|
366
|
+
|
|
367
|
+
Os três entram como estão, sem adaptação no conteúdo.
|
|
368
|
+
|
|
369
|
+
### As 20 skills de stack
|
|
370
|
+
|
|
371
|
+
São skills públicas dos autores de cada tecnologia, copiadas para `.claude/skills/` e fixadas
|
|
372
|
+
no `skills-lock.json`. Cada papel usa só as suas; onde uma skill diverge das regras do
|
|
373
|
+
projeto, vale o que está em `docs/agents/stack.md`.
|
|
374
|
+
|
|
375
|
+
| Papel | Skill | Origem | Para quê |
|
|
376
|
+
|---|---|---|---|
|
|
377
|
+
| quem fatia | `parallel-feature-development` | `wshobson/agents` | fatiar para trabalho paralelo: um dono por arquivo, contrato primeiro |
|
|
378
|
+
| ticket de contrato | `pnpm` | `antfu/skills` | monorepo e dependências |
|
|
379
|
+
| ticket de contrato e páginas públicas | `seo` | `addyosmani/web-quality-skills` | SEO técnico |
|
|
380
|
+
| implementadores | `zod` | `anivar/zod-skill` | validação e contrato |
|
|
381
|
+
| todos | `vitest` | `antfu/skills` | testes de unidade e integração |
|
|
382
|
+
| módulo do back | `hexagonal-architecture` | `affaan-m/ecc` | use case, portas, adaptadores, ponto único de montagem |
|
|
383
|
+
| módulo do back | `nestjs-best-practices` | `kadajett/agent-nestjs-skills` | NestJS: módulos, injeção, erros, testes |
|
|
384
|
+
| módulo do back | `drizzle-orm-patterns` | `giuseppe-trisciuoglio/developer-kit` | acesso a banco |
|
|
385
|
+
| módulo do back | `supabase-postgres-best-practices` | `supabase/agent-skills` | esquema e consultas no Postgres |
|
|
386
|
+
| módulo do back | `bullmq` | `jgamaraalv/ts-dev-kit` | filas |
|
|
387
|
+
| módulo do back e caçador de bugs | `property-based-testing` | `trailofbits/skills` | teste por propriedade em regra com borda (data, dinheiro, intervalo) |
|
|
388
|
+
| fatia do front | `feature-sliced-design` | `feature-sliced/skills` | camadas, fatias, entrada pública |
|
|
389
|
+
| fatia do front | `nextjs-app-router-patterns` | `wshobson/agents` | Next.js: App Router, componentes de servidor e de cliente |
|
|
390
|
+
| fatia do front | `vercel-react-best-practices` | `vercel-labs/agent-skills` | React e desempenho no front |
|
|
391
|
+
| fatia do front | `shadcn` | `shadcn-ui/ui` | componentes de interface |
|
|
392
|
+
| ticket de ponta a ponta | `playwright-best-practices` | `currents-dev/playwright-best-practices-skill` | testes de ponta a ponta |
|
|
393
|
+
| revisor de código | `clean-code-guard` | `amelnagdy/guard-skills` | a rubrica do revisor: nomes, funções, SOLID, DRY |
|
|
394
|
+
| revisor de código | `accessibility` | `addyosmani/web-quality-skills` | acessibilidade |
|
|
395
|
+
| revisor de segurança | `owasp-security` | `agamm/claude-code-owasp` | lista do que procurar na revisão de segurança |
|
|
396
|
+
| quem fecha a entrega | `write-pr-description` | `warpdotdev/common-skills` | texto do pull request |
|
|
397
|
+
|
|
398
|
+
As 20 valem no perfil `fullstack-typescript`. O perfil `livre` recebe
|
|
399
|
+
`hexagonal-architecture`, `parallel-feature-development` e `clean-code-guard`; o perfil
|
|
400
|
+
`existente`, as duas últimas. Para outra tecnologia, `/harness:buscar-skills` procura, lê e
|
|
401
|
+
mostra candidatas, e só instala o que você aprovar.
|
|
402
|
+
|
|
403
|
+
### Arquivos gravados no projeto
|
|
404
|
+
|
|
405
|
+
| Caminho | O que é | Quem muda |
|
|
406
|
+
|---|---|---|
|
|
407
|
+
| `.harness/` | os scripts, os hooks, os hooks de git e os roteiros da entrega | gerenciado: só `.harness/update` |
|
|
408
|
+
| `.claude/settings.json` | plugins, hooks, sandbox e permissões | gerenciado; o que é do projeto entra por `harness.d/settings.json` |
|
|
409
|
+
| `CLAUDE.md` | aponta para o `AGENTS.md` | gerenciado |
|
|
410
|
+
| `docs/agents/` | onde ficam o glossário, os ADRs e os tickets e, no perfil padrão, a stack (`stack.md`) | gerenciado |
|
|
411
|
+
| `orca.yaml` | integração com o Orca: prepara o worktree ao abrir | gerenciado |
|
|
412
|
+
| `AGENTS.md` | papéis, ciclo, arquitetura e portões, entre os marcadores `harness:begin` e `harness:end` | a região entre os marcadores é gerenciada; o que está abaixo dela é do projeto |
|
|
413
|
+
| `harness.conf` | a configuração do projeto | o dono, ou o agente por `.harness/conf-apply` |
|
|
414
|
+
| `harness.d/settings.json` | hooks, permissões, servidores MCP e sites liberados só do projeto, somados na geração | só o dono |
|
|
415
|
+
| `.claude/skills/` e `skills-lock.json` | as skills dos autores | só `.harness/skills-add`, com a sua confirmação |
|
|
416
|
+
|
|
417
|
+
Arquivo gerenciado não se edita no projeto: uma mudança de padrão se faz no repositório do
|
|
418
|
+
harness e chega por atualização. Ficam livres o código, o `CLAUDE.local.md` e a parte do
|
|
419
|
+
`AGENTS.md` abaixo da região gerenciada. Durante o trabalho, os arquivos temporários ficam em
|
|
420
|
+
`.harness-run/`, fora do versionamento.
|
|
54
421
|
|
|
55
422
|
## Instalar num projeto
|
|
56
423
|
|
|
@@ -98,9 +465,9 @@ No fim, relate em poucas linhas o que foi instalado e o comando para começar a
|
|
|
98
465
|
|
|
99
466
|
Ele grava `.harness/`, `.claude/settings.json`, `AGENTS.md`, `CLAUDE.md`, `docs/agents/` e
|
|
100
467
|
`orca.yaml`, registra os marketplaces, e instala no escopo do projeto o plugin do harness e os
|
|
101
|
-
de terceiros (`mattpocock-skills`, `ponytail`). Se o `harness.conf` já
|
|
102
|
-
também grava as portas no `.env` e instala as dependências. Pode ser
|
|
103
|
-
gerenciado alterado à mão trava a instalação; `--force` substitui.
|
|
468
|
+
de terceiros (`mattpocock-skills`, `ponytail`, `frontend-design`). Se o `harness.conf` já
|
|
469
|
+
estiver preenchido, também grava as portas no `.env` e instala as dependências. Pode ser
|
|
470
|
+
rodado de novo. Arquivo gerenciado alterado à mão trava a instalação; `--force` substitui.
|
|
104
471
|
|
|
105
472
|
### Perfis
|
|
106
473
|
|
|
@@ -112,120 +479,201 @@ O instalador aceita `--profile`, e a escolha fica no `harness.conf`:
|
|
|
112
479
|
| `livre` | projeto novo em outra stack | os conceitos de arquitetura; a stack é escolhida na spec |
|
|
113
480
|
| `existente` | projeto que já tinha código | nada de arquitetura nem de língua: vale o que o projeto já usa |
|
|
114
481
|
|
|
115
|
-
O núcleo vale nos três: sandbox, os
|
|
116
|
-
|
|
482
|
+
O núcleo vale nos três: sandbox, os portões do push, tickets com posse de arquivo, contrato
|
|
483
|
+
primeiro e paralelismo.
|
|
117
484
|
|
|
118
485
|
O que é só do projeto (hooks, permissões, servidores MCP, sites liberados) vai em
|
|
119
486
|
`harness.d/settings.json`, que é somado na geração.
|
|
120
487
|
|
|
121
|
-
##
|
|
488
|
+
## Comandos
|
|
122
489
|
|
|
123
|
-
|
|
124
|
-
o servidor de git e só acessa os sites liberados. Para você, no terminal, nada muda.
|
|
490
|
+
### Os comandos do plugin
|
|
125
491
|
|
|
126
|
-
|
|
492
|
+
| Comando | Para quê |
|
|
493
|
+
|---|---|
|
|
494
|
+
| `/harness:entregar <pedido>` | conduz uma mudança da entrevista ao pull request, dentro do worktree de uma feature |
|
|
495
|
+
| `/harness:setup` | configura o harness num projeto que já tinha código: propõe o `harness.conf` e a parte do projeto no `AGENTS.md` |
|
|
496
|
+
| `/harness:buscar-skills` | procura skills públicas para a stack do projeto, lê cada candidata, mostra o que achou e só instala o que você aprovar |
|
|
497
|
+
| `/harness:mapear` | gera ou atualiza o mapa do código e as âncoras do glossário e dos ADRs |
|
|
498
|
+
| `/harness:aprender` | depois do merge: atualiza o mapa, mede o consumo por papel, faz a retrospectiva e consolida as notas |
|
|
499
|
+
| `/harness:dream` | transforma o que as sessões ensinaram sobre o projeto em notas curtas, ancoradas no código |
|
|
127
500
|
|
|
128
|
-
|
|
501
|
+
### Os scripts do projeto
|
|
502
|
+
|
|
503
|
+
| Script | Para quê | Quem roda |
|
|
129
504
|
|---|---|---|
|
|
130
|
-
| `.harness/up` | sobe a infra da feature | você ou o
|
|
131
|
-
| `.harness/prepare` | migration e seed | você ou o
|
|
132
|
-
| `.harness/dev` | o
|
|
133
|
-
| `.harness/down` | para o
|
|
134
|
-
| `.harness/destroy` | remove o ambiente da feature |
|
|
135
|
-
| `.harness/
|
|
136
|
-
| `.harness/
|
|
137
|
-
| `.harness/
|
|
138
|
-
| `.harness/
|
|
505
|
+
| `.harness/up` | sobe a infra da feature | você ou o orquestrador |
|
|
506
|
+
| `.harness/prepare` | migration e seed (`AFTER_UP`) | você ou o orquestrador |
|
|
507
|
+
| `.harness/dev` | o aplicativo (`DEV_CMD`); `--background` deixa rodando | você ou o orquestrador |
|
|
508
|
+
| `.harness/down` | para o aplicativo e os contêineres, mantém os dados | você ou o orquestrador |
|
|
509
|
+
| `.harness/destroy` | remove o ambiente da feature e apaga os dados | você, ou o agente com a sua permissão |
|
|
510
|
+
| `.harness/ports-free` | encerra processo esquecido numa porta da feature | o orquestrador; roda sozinho quando um revisor termina |
|
|
511
|
+
| `.harness/setup-worktree` | prepara um worktree: `.env` e dependências | o Orca ao abrir o worktree, você, ou cada implementador |
|
|
512
|
+
| `.harness/worktree-env` | deriva o projeto Docker e as portas da feature e grava no `.env` | chamado pelos outros scripts |
|
|
513
|
+
| `.harness/conf-apply` | grava o `harness.conf` que o agente propôs, depois de conferido | o agente |
|
|
514
|
+
| `.harness/ticket claim\|reopen` | marca tickets como em andamento, ou reabre um, já com o commit | o orquestrador |
|
|
515
|
+
| `.harness/integrate <ticket> <branch>` | junta o trabalho de um implementador: revisão, posse, merge, checagem | o orquestrador |
|
|
516
|
+
| `.harness/agents-clean` | remove os worktrees de agente já integrados | o orquestrador |
|
|
517
|
+
| `.harness/pendings` | lista as pendências abertas da feature | você ou o agente |
|
|
518
|
+
| `.harness/validate --profile push\|merge` | checagens do projeto, sem custo de IA | você ou o agente |
|
|
139
519
|
| `.harness/fetch` | atualiza as referências do remoto | o agente |
|
|
140
520
|
| `.harness/push` | envia a branch, depois do portão | o agente |
|
|
141
|
-
| `.harness/pr` | abre ou consulta o pull request | o agente |
|
|
142
|
-
| `.harness/
|
|
143
|
-
| `.harness/
|
|
144
|
-
| `.harness/
|
|
145
|
-
| `.harness/
|
|
521
|
+
| `.harness/pr create\|view` | abre ou consulta o pull request | o agente |
|
|
522
|
+
| `.harness/skills-search <termo>` | procura skills públicas | o agente |
|
|
523
|
+
| `.harness/skills-show <repositório> <skill>` | mostra o texto de uma skill candidata | o agente |
|
|
524
|
+
| `.harness/skills-add <repositório> <skill>` | instala uma skill e a fixa no `skills-lock.json` | o agente, com a sua confirmação |
|
|
525
|
+
| `.harness/memory` | o mapa do código, as âncoras e as notas: `check`, `slice <caminho>`, `index`, `units`, `record`, `anchor`, `note` | você ou o agente |
|
|
526
|
+
| `.harness/learn` | as sessões passadas: `sessions`, `usage`, `digest`, `mark` | você ou o agente |
|
|
527
|
+
| `.harness/approve <portão> "<resumo>"` | a sua aprovação manual de um portão | só você, no terminal |
|
|
146
528
|
| `.harness/update <tag>` | leva o projeto para uma versão do harness | só você, no terminal |
|
|
147
529
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
scripts do harness. A qualidade não depende da sua atenção: vem dos portões, dos revisores e do
|
|
152
|
-
sandbox. Se quiser alguma pergunta de volta, acrescente a regra em `permissions.ask` num
|
|
153
|
-
fragmento do projeto (`harness.d/settings.json`); pergunta vence liberação.
|
|
154
|
-
|
|
155
|
-
## Uma primeira entrega
|
|
156
|
-
|
|
157
|
-
1. Abra um worktree para a feature, pelo Orca ou com `git worktree add`. O
|
|
158
|
-
`.harness/setup-worktree` grava as portas dela no `.env` e instala as dependências.
|
|
159
|
-
2. Na sessão do Claude Code, dentro do worktree: `/harness:entregar`.
|
|
160
|
-
3. Responda a entrevista. Leia os achados do revisor da spec e aprove a spec.
|
|
161
|
-
4. Acompanhe: os tickets são criados, os implementadores trabalham em paralelo, a
|
|
162
|
-
checagem roda, os dois revisores e o portão de qualidade dão o veredito, a branch é enviada e o pull request é aberto.
|
|
163
|
-
5. Faça o merge, preservando os commits.
|
|
164
|
-
|
|
165
|
-
## Seguir sem você
|
|
530
|
+
Os scripts que saem do sandbox (`up`, `down`, `destroy`, `conf-apply`, `push`, `fetch`, `pr`,
|
|
531
|
+
`ports-free` e os de skills) rodam sozinhos, um por chamada, na forma exata: sem `&&`, `;`,
|
|
532
|
+
`|` nem `bash` na frente. Para você, no terminal, nada muda.
|
|
166
533
|
|
|
167
|
-
|
|
168
|
-
pergunta recebe a resposta recomendada, a aprovação da spec deixa de ser uma parada, e cada
|
|
169
|
-
decisão tomada sem você fica escrita na spec, na seção "Decisões tomadas sem o dono". Você
|
|
170
|
-
só é chamado se a entrega não fechar em três rodadas de correção, se faltar um dado que só
|
|
171
|
-
você tem, e para o merge.
|
|
534
|
+
## Configuração
|
|
172
535
|
|
|
173
|
-
|
|
536
|
+
O `harness.conf` fica na raiz do projeto, no formato `CHAVE=valor`, uma por linha. Em projeto
|
|
537
|
+
novo ele é preenchido na primeira entrega, a partir da spec; em projeto que já tinha código,
|
|
538
|
+
`/harness:setup` propõe o conteúdo.
|
|
174
539
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
540
|
+
| Chave | O que define | Exemplo |
|
|
541
|
+
|---|---|---|
|
|
542
|
+
| `PROFILE` | o perfil do projeto; mudar pede nova sincronização | `fullstack-typescript` |
|
|
543
|
+
| `PROJECT` | o nome usado no projeto Docker de cada worktree | `meuapp` |
|
|
544
|
+
| `SERVICES` | os serviços que precisam de porta; a ordem define o deslocamento dentro do bloco | `"web api postgres redis"` |
|
|
545
|
+
| `COMPOSE_FILE` | o compose do ambiente | `docker-compose.dev.yml` |
|
|
546
|
+
| `INSTALL_CMD` | a instalação de dependências, rodada ao criar um worktree | `"pnpm install --frozen-lockfile"` |
|
|
547
|
+
| `AFTER_UP` | o que roda depois de a infra ficar saudável: migration, seed | `"pnpm db:migrate"` |
|
|
548
|
+
| `DEV_CMD` | o processo do aplicativo | `"pnpm dev"` |
|
|
549
|
+
| `VALIDATE_PUSH` | a checagem ao fechar e ao integrar cada ticket, e no push feito à mão | `"pnpm test"` |
|
|
550
|
+
| `VALIDATE_MERGE` | a checagem completa, antes de abrir o pull request; é onde entram os testes de ponta a ponta | `"pnpm test && pnpm build"` |
|
|
551
|
+
| `CONTRACT_PATHS` | os caminhos do que é comum (o contrato, a camada `shared` do front): só o ticket de contrato os possui | `"packages/contracts apps/web/src/shared"` |
|
|
552
|
+
| `MODULE_ROOTS` | onde ficam os módulos do back; o harness recusa a importação por dentro de outro módulo | `"apps/api/src/modules"` |
|
|
553
|
+
| `VALIDATE_ARCH` | o comando que confere as demais fronteiras, com a ferramenta da linguagem | `"pnpm exec depcruise apps/api/src && pnpm exec steiger apps/web/src"` |
|
|
554
|
+
| `DEFAULT_BRANCH` | a branch padrão, quando não for `main` nem `master` e o remoto não a anunciar | `trunk` |
|
|
555
|
+
| `MAX_PARALLEL` | o máximo de implementadores em paralelo (3, se não houver) | `3` |
|
|
556
|
+
| `MAP_DEPTH` | a profundidade das unidades do mapa do código | `2` |
|
|
557
|
+
| `MAP_EXCLUDE` | as pastas que ficam fora do mapa | `"docs .harness .claude .github"` |
|
|
558
|
+
| `ADR_REVIEW_COMMITS` | quantos commits na área de um ADR pedem que ele seja relido | `20` |
|
|
559
|
+
| `CONDUCTOR` | gera também a integração com o Conductor (`.conductor/settings.toml`) | `1` |
|
|
560
|
+
| `ENV_<NOME>` | variável derivada das portas, gravada no `.env` do worktree | `ENV_DATABASE_URL='postgresql://app:app@localhost:${POSTGRES_PORT}/app'` |
|
|
561
|
+
|
|
562
|
+
Os perfis estão em [Instalar num projeto](#perfis).
|
|
563
|
+
|
|
564
|
+
## Arquitetura que o harness espera
|
|
565
|
+
|
|
566
|
+
No perfil `fullstack-typescript`, a arquitetura vem junto e está na seção Arquitetura do
|
|
567
|
+
`AGENTS.md`. As skills dos autores ensinam o como; onde elas divergem, vale o `AGENTS.md`.
|
|
568
|
+
|
|
569
|
+
| Parte | Stack padrão |
|
|
570
|
+
|---|---|
|
|
571
|
+
| back | NestJS, Drizzle, Postgres; filas com BullMQ sobre Redis |
|
|
572
|
+
| front | Next.js (App Router), shadcn, Tailwind |
|
|
573
|
+
| contrato e validação | Zod, num pacote comum importado pelos dois lados |
|
|
574
|
+
| testes | Vitest (unidade e integração) e Playwright (ponta a ponta) |
|
|
575
|
+
| monorepo | pnpm |
|
|
576
|
+
|
|
577
|
+
- **Módulos com contrato.** O back se divide em módulos por área de negócio. Um módulo nunca
|
|
578
|
+
importa outro por dentro: o que um oferece ao outro é uma porta definida no que é comum,
|
|
579
|
+
pelo ticket de contrato. O que front e back trocam fica num pacote comum, importado pelos dois.
|
|
580
|
+
- **Portas e adaptadores no back.** Dentro de cada módulo: domínio, use cases, portas e
|
|
581
|
+
adaptadores, com as dependências apontando para dentro. Um use case por comportamento,
|
|
582
|
+
recebendo as portas por injeção, sem importar framework. Porta só para o que sai do
|
|
583
|
+
processo (banco, fila, serviço externo); log, relógio e utilitário não viram porta.
|
|
584
|
+
- **Feature-Sliced Design no front.** O código nasce na página, cada fatia tem entrada
|
|
585
|
+
pública, e só se importa de camada abaixo.
|
|
586
|
+
- **Código em inglês.** Identificadores, arquivos, pastas, rotas e mensagens de commit. Em
|
|
587
|
+
português ficam o texto que o usuário vê, a spec, os tickets e o glossário, que traz o nome
|
|
588
|
+
em inglês de cada termo de domínio.
|
|
589
|
+
|
|
590
|
+
Uma spec pode escolher outra peça da stack, dizendo o motivo. No perfil `livre` valem os
|
|
591
|
+
conceitos (módulos, portas, contrato num lugar só) em qualquer linguagem; no perfil
|
|
592
|
+
`existente` vale a organização que o repositório já tem.
|
|
593
|
+
|
|
594
|
+
## Ambiente por feature
|
|
595
|
+
|
|
596
|
+
Uma feature é um worktree, e cada worktree tem o próprio ambiente: um projeto Docker e um
|
|
597
|
+
bloco de portas derivados do nome da pasta, gravados no `.env`. Ninguém escolhe porta à mão.
|
|
598
|
+
Os worktrees de agente, onde os implementadores trabalham, usam o ambiente da feature de onde
|
|
599
|
+
saíram. O ambiente só sobe quando a validação exige; `docker` solto não funciona dentro do
|
|
600
|
+
sandbox, e o caminho é `.harness/up`, que confere o compose antes de subir.
|
|
601
|
+
|
|
602
|
+
## Memória do projeto
|
|
603
|
+
|
|
604
|
+
- **O mapa do código.** `/harness:mapear` gera um resumo curto de cada parte do repositório,
|
|
605
|
+
escrito por subagentes em Haiku e guardado fora dos arquivos versionados. Cada resumo fica
|
|
606
|
+
ancorado no commit em que foi escrito: `.harness/memory check` diz, sem custo de IA, o que
|
|
607
|
+
envelheceu, e só isso é refeito. Toda sessão começa com o índice do mapa.
|
|
608
|
+
- **Glossário e ADRs ancorados.** O `check` também aponta termos do glossário cujo código não
|
|
609
|
+
existe mais e ADRs cuja área mudou bastante. A decisão sobre eles é do dono.
|
|
610
|
+
- **Depois do merge.** `/harness:aprender` atualiza o mapa, mostra os tokens de cada papel
|
|
611
|
+
(`.harness/learn usage`), faz a retrospectiva da entrega e, com `/harness:dream`, grava
|
|
612
|
+
notas ancoradas no código. Uma nota só entra se o código de hoje a confirma. As propostas
|
|
613
|
+
de melhoria ficam em `.harness-run/propostas/`.
|
|
614
|
+
|
|
615
|
+
## Projeto sem remoto
|
|
616
|
+
|
|
617
|
+
O harness não exige remoto para começar. Sem ele, a entrega roda até o fim: os tickets são
|
|
618
|
+
integrados, a checagem passa, os quatro vereditos são dados, e `.harness/push` confere os
|
|
619
|
+
portões do mesmo jeito e termina dizendo que a branch está aprovada e que nada foi enviado.
|
|
620
|
+
Não há pull request; o aplicativo fica de pé e o relato diz o que falta para publicar. Quando
|
|
621
|
+
o remoto existir, o primeiro envio da branch padrão é seu, no terminal.
|
|
622
|
+
|
|
623
|
+
## Atualizar o harness
|
|
624
|
+
|
|
625
|
+
Uma mudança de padrão se faz no repositório do harness e sai numa tag. No projeto, no seu
|
|
626
|
+
terminal:
|
|
191
627
|
|
|
192
628
|
```bash
|
|
193
|
-
.harness/update
|
|
629
|
+
.harness/update <tag>
|
|
194
630
|
```
|
|
195
631
|
|
|
196
|
-
|
|
632
|
+
O comando baixa a tag e executa o sincronizador daquela versão, para que o plugin, a pasta
|
|
633
|
+
`.harness/` e os arquivos gerados saiam todos com a mesma versão. Arquivo gerenciado que foi
|
|
634
|
+
alterado à mão trava a atualização, que lista o que encontrou; `--force` substitui. O agente
|
|
635
|
+
não roda a atualização: dentro do sandbox ele não grava em `.harness/`.
|
|
636
|
+
|
|
637
|
+
## O que já foi provado e o que ainda não
|
|
197
638
|
|
|
198
|
-
|
|
639
|
+
**O que tem prova:**
|
|
199
640
|
|
|
200
|
-
|
|
201
|
-
|
|
641
|
+
- As peças têm testes automáticos: os guards, o carimbo a partir do veredito, o portão de
|
|
642
|
+
push, o validador do grafo de tickets, a integração com posse, as pendências, as fronteiras
|
|
643
|
+
entre módulos, o instalador, a atualização e os scripts de ambiente. A suíte roda no CI.
|
|
644
|
+
- Os testes também conferem a coerência entre o que os roteiros mandam fazer e o que os
|
|
645
|
+
guards aceitam.
|
|
646
|
+
- O ciclo completo foi exercitado em entregas que partem de um projeto do zero, com um pedido
|
|
647
|
+
curto, no perfil `fullstack-typescript`.
|
|
202
648
|
|
|
203
|
-
|
|
204
|
-
- `.harness/push` enviando para o GitHub com as suas credenciais, e `.harness/pr` com o `gh`.
|
|
205
|
-
- `/harness:setup` e `/harness:entregar` de ponta a ponta. A orquestração é conduzida por
|
|
206
|
-
um modelo e não tem teste automático: os testes cobrem as peças e a coerência entre o que
|
|
207
|
-
a skill manda fazer e o que os guards aceitam.
|
|
208
|
-
- O carimbo automático a partir do veredito dos revisores, com os dois revisores. Só o
|
|
209
|
-
de segurança rodou de ponta a ponta numa sessão real.
|
|
210
|
-
- Instalar dependências (`pnpm install`) dentro do sandbox, num projeto com muitas.
|
|
211
|
-
- A trava contra desligar o sandbox, numa sessão interativa.
|
|
212
|
-
- `/harness:aprender` e `/harness:dream` sobre uma entrega de verdade: se a leitura das
|
|
213
|
-
transcrições reconhece o formato das suas sessões, se os números de consumo batem, e se as
|
|
214
|
-
notas que saem valem a pena.
|
|
215
|
-
- `/harness:mapear` num projeto de verdade: a qualidade dos resumos, o custo da primeira
|
|
216
|
-
geração, e o hook que injeta o índice no começo da sessão.
|
|
217
|
-
- Um push por SSH: a rede é negada por nome de servidor, e não foi conferido se isso cobre SSH.
|
|
649
|
+
**O que ainda não foi provado:**
|
|
218
650
|
|
|
219
|
-
|
|
651
|
+
- **Uma segunda entrega sobre código que já existe.** As entregas exercitadas partiram de um
|
|
652
|
+
projeto vazio. Evoluir um sistema já entregue, com o mapa, o glossário e a suíte de ponta a
|
|
653
|
+
ponta protegendo o que funciona, ainda não foi posto à prova.
|
|
654
|
+
- **Os perfis fora do `fullstack-typescript`.** `livre` e `existente` têm testes das peças,
|
|
655
|
+
mas não uma entrega de ponta a ponta.
|
|
656
|
+
- **Achar defeito continua dependendo de um revisor que é um modelo.** Os trilhos garantem
|
|
657
|
+
que a revisão acontece, sobre o commit certo, por quem não escreveu o código. Não garantem
|
|
658
|
+
que o revisor enxergue todo defeito.
|
|
659
|
+
- **A orquestração em si não tem teste automático.** Ela é conduzida por um modelo: os testes
|
|
660
|
+
cobrem as peças, não a condução.
|
|
661
|
+
|
|
662
|
+
**Limites conhecidos:**
|
|
220
663
|
|
|
221
664
|
- Sem o sandbox ligado, os portões protegem contra descuido, não contra um agente que insiste.
|
|
222
|
-
- Um servidor de desenvolvimento que vigia arquivos pode não subir dentro do sandbox (visto
|
|
223
|
-
o `next dev`).
|
|
665
|
+
- Um servidor de desenvolvimento que vigia arquivos pode não subir dentro do sandbox (visto
|
|
666
|
+
com o `next dev`). Os testes de ponta a ponta rodam sobre o build de produção.
|
|
667
|
+
- O navegador dos testes de ponta a ponta não abre dentro do sandbox: ele roda num contêiner
|
|
668
|
+
do ambiente.
|
|
224
669
|
- No Linux o sandbox não alcança `localhost`; `prepare` e `dev` precisariam de outra saída.
|
|
225
|
-
-
|
|
670
|
+
- Os implementadores de uma mesma feature dividem o ambiente dela; a spec precisa dizer como
|
|
671
|
+
cada um isola o seu banco de teste.
|
|
672
|
+
- O sandbox só alcança o registro do npm. Dependência de outro lugar pede um domínio liberado
|
|
673
|
+
em `harness.d/settings.json`, e liberar é do dono.
|
|
674
|
+
- O carimbo automático lê o veredito da transcrição do subagente. Se ele não acontecer, a
|
|
675
|
+
falha é fechada: o push fica negado, e o dono usa `.harness/approve`.
|
|
226
676
|
- Não há suporte ao Codex ainda.
|
|
227
|
-
- Seis revisões adversariais acharam falhas reais, todas corrigidas. Isso mostra que
|
|
228
|
-
revisar funciona, e não que não reste nenhuma.
|
|
229
677
|
|
|
230
678
|
## Desenvolver o harness
|
|
231
679
|
|
|
@@ -236,4 +684,6 @@ python3 -m unittest discover -s tests
|
|
|
236
684
|
Os testes gravam em `~/.claude/harness/` e apagam ao sair, então não rodam de dentro de
|
|
237
685
|
uma sessão com o sandbox ligado. Alguns usam Docker de verdade e são pulados sem ele.
|
|
238
686
|
|
|
239
|
-
Licença
|
|
687
|
+
## Licença
|
|
688
|
+
|
|
689
|
+
MIT.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fullchico/harness",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "Trilhos e portões para projetos desenvolvidos com agentes no Claude Code: orquestração por ticket, revisão independente presa ao commit, ambiente por feature.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "FullChico",
|
|
Binary file
|
|
Binary file
|