docs: rebrand to GSD Core and restructure docs with Diataxis (#605)
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
90
docs/pt-BR/explanation/context-engineering.md
Normal file
90
docs/pt-BR/explanation/context-engineering.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# Engenharia de contexto
|
||||
|
||||
> Por que o GSD Core existe e qual problema ele foi projetado para resolver.
|
||||
|
||||
---
|
||||
|
||||
## O problema: degradação de contexto
|
||||
|
||||
Toda sessão de programação com IA começa do zero. O modelo lê sua pergunta, raciocina sobre ela e responde. Mas raramente uma sessão é composta de uma única troca. Você faz perguntas de acompanhamento, cola mensagens de erro, itera sobre o código, redireciona o modelo quando ele se desvia. Cada turno adiciona tokens à janela de contexto — o buffer finito de texto que o modelo consegue "enxergar" de uma só vez.
|
||||
|
||||
À medida que essa janela vai se preenchendo, algo sutil acontece. O modelo não falha de forma escancarada. Ele continua respondendo. Mas a qualidade das suas respostas vai se degradando silenciosamente. As instruções iniciais são empurradas para as bordas do que ele consegue atentar. A nuance das primeiras trocas — as restrições que você estabeleceu, a arquitetura que você acordou, os casos extremos que você sinalizou — compete por atenção com tudo o que veio depois. Pesquisadores chamam isso de **degradação de contexto** (*context rot*).
|
||||
|
||||
A degradação de contexto se manifesta de várias formas:
|
||||
|
||||
- O modelo começa a contradizer decisões anteriores que havia reconhecido.
|
||||
- O estilo do código se distancia das convenções estabelecidas no início da sessão.
|
||||
- Os planos passam a ignorar requisitos que foram claramente declarados, mas que agora estão soterrados no histórico.
|
||||
- O modelo alucina nomes de arquivos ou assinaturas de funções que tinha corretos vinte mensagens atrás.
|
||||
|
||||
Nada disso é um bug do modelo. É uma propriedade fundamental de como a atenção de transformers funciona sobre sequências longas. O modelo não está esquecendo — ele nunca "lembrou" no sentido humano. Ele está ponderando a relevância ao longo de uma janela finita e, à medida que essa janela se preenche com ruído acumulado, a relação sinal-ruído se degrada.
|
||||
|
||||
A resposta ingênua é usar `/clear` e recomeçar. Mas isso perde a continuidade. Você precisa reexplicar o contexto, recolar os arquivos relevantes, reafirmar as restrições. A sessão essencialmente volta à estaca zero.
|
||||
|
||||
---
|
||||
|
||||
## A resposta do GSD Core: subagentes com contexto limpo
|
||||
|
||||
O insight central do GSD Core é que *a maior parte* do trabalho em uma sessão de programação não precisa acontecer no contexto principal. Pesquisa, planejamento, escrita de código e verificação são tarefas discretas e delimitadas. Cada uma pode ser entregue a um subagente especializado que começa com uma janela de contexto limpa e cuidadosamente delimitada — e reporta seu resultado de volta a um orquestrador enxuto que permanece leve.
|
||||
|
||||
Isso não é um contorno para a degradação de contexto. É uma solução estrutural.
|
||||
|
||||
O orquestrador — sua sessão principal — nunca toca os arquivos-fonte. Ele spawna agentes, coleta seus resultados, atualiza o estado compartilhado e encaminha para o próximo passo. Como ele faz muito pouco por conta própria, sua janela de contexto cresce de forma lenta e previsível. O trabalho pesado acontece em agentes que cada um começa do zero, recebe exatamente o contexto necessário para sua tarefa e termina quando concluído.
|
||||
|
||||
Considere o que isso significa na prática. Quando você executa `/gsd-plan-phase`, o orquestrador:
|
||||
|
||||
1. Carrega um payload de contexto JSON compacto (resumo do projeto, objetivo da fase, configuração relevante).
|
||||
2. Spawna um agente pesquisador com uma janela limpa de 200k tokens.
|
||||
3. Spawna um agente planejador com a saída da pesquisa e os requisitos da fase.
|
||||
4. Spawna um agente verificador de plano para validar o plano antes da execução.
|
||||
|
||||
Cada agente opera com capacidade total, sem o peso do histórico acumulado da sua sessão. Quando o planejador escreve seus arquivos `PLAN.md` em `.planning/phases/`, essa saída se torna um artefato durável — não uma memória frágil em uma janela de contexto compartilhada.
|
||||
|
||||
---
|
||||
|
||||
## Desenvolvimento orientado a especificações e meta-prompting
|
||||
|
||||
A engenharia de contexto por si só não é suficiente. Se um agente começa do zero mas recebe instruções vagas, ele vai produzir saídas vagas. O GSD Core combina subagentes com contexto limpo com duas disciplinas complementares:
|
||||
|
||||
**Desenvolvimento orientado a especificações** significa que toda fase produz artefatos estruturados antes de a execução começar. Um `CONTEXT.md` captura as decisões de implementação da etapa Discuss. Um `RESEARCH.md` registra o que o pesquisador encontrou. Um `PLAN.md` divide o trabalho em tarefas discretas, ordenadas por dependência, com critérios de aceite explícitos. Quando um agente executor toca um arquivo, ele tem uma especificação precisa para seguir — não uma reinterpretação de uma conversa longa.
|
||||
|
||||
**Meta-prompting** significa que as próprias definições de agentes são prompts cuidadosamente engenheirados, não instruções ad-hoc. Os arquivos em `get-shit-done/workflows/` e `agents/` codificam conhecimento conquistado a duras penas sobre como delimitar tarefas, o que verificar e quando escalar para um checkpoint humano. O usuário não precisa reexplicar esse conhecimento a cada sessão; ele está integrado aos próprios prompts do sistema.
|
||||
|
||||
A combinação é deliberada. O contexto limpo garante que cada agente raciocine com clareza. Os artefatos orientados a especificações garantem que cada agente raciocine sobre a *coisa certa*. O meta-prompting garante que cada agente saiba *como* raciocinar bem sobre ela.
|
||||
|
||||
---
|
||||
|
||||
## O papel do `.planning/`
|
||||
|
||||
A engenharia de contexto exige que o conhecimento sobreviva a reinicializações de contexto. O GSD Core usa o sistema de arquivos para isso. Toda saída significativa é escrita em `.planning/` como Markdown ou JSON legível por humanos. Isso significa que:
|
||||
|
||||
- Reiniciar sua sessão (ou uma falha do modelo) não faz você perder trabalho.
|
||||
- Qualquer agente subsequente pode ler artefatos anteriores diretamente, sem depender de um histórico de conversa compartilhado.
|
||||
- Você pode inspecionar, editar ou commitar artefatos de planejamento no git — são texto simples, não estado opaco em um banco de dados.
|
||||
|
||||
`STATE.md` é a espinha dorsal desse sistema. Ele registra a posição atual do projeto (qual milestone, qual fase, quais planos estão completos), decisões ativas e bloqueadores, e métricas de progresso. Quando qualquer workflow começa, ele lê o `STATE.md` para se orientar. Quando qualquer workflow conclui uma etapa significativa, ele escreve de volta no `STATE.md`. Os agentes não dependem de memória; dependem do arquivo.
|
||||
|
||||
---
|
||||
|
||||
## Concessões e limitações
|
||||
|
||||
É importante ser honesto sobre as concessões envolvidas.
|
||||
|
||||
**Sobrecarga.** O ciclo de fases introduz atrito real. Executar `/gsd-discuss-phase`, `/gsd-plan-phase` e `/gsd-execute-phase` como etapas separadas leva mais tempo que digitar "escreva esse recurso" em uma sessão simples. Para uma mudança pequena e bem compreendida, essa sobrecarga não se justifica.
|
||||
|
||||
**Latência.** Spawnar múltiplos subagentes com contexto limpo é mais lento do que uma única edição no contexto. Pesquisa, planejamento e execução incorrem cada um em custos de ida e volta.
|
||||
|
||||
**Cerimônia para tarefas simples.** Se você precisa renomear uma variável, corrigir um erro de digitação ou adicionar um import ausente, o ciclo de fases é exagero. O GSD Core fornece `/gsd-quick` e `/gsd-fast` para trabalho ad-hoc que não justifica uma fase completa. Veja [Lidar com tarefas rápidas](../how-to/handle-quick-and-fast-tasks.md).
|
||||
|
||||
O ciclo de fases se paga quando o trabalho é suficientemente complexo para que a degradação de contexto seja um risco real — recursos com múltiplos arquivos, refatorações transversais, trabalho que se estende por horas ou sessões. Para todo o resto, recorra ao primitivo mais leve.
|
||||
|
||||
Uma regra de bolso útil: se a tarefa pudesse ser totalmente especificada em um prompt único e curto e concluída em um turno de agente sem mais esclarecimentos, pule o ciclo de fases. Se a tarefa requer pesquisa, envolve arquivos que você não leu recentemente, ou depende de decisões que ainda não estão definidas, o ciclo de fases te protege.
|
||||
|
||||
---
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [O ciclo de fases](the-phase-loop.md) — como o ciclo Discuss → Plan → Execute → Verify → Ship coloca a engenharia de contexto em prática
|
||||
- [Orquestração multi-agente](multi-agent-orchestration.md) — como subagentes são spawnados, delimitados e coordenados
|
||||
- [Arquitetura](../ARCHITECTURE.md) — arquitetura do sistema, modelo de agentes e fluxo de dados
|
||||
- [Índice de documentação](../README.md)
|
||||
234
docs/pt-BR/explanation/multi-agent-orchestration.md
Normal file
234
docs/pt-BR/explanation/multi-agent-orchestration.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# Orquestração multi-agente no GSD Core
|
||||
|
||||
> **Explicação** — Este documento descreve *por que* o GSD Core foi projetado em torno da
|
||||
> orquestração multi-agente e *como as partes se encaixam*. Não é um guia
|
||||
> passo a passo. Para configuração, consulte
|
||||
> [Configurar perfis de modelo](../how-to/configure-model-profiles.md) e a
|
||||
> [Referência de configuração](../CONFIGURATION.md). Para o catálogo completo de agentes,
|
||||
> consulte [Inventário](../INVENTORY.md).
|
||||
|
||||
---
|
||||
|
||||
## O problema que este design resolve
|
||||
|
||||
Agentes de codificação com IA degradam. Não porque o modelo piora, mas porque a
|
||||
*janela de contexto fica cheia*. À medida que uma conversa cresce, decisões e código
|
||||
anteriores são expulsos ou diluídos pelo ruído das etapas intermediárias. Quando um
|
||||
agente escreve o quinto arquivo em uma tarefa complexa, pode já ter esquecido
|
||||
a restrição declarada na primeira mensagem. Isso é às vezes chamado de *podridão
|
||||
de contexto* (*context rot*).
|
||||
|
||||
O design multi-agente do GSD Core é uma resposta direta a esse problema. Em vez de
|
||||
um único agente de longa duração carregando toda a sessão, um orquestrador enxuto gera
|
||||
agentes especializados de curta duração, cada um com uma **janela de contexto fresca de 200 K tokens**
|
||||
e *somente os artefatos de que precisa* para realizar seu trabalho específico. O orquestrador
|
||||
nunca faz o trabalho pesado por conta própria; ele carrega o contexto, gera o agente
|
||||
adequado, coleta o resultado e atualiza o estado compartilhado em `.planning/`.
|
||||
|
||||
---
|
||||
|
||||
## O padrão orquestrador → agente
|
||||
|
||||
Todos os workflows em `get-shit-done/workflows/` seguem a mesma estrutura:
|
||||
|
||||
```text
|
||||
Orquestrador (arquivo .md de workflow)
|
||||
│
|
||||
├── Carregar contexto
|
||||
│ gsd-tools.cjs init <workflow> <phase>
|
||||
│ → JSON: informações do projeto, config, estado, detalhes da fase
|
||||
│
|
||||
├── Resolver modelo
|
||||
│ gsd-tools.cjs resolve-model <agent-name>
|
||||
│ → opus | sonnet | haiku | inherit
|
||||
│
|
||||
├── Gerar agente especializado (chamada Task/SubAgent)
|
||||
│ ├── Definição do agente (agents/*.md)
|
||||
│ ├── Payload de contexto (JSON de init)
|
||||
│ ├── Atribuição de modelo
|
||||
│ └── Permissões de ferramentas
|
||||
│
|
||||
├── Coletar resultado
|
||||
│
|
||||
└── Atualizar estado
|
||||
gsd-tools.cjs state update / state patch / state advance-plan
|
||||
```
|
||||
|
||||
O orquestrador é deliberadamente enxuto. Ele não raciocina sobre o domínio,
|
||||
não escreve código e não interpreta resultados além de roteá-los para a
|
||||
próxima etapa. Esse limite mantém a responsabilidade de cada camada clara e impede
|
||||
que o contexto do orquestrador acumule ruído de domínio.
|
||||
|
||||
### O catálogo de agentes
|
||||
|
||||
Os agentes do GSD Core se enquadram em categorias funcionais que mapeiam o
|
||||
pipeline pesquisa → planejamento → execução → verificação:
|
||||
|
||||
| Categoria | Agentes | Paralelismo típico |
|
||||
|---|---|---|
|
||||
| Pesquisadores | `gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher` | 4 em paralelo (stack, funcionalidades, arquitetura, armadilhas) |
|
||||
| Sintetizadores | `gsd-research-synthesizer` | Sequencial, após a conclusão dos pesquisadores |
|
||||
| Planejadores | `gsd-planner`, `gsd-roadmapper` | Sequencial |
|
||||
| Verificadores | `gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor` | Sequencial, até 3 iterações de revisão |
|
||||
| Executores | `gsd-executor` | Paralelo dentro de uma onda, sequencial entre ondas |
|
||||
| Validadores | `gsd-verifier` | Sequencial, após a conclusão de todos os executores |
|
||||
| Mapeadores | `gsd-codebase-mapper` | 4 sub-sondas em paralelo |
|
||||
| Auditores | `gsd-ui-auditor`, `gsd-security-auditor` | Sequencial |
|
||||
|
||||
Cada definição de agente (em `agents/*.md`) declara o acesso às ferramentas permitido,
|
||||
a finalidade e a cor para saída no terminal. Um agente que só precisa ler arquivos
|
||||
e escrever um único documento de saída recebe exatamente essas permissões — sem
|
||||
execução de Bash, sem acesso a um estado mais amplo. Essa restrição é intencional: ela
|
||||
mantém o raio de impacto pequeno caso um agente se comporte de forma inesperada.
|
||||
|
||||
Para o catálogo completo de 31 agentes, consulte [Inventário](../INVENTORY.md#agents-31-shipped).
|
||||
|
||||
---
|
||||
|
||||
## Execução paralela baseada em ondas
|
||||
|
||||
A expressão mais visível do design multi-agente é como o `/gsd-execute-phase`
|
||||
lida com um conjunto de planos que podem depender uns dos outros.
|
||||
|
||||
Antes de gerar qualquer executor, o orquestrador realiza uma **análise de ondas**:
|
||||
ele lê as declarações de dependência em cada arquivo `PLAN.md` e agrupa os planos
|
||||
em ondas. Planos sem dependências declaradas formam a Onda 1 e executam em
|
||||
paralelo. Planos que dependem da Onda 1 formam a Onda 2, e assim por diante.
|
||||
|
||||
```text
|
||||
Plano 01 (sem deps) ─┐
|
||||
Plano 02 (sem deps) ─┤─── Onda 1 (paralelo)
|
||||
Plano 03 (depende de: 01) ─┤─── Onda 2 (aguarda Onda 1)
|
||||
Plano 04 (depende de: 02) ─┘
|
||||
Plano 05 (depende de: 03, 04) ─── Onda 3 (aguarda Onda 2)
|
||||
```
|
||||
|
||||
Cada executor dentro de uma onda:
|
||||
|
||||
- recebe uma janela de contexto fresca (200 K tokens, ou até 1 M em modelos capazes)
|
||||
- recebe o `PLAN.md` específico pelo qual é responsável
|
||||
- recebe o contexto do projeto (`PROJECT.md`, `STATE.md`)
|
||||
- recebe o contexto da fase (`CONTEXT.md`, `RESEARCH.md` se disponível)
|
||||
- produz commits git atômicos ao concluir
|
||||
- escreve um `SUMMARY.md` descrevendo o que foi construído
|
||||
|
||||
Após a conclusão de todos os executores em uma onda, o orquestrador executa o hook
|
||||
de pré-commit uma vez para a onda como um todo. Os executores fazem commit com `--no-verify` para
|
||||
evitar contenção de bloqueio de build (por exemplo, conflitos de lock do Cargo em projetos
|
||||
Rust) quando múltiplos agentes fazem commit em paralelo. O hook, portanto, é executado
|
||||
uma vez por onda em vez de uma vez por commit.
|
||||
|
||||
### Segurança de commits paralelos
|
||||
|
||||
Dois mecanismos previnem conflitos de escrita quando múltiplos executores executam
|
||||
simultaneamente:
|
||||
|
||||
1. **Lock atômico em `STATE.md`** — Toda escrita em `STATE.md` usa um
|
||||
arquivo de lock (`STATE.md.lock`) com criação atômica `O_EXCL`. Isso previne
|
||||
a corrida de leitura-modificação-escrita onde dois agentes leem o arquivo, modificam
|
||||
campos diferentes, e o escritor posterior sobrescreve as alterações do anterior.
|
||||
Locks obsoletos (com mais de 10 segundos) são automaticamente removidos.
|
||||
|
||||
2. **Execução de hook por onda** — Em vez de cada executor executar hooks de pré-commit
|
||||
de forma independente (o que pode causar contenção em nível de arquivo em artefatos
|
||||
de build compartilhados), o orquestrador executa `git hook run pre-commit` uma vez após
|
||||
a conclusão de cada onda.
|
||||
|
||||
---
|
||||
|
||||
## Enriquecimento adaptativo de contexto para modelos de janela grande
|
||||
|
||||
Janelas de contexto padrão de 200 K são suficientes para um executor implementar um
|
||||
plano único e focado. Quando o `context_window` configurado é de 500 K tokens ou
|
||||
maior (por exemplo, ao usar o Opus 4.6 ou Sonnet 4.6 no modo de 1 M), o orquestrador
|
||||
automaticamente enriquece os prompts de subagentes com contexto adicional que não
|
||||
caberia em uma janela padrão:
|
||||
|
||||
- **Agentes executores** recebem arquivos `SUMMARY.md` de ondas anteriores e o
|
||||
`CONTEXT.md`/`RESEARCH.md` da fase, fornecendo a eles consciência entre planos
|
||||
dentro da fase
|
||||
- **Agentes validadores** recebem todos os arquivos `PLAN.md`, `SUMMARY.md` e `CONTEXT.md`
|
||||
mais `REQUIREMENTS.md`, habilitando verificação com consciência histórica
|
||||
|
||||
Esse enriquecimento é condicional ao valor de `context_window` em
|
||||
`config.json`. Em configurações de janela padrão, os prompts usam versões truncadas
|
||||
com ordenação favorável ao cache para maximizar a eficiência de tokens.
|
||||
|
||||
---
|
||||
|
||||
## Por que este design — a conexão com a engenharia de contexto
|
||||
|
||||
O padrão orquestrador → agente só faz sentido como parte de uma abordagem mais ampla
|
||||
de *engenharia de contexto*: a ideia de que o que um agente de IA recebe em sua
|
||||
janela de contexto importa tanto quanto o nível do modelo ou a qualidade do prompt. Consulte
|
||||
[Engenharia de contexto](context-engineering.md) para o tratamento completo.
|
||||
|
||||
A orquestração multi-agente operacionaliza a engenharia de contexto de duas formas:
|
||||
|
||||
**Isolamento de contexto.** Cada agente recebe apenas o que precisa. Um pesquisador
|
||||
recebe a descrição do projeto e as questões de domínio; ele não recebe o histórico
|
||||
completo de planejamento. Um validador recebe todos os planos e resumos; ele não recebe
|
||||
a pesquisa bruta. O isolamento mantém o contexto de cada agente denso em sinal em vez
|
||||
de diluído pelo ruído de outros estágios do pipeline.
|
||||
|
||||
**Higiene de contexto entre sessões.** Como todo o estado vive em
|
||||
`.planning/` como Markdown e JSON legíveis por humanos (não na janela de contexto
|
||||
de nenhum agente), os workflows do GSD sobrevivem a resets de contexto (`/clear`), trocas de
|
||||
abas e intervalos de vários dias. O próximo agente sempre começa a partir de artefatos
|
||||
persistidos e verificados, em vez de uma memória reconstruída de uma longa conversa.
|
||||
|
||||
---
|
||||
|
||||
## Compensações
|
||||
|
||||
A orquestração multi-agente não é gratuita.
|
||||
|
||||
**Sobrecarga de coordenação.** Cada geração de agente é uma ida e volta: o orquestrador
|
||||
deve formatar um prompt, repassar o contexto, aguardar a conclusão do subagente
|
||||
(tipicamente 1–5 minutos) e então analisar o resultado. Um único agente capaz
|
||||
trabalhando em um contexto terminaria mais rápido para tarefas simples. O GSD mitiga
|
||||
isso tornando o paralelismo o padrão sempre que as dependências permitirem — os
|
||||
quatro pesquisadores em um `plan-phase` executam simultaneamente, não sequencialmente.
|
||||
|
||||
**Opacidade durante a execução.** Enquanto um subagente está em execução, seu trabalho é
|
||||
invisível para a sessão pai. Não há fluxo de progresso ao vivo. Esta é uma
|
||||
consequência deliberada do design de contexto fresco: o subagente está operando
|
||||
em sua própria janela de contexto. O orquestrador exibe uma nota de atividade na
|
||||
linha de geração ("executado em um subagente — sem saída até retornar") para definir
|
||||
expectativas.
|
||||
|
||||
**Custo de costura de contexto.** Empacotar os artefatos certos para cada agente
|
||||
requer que o orquestrador gaste tokens montando e transmitindo payloads de contexto.
|
||||
Este é o custo do isolamento. O handler `gsd-tools.cjs init`
|
||||
produz um payload JSON que equilibra completude com orçamento de tokens, aplicando
|
||||
ordenação favorável ao cache para que as partes estáveis do payload (definição do projeto,
|
||||
config) acertem o cache em invocações repetidas.
|
||||
|
||||
**Amplificação do custo do modelo.** Executar cinco agentes em paralelo no nível Opus
|
||||
custa mais do que executar um. O sistema de perfis de modelo (`model_profiles.md`,
|
||||
resolvido por agente pelo `model-profiles.cjs`) permite atribuir níveis mais baratos a
|
||||
agentes menos críticos. O recurso `dynamic_routing` reduz ainda mais o custo ao
|
||||
iniciar cada agente em um nível mais barato e escalar apenas em caso de falha suave.
|
||||
Consulte [Configuração](../CONFIGURATION.md) para as opções completas.
|
||||
|
||||
Em troca desses custos, o design compra *qualidade consistente em fases grandes*.
|
||||
Um executor escrevendo o décimo arquivo em um plano de 400 linhas não degrada porque
|
||||
seu contexto está fresco. Um validador verificando vinte requisitos não esquece os
|
||||
primeiros dez porque os recebeu todos como entrada estruturada em vez de histórico
|
||||
de conversa.
|
||||
|
||||
---
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Engenharia de contexto](context-engineering.md) — o princípio upstream que
|
||||
motiva este design
|
||||
- [Configurar perfis de modelo](../how-to/configure-model-profiles.md) — como
|
||||
atribuir níveis de modelo por agente
|
||||
- [Referência de configuração](../CONFIGURATION.md) — schema completo de `config.json`
|
||||
incluindo `models`, `model_overrides`, `dynamic_routing` e
|
||||
`context_window`
|
||||
- [Inventário](../INVENTORY.md) — catálogo autoritativo de agentes e lista de workflows
|
||||
- [Arquitetura](../ARCHITECTURE.md#agent-model) — detalhes em nível de implementação
|
||||
sobre o padrão orquestrador → agente e o modelo de execução por ondas
|
||||
- [Índice de documentação](../README.md)
|
||||
270
docs/pt-BR/explanation/security-model.md
Normal file
270
docs/pt-BR/explanation/security-model.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Modelo de segurança do GSD Core
|
||||
|
||||
> **Explicação** — Este documento descreve *por que* o GSD Core possui a
|
||||
> postura de segurança que possui e *como as camadas se articulam*. Não é uma
|
||||
> referência para todos os parâmetros de hook. Para o comando `/gsd-secure-phase`
|
||||
> e suas opções, consulte [Comandos](../COMMANDS.md). Para a arquitetura de
|
||||
> hooks em nível de implementação, consulte
|
||||
> [Arquitetura § Sistema de Hooks](../ARCHITECTURE.md#hook-system).
|
||||
> Para a linha de base de segurança organizacional (controles de scanner,
|
||||
> checklists de incidentes, modelo de responsabilidade), consulte
|
||||
> [SECURITY.md](../../../SECURITY.md).
|
||||
|
||||
---
|
||||
|
||||
## Por que o desenvolvimento orientado por IA precisa de uma postura de segurança dedicada
|
||||
|
||||
Um editor de código convencional não executa pacotes arbitrários em seu nome.
|
||||
O GSD Core sim. O pipeline pesquisa → plano → execução automatiza o caminho
|
||||
completo de "nomear um pacote" até "executar `npm install <package>`", de
|
||||
"escrever um artefato de planejamento" até "usar esse artefato como prompt de
|
||||
sistema de um LLM". Cada etapa de automação remove um humano do ciclo — e cada
|
||||
remoção é uma superfície de ataque potencial.
|
||||
|
||||
O modelo de segurança do GSD Core é construído em torno de um princípio
|
||||
organizador: **defesa em profundidade**. Nenhum controle isolado é assumido
|
||||
como perfeito. Várias camadas sobrepostas reduzem, cada uma, uma classe distinta
|
||||
de risco e, juntas, tornam a superfície de ataque substancialmente mais difícil
|
||||
de explorar sem eliminá-la completamente. O resumo honesto ao final deste
|
||||
documento explica o que o sistema não consegue proteger.
|
||||
|
||||
---
|
||||
|
||||
## Camada 1 — Proteção da cadeia de suprimentos: o Package Legitimacy Gate
|
||||
|
||||
### A ameaça
|
||||
|
||||
Modelos de IA alucinam nomes de pacotes. Este não é um modo de falha marginal:
|
||||
pesquisas de 2025 documentam aproximadamente 20% das referências de pacotes
|
||||
geradas por IA como nomes alucinados que não correspondem a pacotes legítimos.
|
||||
Um subconjunto desses nomes alucinados — aproximadamente 43% na mesma pesquisa —
|
||||
recorre consistentemente entre prompts, o que significa que um atacante pode
|
||||
observar quais nomes as ferramentas de IA costumam produzir e pré-registrar
|
||||
esses nomes no npm, PyPI ou crates.io com scripts de pós-instalação maliciosos.
|
||||
A técnica é chamada de *slopsquatting*.
|
||||
|
||||
A qualidade insidiosa do slopsquatting é que um nome alucinado que passa no
|
||||
`npm view` *parece legítimo*. A entrada no registro prova apenas que alguém
|
||||
registrou o nome — não que o pacote faz o que a IA disse que faz, não que
|
||||
possui usuários legítimos e não que seus scripts de instalação são seguros.
|
||||
Sem uma barreira, um nome alucinado fluiria sem ser detectado pelo pipeline
|
||||
pesquisador → planejador → executor do GSD e eventualmente seria executado como
|
||||
`npm install <attacker-package>` na sua máquina.
|
||||
|
||||
### Como a barreira funciona
|
||||
|
||||
A barreira opera em três estágios do pipeline:
|
||||
|
||||
**Estágio de pesquisa.** Quando `gsd-phase-researcher` recomenda pacotes
|
||||
externos, executa `slopcheck install <pkgs> --json` para cada um. Os resultados
|
||||
são gravados em uma tabela `## Package Legitimacy Audit` no `RESEARCH.md`.
|
||||
Pacotes marcados com `[SLOP]` (alucinação de alta confiança ou registrado por
|
||||
atacante) são **removidos inteiramente do `RESEARCH.md`** antes de o arquivo
|
||||
ser salvo. Eles nunca chegam ao planejador.
|
||||
|
||||
**Estágio de planejamento.** `gsd-planner` lê a tabela de auditoria. Para
|
||||
qualquer pacote marcado com `[SUS]` (suspeito: recém-registrado, baixa contagem
|
||||
de downloads, sem repositório de código-fonte ou padrão de nomenclatura próximo
|
||||
a um pacote popular) ou `[ASSUMED]` (originado de WebSearch em vez de
|
||||
verificação direta no registro), o planejador **insere uma tarefa
|
||||
`checkpoint:human-verify`** antes da etapa de instalação. O checkpoint inclui
|
||||
um link direto para a página do registro e aspectos específicos a verificar:
|
||||
histórico do mantenedor, atividade no rastreador de problemas, ausência de
|
||||
scripts de instalação suspeitos.
|
||||
|
||||
**Estágio de execução.** Se uma instalação falhar, `gsd-executor` **exibe um
|
||||
checkpoint e para**. Ele não tenta silenciosamente um nome de pacote alternativo
|
||||
— que poderia ser malicioso. Esta é uma regra explícita no comportamento do
|
||||
executor (RULE 3 na definição do agente executor).
|
||||
|
||||
### Por que pacotes do WebSearch são sempre `[ASSUMED]`
|
||||
|
||||
Nomes de pacotes descobertos via WebSearch são marcados como `[ASSUMED]`
|
||||
independentemente de o `npm view` ser bem-sucedido. Um pacote que existe no
|
||||
registro não é o mesmo que um pacote seguro de instalar. `npm view` prova o
|
||||
registro, não a legitimidade. A marcação `[ASSUMED]` aciona o mesmo checkpoint
|
||||
de verificação humana que `[SUS]`, garantindo que qualquer recomendação
|
||||
descoberta na web e não verificada sempre receba revisão humana antes da
|
||||
instalação.
|
||||
|
||||
### Cobertura por ecossistema
|
||||
|
||||
O pesquisador usa comandos de verificação específicos de cada registro, em vez
|
||||
de uma única verificação genérica:
|
||||
|
||||
- Node.js: `npm view`
|
||||
- Python: `pip index versions`
|
||||
- Rust: `cargo search`
|
||||
|
||||
Isso cobre alucinações entre ecossistemas, que ocorrem em aproximadamente 9%
|
||||
dos casos de acordo com a pesquisa USENIX de 2025 — situações em que uma IA
|
||||
recomenda um pacote que existe em um ecossistema, mas não no que está realmente
|
||||
em uso.
|
||||
|
||||
### Degradação graciosa
|
||||
|
||||
Se `slopcheck` não estiver disponível (não instalado, ou se a instalação via
|
||||
pip falhar no momento da pesquisa), o GSD aplica o fallback mais restrito
|
||||
possível: **todo pacote recomendado é marcado como `[ASSUMED]`**, e o planejador
|
||||
bloqueia cada instalação com uma tarefa `checkpoint:human-verify`. Pesquisa e
|
||||
planejamento prosseguem normalmente — o sistema nunca falha irrecuperavelmente
|
||||
por dependência de ferramenta ausente. Isso é intencionalmente mais restritivo
|
||||
do que o fluxo normal: a indisponibilidade do slopcheck significa que toda
|
||||
instalação de pacote recebe um checkpoint humano.
|
||||
|
||||
A ferramenta `slopcheck` é licenciada sob MIT e instalável via pip. Se for
|
||||
descontinuada, o fallback de barreira `[ASSUMED]` garante que a cobertura por
|
||||
checkpoint humano seja mantida independentemente.
|
||||
|
||||
---
|
||||
|
||||
## Camada 2 — Defesas contra injeção de prompt
|
||||
|
||||
### A ameaça
|
||||
|
||||
O GSD Core gera arquivos Markdown que se tornam prompts de sistema de LLMs. O
|
||||
pipeline de pesquisa lê conteúdo externo da web; o pipeline de planejamento
|
||||
incorpora texto fornecido pelo usuário (`--text-file`, `--prd`); o pipeline de
|
||||
execução grava artefatos de planejamento que são relidos posteriormente como
|
||||
contexto de agente. Qualquer texto controlado pelo usuário que flua para esses
|
||||
artefatos é um vetor potencial de **injeção indireta de prompt** — uma string
|
||||
controlada por um atacante que, uma vez dentro de um prompt de sistema, tenta
|
||||
substituir as instruções do agente ou exfiltrar informações.
|
||||
|
||||
### Como as defesas funcionam
|
||||
|
||||
O GSD Core trata a injeção de prompt em três níveis.
|
||||
|
||||
**Validação de entrada (`security.cjs`).** O módulo
|
||||
`get-shit-done/bin/lib/security.cjs` é o utilitário central de segurança.
|
||||
Ele fornece:
|
||||
|
||||
- Prevenção de path traversal: caminhos de arquivo fornecidos pelo usuário
|
||||
(`--text-file`, `--prd`) são validados para resolver dentro do diretório do
|
||||
projeto, com resolução explícita do symlink `/var` → `/private/var` no macOS
|
||||
- Detecção de injeção de prompt: padrões de injeção conhecidos (sobrescritas de
|
||||
papel, desvios de instrução, injeções de tag de sistema) são escaneados em
|
||||
texto fornecido pelo usuário antes de entrar em qualquer artefato de
|
||||
planejamento
|
||||
- Parsing seguro de JSON: um wrapper que previne ataques de poluição de
|
||||
protótipo via payloads JSON manipulados
|
||||
- Validação de argumentos de shell: argumentos passados a comandos de subshell
|
||||
são validados antes do uso
|
||||
|
||||
**Hook de runtime: `gsd-prompt-guard.js`.** Este hook é acionado a cada
|
||||
chamada de Write ou Edit que tem como alvo arquivos `.planning/`. Ele escaneia
|
||||
o conteúdo sendo gravado em busca dos mesmos padrões de injeção que o
|
||||
`security.cjs` (um subconjunto inlinado diretamente no hook para independência
|
||||
— o hook não usa `require()` para carregar o módulo, portanto é executado mesmo
|
||||
que o caminho do módulo mude). A detecção é **apenas consultiva**: o hook
|
||||
registra a descoberta, mas não bloqueia a gravação. A justificativa é que um
|
||||
bloqueio falso-positivo em uma gravação de planejamento legítima seria mais
|
||||
disruptivo do que uma injeção não detectada em uma camada de varredura
|
||||
secundária.
|
||||
|
||||
**Hook de runtime: `gsd-read-injection-scanner.js`.** Este hook é acionado na
|
||||
saída de cada chamada da ferramenta Read. Ele escaneia o *conteúdo que acabou
|
||||
de ser lido* em busca de instruções injetadas em conteúdo não confiável —
|
||||
capturando casos em que um atacante incorporou instruções em um arquivo que o
|
||||
GSD está prestes a incorporar ao contexto de um agente.
|
||||
|
||||
**Scanner de CI.** `prompt-injection-scan.test.cjs` escaneia todos os arquivos
|
||||
de agente, workflow e comando em busca de vetores de injeção embutidos como
|
||||
parte do conjunto de testes. Isso detecta tentativas de injeção no próprio
|
||||
código-fonte do GSD — por exemplo, um ataque de cadeia de suprimentos que
|
||||
modificou um arquivo de workflow para adicionar uma instrução de sobrescrita de
|
||||
papel.
|
||||
|
||||
### Read Injection Scanner vs Prompt Guard
|
||||
|
||||
Os dois hooks cobrem superfícies complementares. `gsd-prompt-guard.js` monitora
|
||||
*gravações em artefatos de planejamento* — ele detecta injeções sendo plantadas.
|
||||
`gsd-read-injection-scanner.js` monitora *leituras de qualquer arquivo* — ele
|
||||
detecta injeções sendo ingeridas a partir de conteúdo externo (o README de uma
|
||||
dependência, um arquivo de configuração de terceiros, um documento fornecido
|
||||
pelo usuário). Juntos, eles delimitam o ciclo de vida ingestão → armazenamento
|
||||
→ releitura.
|
||||
|
||||
---
|
||||
|
||||
## Camada 3 — Integridade do repositório e das dependências
|
||||
|
||||
Acima do comportamento de runtime do GSD, a organização `open-gsd` aplica
|
||||
controles nos níveis de repositório e pacote. Eles estão documentados
|
||||
integralmente em [`docs/security/baseline.md`](../../security/baseline.md) e são
|
||||
resumidos aqui para completude.
|
||||
|
||||
**Integridade das dependências.** Todas as dependências de terceiros são
|
||||
fixadas via `package-lock.json` e verificadas em relação aos checksums
|
||||
publicados antes da instalação. Uma barreira `scripts/check-npm-integrity.cjs`
|
||||
detecta versões inválidas, pacotes ausentes e pacotes estranhos no momento do
|
||||
CI. Isso mitiga ataques de confusão de dependências e typosquatting contra as
|
||||
próprias dependências do GSD.
|
||||
|
||||
**Varredura de segredos.** Cada commit e PR é escaneado em busca de segredos
|
||||
codificados no código. Fixtures de teste intencionais devem ser anotadas com a
|
||||
gramática de exclusão padrão do projeto (consulte `SECURITY.md` para o formato
|
||||
de anotação). Supressões não anotadas falham no CI.
|
||||
|
||||
**Varredura de texto com segurança de localidade.** Strings de saída e voltadas
|
||||
ao usuário são escaneadas em busca de homóglifos Unicode, caracteres de
|
||||
substituição bidirecional e Unicode invisível — a classe de ataques documentada
|
||||
na CVE-2021-42574 ("Trojan Source") que pode ocultar conteúdo malicioso em
|
||||
diffs.
|
||||
|
||||
---
|
||||
|
||||
## Concessões e limitações
|
||||
|
||||
O modelo de segurança descrito aqui reduz significativamente a superfície de
|
||||
ataque para o desenvolvimento orientado por IA. Ele não elimina o risco da
|
||||
cadeia de suprimentos.
|
||||
|
||||
**O que o Package Legitimacy Gate reduz:** A probabilidade de que um pacote
|
||||
alucinado ou registrado por um atacante chegue ao `npm install` sem um
|
||||
checkpoint humano. A barreira `[SLOP]` remove completamente pacotes ruins de
|
||||
alta confiança; as barreiras `[SUS]` / `[ASSUMED]` exigem revisão humana antes
|
||||
da execução. Isso eleva substancialmente o custo de um ataque de slopsquatting
|
||||
bem-sucedido.
|
||||
|
||||
**O que o Package Legitimacy Gate não elimina:** Um pacote legítimo que é
|
||||
comprometido posteriormente (tomada de conta, confusão de dependências em sua
|
||||
própria árvore) não é detectado pelo slopcheck, que verifica sinais de registro
|
||||
no momento da pesquisa. Lock files e `npm audit` na camada de integridade de
|
||||
dependências são os controles para essa classe de ataque.
|
||||
|
||||
**O que as defesas contra injeção de prompt reduzem:** A probabilidade de que
|
||||
texto controlado pelo usuário em artefatos de planejamento substitua com sucesso
|
||||
as instruções do agente. A correspondência de padrões com formas de injeção
|
||||
conhecidas detecta os casos comuns; jailbreaks novos ou injeções de baixo sinal
|
||||
podem passar sem ser detectados. A postura apenas consultiva significa que a
|
||||
detecção é registrada, mas não bloqueada — uma escolha deliberada que preserva
|
||||
a continuidade do fluxo de trabalho ao custo de não interromper definitivamente
|
||||
em uma detecção.
|
||||
|
||||
**O que as defesas contra injeção de prompt não eliminam:** Uma injeção
|
||||
suficientemente criativa que não corresponde a padrões conhecidos, ou uma
|
||||
injeção que chega por um canal que os hooks não cobrem (por exemplo, conteúdo
|
||||
injetado no README publicado de uma dependência que é lido por um subagente
|
||||
navegando em documentação). Defesa em profundidade significa que cada camada
|
||||
torna o ataque mais difícil, não que qualquer camada isolada o torna impossível.
|
||||
|
||||
**Reportando vulnerabilidades.** Relate por meio de advisory de segurança
|
||||
privado do GitHub em
|
||||
`https://github.com/open-gsd/gsd-core/security/advisories/new`. Não abra
|
||||
issues públicas. Consulte [SECURITY.md](../../../SECURITY.md) para o cronograma
|
||||
de resposta e a política de divulgação.
|
||||
|
||||
---
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Comandos](../COMMANDS.md) — inclui `/gsd-secure-phase` e
|
||||
`/gsd-code-review` com flags relevantes para segurança
|
||||
- [Arquitetura § Sistema de Hooks](../ARCHITECTURE.md#hook-system) —
|
||||
detalhes de implementação de cada hook, seu gatilho de evento e propriedades
|
||||
de segurança
|
||||
- [SECURITY.md](../../../SECURITY.md) — reporte de vulnerabilidades, linha de
|
||||
base de segurança organizacional, governança de exclusão de varredura de
|
||||
segredos e verificação de integridade de dependências
|
||||
- [Índice de documentação](../README.md)
|
||||
129
docs/pt-BR/explanation/the-phase-loop.md
Normal file
129
docs/pt-BR/explanation/the-phase-loop.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# O loop de fases
|
||||
|
||||
> O modelo mental central de como o GSD Core organiza o trabalho.
|
||||
|
||||
---
|
||||
|
||||
## O que é o loop
|
||||
|
||||
O GSD Core estrutura todo o trabalho de desenvolvimento como um ciclo que se repete:
|
||||
|
||||
```text
|
||||
Discuss → (UI design) → Plan → Execute → Verify → Ship
|
||||
```
|
||||
|
||||
Cada unidade de trabalho — chamada de **fase** — percorre essas etapas em ordem. O loop não é uma formalidade. Cada etapa existe porque protege contra uma classe específica de falha que a etapa anterior, por si só, não consegue evitar.
|
||||
|
||||
Este documento explica *por que* o loop tem a forma que tem. Para instruções sobre como executar cada etapa, veja os guias práticos linkados ao final.
|
||||
|
||||
---
|
||||
|
||||
## Por que cada etapa existe
|
||||
|
||||
### Discuss
|
||||
|
||||
O planejamento não pode começar até que você saiba *como* construir a coisa, não apenas *o que* construir. O objetivo da fase em `ROADMAP.md` descreve o resultado. A etapa Discuss captura as decisões de implementação que moldam o caminho até esse resultado: quais bibliotecas, qual estratégia de tratamento de erros, se uma funcionalidade é por rota ou global, como os casos extremos devem se comportar.
|
||||
|
||||
Sem uma etapa Discuss, o planejador precisa tomar essas decisões por conta própria. Às vezes acerta. Muitas vezes acerta de forma plausível, mas errada — produzindo um plano coerente, porém desalinhado com suas preferências reais. Quando a execução termina e você percebe o erro, já está desfazendo um trabalho significativo.
|
||||
|
||||
A etapa Discuss é deliberadamente leve. É uma conversa, não um exercício de especificação. O resultado é um `CONTEXT.md` no diretório da fase: um registro estruturado de decisões que o planejador, executor e verificador podem ler. A conversa leva alguns minutos; pode economizar horas de retrabalho.
|
||||
|
||||
### UI design (opcional)
|
||||
|
||||
Para fases com componente visual, existe uma etapa opcional `/gsd-ui-phase` entre Discuss e Plan. Ela produz um `UI-SPEC.md` — um contrato de design que descreve layout, interação e comportamento visual antes de qualquer código ser escrito. Vale a pena executar essa etapa quando a interface é complexa o suficiente para que ambiguidades no design produzam escolhas de implementação divergentes. Um contrato de design claro é muito mais barato de escrever do que de reimplementar.
|
||||
|
||||
### Plan
|
||||
|
||||
A etapa Plan realiza a pesquisa, a decomposição e o raciocínio estrutural que a execução exige. Ela roda como uma sequência de subagentes com contexto zerado: um pesquisador que investiga o ecossistema e registra os achados em `RESEARCH.md`, um planejador que lê tanto a pesquisa quanto o `CONTEXT.md` para produzir os arquivos `PLAN.md`, e um verificador de planos que confere se os planos estão completos, consistentes e dentro do escopo.
|
||||
|
||||
O que um plano contém? Cada `PLAN.md` descreve uma unidade delimitada de trabalho: os arquivos a serem tocados, as mudanças específicas a serem feitas, os critérios de aceite que definem o que é "concluído". Os planos são ordenados em ondas de dependência para que a execução paralela seja segura — executores na mesma onda tocam preocupações que não se sobrepõem.
|
||||
|
||||
A etapa Plan é o momento em que a ambiguidade é mais cara. Um plano ambíguo produz um executor que faz suposições. Múltiplos executores paralelos fazendo suposições diferentes sobre a mesma preocupação produzem conflitos. O trabalho do verificador de planos é capturar isso antes de a execução começar, não depois.
|
||||
|
||||
### Execute
|
||||
|
||||
A execução roda os planos. Cada executor recebe uma janela de contexto zerada de 200k tokens carregada com exatamente o que precisa: o resumo do projeto, o contexto da fase, a pesquisa e o `PLAN.md` específico para sua tarefa. Nada mais.
|
||||
|
||||
Os executores escrevem código e fazem commits de forma atômica. Cada commit corresponde a uma tarefa concluída em um plano. Quando uma onda de executores paralelos termina, o orquestrador mescla o estado deles e inicia a próxima onda.
|
||||
|
||||
O contexto zerado do executor não é uma conveniência — é o mecanismo pelo qual a degradação de contexto é evitada. Um executor rodando com 180k tokens de histórico de sessão acumulado é um executor degradado. Um executor que começa do zero e lê apenas o que seu plano exige é um executor operando em plena capacidade.
|
||||
|
||||
### Verify
|
||||
|
||||
Após todos os executores terem concluído, um agente verificador lê o objetivo da fase, as decisões do `CONTEXT.md`, os planos e os resumos de execução — e verifica se o que foi construído corresponde ao que foi pretendido. Ele produz um `VERIFICATION.md` e, se houver discrepâncias, gera planos de correção direcionados.
|
||||
|
||||
A verificação não é apenas testes. Ela confere a cobertura de requisitos (todos os REQ-IDs foram endereçados?), a cobertura de decisões (as decisões capturadas no `CONTEXT.md` foram realmente implementadas?) e o alinhamento geral com o objetivo da fase. Uma fase não está concluída porque a execução terminou sem erros. Está concluída porque o que foi construído é o que foi planejado, e o que foi planejado é o que foi decidido.
|
||||
|
||||
### Ship
|
||||
|
||||
A etapa Ship cria o pull request e arquiva os artefatos da fase. O `STATE.md` é atualizado para marcar a fase como concluída. O loop então recomeça para a próxima fase.
|
||||
|
||||
---
|
||||
|
||||
## Marcos e fases
|
||||
|
||||
Um **marco** é um ciclo de versão — um incremento significativo e entregável do projeto. Tem um nome, um número de versão e um conjunto de requisitos que definem o que deve entregar. Um marco está completo quando todas as suas fases foram entregues e seus requisitos estão cobertos.
|
||||
|
||||
Uma **fase** é uma unidade de trabalho dentro de um marco. Uma fase tem um objetivo, um conjunto de requisitos que endereça e um conjunto de planos que a implementam.
|
||||
|
||||
A relação importa porque marcos e fases têm escopos de preocupação diferentes. Um marco pergunta: "O que esta versão do produto faz e o que ela não faz?" Uma fase pergunta: "Qual é a próxima coisa delimitada que podemos pesquisar, planejar, executar e verificar?"
|
||||
|
||||
Os limites dos marcos são traçados em fronteiras naturais do produto — uma API implantável, um fluxo de interface funcional, um modelo de dados completo. Os limites das fases são traçados nos limites do que pode ser executado com segurança em um loop sem que ele se torne incontrolável.
|
||||
|
||||
---
|
||||
|
||||
## O que define um bom escopo de fase
|
||||
|
||||
Vale a pena refletir sobre isso, pois é a fonte mais comum de atrito com o loop.
|
||||
|
||||
Uma fase muito grande torna-se um projeto de pesquisa em si mesma. O planejador tem dificuldade para decompô-la em planos independentes. Executores em ondas posteriores ficam bloqueados aguardando ondas anteriores. A verificação torna-se uma auditoria completa em vez de uma revisão direcionada. O ciclo de feedback se estende de horas para dias, e o risco de descobrir um erro de design fundamental tarde — após muito código ter sido escrito — aumenta drasticamente.
|
||||
|
||||
Uma fase muito pequena fragmenta trabalho que naturalmente pertence junto. Você acaba com arquivos de plano de meia dúzia de linhas, fases que completam em minutos e um custo de planejamento que supera em muito o custo de execução. O loop parece burocrático em vez de útil.
|
||||
|
||||
Um bom escopo de fase é aquele em que:
|
||||
|
||||
- O objetivo pode ser enunciado em uma única frase que não seja obviamente trivial nem suspeito de ser ampla demais.
|
||||
- A pesquisa necessária para planejá-la é delimitada — as questões sobre o ecossistema têm respostas que não dependem de outras fases sendo concluídas primeiro.
|
||||
- A execução pode ser paralelizada em um punhado de planos que não se sobrepõem, não dezenas.
|
||||
- Existe uma definição clara e testável de "concluído" que um verificador pode checar sem ler todo o código-base.
|
||||
|
||||
Concretamente: "Adicionar middleware de validação de assinatura HMAC-SHA256" é um bom escopo de fase. "Construir o sistema de autenticação" geralmente não é — quase sempre contém múltiplas preocupações independentes que seriam melhor tratadas como fases separadas. "Corrigir o erro de digitação no README" está abaixo do limite onde o loop agrega valor; use `/gsd-quick` nesse caso.
|
||||
|
||||
Na dúvida, divida. Uma fase menor completa mais rápido, verifica com mais confiança e facilita a correção de curso se uma decisão de design se mostrar errada.
|
||||
|
||||
---
|
||||
|
||||
## Como `.planning/` transporta estado ao longo do loop
|
||||
|
||||
O loop não é uma sessão única. Pesquisa, planejamento e execução podem acontecer em múltiplas sessões, com reinicializações de contexto no meio. O diretório `.planning/` é o que torna isso possível.
|
||||
|
||||
Cada etapa do loop lê artefatos produzidos por etapas anteriores e escreve artefatos para etapas posteriores. O CONTEXT.md que a etapa Discuss produz ainda está disponível quando o Planejador roda — mesmo que isso ocorra em uma sessão diferente, horas depois. Os arquivos PLAN.md que o Planejador produz ainda estão disponíveis quando o Executor roda — mesmo após uma reinicialização. O VERIFICATION.md que o Verificador escreve ainda está disponível quando você revisa a fase.
|
||||
|
||||
`STATE.md` é a camada de navegação acima de tudo isso. Ele registra exatamente onde no loop o projeto está atualmente: qual marco está ativo, qual fase está em andamento, quais planos estão completos e quais estão pendentes. Qualquer agente ou fluxo de trabalho que precise se orientar lê o `STATE.md` primeiro.
|
||||
|
||||
Para a estrutura precisa desses arquivos, consulte [Artefatos de planejamento](../reference/planning-artifacts.md) e o [esquema do STATE.md](../reference/state-md.md).
|
||||
|
||||
---
|
||||
|
||||
## O loop é um ritmo, não uma restrição
|
||||
|
||||
É tentador ver o loop como burocracia — um conjunto de etapas obrigatórias que você tem que executar antes de ter permissão para escrever código. Essa visão está errada.
|
||||
|
||||
O loop existe porque cada etapa previne falhas que são genuinamente caras de corrigir depois. O Discuss previne o planejamento com base em suposições erradas. O Plan previne a execução de um design fundamentalmente quebrado. O Verify previne a entrega de trabalho que perdeu o escopo. Esses não são problemas inventados. São os modos de falha reais do desenvolvimento assistido por IA na escala de funcionalidades reais.
|
||||
|
||||
Quando o loop funciona bem, ele parece um ritmo: uma cadência de trabalho focado e delimitado em que cada etapa é clara porque a etapa anterior fez seu trabalho. O custo adicional é real, mas está concentrado no início — pago em minutos de planejamento em vez de horas de retrabalho.
|
||||
|
||||
Para trabalhos que ficam abaixo do limite em que o loop é justificado, o GSD Core oferece primitivas mais leves. O loop de fases é uma ferramenta, não a única ferramenta.
|
||||
|
||||
---
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Engenharia de contexto](context-engineering.md) — por que subagentes com contexto zerado evitam a degradação de qualidade que torna o loop necessário
|
||||
- [Discutir uma fase](../how-to/discuss-a-phase.md)
|
||||
- [Planejar uma fase](../how-to/plan-a-phase.md)
|
||||
- [Executar uma fase](../how-to/execute-a-phase.md)
|
||||
- [Verificar e entregar](../how-to/verify-and-ship.md)
|
||||
- [Artefatos de planejamento](../reference/planning-artifacts.md)
|
||||
- [Esquema do STATE.md](../reference/state-md.md)
|
||||
- [índice de documentação](../README.md)
|
||||
Reference in New Issue
Block a user