🌍 Languages: English | Tiếng Việt | Português | Español | Русский
🎥 Watch the PUDO Code System overview video
You open your editor. You type a vague request to your AI assistant. It generates something. You paste it in. It half-works. You ask for a fix. It breaks something else. Repeat for 3 hours.
This is chaos coding. It feels productive, but it's not.
The issue isn't the AI — it's the lack of structure. Without a clear methodology, AI-assisted development becomes a random walk through your codebase.
PUDO is an AI Agent Operating Layer for configuring coding agents across Cursor, Claude, Codex, GitHub Copilot, and Gemini/Antigravity: installable rules, measurable quality gates, token-budgeted prompts, workflow templates, and benchmark evidence for real codebases.
Recent research on configuring agentic coding tools identifies repository-level context files as the dominant mechanism and notes AGENTS.md emerging as an interoperable standard across tools, while advanced mechanisms such as Skills and Subagents remain less adopted. PUDO starts from that repo-level layer and adds executable checks, quality gates, handoff, and measurement. (arXiv:2602.14690)
| Phase | Goal | You Do | AI Does |
|---|---|---|---|
| (P) Plan | Define what and why | Set scope, constraints, success criteria | Draft implementation plan, identify risks |
| (U) Understand | Know where and how | Point to relevant code, explain context | Analyze codebase, map dependencies, find patterns |
| (D) Develop | Build it | Review, approve, test | Write code, run tests, track progress |
| (O) Optimize | Make it better | Validate improvements, merge | Refactor, benchmark, document changes |
Key insight: PUDO is a cycle, not a pipeline. You revisit phases as you learn more. A discovery in Develop might send you back to Plan. That's expected.
Use the init command to generate agent rules, PR templates, quality checklists, and a PUDO session handoff file in a real repository:
npx pudo-code-system initNon-interactive setup:
npx pudo-code-system init --yes --tools=cursor,claude,codex,copilot --project=nextjs --strictness=standardGenerated files can include AGENTS.md, CLAUDE.md, .cursor/rules/pudo-core.mdc, .github/copilot-instructions.md, .github/pull_request_template.md, .pudo/config.json, and .pudo/session.md.
Executable workflow:
npx pudo-code-system check
npx pudo-code-system score
npx pudo-code-system doctor| Path | Best For | Setup |
|---|---|---|
| Solo dev | Small projects, personal repos, fast iteration | npx pudo-code-system init --strictness=lite |
| Team lead | Shared PR review, handoff, medium features | npx pudo-code-system init --strictness=standard --tools=cursor,claude,codex,copilot |
| Enterprise / security | Production, compliance, migrations, sensitive data | npx pudo-code-system init --strictness=enterprise plus Release Gate |
Use the smallest mode that safely fits the task. See PUDO Modes for the full guide.
| Mode | Use For | Process |
|---|---|---|
| PUDO Lite | Small fixes, scripts, tasks under 30 minutes | Three checks: scope, relevant files, verification |
| PUDO Standard | Medium features, real bugs, focused refactors | Full Plan -> Understand -> Develop -> Optimize |
| PUDO Enterprise | Team, production, security, compliance | Full PUDO plus owner, rollback, monitoring, migration, risk log |
Each phase ends with a gate. Do not move forward until the gate passes, or until the risk is explicitly accepted.
| Gate | Run Before | Must Prove |
|---|---|---|
| Plan Gate | Understand | Scope, success criteria, constraints, and out-of-scope items are clear |
| Understand Gate | Develop | Relevant files, architecture, APIs, and patterns were verified |
| Develop Gate | Optimize | Implementation stays in scope, has tests, and handles key edge cases |
| Optimize Gate | Release | Refactors preserve behavior; performance, security, docs, and risks were reviewed |
| Release Gate | Merge/deploy | Changelog, migration, rollback, monitoring, and owner approval are handled |
Start with Quality Gates, use the QC checklists, review AI-generated changes with AI Output Review, enforce Anti-Hallucination Rules, manage context with Token Budget Rules, engineer context with Context Engineering, and pull failure modes from the general edge case catalogue.
These numbers are practical directional estimates, not guarantees. The gains depend on task size, repo quality, and how consistently the team actually follows PUDO.
| Task Type | Token Waste Reduction | Dev Time Reduction |
|---|---|---|
| One-line fix / small script | 0-8% | -5% to +5% |
| Small/medium feature | 25-38% | 12-20% |
| Hard bug / production issue | 22-35% | 10-18% |
| Multi-file feature / tests / team handoff | 35-48% | 18-28% |
| Practical average claim | 34% | 18% |
Measure your own results with the Benchmark Kit. Track tokens, AI turns, failed attempts, unnecessary file reads, time to verified implementation, bugs found after AI output, and PR review comments. See the sample measured case in benchmarks/results/stripe-webhook-2026-05.
Before writing any code, define what you're building:
I need to build [FEATURE].
The success criteria are [CRITERIA].
The constraints are [CONSTRAINTS].
Create an implementation plan before writing any code.
Research before you build:
Before implementing, analyze the existing codebase:
- What patterns are already established?
- What dependencies are involved?
- What could break?
Build with structure:
Implement the plan. Track progress with a task checklist.
Write tests alongside the implementation.
Flag any deviations from the plan.
Don't ship the first draft:
Review the implementation:
- Are there performance improvements?
- Is the code consistent with existing patterns?
- Write a walkthrough summarizing what changed and why.
Every task, every feature, every bug fix. Plan → Understand → Develop → Optimize.
See PUDO applied to real-world scenarios:
| # | Scenario | Complexity | Key Takeaway |
|---|---|---|---|
| 01 | Building a landing page | Beginner | How Plan prevents scope creep |
| 02 | Stripe API integration | Intermediate | How Understand saves debugging time |
| 03 | Fixing a production bug | Advanced | How the full cycle prevents regressions |
| 04 | Quality gate failure case | Intermediate | How a failed gate prevents bad releases |
| 05 | Before/after token waste | Intermediate | How source grounding reduces wasted AI turns |
PUDO includes files that can be installed into real projects, not only read as methodology docs:
| Area | Files |
|---|---|
| CLI | bin/pudo.js, package.json |
| Project state | .pudo/config.json, .pudo/session.md, .pudo/checklists/release.md |
| GitHub workflow | .github/pull_request_template.md, .github/ISSUE_TEMPLATE/, .github/workflows/pudo-check.yml |
| Stack templates | templates/ |
| Measurement | benchmarks/ |
| Context engineering | docs/context-engineering.md, docs/agent-skill-contract.md |
| Release tracking | CHANGELOG.md |
| Roadmap | ROADMAP.md |
PUDO ships with a ready-to-use prompt library — 21 prompts across 4 phases and domain skills that you can copy-paste into any AI assistant. Each phase directory includes a detailed README.md explaining how to modify and extend the prompts for your team's needs.
| Phase | Prompts |
|---|---|
| (P) Plan | Scope Definition · Architecture Draft · Risk Assessment · Database Schema · API Contract · Security Threat Model |
| (U) Understand | Codebase Analysis · Dependency Audit · Pattern Recognition · Crash Log Analysis |
| (D) Develop | Feature Implementation · Test-Driven Dev · Component Scaffold · Integration Test Suite · E2E Test Suite |
| (O) Optimize | Performance Review · Code Review Checklist · Refactor Opportunities · Memory Profiling · Network Troubleshooting |
| Skills | Architecture & Planning · Software Engineering · Troubleshooting & Debugging · DevOps Engineering · Test Engineering |
| DevOps Tools | GitHub Actions · GitLab CI · Argo CD · Jenkins · Terraform · Docker · Kubernetes |
PUDO is designed to be the default operating system for AI coding agents. Prefer the current config format for each tool, while keeping legacy files where they still help older workspaces.
| Tool | Current Files | Recommended Setup | Status |
|---|---|---|---|
| Codex | AGENTS.md, codex/AGENTS.md | Keep root AGENTS.md; copy codex/AGENTS.md into target repos that need a fuller Codex template |
OK |
| Claude Code / Projects | CLAUDE.md, claude/CLAUDE.md, .claude/settings.json | Use root CLAUDE.md as the bridge; keep detailed Claude workflow in claude/CLAUDE.md |
Updated |
| Cursor | Project Rules, legacy .cursorrules | Prefer .cursor/rules/*.mdc; keep .cursorrules for legacy Cursor versions |
Migrated |
| GitHub Copilot | .github/copilot-instructions.md, .github/instructions/ | Use repo-wide instructions plus path-specific .instructions.md files |
Added |
| OpenCode | opencode/opencode.md | Add to OpenCode system prompts or workspace instructions | OK |
| Antigravity / Gemini-style | antigravity/instructions.xml | Copy to .gemini/antigravity/instructions.xml in the target workspace |
OK |
| Kiro | kiro/system-prompt.md | Set as the Kiro system prompt | OK |
PUDO isn't just a checklist — it's a mindset. Read the full philosophy to understand the principles behind the method.
TL;DR:
- Anti-chaos — Structure beats improvisation at scale
- Iterative — It's a cycle, not a waterfall
- AI-native — Designed for human+AI pair programming
- Phase integrity — Each phase has clear entry and exit criteria
PUDO may be overkill for one-line fixes, throwaway prototypes, pure exploration, and non-critical scripts. Use the full cycle when correctness, maintainability, security, or team handoff matters.
- PUDO does not guarantee AI output is correct.
- Human review is still required.
- Security-sensitive changes still need dedicated security review.
- Examples are illustrative, not universal.
- The method requires discipline; skipping gates turns it back into ad hoc prompting.
- Developers using AI assistants (ChatGPT, Claude, Gemini, Copilot, etc.) who want better results
- Team leads looking for a shared methodology for AI-assisted development
- Students learning to code with AI the right way from day one
PUDO grows with the community. See CONTRIBUTING.md for how to:
- Add new prompts to the library
- Submit real-world example walkthroughs
- Improve the documentation
If you find PUDO helpful, consider supporting the project:
<iframe src="https://github.com/sponsors/DongDuong2001/button" title="Sponsor DongDuong2001" height="32" width="114" style="border: 0; border-radius: 6px;"></iframe>MIT — Use it, fork it, make it yours.
Stop vibing. Start PUDO-ing.
Plan → Understand → Develop → Optimize
