golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

Browse Source 
* 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:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
docs/pt-BR/tutorials/onboarding-an-existing-codebase.md Normal file
View File

@@ -0,0 +1,226 @@
# Integrando uma base de código existente
Neste tutorial você integrará o GSD Core a um repositório que já possui código. Você mapeará a base de código, criará um projeto que descreve o que está *adicionando* e executará seu primeiro ciclo de discussão e planejamento para uma mudança pequena e focada. Ao final, o pipeline de planejamento do GSD Core conhecerá sua stack, suas convenções e suas preocupações — e usará esse conhecimento toda vez que planejar.
---
## O que você vai construir
Adicionaremos um único endpoint `GET /health` a uma aplicação Express existente. A mudança é pequena o suficiente para nunca desviar do objetivo real da lição: como o GSD Core aprende sua base de código antes de planejar qualquer coisa.
---
## Pré-requisitos
- **Node.js 18 ou superior** — `node --version` deve exibir `v18.x.x` ou mais recente.
- **Um projeto existente** — qualquer repositório com código. Não precisa ser Express; os passos se aplicam a qualquer stack.
- **Claude Code** — aberto na raiz do seu repositório.
---
## Passo 1 — Instalar o GSD Core
Na raiz do seu repositório:
```bash
npx @opengsd/gsd-core@latest
```
Escolha **Claude Code** e **local** quando solicitado. Você verá:
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
```
---
## Passo 2 — Iniciar o Claude Code com permissões
```bash
claude --dangerously-skip-permissions
```
---
## Passo 3 — Mapear a base de código
Antes de criar um projeto, deixe o GSD Core aprender o que já existe. Este é o passo que torna o planejamento brownfield preciso.
```text
/gsd-map-codebase
```
O GSD Core cria quatro sub-agentes mapeadores paralelos (você verá "Spawning 4 parallel codebase mapper agents…" — isso leva de 1 a 5 minutos; não interrompa). Cada agente foca em uma preocupação diferente:
| Agente | Foco |
|--------|------|
| Tech mapper | Stack, frameworks, dependências |
| Architecture mapper | Padrões, camadas, fluxo de dados |
| Quality mapper | Convenções, práticas de teste |
| Concerns mapper | Dívida técnica, áreas de risco |
Quando os quatro retornarem, você verá:
```text
Codebase mapping complete.
Created .planning/codebase/:
- STACK.md (47 lines) - Technologies and dependencies
- ARCHITECTURE.md (62 lines) - System design and patterns
- STRUCTURE.md (38 lines) - Directory layout and organisation
- CONVENTIONS.md (55 lines) - Code style and patterns
- TESTING.md (41 lines) - Test structure and practices
- INTEGRATIONS.md (29 lines) - External services and APIs
- CONCERNS.md (33 lines) - Technical debt and issues
```
Abra `.planning/codebase/STACK.md`. Você verá a linguagem, o runtime, as versões do framework e as dependências principais que o GSD Core detectou — fundamentadas nos arquivos reais que leu, não em suposições.
Abra `.planning/codebase/CONVENTIONS.md`. Você verá as convenções de nomenclatura, os padrões de tratamento de erros e as regras de estilo de código que ele observou no seu código-fonte. Todos os planos que o GSD Core produzir para este repositório seguirão essas convenções automaticamente.
Abra `.planning/codebase/CONCERNS.md`. Este é o arquivo mais útil para ler antes de qualquer trabalho em novo recurso — ele expõe dívidas técnicas e áreas frágeis que podem afetar seus planos.
---
## Passo 4 — Limpar o contexto e criar o projeto
Limpe a janela de sessão:
```text
/clear
```
Agora crie o projeto. Como o GSD Core encontrou código existente no passo anterior, já sabe que se trata de um projeto brownfield. Quando você executa `/gsd-new-project`, as perguntas focam no que você está *adicionando*, e não em reconstruir o que já existe:
```text
/gsd-new-project
```
O GSD Core pergunta o que você quer construir. Responda com o recurso que está adicionando, e não com uma descrição de toda a base de código:
```text
Add a GET /health endpoint to the Express app. It should return
{ "status": "ok", "uptime": <seconds> }. We'll use it for load-balancer
health checks.
```
O GSD Core faz um pequeno número de perguntas de esclarecimento e depois prossegue para a criação de requisitos e roteiro. Como já leu `ARCHITECTURE.md` e `STACK.md`, mapeará as capacidades existentes para a seção **Validated** de `PROJECT.md` automaticamente — você não precisa descrever a superfície de API existente.
Escolha os padrões recomendados para todas as configurações do fluxo de trabalho.
Quando o sub-agente roadmapper retornar, você verá um roteiro proposto. Para uma única mudança pequena, haverá uma fase:
```text
Proposed Roadmap
1 phase | 2 requirements mapped | All v1 requirements covered ✓
| # | Phase | Goal | Requirements |
|---|----------------|-----------------------------------------------|--------------|
| 1 | Health endpoint| GET /health returning status and uptime JSON | HLT-01, HLT-02 |
```
Aprove o roteiro.
**O que é criado em `.planning/`:**
```text
.planning/
PROJECT.md ← descrição do projeto; capacidades existentes em "Validated"
REQUIREMENTS.md ← HLT-01, HLT-02
ROADMAP.md ← Fase 1, status: pending
STATE.md ← memória de sessão
config.json ← configurações do fluxo de trabalho
codebase/ ← os sete arquivos de mapa do Passo 3
```
Observe que `.planning/codebase/` já está lá desde o Passo 3. O GSD Core leu esses arquivos ao escrever `PROJECT.md`, por isso conseguiu preencher os requisitos Validated sem que você os descrevesse.
---
## Passo 5 — Limpar o contexto e discutir a Fase 1
```text
/clear
```
```text
/gsd-discuss-phase 1
```
Como o GSD Core leu seu `CONVENTIONS.md` e `ARCHITECTURE.md`, suas perguntas são fundamentadas na sua base de código real — não em conselhos genéricos. Você pode ver:
```text
> Your routes are registered in src/routes/index.js. Should the health
endpoint live there, or in a dedicated src/routes/health.js?
A dedicated health.js — keep routes separated.
> Your existing error middleware returns { error: "message" }. Should
/health use the same shape for error responses?
Yes, stay consistent.
> Should uptime be calculated from process.uptime() or a stored start time?
process.uptime() is fine.
```
Quando a discussão encerrar, o GSD Core escreverá:
```text
.planning/phases/01-health-endpoint/CONTEXT.md
```
Abra esse arquivo. A seção `## Implementation Decisions` captura suas respostas. O planejador lerá este arquivo antes de escrever qualquer tarefa — portanto, suas preferências sobre posicionamento de arquivos e formato de resposta aparecerão nos planos, não apenas na discussão.
---
## Passo 6 — Planejar a Fase 1
```text
/gsd-plan-phase 1
```
Quatro sub-agentes de pesquisa rodam em paralelo (1–5 minutos). Quando retornarem, o planejador lê `CONTEXT.md`, os resultados da pesquisa e o mapa da sua base de código para criar planos de tarefas que correspondem às suas convenções.
**O que é criado:**
```text
.planning/phases/01-health-endpoint/
RESEARCH.md ← descobertas sobre padrões de health endpoint
01-01-PLAN.md ← Tarefa: criar src/routes/health.js
01-02-PLAN.md ← Tarefa: registrar rota health em src/routes/index.js
```
Abra `01-01-PLAN.md`. Observe que a tag `<files>` referencia `src/routes/health.js` — exatamente o caminho que você especificou na discussão, consistente com o padrão de roteamento que o GSD Core observou no mapa da sua base de código. Isso é o mapa da base de código em ação.
---
## Próximos passos
Você agora tem um projeto com um mapa da base de código, um registro de decisões de discussão e planos de tarefas verificados — tudo fundamentado no seu código real. A partir daqui, o fluxo de trabalho é idêntico ao de um projeto greenfield:
```text
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1
```
Para cada recurso futuro, execute `/gsd-map-codebase` novamente sempre que a estrutura mudar significativamente, para manter o mapa da base de código atualizado.
---
## O que você aprendeu
- Como `/gsd-map-codebase` executa quatro agentes paralelos para produzir `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md` e `INTEGRATIONS.md` em `.planning/codebase/`.
- Como `/gsd-new-project` em um repositório brownfield concentra as perguntas no que você está *adicionando* e preenche os requisitos Validated a partir do código existente.
- Como o mapa da base de código orienta cada pergunta em `/gsd-discuss-phase` — caminhos de arquivos, padrões e convenções vêm do seu código real.
- Como o planejador lê `CONTEXT.md` e `CONVENTIONS.md` para produzir planos que correspondem ao estilo do seu repositório.
---
## Relacionados
- [Seu primeiro projeto](your-first-project.md) — o ciclo greenfield completo, da instalação ao PR
- [Mapear base de código via Comandos](../COMMANDS.md) — todos os flags e subcomandos de `/gsd-map-codebase`
- [Índice de documentação](../README.md)

