Skip to content

Commit 51a6d70

Browse files
sanbuphysanbuphy
authored
Merge pull request #45 from jpcmf/add-projects-and-skills-portuguese-br-translation
Add Portuguese (BR) localization for projects and skills documentation
2 parents 7913b8c + 32d61ee commit 51a6d70

19 files changed

Lines changed: 726 additions & 8 deletions

File tree

‎docs-readme/pt-BR/README.md‎

Lines changed: 298 additions & 8 deletions
Large diffs are not rendered by default.

‎projects/project-01/README-PT-BR.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Projeto 01: Baseline vs. Harness Mínimo
2+
3+
Compare como um harness fraco (apenas prompt) e um harness explícito (arquivos de regras mais mecanismos de verificação) afetam a taxa de conclusão de tarefas de agentes de programação com IA.
4+
5+
## Guia de Diretórios
6+
7+
| Diretório | Significado |
8+
|------|------|
9+
| `starter/` | **Ponto de partida**: apenas um `task-prompt.md` vago, sem `AGENTS.md` e sem `feature_list.json`. Esta é a versão de "harness fraco" que você entrega ao agente. |
10+
| `solution/` | **Implementação de referência**: o mesmo código da aplicação, mas com arquivos completos de harness (`AGENTS.md`, `feature_list.json`, `init.sh`, `claude-progress.md`). Esta é a versão de "harness explícito". |
11+
12+
## Como Usar
13+
14+
```sh
15+
# 1. Execute a tarefa do agente uma vez com starter (harness fraco)
16+
cd starter
17+
npm install
18+
# Forneça o conteúdo de task-prompt.md como prompt para Claude Code / Codex
19+
# Peça ao agente para concluir: inicialização da janela, lista de documentos, painel de QA, diretório de dados
20+
# Não forneça os arquivos da solução ao agente durante esta execução.
21+
22+
# 2. Execute a mesma tarefa com solution (harness explícito)
23+
cd ../solution
24+
npm install
25+
# Peça ao agente para ler AGENTS.md, init.sh, feature_list.json e claude-progress.md
26+
# antes de alterar o código. O código do produto já deve satisfazer as mesmas quatro funcionalidades.
27+
28+
# 3. Compare os dois resultados
29+
# - A tarefa foi concluída?
30+
# - Quantas tentativas adicionais foram necessárias?
31+
# - O agente afirmou "concluído" cedo demais?
32+
```
33+
34+
## Contrato Exato da Tarefa
35+
36+
O prompt inicial é intencionalmente vago (`starter/task-prompt.md` contém apenas
37+
"Construa uma aplicação Electron que possa exibir documentos e responder perguntas."). Use o harness da solução para tornar essa solicitação vaga concreta:
38+
39+
| Funcionalidade | Evidência do Starter para inspecionar | Evidência da Solution para comparar |
40+
|------|------|------|
41+
| Inicialização da janela | `src/main/main.ts`, `src/preload/preload.ts` | Item `window-launch` do `feature_list.json` |
42+
| Painel de lista de documentos | `src/renderer/components/DocumentList.tsx` | Item `document-list` do `feature_list.json` |
43+
| Painel de perguntas | `src/renderer/components/QuestionPanel.tsx` | Item `question-panel` do `feature_list.json` |
44+
| Diretório de dados | `src/services/persistence-service.ts` | Item `data-directory` do `feature_list.json` |
45+
46+
Este projeto é um experimento, não uma tarefa comum de "preencher o starter até que ele seja igual à solução". O resultado de aprendizado é a diferença medida entre uma execução baseada apenas em prompt e uma execução que começa com regras explícitas do repositório e artefatos de verificação.
47+
48+
## Funcionalidades Cobertas
49+
50+
- A janela do Electron inicia com sucesso
51+
- A interface exibe a área da lista de documentos
52+
- A interface exibe o painel de QA
53+
- A aplicação cria e utiliza um diretório de dados local
54+
55+
## Aulas Relacionadas
56+
57+
- [Aula 01: Por Que Agentes Capazes Ainda Falham](../../docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.md)
58+
- [Aula 02: O Que É Um Harness na Prática](../../docs/pt-BR/lectures/lecture-02-what-a-harness-actually-is/index.md)

