💡 Como ler este módulo
Contribuir para DeerFlow é mais sobre ler do que sobre escrever. Quem lê CONTRIBUTING.md, AGENTS.md e os PRs recentes escreve código que combina com o projeto — e passa na revisão. Quem só escreve, acumula rejeições. Faça a leitura inteira antes de abrir qualquer branch. O lab final é a prova de que você entendeu.
📜 CONTRIBUTING.md e AGENTS.md (backend + frontend)
Três documentos cobrem as regras do jogo: CONTRIBUTING.md na raiz do repo (processo geral), AGENTS.md em src/ (convenções de backend Python) e um segundo AGENTS.md em web/ (convenções de frontend TypeScript/React). Cada PR precisa obedecer ao do escopo que toca. Desrespeitar é caminho curto para "please read the AGENTS.md before resubmitting".
CONTRIBUTING.md
Setup, CLA, fluxo de PR, política de review
Instruções para clonar, instalar (uv sync no backend, pnpm install no web), rodar testes (pytest, vitest). Descreve branch strategy (trunk-based, sem long-lived feature branches), política de squash merge e o que precisa passar antes do review (lint + testes + type-check).
AGENTS.md do backend
Convenções Python: tipos, testes, middleware, async
Tipagem estrita (mypy --strict), testes com pytest e markers por categoria, padrões de middleware para passar pelo pipeline de mensagens, uso obrigatório de async em I/O, proibição de print() (usar structlog). Todo novo módulo precisa de docstring no topo descrevendo propósito.
AGENTS.md do frontend
Convenções TS/React: server components, state, styling
Next.js 15 App Router, React Server Components como default, Zustand ou Jotai para state client-side (nunca Redux novo), Tailwind com design tokens definidos em tokens.css, TypeScript strict + eslint com regra de ordenação de imports. Componentes shadcn/ui são alterados localmente, não via prop drilling.
Commits e PR template
Conventional Commits, descrição rica
Conventional Commits obrigatório (feat:, fix:, docs:, refactor:, test:). Descrição do PR segue template com seções Summary, Motivation, Changes, Testing, Screenshots (se UI). PRs sem testes são rejeitados automaticamente por bot, salvo marcação especial.
📝 RFCs e docs/plans — onde moram as decisões
Mudança não-trivial no DeerFlow passa por RFC (proposta técnica formal) ou doc/plan (plano de execução sequencial). Os dois vivem em docs/rfcs/ e docs/plans/ no repo. Ler RFCs antigos evita reabrir discussões já encerradas; ler doc/plans em progresso evita duplicar trabalho.
🎯 Conceito Central
RFC e plan servem propósitos diferentes:
- •RFC (rfc-NNNN-titulo.md) — proposta aberta, discute trade-offs, menciona alternativas, status (draft/accepted/rejected/superseded). Pode durar semanas antes de aprovar.
- •Plan (plan-NNNN-titulo.md) — plano de execução de um RFC aprovado ou feature bem definida. Lista milestones, PRs esperados, owner e data. Quase um mini-projeto.
- •Link entre eles — todo plan cita o RFC que aprovou; todo RFC aprovado cita o plan que executa.
Template de RFC do DeerFlow (resumido)
# RFC-0042: Título conciso
Status: draft | accepted | rejected | superseded-by-rfc-NNNN
Author: @handle
Date: YYYY-MM-DD
## Summary
Uma frase. Duas no máximo.
## Motivation
Por que isso importa. Qual problema resolve.
## Design
Proposta técnica detalhada. Snippets, diagramas.
## Alternatives
O que foi considerado e rejeitado.
## Open Questions
Perguntas explícitas para a discussão.
## Migration
O que quebra, como mitigar.💡 Dica prática
Antes de propor mudança grande via issue/PR, confira os RFCs existentes. Já houve um rfc-0017 sobre isolamento de sub-agents que foi rejeitado — abrir o assunto de novo sem citar por que a rejeição anterior não se aplica queima sua credibilidade. Reference RFCs antigos como parte do seu novo RFC.
🔁 Padrões de PR recentes — leituras obrigatórias
A melhor forma de entender "o que passa na revisão" é ler os PRs que passaram recentemente. O DeerFlow tem quatro linhas de trabalho ativas onde o volume é maior: middleware, guardrails, async wrapping e canais IM. Ler 2-3 PRs de cada uma calibra seu senso de tamanho, descrição e qualidade de teste esperada.
📊 Anatomia média de um PR aprovado
- Tamanho — 200-600 linhas de diff, 3-8 arquivos tocados. PRs maiores quase sempre voltam para dividir.
- Commits — 1 a 5, squashed no merge. Cada commit roda CI individualmente sem quebrar.
- Testes — 30-50% das linhas adicionadas são de teste. PR sem teste = PR rejeitado.
- Descrição — Summary, Motivation, Changes, Testing sections preenchidas. Screenshots em mudanças de UI.
- Tempo até merge — mediana de 2 dias, com 1-2 rounds de review. PRs limpos e focados mergem em <24h.
- Referência a issue — link para issue, TODO.md ou RFC que motivou o trabalho.
Middleware
Novos middlewares entram na pipeline de mensagens entre lead_agent e sub-agents. Padrão: classe herdando de MessageMiddleware, método process async, teste unitário isolado + teste de integração na pipeline.
Guardrails
Regras que barram outputs problemáticos (PII, prompt injection detectado, output vazio). Sempre com modo "log only" primeiro antes de "block" — a transição é um PR separado, com métrica de false positive anexada.
Async wrapping
Conversão de código síncrono legado para async. Padrão: criar versão async que o código existente passa a delegar, manter facade síncrona para compatibilidade, deprecar a sync em 1-2 releases.
Canais IM
Slack, Discord, Telegram como channels de entrada. Implementam IMChannel protocol, trazem webhook handler, tratamento de reply threads, e sempre um arquivo de doc em docs/channels/ explicando setup do lado do serviço.
🎯 Como achar um "good first issue"
Primeira contribuição vale pela entrega, não pela grandeza. Escolher a issue do tamanho certo é metade do trabalho — issue muito grande você não termina, muito pequena não ensina. O DeerFlow tem label oficial good first issue, mas também existem "boas primeiras" não etiquetadas no TODO.md.
🎯 Heurística de seleção
- •Escopo fechado — título que descreve a mudança sem "e X, e Y, e Z"
- •Sem dependências abertas — não depende de RFC que ainda não foi aprovado
- •Mais de 7 dias, menos de 90 — velha demais pode ter sido esquecida ou resolvida noutro lugar; nova demais tem dono silencioso
- •Thread quieto — ninguém disse "I'll pick this" nos últimos 14 dias
- •Toca 1 arquivo ou 1 módulo — primeiro PR não é refactor global
✓ Fazer
- ✓Comentar "working on this" na issue antes de começar
- ✓Preferir
docs:etest:como primeiro PR - ✓Ler os últimos 5 PRs do módulo que você vai tocar
- ✓Rodar
pytest,mypyeruffantes de abrir PR
✗ Evitar
- ✗Refactor global "só para limpar" — raramente é well-received
- ✗PR que toca >10 arquivos sem issue/RFC ancorando
- ✗Sumir depois de "I'll pick this" — libere a issue se desistir
- ✗Questionar convenções de AGENTS.md no seu primeiro PR
💡 Dica prática
O TODO.md do DeerFlow tem itens menores e mais óbvios que as issues formais. Muitos são "wanted, não agendado". Pegar um item marcado "TODO: handler para canal IM XYZ" é mais fácil de vender do que propor mudança do zero — já foi aprovado em algum momento, só precisa de alguém que faça.
🧪 Lab: abrir draft PR a partir do TODO.md
Entregável final da trilha: um draft PR aberto no repositório oficial, a partir de um item do TODO.md, com testes, descrição no template e CI verde. Draft porque você não precisa mergear — precisa ter aberto. A prova de que o ciclo todo funciona é o link do PR no seu próprio registro.
Fork e clone
Fork o repositório no GitHub, clone o fork, adicione o upstream como remote extra (git remote add upstream ...). Crie branch a partir de main atualizado com nome descritivo: feat/im-channel-mattermost, docs/security-md-threat-model, etc.
Escolha o item do TODO.md
Abra TODO.md na raiz. Procure bullets com escopo claro e tamanho baixo — idealmente um item que toque 1-2 arquivos. Se algum está marcado com owner, pule. Comente na issue correspondente (se existir) "picking this for my onboarding PR".
Implemente respeitando AGENTS.md
Siga o padrão do módulo que está tocando. Se é backend, mypy --strict, testes pytest no diretório tests/ espelhando a estrutura. Se é frontend, TypeScript strict, componentes em web/src/components/, teste com vitest. Rode uv run pytest / pnpm test / pnpm lint antes de commitar.
Commits Conventional
1 a 5 commits, cada um passando CI sozinho. Nomes tipo feat(channels): add mattermost webhook handler, test(channels): cover mattermost thread replies, docs(channels): setup guide for mattermost.
Abra draft PR com template preenchido
Push para o fork, abra PR contra upstream/main, marque Draft. Preencha o template todo: Summary, Motivation (linkando TODO.md), Changes (bullets), Testing (o que rodou e passou). Anexe screenshot se mudou UI. Confirme CI verde antes de mudar para "ready for review".
Registre o link do PR
Salve a URL do draft PR no seu documento de progresso do curso. É o entregável. Opcionalmente, mude para "ready for review" quando estiver confortável; o projeto vai conduzir a revisão normalmente.
💡 Parabéns
Se você chegou aqui com um draft PR vivo, você concluiu a Trilha 3. Você configura providers, protege sandbox, debuga memória, embute DeerFlow em outro app e consegue devolver valor para o projeto. É tudo que define um engenheiro de IA sênior nesse harness. A Trilha 4 é comparativa — você vai colocar DeerFlow contra outros super agent harnesses e decidir quando é certo escolher ele e quando não é.
📝 Resumo do Módulo
docs: e test: como primeiro PR.Próxima Trilha:
Trilha 4 — 🔍 Comparativo com outros super agent harnesses
Claude Code, Manus, GenSpark, smolagents e outros. Quando escolher DeerFlow, quando escolher o competidor, e como decidir sem religião.