O que é PLAN.md em projetos de IA?

PLAN.md é um documento de planejamento técnico que vive no repositório junto com o código. Ele descreve o objetivo do projeto, a arquitetura escolhida, as decisões técnicas tomadas e o roadmap de entrega. Serve como contexto estruturado para a IA programadora (Cursor, Copilot, Claude) entender o projeto antes de gerar código — evitando que a IA tome decisões que contradizem a arquitetura planejada.

Qual a diferença entre PLAN.md e TASKS.md?

PLAN.md é estratégico — define o 'para onde' e o 'por quê'. TASKS.md é operacional — define o 'o quê fazer agora', com tarefas granulares, critérios de aceite e status. O PLAN.md muda poucas vezes no projeto; o TASKS.md é atualizado a cada sprint ou semana. Juntos, formam o contexto que a IA programadora precisa para gerar código alinhado com a arquitetura e os objetivos do projeto.

A IA programadora realmente usa esses arquivos?

Sim, quando configurado corretamente. Ferramentas como Cursor (com @PLAN.md), Claude Code (com CLAUDE.md) e configurações de contexto do Copilot permitem incluir esses arquivos na context window do modelo. A diferença na qualidade do código gerado é significativa: com contexto estruturado, a IA toma decisões arquiteturais consistentes; sem contexto, ela inventa padrões baseados nos dados de treinamento — que podem não se encaixar no projeto.

SPEC-Driven Development · MOFU · IT

PLAN.md e TASKS.md para guiar a IA programadora

Por Adriano Schneider · 5 de maio de 2026 · 9 min de leitura

Você usa Cursor, Copilot ou Claude para escrever código — e ainda assim o resultado são arquivos que não seguem a arquitetura do projeto, que reinventam padrões que já existem, que ignoram decisões que levaram semanas para ser tomadas. O problema não é a IA. É a falta de contexto estruturado. PLAN.md e TASKS.md resolvem exatamente isso.

Por que a IA programadora precisa de contexto estruturado

A IA programadora — seja Cursor, GitHub Copilot, Claude Code ou qualquer outra — funciona com base no que está na context window no momento em que você faz uma pergunta ou pede uma implementação. Sem contexto do projeto, ela infere o máximo que consegue a partir dos arquivos abertos e do histórico de conversa.

O resultado é código que funciona isoladamente mas não encaixa no projeto: ela escolhe uma biblioteca que você não usa, cria um padrão arquitetural diferente do que já existe, ignora convenções de nomenclatura, repete lógica que já está implementada em outro módulo.

Em 2026, vejo times que usam IA para programação há mais de um ano chegando à mesma conclusão: o que separa uso produtivo de uso frustrante é a qualidade do contexto que você fornece à ferramenta. PLAN.md e TASKS.md são a forma estruturada de fazer isso.

O que é PLAN.md e o que vai nele

PLAN.md é o documento estratégico do projeto — uma especificação técnica legível tanto por humanos quanto por IA. Ele vive na raiz do repositório e é lido pela IA no início de cada sessão de trabalho (via configuração da ferramenta).

O PLAN.md responde às perguntas que qualquer novo desenvolvedor (humano ou IA) teria ao entrar no projeto:

O que este projeto faz e por quê existe?
Qual é a arquitetura escolhida e por que essa, não outra?
Quais tecnologias são usadas e quais são proibidas?
Quais são as convenções de código deste projeto?
Quais são as decisões já tomadas que não devem ser questionadas sem uma ADR?

Template de PLAN.md com exemplo preenchido

Abaixo está o template real que uso em projetos. O exemplo preenchido é de um agente de triagem de tickets de suporte — projeto recorrente em PMEs de médio porte.

# PLAN.md — Agente de Triagem de Suporte
## Visão Geral

      Agente de IA que classifica e roteia tickets de suporte recebidos por e-mail e formulário web. Objetivo: reduzir em 70% o tempo de triagem manual da equipe de suporte (atualmente 2h/dia por analista).
