msd-core/docs/pt-BR/tutorials/onboarding-an-existing-codebase.md

Integrando uma base de código existente

Neste tutorial você integrará o MSD 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 MSD 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 MSD 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 MSD Core

Na raiz do seu repositório:

npx @golem15/msd-core@latest

Escolha Claude Code e local quando solicitado. Você verá:

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

---

Passo 2 — Iniciar o Claude Code com permissões

claude --dangerously-skip-permissions

Caution

The permissions flag is optional. It skips per-file confirmation while MSD's sub-agents read and write files. Use it only in low-stakes or throwaway contexts. To keep confirmations enabled, start with claude instead. For real work, read the security model first.

---

Passo 3 — Iniciar o onboarding brownfield

Antes de criar um projeto, deixe o MSD Core inspecionar o estado do repositório e indicar o próximo comando de nível superior seguro. Este passo evita pular contexto de código ou sobrescrever arquivos de planning existentes.

/msd-onboard

Se o onboarding informar que o mapa da base de código está ausente, escolha a opção recomendada e execute o handoff /msd-map-codebase impresso antes de rodar /msd-onboard novamente. /msd-onboard --fast serve para uma primeira passada leve, mas um mapa completo ainda é necessário antes de /msd-new-project. O /msd-map-codebase 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á:

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 MSD 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 MSD 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 — Reexecutar o onboarding e inicializar o projeto

Limpe a janela de sessão:

/clear

Agora execute /msd-onboard novamente. Se o MSD Core detectar ADRs, PRDs, specs, RFCs ou requisitos de nível raiz, aceite o handoff recomendado para /msd-ingest-docs primeiro e depois rode /msd-onboard de novo. Quando o contexto estiver pronto, o onboarding imprimirá o handoff de inicialização:

/msd-new-project

Como o MSD Core encontrou código existente no passo anterior, /msd-new-project sabe que é um projeto brownfield. As perguntas focam no que você está adicionando, não em reconstruir o que já existe:

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

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

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.

Execute /msd-onboard mais uma vez depois que a configuração do projeto terminar. Agora que PROJECT.md, REQUIREMENTS.md, ROADMAP.md e STATE.md existem, o onboarding cria ou confirma .planning/onboarding/SUMMARY.md.

O que é criado em .planning/:

.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
  onboarding/SUMMARY.md ← status do onboarding e próximo comando
  codebase/           ← os sete arquivos de mapa do Passo 3

Observe que .planning/codebase/ já está lá desde o Passo 3. O MSD 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

/clear

/msd-discuss-phase 1

Como o MSD 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:

> 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 MSD Core escreverá:

.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

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

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

/msd-execute-phase 1
/msd-verify-work 1
/msd-ship 1

Para cada recurso futuro, execute /msd-map-codebase novamente sempre que a estrutura mudar significativamente, para manter o mapa da base de código atualizado.

---

O que você aprendeu

• Como /msd-onboard sequencia com segurança o setup brownfield sem aninhar comandos interativos ou sobrescrever planning existente.
• Como /msd-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 /msd-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 /msd-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 — o ciclo greenfield completo, da instalação ao PR
• Mapear base de código via Comandos — todos os flags e subcomandos de /msd-map-codebase
• Índice de documentação