msd-core/docs/pt-BR/tutorials/your-first-project.md

Seu primeiro projeto

Neste tutorial você instalará o MSD 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 MSD Core é instalado no próximo passo.

---

Passo 1 — Instalar o MSD Core

Abra um terminal no diretório do seu projeto e execute:

npx @golem15/msd-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:

✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ MSD Core ready — run /msd-new-project to start

Observe que um diretório .claude/ agora existe no seu projeto. É onde os comandos e agentes do MSD 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 quando quiser instalar globalmente.

---

Passo 2 — Iniciar o Claude Code com permissões

O MSD 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:

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:

/msd-new-project

O MSD Core abrirá uma conversa. Ele faz uma pergunta primeiro:

What do you want to build?

Digite algo como:

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 MSD 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 MSD 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 MSD Core apresentará um roadmap proposto. Para um projeto de uma única fase, ele terá uma aparência semelhante a:

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/:

.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 MSD Core é projetado em torno de contextos frescos. Limpe a janela de sessão principal antes de cada fase:

/clear

Em seguida, inicie a discussão para a Fase 1:

/msd-discuss-phase 1

O MSD 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:

> 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 MSD Core escreve:

.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

/msd-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:

.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 MSD Core executará esse comando após escrever o código.

---

Passo 6 — Executar a Fase 1

/msd-execute-phase 1

O MSD 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:

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:

.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:

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 MSD Core.

---

Passo 7 — Verificar o trabalho

/msd-verify-work 1

O MSD Core extrai os critérios de sucesso da fase e os percorre um a um:

[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 MSD Core diagnostica a causa raiz e cria um plano de correção. Execute /msd-execute-phase 1 novamente para aplicá-lo e depois re-execute /msd-verify-work 1.

O que é criado:

.planning/phases/01-core-cli/UAT.md   ← todas as verificações e seus resultados

---

Passo 8 — Publicar

/msd-ship 1

O MSD 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á:

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 MSD Core com npx @golem15/msd-core@latest.
• Como /msd-new-project transforma uma conversa em um roadmap respaldado por artefatos em .planning/.
• Como /msd-discuss-phase captura decisões de implementação antes de qualquer planejamento acontecer.
• Como /msd-plan-phase spawna pesquisadores em paralelo e produz planos de tarefa atômicos.
• Como /msd-execute-phase executa esses planos em ondas paralelas e confirma cada tarefa.
• Como /msd-verify-work percorre os critérios de sucesso e gera planos de correção quando necessário.
• Como /msd-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 /msd-progress --next para deixar o MSD Core detectar o próximo passo automaticamente.

---

Relacionados

• O ciclo de fase — por que o ciclo tem esse formato
• Guias práticos — receitas focadas em tarefas para situações específicas
• Integrando uma base de código existente — traga o MSD Core para um repositório já existente