291
docs/pt-BR/tutorials/your-first-project.md Normal file
View File

@@ -0,0 +1,291 @@
# Seu primeiro projeto
Neste tutorial você instalará o GSD Core e construirá um pequeno aplicativo de linha de comando para gerenciar tarefas do zero — uma fase, um PR, o ciclo completo. Ao final, você terá executado cada comando do ciclo de fase principal pelo menos uma vez e terá visto os artefatos de planejamento que cada comando produz.
---
## O que você vai construir
Um CLI em Node.js que permite adicionar, listar e concluir itens de tarefas armazenados em um arquivo JSON local. É pequeno o suficiente para terminar em uma sessão e não utiliza nada além da biblioteca padrão do Node.js, portanto não há nada incomum para instalar.
---
## Pré-requisitos
- **Node.js 18 ou superior** — `node --version` deve exibir `v18.x.x` ou maior.
- **Claude Code** — aberto no diretório do projeto que você deseja utilizar.
- Uma conexão com a internet para a instalação inicial.
Nenhuma outra ferramenta é necessária. O próprio GSD Core é instalado no próximo passo.
---
## Passo 1 — Instalar o GSD Core
Abra um terminal no diretório do seu projeto e execute:
```bash
npx @opengsd/gsd-core@latest
```
O instalador pergunta qual ambiente de execução de IA você está usando e se deseja instalar globalmente ou no projeto atual. Escolha **Claude Code** e **local** (apenas este projeto) por enquanto.
Você verá uma saída como:
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
```
Observe que um diretório `.claude/` agora existe no seu projeto. É onde os comandos e agentes do GSD Core residem.
> Por que local vs global? Uma instalação local mantém a versão das skills fixada neste projeto. Consulte [Instalar no seu ambiente de execução](../how-to/install-on-your-runtime.md) quando quiser instalar globalmente.
---
## Passo 2 — Iniciar o Claude Code com permissões
O GSD Core spawna sub-agentes que leem e escrevem arquivos. Inicie o Claude Code com o sinalizador de permissões para que ele não pause para perguntar sobre cada operação de arquivo:
```bash
claude --dangerously-skip-permissions
```
Você chegará ao prompt do Claude Code no diretório do seu projeto.
---
## Passo 3 — Criar o projeto
Digite este comando slash no prompt do Claude Code:
```text
/gsd-new-project
```
O GSD Core abrirá uma conversa. Ele faz uma pergunta primeiro:
```text
What do you want to build?
```
Digite algo como:
```text
A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
No external dependencies — Node built-ins only.
```
O GSD Core faz uma série de perguntas de esclarecimento. Responda naturalmente. Ele está aprendendo o que é importante para você antes de escrever qualquer plano.
Após as perguntas, ele oferece a opção de realizar pesquisa de domínio. Para um projeto deste tamanho você pode pular a pesquisa — escolha **Skip research** quando solicitado.
O GSD Core então pede que você escolha as configurações de fluxo de trabalho (modo, granularidade, agentes de pesquisa). Escolha os padrões recomendados para cada um. Eles são gravados em `.planning/config.json`.
Por fim, um sub-agente de roadmap é executado (você verá o aviso "Spawning roadmapper…" — isso é normal e leva cerca de um minuto). Quando ele retornar, o GSD Core apresentará um roadmap proposto. Para um projeto de uma única fase, ele terá uma aparência semelhante a:
```text
Proposed Roadmap
1 phase | 4 requirements mapped | All v1 requirements covered ✓
| # | Phase | Goal | Requirements |
|---|--------------------|-----------------------------------------|-------------------|
| 1 | Core CLI | add / list / done commands, todos.json | CLI-01 … CLI-04 |
```
Digite **Approve** para aceitar o roadmap.
**O que é criado em `.planning/`:**
```text
.planning/
PROJECT.md ← descrição e requisitos do seu projeto
REQUIREMENTS.md ← REQ-IDs para cada capacidade v1
ROADMAP.md ← Fase 1, status: pending
STATE.md ← memória de sessão, posição atual
config.json ← configurações de fluxo de trabalho
```
Abra `.planning/ROADMAP.md` agora e leia. Observe que a Fase 1 tem uma Meta, uma lista de Requisitos que deve satisfazer e Critérios de Sucesso — estes são os comportamentos observáveis que a execução deve entregar.
---
## Passo 4 — Limpar o contexto e discutir a Fase 1
O GSD Core é projetado em torno de contextos frescos. Limpe a janela de sessão principal antes de cada fase:
```text
/clear
```
Em seguida, inicie a discussão para a Fase 1:
```text
/gsd-discuss-phase 1
```
O GSD Core lê a meta da fase e pergunta sobre suas preferências de implementação. Estas são as decisões que moldam *como* ele constrói, não apenas *o que* ele constrói. Exemplo de troca:
```text
> How should done items be stored — mark them in place or move them?
Mark them in place with a "done" flag.
> Should `todo list` show completed items by default?
No, hide them unless --all is passed.
> Error format when todos.json doesn't exist yet?
Create it silently on first add.
```
Quando a discussão encerra, o GSD Core escreve:
```text
.planning/phases/01-core-cli/CONTEXT.md
```
Abra esse arquivo. Você verá uma seção `## Implementation Decisions` capturando exatamente o que você disse. O planejador lê este arquivo — portanto, as decisões que você tomou aqui fluirão para cada plano de tarefa.
---
## Passo 5 — Planejar a Fase 1
```text
/gsd-plan-phase 1
```
Quatro sub-agentes de pesquisa se expandem em paralelo (você verá o aviso "Spawning 4 researchers…"). Eles levam de 1 a 5 minutos. Não interrompa.
Quando retornarem, um planejador lê o CONTEXT.md mais os resultados da pesquisa e cria planos de tarefa atômicos. Um verificador de planos então verifica se cada plano atinge a meta da fase antes de salvar.
**O que é criado:**
```text
.planning/phases/01-core-cli/
RESEARCH.md ← descobertas de domínio
01-01-PLAN.md ← Tarefa: criar helpers de leitura/escrita de todos.json
01-02-PLAN.md ← Tarefa: implementar os comandos add / list / done
```
Abra `01-01-PLAN.md`. Você verá um bloco `<task>` com um nome, os arquivos que toca, as etapas de ação, um comando de verificação e uma condição de conclusão. Observe a tag `<verify>` — o executor do GSD Core executará esse comando após escrever o código.
---
## Passo 6 — Executar a Fase 1
```text
/gsd-execute-phase 1
```
O GSD Core agrupa os planos em ondas (planos independentes são executados em paralelo), spawna um executor fresco com 200k de contexto por plano e confirma cada tarefa atomicamente.
Você verá algo como:
```text
Wave 1 (parallel):
[Executor A] → 01-01-PLAN.md (read/write helpers) ✓ committed
[Executor B] → 01-02-PLAN.md (CLI commands) ✓ committed
[Verifier] Checking codebase against phase goals...
CLI-01 todo add ✓
CLI-02 todo list ✓
CLI-03 todo done ✓
CLI-04 --all flag ✓
Status: PASS
```
**O que é criado:**
```text
.planning/phases/01-core-cli/
01-01-SUMMARY.md ← o que o Executor A construiu e confirmou
01-02-SUMMARY.md ← o que o Executor B construiu e confirmou
VERIFICATION.md ← cobertura de REQ: PASS
```
Execute seu CLI agora:
```bash
node todo.js add "buy milk"
node todo.js add "write tests"
node todo.js list
node todo.js done 1
node todo.js list
```
Você deve ver os itens aparecerem e o item 1 desaparecer da lista padrão após marcá-lo como concluído. Esse é o seu primeiro resultado visível entregue pelo GSD Core.
---
## Passo 7 — Verificar o trabalho
```text
/gsd-verify-work 1
```
O GSD Core extrai os critérios de sucesso da fase e os percorre um a um:
```text
[1/3] Can you run `node todo.js add "buy milk"` without errors?
> yes
[2/3] Does `node todo.js list` show only incomplete items by default?
> yes
[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list?
> yes
All 3 checks passed. Phase 1 verified.
```
Se alguma verificação falhar, o GSD Core diagnostica a causa raiz e cria um plano de correção. Execute `/gsd-execute-phase 1` novamente para aplicá-lo e depois re-execute `/gsd-verify-work 1`.
**O que é criado:**
```text
.planning/phases/01-core-cli/UAT.md ← todas as verificações e seus resultados
```
---
## Passo 8 — Publicar
```text
/gsd-ship 1
```
O GSD Core cria um pull request com um corpo gerado automaticamente. O corpo do PR sempre inclui: Resumo, Alterações, Requisitos Atendidos, Verificação e Decisões Principais.
Você verá:
```text
Pull request created: https://github.com/your-org/your-repo/pull/1
Title: feat(phase-1): core CLI — add / list / done commands
```
Esse é o ciclo completo — da ideia ao PR mesclado — para uma fase.
---
## O que você aprendeu
- Como instalar o GSD Core com `npx @opengsd/gsd-core@latest`.
- Como `/gsd-new-project` transforma uma conversa em um roadmap respaldado por artefatos em `.planning/`.
- Como `/gsd-discuss-phase` captura decisões de implementação antes de qualquer planejamento acontecer.
- Como `/gsd-plan-phase` spawna pesquisadores em paralelo e produz planos de tarefa atômicos.
- Como `/gsd-execute-phase` executa esses planos em ondas paralelas e confirma cada tarefa.
- Como `/gsd-verify-work` percorre os critérios de sucesso e gera planos de correção quando necessário.
- Como `/gsd-ship` transforma uma fase verificada em um pull request.
Para um projeto de múltiplas fases, repita os Passos 4–8 para cada fase e depois execute `/gsd-progress --next` para deixar o GSD Core detectar o próximo passo automaticamente.
---
## Relacionados
- [O ciclo de fase](../explanation/the-phase-loop.md) — por que o ciclo tem esse formato
- [Guias práticos](../README.md#how-to-guides) — receitas focadas em tarefas para situações específicas
- [Integrando uma base de código existente](onboarding-an-existing-codebase.md) — traga o GSD Core para um repositório já existente