pudo-code-system
Uma metodologia estruturada de 4 fases para programar com assistentes de IA.
🌍 Idiomas: English | Tiếng Việt | Português | Español | Русский
🎥 Watch the PUDO Code System overview video
O Problema
Você abre seu editor. Você digita uma solicitação vaga para seu assistente de IA. Ele gera algo. Você cola. Funciona pela metade. Você pede uma correção. Quebra outra coisa. Repita por 3 horas.
Isso é a programação do caos. Parece produtivo, mas não é.
O problema não é a IA — é a falta de estrutura. Sem uma metodologia clara, o desenvolvimento assistido por IA se torna uma caminhada aleatória pela sua base de código.
A Solução: PUDO
PUDO oferece um ciclo repetível de 4 fases que transforma a IA de uma máquina caça-níqueis em uma ferramenta de precisão.
| Fase | Objetivo | Você Faz | IA Faz |
|---|---|---|---|
| (P) Plan (Planejar) | Definir o que e por quê | Definir escopo, restrições, critérios de sucesso | Elaborar plano de implementação, identificar riscos |
| (U) Understand (Entender) | Saber onde e como | Apontar para o código relevante, explicar o contexto | Analisar a base de código, mapear dependências, encontrar padrões |
| (D) Develop (Desenvolver) | Construir isso | Revisar, aprovar, testar | Escrever código, executar testes, acompanhar o progresso |
| (O) Optimize (Otimizar) | Tornar melhor | Validar melhorias, mesclar (merge) | Refatorar, benchmark, documentar alterações |
Conceito chave: PUDO é um ciclo, não um pipeline. Você revisita as fases à medida que aprende mais. Uma descoberta no Desenvolvimento pode enviá-lo de volta ao Planejamento. Isso é esperado.
Portões de Qualidade
Cada fase termina com um portão de controle. Não avance até que esse portão passe, ou até que o risco tenha sido explicitamente aceito.
| Portão | Executado antes de | Deve provar |
|---|---|---|
| Plan Gate | Understand | Escopo, critérios de sucesso, restrições e itens fora de escopo estão claros |
| Understand Gate | Develop | Os arquivos relevantes, a arquitetura, as APIs e os padrões foram verificados |
| Develop Gate | Optimize | A implementação permanece no escopo, tem testes e cobre os principais edge cases |
| Optimize Gate | Release | Refactors não mudam comportamento; desempenho, segurança, documentação e riscos foram revisados |
| Release Gate | Merge/deploy | Changelog, migração, rollback, monitoramento e aprovação do owner foram tratados |
Comece com Quality Gates, use os QC checklists, revise alterações geradas por IA com AI Output Review, e use failure modes do general edge case catalogue.
Impacto Esperado
Esses números são estimativas práticas e direcionais, não garantias. O ganho depende do tamanho da tarefa, da qualidade do repositório e de quão consistentemente a equipe realmente segue o PUDO.
| Tipo de tarefa | Redução de desperdício de tokens | Redução do tempo de desenvolvimento |
|---|---|---|
| Correção de uma linha / script pequeno | 0-8% | -5% a +5% |
| Feature pequena ou média | 25-38% | 12-20% |
| Bug difícil / incidente de produção | 22-35% | 10-18% |
| Feature com muitos arquivos / testes / handoff de equipe | 35-48% | 18-28% |
| Média prática para comunicar | 34% | 18% |
Início Rápido
1. Comece com o Planejamento (Plan)
Antes de escrever qualquer código, defina o que você está construindo:
Eu preciso construir [RECURSO].
Os critérios de sucesso são [CRITÉRIOS].
As restrições são [RESTRIÇÕES].
Crie um plano de implementação antes de escrever qualquer código.
2. Siga para o Entendimento (Understand)
Pesquise antes de construir:
Antes de implementar, analise a base de código existente:
- Quais padrões já estão estabelecidos?
- Quais dependências estão envolvidas?
- O que pode quebrar?
3. Execute no Desenvolvimento (Develop)
Construa com estrutura:
Implemente o plano. Acompanhe o progresso com uma lista de tarefas (checklist).
Escreva testes junto com a implementação.
Sinalize quaisquer desvios do plano.
4. Encerre com Otimização (Optimize)
Não envie o primeiro rascunho:
Revise a implementação:
- Há melhorias de desempenho?
- O código é consistente com os padrões existentes?
- Escreva um resumo (walkthrough) explicando o que mudou e por quê.
5. Repita
Para cada tarefa, cada recurso, cada correção de bug. Plan → Understand → Develop → Optimize.
Biblioteca de Prompts
O PUDO vem com uma biblioteca de prompts pronta para uso — 21 prompts distribuídos por 4 fases e habilidades de domínio que você pode copiar e colar em qualquer assistente de IA. Cada diretório de fase inclui um README.md detalhado explicando como modificar e estender os prompts para as necessidades da sua equipe.
| Fase | Prompts |
|---|---|
| (P) Plan | Definição de Escopo · Rascunho de Arquitetura · Avaliação de Risco · Esquema de Banco de Dados · Contrato de API · Modelo de Ameaça de Segurança |
| (U) Understand | Análise da Base de Código · Auditoria de Dependências · Reconhecimento de Padrões · Análise de Log de Falhas |
| (D) Develop | Implementação de Recurso · Test-Driven Dev (TDD) · Estrutura de Componente · Suite de Teste de Integração · Suite de Teste E2E |
| (O) Optimize | Revisão de Desempenho · Checklist de Revisão de Código · Oportunidades de Refatoração · Análise de Perfil de Memória · Solução de Problemas de Rede |
| Skills | Arquitetura e Planejamento · Engenharia de Software · Solução de Problemas e Depuração · Engenharia DevOps · Engenharia de Teste (Test) |
| Ferramentas DevOps | GitHub Actions · GitLab CI · Argo CD · Jenkins · Terraform · Docker · Kubernetes |
Integrações com IA
O PUDO foi projetado para ser o sistema operacional padrão dos agentes de programação com IA. Prefira o formato de configuração atual de cada ferramenta, mantendo arquivos legacy quando ainda forem úteis para workspaces antigos.
| Ferramenta | Arquivos atuais | Configuração recomendada | Status |
|---|---|---|---|
| Codex | AGENTS.md, codex/AGENTS.md | Mantenha AGENTS.md na raiz; copie codex/AGENTS.md para o repositório de destino quando precisar de um template Codex mais completo |
OK |
| Claude Code / Projects | CLAUDE.md, claude/CLAUDE.md, .claude/settings.json | Use CLAUDE.md na raiz como arquivo ponte; mantenha o fluxo detalhado do Claude em claude/CLAUDE.md |
Atualizado |
| Cursor | Project Rules, legacy .cursorrules | Prefira .cursor/rules/*.mdc; mantenha .cursorrules para versões antigas do Cursor |
Migrado |
| GitHub Copilot | .github/copilot-instructions.md, .github/instructions/ | Use instruções no nível do repositório junto com arquivos .instructions.md por caminho |
Adicionado |
| OpenCode | opencode/opencode.md | Adicione aos system prompts ou workspace instructions do OpenCode | OK |
| Antigravity / Gemini-style | antigravity/instructions.xml | Copie para .gemini/antigravity/instructions.xml no workspace de destino |
OK |
| Kiro | kiro/system-prompt.md | Defina como system prompt do Kiro | OK |
Filosofia
O PUDO não é apenas uma lista de verificação — é uma mentalidade. Leia a filosofia completa para entender os princípios por trás do método.
TL;DR:
- Anti-caos — A estrutura vence a improvisação em escala
- Iterativo — É um ciclo, não um modelo cascata (waterfall)
- Nativo para IA — Projetado para programação em par entre humanos e IA
- Integridade de fase — Cada fase possui critérios claros de entrada e saída
Quando Não Usar PUDO
PUDO pode ser excessivo para correções de uma linha, protótipos descartáveis, exploração pura ou scripts não críticos. Use o ciclo completo quando correção, manutenibilidade, segurança ou handoff em equipe forem importantes.
Limitações Atuais
- PUDO não garante que a saída da IA esteja correta.
- Revisão humana continua sendo obrigatória.
- Mudanças sensíveis de segurança ainda exigem revisão dedicada.
- Os exemplos são ilustrativos, não universais.
- O método exige disciplina; pular quality gates faz você voltar ao prompting ad hoc.
Para Quem É Isso?
- Desenvolvedores usando assistentes de IA (ChatGPT, Claude, Gemini, Copilot, etc.) que desejam resultados melhores
- Líderes de equipe em busca de uma metodologia compartilhada para desenvolvimento assistido por IA
- Estudantes aprendendo a programar com IA da maneira correta desde o primeiro dia
Contribuindo
O PUDO cresce com a comunidade. Veja CONTRIBUTING.md para saber como:
- Adicionar novos prompts à biblioteca
- Enviar tutoriais (walkthroughs) de cenários reais
- Melhorar a documentação
Apoio & Financiamento
Se você achar o PUDO útil, considere apoiar o projeto:
- GitHub Sponsors
- Patreon
- Ko-fi
- Buy Me a Coffee
- PayPal: dongduong840@gmail.com
Licença
MIT — Use, faça fork, torne isso seu.
Pare de improvisar. Comece a fazer PUDO.
Plan → Understand → Develop → Optimize