**Proprietário:** Equipe de Tecnologia — Solução21

      **Data de início:** 2026-03-10

      **Previsão de go-live:** 2026-06-30

      **Status:** Piloto — sprint 4 de 6
## Arquitetura

      ```

      Entrada (e-mail / webhook formulário)

        ↓

      Parser de entrada (normalização de texto)

        ↓

      Agente de classificação (LLM + few-shot)

        ↓

      Validador de confiança (score ≥ 0.75 → auto; < 0.75 → fila humana)

        ↓

      Integração Helpdesk (API Zendesk)

        ↓

      Notificação (Slack channel por urgência)

      ```
## Stack Tecnológico

      - **Linguagem:** Python 3.12

      - **Framework de agente:** LangGraph 0.2

      - **Modelo LLM:** Claude 3.5 Sonnet via API Anthropic (decisão em ADR-001)

      - **Infraestrutura:** AWS Lambda + SQS para filas

      - **Observabilidade:** Langfuse para rastreamento de chamadas LLM

      - **Testes:** pytest + pytest-asyncio
## Convenções de Código

      - Todos os nomes de variáveis, funções e comentários em português do Brasil

      - Type hints obrigatórios em todas as funções

      - Docstrings no formato Google Style em português

      - Funções máximo de 40 linhas — funções maiores devem ser divididas

      - Nenhuma chamada direta ao modelo fora do módulo `agente/classificador.py`

      - Logging via structlog — nunca usar print() em código de produção
## Decisões Tomadas (não alterar sem nova ADR)

      - ADR-001: Claude Sonnet escolhido sobre GPT-4o por custo-benefício e latência (ver /docs/adr/001-modelo-llm.md)

      - ADR-002: LangGraph escolhido sobre CrewAI por maior controle sobre fluxo de execução

      - ADR-003: Classificação com few-shot escolhida sobre fine-tuning — dataset insuficiente para fine-tuning robusto

      - ADR-004: Zendesk mantido como sistema de helpdesk — migração fora de escopo deste projeto
## Fora de Escopo (não implementar sem aprovação)

      - Resposta automática ao usuário final (apenas classificação e roteamento)

      - Análise de sentimento (ver roadmap v2)

      - Integração com CRM (projeto separado)

      - Suporte a tickets em espanhol ou inglês (apenas português)
## Referências

      - Requisitos funcionais: /docs/requisitos/

      - ADRs: /docs/adr/

      - Dataset de teste: /testes/dados/

      - Documentação da API Zendesk: https://developer.zendesk.com/api-reference/

O que é TASKS.md e o que vai nele

Enquanto o PLAN.md é estratégico e muda pouco, o TASKS.md é operacional e muda toda semana. Ele lista as tarefas do sprint atual, com granularidade suficiente para que a IA programadora implemente cada uma sem precisar fazer suposições sobre escopo.

A chave do TASKS.md eficaz: cada tarefa referencia o requisito que está implementando (via ID), define o critério de aceite da tarefa específica, e indica arquivos que serão afetados. Isso dá à IA programadora tudo que precisa para gerar código preciso sem "inventar" contexto.

Template de TASKS.md com exemplo preenchido

# TASKS.md — Sprint 4 (2026-05-05 a 2026-05-16)
## Status de Sprint

      **Meta:** Implementar validação de confiança e integração Zendesk

      **Progresso:** 3/8 tarefas concluídas
---
## ✅ Concluídas
### T-4.1 — Implementar parser de e-mail

      **Requisito:** RF-003-PARSER

      **Status:** Concluída — 2026-05-06

      **Arquivos:** `parser/email_parser.py`, `testes/test_email_parser.py`

      **Notas:** Suporte a multipart MIME implementado. Anexos ignorados nesta versão (ver RF-015 para v2).
### T-4.2 — Configurar Langfuse para rastreamento

      **Requisito:** NFR-002-OBSERVABILIDADE

      **Status:** Concluída — 2026-05-07

      **Arquivos:** `infra/observabilidade.py`, `.env.example`
