Kaique Mitsuo Silva Yamamoto
IaDesenvolvimento com ia

Onboarding de Projeto com IA — Primeiros Passos em um Código Novo

Como usar IA para fazer onboarding rápido em um projeto desconhecido. Mapa de dependências, arquitetura, convenções e o primeiro commit.

Entrar em um projeto novo é uma das tarefas mais difíceis para um desenvolvedor. A IA pode acelerar o onboarding de semanas para horas — se você usar o método certo.


O método dos 4 passos

Passo 1: Mapa do território (30 minutos)

Analyze this codebase and generate:

1. Project overview: what does this project do?
2. Tech stack: languages, frameworks, databases, tools
3. Directory structure: what lives where
4. Entry points: where does the app start?
5. Key files: the 10 most important files in the project

Output: docs/onboarding/overview.md

Passo 2: Fluxo de dados (30 minutos)

Trace the data flow in this codebase:

1. Where do requests enter? (API routes, CLI commands, webhooks)
2. How is data validated? (middleware, schemas, types)
3. Where is data stored? (database models, schemas)
4. How is data returned? (serializers, response formats)
5. What external services are called? (APIs, queues, caches)

Output: docs/onboarding/data-flow.md

Passo 3: Convenções do projeto (15 minutos)

Analyze the coding style in this project:

1. Naming conventions (files, functions, variables)
2. Import style (named vs default, barrel files)
3. Error handling patterns
4. Testing patterns (framework, naming, coverage)
5. Git conventions (branch naming, commit style)

Output: docs/onboarding/conventions.md

Passo 4: Primeira tarefa (1-2 horas)

I'm onboarding to this project. Pick a small, low-risk task:

1. Read docs/onboarding/overview.md, data-flow.md, and conventions.md
2. Find a TODO comment, a small bug, or a missing test
3. Implement the fix following the project's conventions
4. Write tests for your change
5. Run: pnpm lint:fix && pnpm vitest run
6. If green, commit with a conventional message

This will be my first commit — make it clean.

Prompt para descobrir arquitetura

I just joined this project. Help me understand the architecture:

1. Read the top-level files: package.json, README.md, CLAUDE.md (if exists)
2. List the main directories and what they contain
3. Identify the architecture pattern (MVC, hexagonal, layered, microservices)
4. Find the database layer: ORM, models, migrations
5. Find the API layer: routes, handlers, middleware
6. Find the test setup: framework, config, example tests

Give me a 5-minute briefing on how this project is structured.

Erros comuns no onboarding

ErroConsequênciaCorreção
Pedir "explique tudo" de uma vezContext window sobrecarregadoUma camada por vez (overview → data flow → conventions)
Não ler README/CLAUDE.mdPerde contexto críticoSempre começar pelos docs do projeto
Fazer mudança grande no primeiro diaQuebra coisas que não entendePrimeira tarefa = TODO ou bug pequeno
Não rodar testes antes de mudarNão sabe se o baseline funcionaSempre rodar testes antes de editar
Não perguntar ao timeAssume que entendeuConfirme com humano antes de commitar

On this page