‎projects/project-02/README-PT-BR.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Projeto 02: Workspace Legível por Agentes
2+
3+
Demonstre como a legibilidade do repositório e artefatos explícitos de continuidade reduzem a perda de contexto durante o desenvolvimento em múltiplas sessões.
4+
5+
## Guia de Diretórios
6+
7+
| Diretório | Significado |
8+
|------|------|
9+
| `starter/` | **Ponto de partida**: baseado na solução do P1, com importação de documentos, visualização de detalhes e persistência ainda pendentes de implementação. O harness é fraco: o `AGENTS.md` é mínimo e não existe um handoff de sessão. |
10+
| `solution/` | **Implementação de referência**: todos os novos recursos estão implementados, com documentação completa do workspace (`ARCHITECTURE.md`, `PRODUCT.md`, `session-handoff.md`). |
11+
12+
## Como Usar
13+
14+
```sh
15+
# Requer pelo menos 2 sessões de agente para concluir
16+
cd starter
17+
npm install
18+
# Sessão A: implemente a importação de documentos e a visualização de detalhes
19+
# Sessão B: implemente a persistência (observe se o agente recupera rapidamente o contexto)
20+
21+
cd ../solution
22+
npm install
23+
# Execute novamente com o harness completo e compare a velocidade de recuperação da sessão
24+
```
25+
26+
## Contrato Exato da Tarefa
27+
28+
Comece a partir de `starter/`. O starter já contém o shell do Projeto 01 e um
29+
harness mínimo. O trabalho é adicionar o recorte de produto do Projeto 02 e a
30+
documentação do workspace que permite que uma segunda sessão recupere o contexto rapidamente.
31+
32+
| Funcionalidade / artefato | Estado no Starter | Evidência da Solution |
33+
|------|------|------|
34+
| Importação de documentos | O fluxo de importação está incompleto entre renderer, preload, IPC e `DocumentService` | `src/renderer/components/ImportPanel.tsx`, `src/main/ipc-handlers.ts`, `src/services/document-service.ts` |
35+
| Detalhes do documento | O painel de detalhes não carrega nem renderiza o conteúdo completo do arquivo via IPC | `src/renderer/components/DocumentDetail.tsx`, `IPC_CHANNELS.GET_DOCUMENT_CONTENT` |
36+
| Persistência básica | Documentos importados não são totalmente restaurados após reinicialização | `src/services/persistence-service.ts`, tratamento de `documents-meta.json` |
37+
| Estado legível pelo agente | Não existe arquivo final de handoff no starter | `session-handoff.md`, `docs/ARCHITECTURE.md` expandido, `docs/PRODUCT.md` expandido |
38+
39+
Execute isso como um exercício de duas sessões. Encerre a Sessão A antes que as três
40+
funcionalidades do produto estejam completas e, em seguida, inicie a Sessão B usando
41+
apenas o estado atual do repositório. A principal comparação é o quanto mais rápido
42+
a Sessão B consegue retomar quando `session-handoff.md` e a documentação existem.
43+
44+
## Funcionalidades Cobertas
45+
46+
- Fluxo de importação de documentos (seletor de arquivos mais transferência via IPC)
47+
- Visualização de detalhes do documento (metadados mais exibição do conteúdo)
48+
- Persistência básica (documentos importados permanecem após reinicialização)
49+
50+
## Aulas Relacionadas
51+
52+
- [Aula 03: Por Que o Repositório Deve se Tornar a Fonte Oficial da Verdade](../../docs/pt-BR/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
53+
- [Aula 04: Por Que Um Único Arquivo Gigante de Instruções Falha](../../docs/pt-BR/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)

‎projects/project-03/README-PT-BR.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Projeto 03: Continuidade entre Múltiplas Sessões com Controle de Escopo
2+
3+
Avalie se logs de progresso, handoff de sessão, controle explícito de escopo e
4+
gates de verificação melhoram a precisão da entrega durante reinicializações.
5+
6+
## Guia de Diretórios
7+
8+
| Diretório | Significado |
9+
|------|------|
10+
| `starter/` | **Ponto de partida**: baseado na solução do P2, com divisão de documentos em partes, extração de metadados, status de indexação e QA baseado em contexto ainda pendentes de implementação. Ele possui um `feature_list.json` inicial, mas não possui o harness completo de retomada (`init.sh`, `session-handoff.md`, `claude-progress.md`, checklist de estado limpo). |
11+
| `solution/` | **Implementação de referência**: todos os recursos estão implementados. O `AGENTS.md` inclui a estratégia de "uma funcionalidade por vez", e o repositório adiciona artefatos de reinicialização/continuidade (`init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md`). |
12+
13+
## Como Usar
14+
15+
```sh
16+
cd starter
17+
npm install
18+
# Execute pelo menos duas sessões de agente. Interrompa uma vez no meio da tarefa e depois retome a partir do estado do repositório.
19+
# Observe se o agente mantém o escopo e atualiza o feature_list.json.
20+
21+
cd ../solution
22+
npm install
23+
# Inspecione os artefatos de continuidade concluídos e as evidências das funcionalidades.
24+
```
25+
26+
## Contrato Exato da Tarefa
27+
28+
O starter do Projeto 03 não é uma aplicação vazia. Ele é o Projeto 02 mais o trabalho
29+
de indexação e QA baseado em contexto ainda não concluído. Complete estes itens um por vez:
30+
31+
| Funcionalidade / artefato | Estado no Starter | Evidência da Solution |
32+
|------|------|------|
33+
| Divisão de documentos em partes | `IndexingService` precisa criar chunks considerando parágrafos | `src/services/indexing-service.ts`, item `document-chunking` do `feature_list.json` |
34+
| Extração de metadados | Os metadados dos documentos estão incompletos para o trabalho de indexação | `src/services/document-service.ts`, `DocumentDetail.tsx`, item `metadata-extraction` |
35+
| Interface de status de indexação | Barra de status precisa exibir quantidade indexada / total de chunks / status por cores | `src/renderer/components/StatusBar.tsx`, `App.tsx`, item `indexing-status-ui` |
36+
| QA baseado em contexto | O QA deve citar chunks recuperados com trechos e nível de confiança | `src/services/qa-service.ts`, `QuestionPanel.tsx`, item `grounded-qa` |
37+
| Harness de continuidade | O Starter não possui os artefatos finais de retomada/handoff | `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md` |
38+
39+
Não trate isso como "adicionar qualquer funcionalidade de múltiplas sessões". O recorte
40+
de produto esperado é indexação mais QA baseado em citações, e o recorte de harness
41+
esperado é o rastreamento de progresso que permite retomada.
42+
43+
## Funcionalidades Cobertas
44+
45+
- Divisão de documentos em partes (baseada em parágrafos, cerca de 500 caracteres)
46+
- Extração de metadados (contagem de palavras, contagem de linhas, contagem de parágrafos)
47+
- Status da indexação exibido na interface
48+
- Fluxo básico de QA com citações de fontes
49+
50+
## Aulas Relacionadas
51+
52+
- [Aula 05: Por Que Tarefas de Longa Duração Perdem Continuidade](../../docs/pt-BR/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
53+
- [Aula 06: Por Que a Inicialização Precisa Ter Sua Própria Fase](../../docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)

‎projects/project-04/README-PT-BR.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Projeto 04: Feedback em Tempo de Execução e Controle Estrutural
2+
3+
Introduza observabilidade em tempo de execução e verificações de limites estruturais enquanto depura um defeito de execução pré-configurado.
4+
5+
## Guia de Diretórios
6+
7+
| Diretório | Significado |
8+
|------|------|
9+
| `starter/` | **Ponto de partida**: baseado na solução do P3, com recursos de logging e limites estruturais ainda pendentes de implementação. O `IndexingService` contém um bug oculto pré-configurado: arquivos com mais de 1000 caracteres podem gerar chunks vazios. Não existe script de verificação de arquitetura nem checklist final de estado limpo. |
10+
| `solution/` | **Implementação de referência**: módulo de logging estruturado, script de verificação de limites de arquitetura e o bug pré-configurado corrigido. |
11+
12+
## Como Usar
13+
14+
```sh
15+
cd starter
16+
npm install
17+
# 1. Observe se o agente consegue localizar o bug através dos logs
18+
# 2. Importe um arquivo grande e verifique se o comportamento de divisão em chunks está incorreto
19+
20+
cd ../solution
21+
npm install
22+
# Compare como logs estruturados aceleram o diagnóstico
23+
```
24+
25+
## Contrato Exato da Tarefa
26+
27+
O Projeto 04 é um exercício de depuração e criação de proteções. O starter já contém
28+
o recorte de produto do Projeto 03, mas o ambiente de execução é mais difícil de
29+
inspecionar e o defeito de divisão em chunks pré-configurado deve ser corrigido somente
30+
depois que o agente conseguir visualizar evidências suficientes.
31+
32+
| Funcionalidade / artefato | Estado no Starter | Evidência da Solution |
33+
|------|------|------|
34+
| Logging estruturado | Não existe um serviço de logger compartilhado | `src/services/logger.ts`, chamadas de logging em `main.ts`, `ipc-handlers.ts` e serviços |
35+
| Diagnósticos de importação / indexação | Falhas são difíceis de rastrear a partir da saída de execução | Entradas de log ao redor da importação, início/conclusão da indexação e caminhos de falha do QA |
36+
| Limites de arquitetura | Não existe script que verifique desvios entre limites de renderer/main/service | `scripts/check-architecture.sh`, `docs/ARCHITECTURE.md`, regras de limites no AGENTS |
37+
| Bug pré-configurado de divisão em chunks | Arquivos grandes podem gerar saída de chunks inválida/vazia | Lógica de parágrafos/chunks corrigida em `src/services/indexing-service.ts` |
38+
| Handoff limpo | O Starter não possui checklist final | `clean-state-checklist.md` |
39+
40+
Use um documento de exemplo longo para reproduzir o bug antes e depois da correção.
41+
Uma solução bem-sucedida deve apresentar tanto alterações no código quanto evidências
42+
de diagnóstico, não apenas uma afirmação de que passou.
43+
44+
## Funcionalidades Cobertas
45+
46+
- Logs de inicialização
47+
- Logs de importação e indexação
48+
- Caminho de falha do QA visível
49+
- Limites explícitos entre as camadas main, preload, renderer e services
50+
- Depuração de um defeito de execução pré-configurado
51+
52+
## Aulas Relacionadas
53+
54+
- [Aula 07: Por Que Agentes Extrapolam o Escopo e Não Finalizam](../../docs/pt-BR/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
55+
- [Aula 08: Por Que Listas de Funcionalidades São Primitivas de Harness](../../docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)

‎projects/project-05/README-PT-BR.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Projeto 05: Loops de Avaliação e Evoluções com Três Papéis
2+
3+
Meça como a separação de papéis (um único papel, gerador mais avaliador, planejador mais gerador mais avaliador) altera a qualidade da implementação.
4+
5+
## Guia de Diretórios
6+
7+
| Diretório | Significado |
8+
|------|------|
9+
| `starter/` | **Ponto de partida**: baseado na solução do P4, com o histórico de conversas em múltiplas interações ainda pendente de implementação. |
10+
| `solution/single-role/` | **Variante A**: um agente faz todo o trabalho (planejamento, implementação e autoavaliação). Qualidade de referência inicial. |
11+
| `solution/gen-eval/` | **Variante B**: padrão de gerador mais avaliador. Maior qualidade, com evidências de revisão. |
12+
| `solution/plan-gen-eval/` | **Variante C**: planejador mais gerador mais avaliador. Maior qualidade, com contrato de sprint e critérios de pontuação. |
13+
14+
## Como Usar
15+
16+
```sh
17+
# Comece pelo starter se quiser executar o exercício por conta própria.
18+
cd starter
19+
npm install
20+
# Implemente a mesma evolução do ConversationHistory três vezes usando a configuração de papéis abaixo.
21+
22+
# Inspecione as três variantes de referência independentemente
23+
cd solution/single-role && npm install # modo de papel único
24+
cd solution/gen-eval && npm install # modo gerador mais avaliador
25+
cd solution/plan-gen-eval && npm install # modo completo com três papéis
26+
27+
# Compare as três variantes:
28+
# - Qualidade do código (pontuação do evaluator-rubric.md)
29+
# - Quantidade de defeitos encontrados
30+
# - Quantidade de retrabalho necessário
31+
```
32+
33+
## Contrato Exato da Tarefa
34+
35+
A evolução do produto para as soluções versionadas é fixa: implemente o histórico de
36+
perguntas e respostas em múltiplas interações usando `ConversationHistory`. Os três
37+
diretórios de solução não são etapas sequenciais; são três execuções independentes da
38+
mesma funcionalidade com diferentes papéis de harness.
39+
40+
| Variante | O que demonstra | Evidência para inspecionar |
41+
|------|------|------|
42+
| `starter/` | Aplicação baseada no P4 antes da evolução de histórico de conversas | `src/renderer/components/ConversationHistory.tsx`, `App.tsx` |
43+
| `solution/single-role/` | Um agente planeja, implementa e faz sua própria revisão | Pontuação 1.6/5 do `evaluator-rubric.md` e defeitos listados |
44+
| `solution/gen-eval/` | Gerador e avaliador separados com evidências de revisão | Pontuação 3.3/5 do `evaluator-rubric.md` e notas de revisão |
45+
| `solution/plan-gen-eval/` | Planejador + gerador + avaliador com um contrato de sprint | `sprint-contract.md`, pontuação 4.9/5 do `evaluator-rubric.md` |
46+
47+
Mantenha a funcionalidade constante ao executar novamente o projeto. Alterar a
48+
funcionalidade entre as variantes invalida a comparação, pois a separação de papéis é
49+
a única variável pretendida.
50+
51+
## Funcionalidades Cobertas
52+
53+
- Histórico de QA em múltiplas interações (interface conversacional)
54+
- Contrato de sprint
55+
- Ajuste de critérios de avaliação do avaliador
56+
57+
## Aulas Relacionadas
58+
59+
- [Aula 09: Por Que Agentes Declaram Vitória Cedo Demais](../../docs/pt-BR/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)
60+
- [Aula 10: Por Que Testes End-to-End Alteram os Resultados](../../docs/pt-BR/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)

0 commit comments

Comments
 (0)