### T-4.3 — Criar dataset de few-shot exemplos de classificação

      **Requisito:** RF-007-CLASSIFICACAO

      **Status:** Concluída — 2026-05-08

      **Arquivos:** `dados/few_shot_classificacao.jsonl` (47 exemplos rotulados)
---
## 🔄 Em Progresso
### T-4.4 — Implementar validador de confiança

      **Requisito:** RF-008-VALIDACAO

      **Responsável:** Adriano

      **Arquivos a modificar:** `agente/validador.py` (criar), `agente/classificador.py` (integrar)

      **Critério de aceite desta tarefa:**

      - Função `validar_confianca(resultado_classificacao)` retorna `{"acao": "auto" | "fila_humana", "score": float}`

      - Score ≥ 0.75 → acao = "auto"

      - Score < 0.75 → acao = "fila_humana"

      - Testes unitários cobrindo: score exato em 0.75, score abaixo, score acima, score None (erro)

      **Contexto para IA:** O score de confiança vem do campo `metadata.confidence` retornado pelo classificador. Não confundir com o score de similaridade do RAG (projeto diferente). Padrão de retorno deve ser consistente com `TipoRetornoValidacao` definido em `agente/tipos.py`.
---
## ⬜ Pendentes
### T-4.5 — Integrar API Zendesk para atualização de ticket

      **Requisito:** RF-010-ZENDESK

      **Dependência:** T-4.4 (validador precisa estar concluído)

      **Arquivos a criar/modificar:** `integrações/zendesk_client.py` (criar), `agente/orquestrador.py` (integrar)

      **Critério de aceite desta tarefa:**

      - Classe `ClienteZendesk` com métodos: `buscar_ticket(id)`, `atualizar_urgencia(id, urgencia)`, `adicionar_tag(id, tag)`

      - Autenticação via API token (nunca user/password)

      - Rate limiting respeitado: máximo 700 req/min conforme documentação Zendesk

      - Retry automático com backoff exponencial para erros 429 e 5xx

      - Testes com mock da API Zendesk (não chamar API real em testes unitários)

      **Contexto para IA:** Credenciais Zendesk ficam em variáveis de ambiente `ZENDESK_SUBDOMAIN`, `ZENDESK_EMAIL`, `ZENDESK_TOKEN`. Usar biblioteca `requests` já presente no projeto — não instalar httpx ou aiohttp sem discussão.
### T-4.6 — Implementar notificação Slack por urgência

      **Requisito:** RF-011-NOTIFICACAO

      **Dependência:** T-4.5

      **Arquivos:** `integrações/slack_client.py`

      **Critério:** Canal #suporte-critico para urgência Crítico; #suporte-alto para Alto; Normal sem notificação
### T-4.7 — Escrever testes de integração do fluxo completo

      **Requisito:** Todos os RFs do sprint 4

      **Dependência:** T-4.5 e T-4.6 concluídas

      **Arquivos:** `testes/integracao/test_fluxo_triagem.py`

      **Critério:** 5 cenários end-to-end passando com dados do dataset de teste
### T-4.8 — Atualizar documentação de deploy

      **Requisito:** NFR-005-DOCUMENTACAO

      **Arquivos:** `docs/deploy.md`

      **Critério:** Passos de deploy atualizados com configuração do Langfuse e variáveis Zendesk/Slack
---
## Bloqueios

      - T-4.5 aguarda acesso à conta Zendesk sandbox (solicitar ao Felipe até 2026-05-09)

      - Nenhum outro bloqueio identificado
## Próximo sprint (planejamento em 2026-05-16)

      - Testes de carga (500 tickets simultâneos)

      - Implementação de fila humana na interface do analista

      - Coleta de feedback dos analistas piloto

Antes e depois — o impacto na prática

Para tornar concreto, veja como uma instrução para IA programadora muda com e sem o PLAN.md/TASKS.md no contexto:

Sem PLAN.md/TASKS.md	Com PLAN.md/TASKS.md no contexto
"Implemente a integração com o Zendesk" Resultado: a IA escolhe uma biblioteca aleatória, cria autenticação com user/password (insegura), ignora rate limiting, usa padrões que não existem no projeto	"Implemente T-4.5 conforme TASKS.md" Resultado: a IA cria ClienteZendesk com os métodos especificados, usa requests (já no projeto), implementa autenticação via token, respeita os limites de rate, cria testes com mock
"Adicione logging nessa função" Resultado: a IA adiciona print() ou configura logging padrão do Python, inconsistente com o restante	"Adicione logging nessa função" (com PLAN.md no contexto) Resultado: a IA usa structlog conforme convenção do PLAN.md, com campos estruturados consistentes
"Como devo implementar a classificação?" Resultado: a IA sugere fine-tuning, RAG, e outras abordagens sem saber que já há uma decisão tomada	"Como devo implementar a classificação?" (com PLAN.md no contexto) Resultado: a IA sabe que ADR-003 escolheu few-shot e implementa dentro dessa decisão, sem reinventar

Como configurar nas ferramentas de IA

Cursor

Adicione ao arquivo .cursorrules na raiz do projeto: Leia sempre @PLAN.md e @TASKS.md antes de qualquer implementação. Assim o Cursor incluirá esses arquivos automaticamente no contexto de cada conversa.

Claude Code

O CLAUDE.md na raiz do repositório é lido automaticamente pelo Claude Code. Você pode referenciar PLAN.md e TASKS.md dentro do CLAUDE.md com instruções explícitas sobre quando e como consultá-los.

GitHub Copilot

Abra PLAN.md e TASKS.md como abas no editor antes de pedir sugestões. O Copilot inclui arquivos abertos no contexto. A alternativa mais robusta: use Copilot Chat com #file:PLAN.md e #file:TASKS.md na instrução.

Manutenção — o que torna ou destrói a abordagem

PLAN.md e TASKS.md só têm valor se estiverem atualizados. Documentação desatualizada é pior do que nenhuma documentação — ela induz a IA (e os humanos) a tomar decisões baseadas em premissas erradas.

As regras que funcionam:

TASKS.md atualizado a cada tarefa concluída — mova para "Concluídas" antes de abrir PR. Nenhum merge sem atualização.
PLAN.md atualizado a cada ADR — toda decisão arquitetural documentada em ADR precisa estar refletida no PLAN.md. As seções "Decisões Tomadas" e "Stack Tecnológico" são as que mais ficam desatualizadas.
TASKS.md arquivado por sprint — ao fechar o sprint, mova para /docs/sprints/tasks-sprint-4.md e crie um TASKS.md limpo para o próximo. O histórico é valioso para retrospectiva.

A relação com SPEC-driven e os outros documentos

PLAN.md e TASKS.md são complementares aos requisitos funcionais e às ADRs. A hierarquia:

ADR: registra por que uma decisão foi tomada (contexto, alternativas, consequências)
Requisito funcional: especifica o comportamento esperado de cada feature
PLAN.md: agrega as decisões e o contexto em visão de projeto
TASKS.md: decompõe os requisitos em tarefas implementáveis no sprint atual

O DoD (Definition of Done) do projeto deve incluir: "TASKS.md atualizado" e "Requisito correspondente atualizado se o comportamento mudou." Sem isso, a documentação vai divergir do código — e a IA vai trabalhar com contexto errado.

Toda a abordagem se apoia nos princípios da arquitetura SPEC-driven: documentação como código, versionada, revisada, parte do processo.

Conclusão: contexto estruturado é multiplicador de produtividade

A IA programadora é uma ferramenta poderosa com um limite claro: ela só é boa quanto o contexto que recebe. PLAN.md e TASKS.md não são burocracia — são o investimento de 2 horas no começo do sprint que economiza 10 horas de retrabalho ao longo dele.

Times que implementam essa prática relatam redução de 40–60% nas iterações necessárias para chegar a código aprovável em revisão. A IA para de "adivinhar" e começa a trabalhar com o mesmo contexto que o desenvolvedor humano tem. O resultado é código mais consistente, mais alinhado com a arquitetura, e que precisa de muito menos correção manual.