Skip to content

Harness engineering beginner tutorial, from 0 to 1

refactor: Add AGENTS.md, ARCHITECTURE.md, DESIGN.md, FRONTEND.md, PLANS.md, PRODUCT_SENSE.md, QUALITY_SCORE.md, RELIABILITY.md, SECURITY.md, and index.md

João Paulo Fricks0ceb4674be21
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/AGENTS.md b/docs/pt-BR/resources/openai-advanced/repo-template/AGENTS.md
new file mode 100644
index 0000000..a4632bb
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/AGENTS.md
@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Este repositório é otimizado para trabalhos de agentes de codificação de longa duração. Mantenha este arquivo curto. Use-o como a camada de roteamento para os documentos de sistema de registro, não como um depósito gigante de instruções.
+
+## Fluxo de Trabalho de Inicialização (Startup Workflow)
+
+Antes de alterar o código:
+
+1. Confirme a raiz do repositório com `pwd`.
+2. Leia `ARCHITECTURE.md` para conhecer o mapa atual do sistema e as regras de dependência rígidas.
+3. Leia `docs/QUALITY_SCORE.md` para ver quais domínios ou camadas estão mais fracos.
+4. Leia `docs/PLANS.md` e, em seguida, abra o plano ativo no qual você está trabalhando.
+5. Leia a especificação de produto relevante em `docs/product-specs/`.
+6. Execute o caminho padrão de inicialização e verificação para este repositório.
+7. Se a verificação básica estiver falhando, repare a base antes de adicionar escopo.
+
+## Mapa de Roteamento
+
+- `ARCHITECTURE.md`: mapa de domínio, modelo de camadas, regras de dependência.
+- `docs/design-docs/index.md`: decisões de design e crenças fundamentais.
+- `docs/product-specs/index.md`: comportamentos atuais do produto e metas de aceitação.
+- `docs/PLANS.md`: ciclo de vida do plano e política do plano de execução.
+- `docs/QUALITY_SCORE.md`: saúde do domínio de produto e da camada.
+- `docs/RELIABILITY.md`: sinais de runtime, benchmarks e expectativas de reinicialização.
+- `docs/SECURITY.md`: segredos, sandbox, dados e regras de ações externas.
+- `docs/FRONTEND.md`: restrições de UI, regras do design system, verificações de acessibilidade.
+
+## Contrato de Trabalho
+
+- Trabalhe em um plano delimitado ou fatia de recurso por vez.
+- Não marque o trabalho como concluído apenas pela inspeção do código; evidências executáveis são obrigatórias.
+- Se você alterar o comportamento, atualize os documentos de produto, plano ou confiabilidade correspondentes na mesma sessão.
+- Se você vir feedbacks de revisão repetidos, promova-os para uma regra mecânica, verificação ou linter, em vez de reexplicá-los no chat.
+- Mantenha o material gerado em `docs/generated/` e as referências de origem em `docs/references/`.
+- Prefira adicionar documentos pequenos e atuais em vez de aumentar este arquivo.
+
+## Definição de Concluído (Definition Of Done)
+
+Uma alteração só é considerada concluída quando todos os itens a seguir forem verdadeiros:
+
+- o comportamento pretendido foi implementado.
+- a verificação exigida foi realmente executada.
+- a evidência está vinculada ao plano relevante ou documento de qualidade.
+- os documentos afetados permanecem atualizados.
+- o repositório pode ser reiniciado de forma limpa a partir do caminho de inicialização padrão.
+
+## Fim de Sessão
+
+Antes de encerrar uma sessão:
+
+1. Atualize o plano de execução ativo.
+2. Atualize `docs/QUALITY_SCORE.md` se algum domínio ou camada mudar significativamente.
+3. Registre novas dívidas técnicas em `docs/exec-plans/tech-debt-tracker.md` se você as adiou.
+4. Mova os planos finalizados para `docs/exec-plans/completed/` quando apropriado.
+5. Deixe o repositório em um estado reinicializável com uma próxima ação clara.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/pt-BR/resources/openai-advanced/repo-template/ARCHITECTURE.md
new file mode 100644
index 0000000..fb9604f
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/ARCHITECTURE.md
@@ -0,0 +1,55 @@
+# ARCHITECTURE.md
+
+Este arquivo é o mapa de alto nível do sistema. Ele deve permanecer conciso e apontar para documentos mais profundos quando necessário.
+
+## Formato do Sistema (System Shape)
+
+- Produto: `[substitua pelo nome do produto]`
+- Fluxo de trabalho principal do usuário: `[substitua pelo fluxo de trabalho principal]`
+- Superfícies de runtime: `[desktop / web / cli / serviços / workers]`
+- Fonte da verdade para o comportamento do produto: `docs/product-specs/`
+
+## Mapa de Domínio
+
+| Domínio | Propósito | Principais Pontos de Entrada | Especificação Relacionada |
+|--------|---------|----------------------|--------------|
+| `[dominio-a]` | `[o que ele possui]` | `[módulos / rotas / comandos]` | `[caminho da especificação]` |
+| `[dominio-b]` | `[o que ele possui]` | `[módulos / rotas / comandos]` | `[caminho da especificação]` |
+
+## Modelo de Camadas
+
+Use um modelo direcional fixo para que os agentes não inventem arquiteturas ad hoc:
+
+`Tipos -> Configuração -> Repositório -> Serviço -> Runtime -> UI`
+
+Preocupações transversais (cross-cutting concerns) devem entrar por meio de limites explícitos de provedores ou adaptadores, em vez de acessar as camadas diretamente.
+
+## Regras de Dependência Rígidas
+
+- Camadas inferiores não devem depender de camadas superiores.
+- A UI não deve ignorar os contratos de runtime ou de serviço.
+- O acesso a dados deve entrar por meio de repositórios ou adaptadores equivalentes.
+- Utilitários compartilhados devem permanecer genéricos e não devem acumular lógica de domínio.
+- Novas dependências devem ser justificadas no plano correspondente ou no documento de design.
+
+## Interfaces Transversais
+
+| Preocupação | Limite Aprovado | Notas |
+|--------|-------------------|-------|
+| Logging e tracing | `[caminho do provedor / utilitário]` | `[apenas estruturado, sem uso ad hoc de console]` |
+| Autenticação | `[caminho do provedor]` | `[regras de token/sessão]` |
+| APIs Externas | `[caminho do cliente ou provedor]` | `[orientação de limite de taxa / retentativa]` |
+| Feature flags | `[limite da flag]` | `[propriedade]` |
+
+## Pontos Críticos Atuais (Hot Spots)
+
+- `[área mais difícil para os agentes alterarem com segurança]`
+- `[área com limites fracos ou testes frágeis]`
+
+## Checklist de Mudança
+
+Ao tocar em código relevante para a arquitetura:
+
+1. Atualize este arquivo se o mapa de domínio ou os limites permitidos mudarem.
+2. Atualize o documento de design relacionado em `docs/design-docs/` se a justificativa mudar.
+3. Adicione ou atualize uma verificação executável se a regra deve ser aplicada mecanicamente.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/pt-BR/resources/openai-advanced/repo-template/docs/DESIGN.md
new file mode 100644
index 0000000..95ed0c1
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/docs/DESIGN.md
@@ -0,0 +1,25 @@
+# DESIGN.md
+
+Este arquivo é o ponto de entrada do design. Mantenha-o breve e use-o para direcionar aos arquivos mais detalhados em `docs/design-docs/`.
+
+## Propósito
+
+Registrar decisões duráveis de design de produto e de sistema que devem sobreviver além de um único chat, sprint ou da memória de um revisor.
+
+## Leia Isto Quando
+
+- você precisar da filosofia de design atual.
+- você estiver prestes a introduzir um novo padrão.
+- você precisar saber quais decisões de design estão resolvidas versus quais ainda estão em aberto.
+
+## Documentos de Design Canônicos
+
+- `docs/design-docs/index.md`: índice de documentos aceitos, propostos e descontinuados.
+- `docs/design-docs/core-beliefs.md`: crenças fundamentais do projeto focadas em agentes.
+
+## Regras de Design
+
+- Mantenha os documentos de design pequenos e atualizados.
+- Prefira um documento por área de decisão.
+- Vincule os documentos de design a partir de planos e especificações quando uma mudança depender deles.
+- Se uma regra de design se tornar operacionalmente crítica, promova-a para uma verificação automatizada ou atualize o arquivo `ARCHITECTURE.md`.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/pt-BR/resources/openai-advanced/repo-template/docs/FRONTEND.md
new file mode 100644
index 0000000..862a0de
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/docs/FRONTEND.md
@@ -0,0 +1,23 @@
+# FRONTEND.md
+
+Este arquivo define expectativas estáveis de frontend para que os agentes não inventem padrões de UI de forma imprevisível.
+
+## Princípios de UI
+
+- Otimize pela clareza antes da novidade.
+- Mantenha os fluxos de interação detectáveis e reinicializáveis.
+- Prefira um pequeno número de componentes reutilizáveis em vez de variantes únicas (one-off).
+- Verificações de acessibilidade fazem parte da verificação normal, não são apenas um trabalho de polimento.
+
+## Salvaguardas (Guardrails)
+
+- Documente o design system ou a biblioteca de componentes em `docs/references/`.
+- Registre os principais estados voltados ao usuário: vazio, carregando, sucesso, erro, retentativa.
+- Mantenha a redação (copy), o comportamento do teclado e a hierarquia visual consistentes entre os fluxos.
+- Quando um bug de UI for corrigido, adicione ou atualize a etapa de validação correspondente.
+
+## Expectativas de Verificação
+
+- Capture evidências para jornadas críticas do usuário.
+- Registre as etapas de validação do navegador ou do runtime no plano relevante.
+- Se regressões visuais forem comuns, padronize as verificações de captura de tela ou do DOM.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/pt-BR/resources/openai-advanced/repo-template/docs/PLANS.md
new file mode 100644
index 0000000..de920bc
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/docs/PLANS.md
@@ -0,0 +1,34 @@
+# PLANS.md
+
+Este arquivo define como os planos de execução são criados, atualizados, concluídos e arquivados.
+
+## Quando um Plano é Necessário
+
+Crie um plano de execução quando o trabalho:
+
+- abranger mais de uma sessão.
+- alterar mais de um subsistema.
+- tiver verificação não trivial ou risco de lançamento.
+- depender de decisões em aberto que devem ser registradas.
+
+## Locais dos Planos
+
+- `docs/exec-plans/active/`: planos que atualmente orientam o trabalho.
+- `docs/exec-plans/completed/`: planos finalizados mantidos para contexto futuro do agente.
+- `docs/exec-plans/tech-debt-tracker.md`: trabalho adiado e acompanhamentos (follow-ups).
+
+## Seções Mínimas do Plano
+
+- objetivo.
+- escopo e fora de escopo.
+- caminho de verificação.
+- riscos e bloqueios.
+- log de progresso.
+- decisões em aberto.
+
+## Regras Operacionais
+
+- Um plano ativo deve ter uma etapa atual claramente definida e de responsabilidade única.
+- Atualize o plano conforme o trabalho progride; não o trate como um texto estático.
+- Se uma decisão alterar a direção da implementação, registre-a no plano.
+- Mova os planos finalizados para `completed/` para que os agentes ainda possam descobrir o contexto anterior.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/pt-BR/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
new file mode 100644
index 0000000..d864f33
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
@@ -0,0 +1,24 @@
+# PRODUCT_SENSE.md
+
+Este arquivo captura o julgamento durável do produto que os agentes não conseguem inferir de forma confiável apenas a partir do código.
+
+## Essência do Produto (Product Core)
+
+- Usuário principal: `[substitua]`
+- Trabalho a ser feito (Job to be done): `[substitua]`
+- Principal frustração a ser removida: `[substitua]`
+- Barra de qualidade para aceitação: `[substitua]`
+
+## Regras do Produto
+
+- Favoreça a confiabilidade visível ao usuário em detrimento da contagem de recursos.
+- Trate comportamentos ambíguos como uma lacuna na especificação, não como permissão para adivinhar.
+- Se a implementação alterar o que os usuários veem ou em que confiam, atualize a especificação correspondente.
+- Use especificações de produto para fluxos concretos e use este arquivo para prioridades transversais do produto.
+
+## Padrões Proibidos (No-Go Patterns)
+
+- Ações destrutivas ocultas.
+- Falha silenciosa sem feedback ao usuário.
+- Fonte da verdade obscura para o estado visível.
+- Recursos que não podem ser explicados em uma única frase.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/pt-BR/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md
new file mode 100644
index 0000000..980ca53
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md
@@ -0,0 +1,39 @@
+# QUALITY_SCORE.md
+
+Este documento rastreia se o repositório está ficando mais forte ou mais fraco ao longo do tempo.
+
+## Escala de Avaliação
+
+- `A`: verificado, legível, estável, limites aplicados.
+- `B`: funcionando com pequenas lacunas.
+- `C`: funcionando parcialmente, confusão ou instabilidade notável.
+- `D`: quebrado, inseguro ou estruturalmente obscuro.
+
+## Domínios de Produto
+
+| Domínio | Nota | Verificação | Legibilidade para Agente | Estabilidade de Teste | Lacunas Principais | Última Atualização |
+|--------|-------|-------------|-------------------------|----------------------|-------------------|-------------------|
+| `[dominio-a]` | - | - | - | - | - | - |
+| `[dominio-b]` | - | - | - | - | - | - |
+| `[dominio-c]` | - | - | - | - | - | - |
+
+## Camadas Arquitetônicas
+
+| Camada | Nota | Aplicação de Limites | Legibilidade para Agente | Lacunas Principais | Última Atualização |
+|-------|-------|---------------------|-------------------------|-------------------|-------------------|
+| Tipos | - | - | - | - | - |
+| Serviços | - | - | - | - | - |
+| Runtime | - | - | - | - | - |
+| UI | - | - | - | - | - |
+
+## Instantâneos de Benchmark (Benchmark Snapshots)
+
+| Data | Variante do Harness | Taxa de Conclusão | Retentativas | Defeitos Antes da Revisão | Notas |
+|------|-----------------|----------------|--------|-----------------------|------|
+| AAAA-MM-DD | `[base / melhorado / simplificado]` | - | - | - | - |
+
+## Log de Simplificação
+
+| Data | Componente Removido | Resultado | Decisão |
+|------|-------------------|---------|----------|
+| AAAA-MM-DD | `[componente]` | `[degradado / inalterado]` | `[restaurar / manter removido]` |
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/pt-BR/resources/openai-advanced/repo-template/docs/RELIABILITY.md
new file mode 100644
index 0000000..df36d12
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/docs/RELIABILITY.md
@@ -0,0 +1,32 @@
+# RELIABILITY.md
+
+Este arquivo define como o sistema prova que está saudável e reinicializável.
+
+## Caminhos Padrão
+
+- Inicialização (Bootstrap): `[comando]`
+- Verificação: `[comando]`
+- Iniciar aplicativo ou serviço: `[comando]`
+- Depurar ou inspecionar o runtime: `[comando]`
+
+## Sinais Obrigatórios de Runtime
+
+- logs estruturados para inicialização e fluxos críticos.
+- verificações de saúde (health checks) para serviços essenciais.
+- dados de rastreamento ou tempo para caminhos lentos, quando disponíveis.
+- estados de erro visíveis ao usuário para falhas recuperáveis.
+
+## Jornadas Críticas (Golden Journeys)
+
+- `[jornada 1]`
+- `[jornada 2]`
+- `[jornada 3]`
+
+Cada jornada crítica deve ter um caminho de verificação repetível e sinais de falha claros.
+
+## Regras de Confiabilidade
+
+- Nenhum recurso está concluído se o sistema não puder reiniciar de forma limpa depois.
+- Falhas em tempo de execução devem ser diagnosticáveis a partir de sinais locais do repositório.
+- Se um modo de falha repetido aparecer, adicione um benchmark ou uma salvaguarda para ele.
+- A limpeza faz parte da confiabilidade, não é uma preocupação separada.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/pt-BR/resources/openai-advanced/repo-template/docs/SECURITY.md
new file mode 100644
index 0000000..0ea0f5c
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/docs/SECURITY.md
@@ -0,0 +1,27 @@
+# SECURITY.md
+
+Este arquivo define as regras de segurança e proteção que os agentes não devem tentar adivinhar.
+
+## Segredos e Credenciais
+
+- Nunca codifique segredos diretamente no código-fonte ou nos documentos.
+- Documente aqui os caminhos aprovados para carregamento de segredos.
+- Oculte tokens, chaves de API e dados pessoais de logs e capturas de tela.
+
+## Entrada Não Confiável (Untrusted Input)
+
+- Trate conteúdos externos como não confiáveis até que sejam validados.
+- Registre aqui os limites permitidos para busca (fetch) ou execução.
+- Se houver risco de injeção de prompt ou injeção de comando, documente a salvaguarda.
+
+## Ações Externas
+
+- Liste quais ações exigem aprovação explícita.
+- Registre quaisquer comandos de produção ou destrutivos que os agentes não devem executar por padrão.
+- Prefira fluxos de trabalho seguros em sandbox para depuração e verificação.
+
+## Regras de Dependência e Revisão
+
+- Novas dependências precisam de justificativa no plano ativo.
+- Alterações sensíveis à segurança exigem etapas de verificação explícitas.
+- Comentários repetidos em revisões de segurança devem se tornar verificações, não apenas conhecimento compartilhado informalmente.
diff --git a/docs/pt-BR/resources/openai-advanced/repo-template/index.md b/docs/pt-BR/resources/openai-advanced/repo-template/index.md
new file mode 100644
index 0000000..58e75de
--- /dev/null
+++ b/docs/pt-BR/resources/openai-advanced/repo-template/index.md
@@ -0,0 +1,21 @@
+# Modelo de Repositório Avançado (Advanced Repo Template)
+
+Copie este modelo inicial para um repositório real quando desejar uma superfície de documentação focada em agentes no estilo OpenAI, em vez de apenas um harness mínimo.
+
+## Ordem de Cópia
+
+1. Copie `AGENTS.md` e `ARCHITECTURE.md` para a raiz do repositório.
+2. Copie toda a árvore `docs/`.
+3. Preencha primeiro `docs/PRODUCT_SENSE.md`, `docs/QUALITY_SCORE.md` e `docs/RELIABILITY.md`.
+4. Adicione seu primeiro plano ativo em `docs/exec-plans/active/`.
+5. Mantenha os arquivos de ponto de entrada curtos e direcione os detalhes para os documentos vinculados.
+
+## Para Que Este Modelo é Otimizado
+
+- contexto local do repositório durável.
+- divulgação progressiva em vez de um único arquivo de instrução gigante.
+- ciclo de vida explícito do plano.
+- rastreamento de qualidade ao longo do tempo.
+- limites legíveis para agentes e humanos.
+
+Trate cada arquivo aqui como um ponto de partida. Substitua espaços reservados, exemplos e comandos de amostra pelas especificidades reais do seu projeto antes de depender dele.