pudo-code-system
A portable operating layer for reliable AI-assisted development.
π Languages: English | TiαΊΏng Viα»t | PortuguΓͺs | EspaΓ±ol | Π ΡΡΡΠΊΠΈΠΉ
Table of Contents
- The Problem
- The Solution: PUDO
- The MCP Server
- The 4 Phases
- Architecture Overview
- Install Into a Project
- Quick Start
- PUDO Modes
- Quality Gates
- Examples
- Prompt Library
- AI Integrations
- Repository Structure
- Measurement Targets
- Philosophy
- Onboarding Paths
- When Not To Use PUDO
- Contributing
- Support & Funding
- License
The Problem
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.
The Solution: PUDO
PUDO is an AI Agent Operating Layer that installs into any repository. It gives you:
- Installable agent rules for Cursor, Claude, Codex, Copilot, Gemini, OpenCode, and Kiro
- Measurable quality gates to prevent shipping unverified AI output
- Token-budgeted prompts that get better results from every AI assistant
- Workflow templates for every task size, from a 5-minute fix to a multi-week feature
- Benchmark evidence to measure whether the method is actually working
PUDO is not a new AI model. Itβs the operating layer that makes your existing AI tools more reliable.
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. PUDO starts from that repo-level layer and adds executable checks, quality gates, handoff, and measurement. (arXiv:2602.14690)
The MCP Server
The PUDO MCP server turns the operating layer into tools that compatible coding agents can call directly. Instead of relying on an agent to remember documentation, the agent calls PUDO tools to generate rules, validate output, run quality gates, and maintain session continuity.
| MCP Tool | What It Gives The Agent |
|---|---|
pudo.generateAgentRules |
Project-specific agent instructions |
pudo.validateAgentRules |
Validation of installed workflow files |
pudo.createContextPack |
Repository-bounded context without sensitive or generated paths |
pudo.runQualityGate |
Evidence checks before advancing or releasing |
pudo.scoreRepoReadiness |
Machine-readable readiness scoring |
pudo.doctor |
Workflow and policy gap diagnosis |
pudo.initProject |
Approval-gated project initialization |
pudo.updateSessionHandoff |
Approval-gated continuity between sessions |
The alpha server uses local stdio, restricts reads to one configured repository root, requires explicit approval for writes, and exposes no shell or network execution.
# Via npx (no install needed)
npx @dongduong2001/mcp-server@alpha
# Or install globally
npm install -g @dongduong2001/mcp-server@alpha
pudo-mcp-server
See PUDO MCP Server, Agent Tool Security, and the MCP Security Checklist.
The 4 Phases
| 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 and by design.
Architecture Overview
PUDO has three product surfaces that work together:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Your Repository β
β β
β βββββββββββββββββββ ββββββββββββββββββββ β
β β Agent Config β β Quality Layer β β
β β β β β β
β β AGENTS.md β β quality-gates β β
β β CLAUDE.md β β qc-checklists β β
β β GEMINI.md β β anti-hallucin. β β
β β .cursor/rules β β token-budget β β
β β copilot-inst. β β ai-output-rev. β β
β ββββββββββ¬βββββββββ ββββββββββ¬ββββββββββ β
β β β β
β βΌ βΌ β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β CLI (npx pudo-code-system) β β
β β β β
β β init Β· check Β· score Β· score --strict Β· doctor β β
β ββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββ β
β β β
βββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Server (stdio, local, sandboxed) β
β β
β generateAgentRules Β· createContextPack β
β runQualityGate Β· scoreRepoReadiness β
β initProject Β· updateSessionHandoff β
β validateAgentRules Β· doctor β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββ
β AI Coding Agents β
β β
β Cursor Claude Codex Copilot β
β Gemini OpenCode Kiro β
ββββββββββββββββββββββββββββββββββββββββββββββ
Agent Config files tell every AI assistant how to behave in your repo. Quality Layer provides checklists, gates, and anti-patterns to validate AI output. CLI gives you executable workflow commands that produce machine-readable results. MCP Server exposes all of the above as callable tools for compatible agents.
Install Into a Project
Use the init command to generate agent rules, PR templates, quality checklists, and a session handoff file in any repository:
npx pudo-code-system init
Non-interactive setup:
npx pudo-code-system init \
--yes \
--tools=cursor,claude,codex,copilot,gemini,opencode,kiro \
--project=nextjs \
--strictness=standard
Generated files include: AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/pudo-core.mdc, .github/copilot-instructions.md, opencode/opencode.md, kiro/system-prompt.md, .github/pull_request_template.md, .pudo/config.json, and .pudo/session.md.
Executable workflow commands:
npx pudo-code-system check # validate installed config files
npx pudo-code-system score # score repo readiness (0-100)
npx pudo-code-system score --json # machine-readable JSON output
npx pudo-code-system score --strict # fail if score is below threshold
npx pudo-code-system doctor # diagnose workflow gaps
score evaluates instruction specificity, context quality, workflow evidence, AI/MCP safety, tests, CI, benchmarks, and release traceability. Its JSON output follows schemas/pudo-score.schema.json.
Quick Start
1. Plan
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.
2. Understand
Research before you build:
Before implementing, analyze the existing codebase:
- What patterns are already established?
- What dependencies are involved?
- What could break?
3. Develop
Build with structure:
Implement the plan. Track progress with a task checklist.
Write tests alongside the implementation.
Flag any deviations from the plan.
4. Optimize
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.
5. Repeat
Every task, every feature, every bug fix β Plan β Understand β Develop β Optimize.
PUDO Modes
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 |
Quality Gates
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 reviewed |
| Release Gate | Merge/deploy | Changelog, migration, rollback, monitoring, and owner approval handled |
See Quality Gates, QC Checklists, AI Output Review, Anti-Hallucination Rules, Token Budget Rules, Context Engineering, and the Edge Case Catalogue.
Examples
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 |
Prompt Library
PUDO ships with 21 ready-to-use prompts across 4 phases. Copy-paste into any AI assistant. Each phase folder includes a README.md explaining how to extend the prompts for your team.
| 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 |
AI Integrations
PUDO is designed to be the default operating layer for AI coding agents, working across all major tools.
| Tool | Current Files | Recommended Setup | Status |
|---|---|---|---|
| Codex | AGENTS.md, codex/AGENTS.md | Keep root AGENTS.md; copy codex/AGENTS.md for 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 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 |
| Gemini | GEMINI.md, antigravity/instructions.xml | Use GEMINI.md as the instruction bridge; keep Antigravity XML for Gemini-style workspaces |
CLI generated |
| OpenCode | opencode/opencode.md | Add to OpenCode system prompts or workspace instructions | CLI generated |
| Kiro | kiro/system-prompt.md | Set as the Kiro system prompt | CLI generated |
Repository Structure
pudo-code-system/
βββ AGENTS.md # Shared agent rules (Codex, cross-tool)
βββ CLAUDE.md # Claude Code memory bridge
βββ GEMINI.md # Gemini agent instructions
β
βββ docs/ # Documentation
β βββ README.md # Documentation index
β βββ philosophy.md # Why PUDO exists and its design principles
β βββ workflow.md # Deep-dive into each phase
β βββ pudo-modes.md # Lite / Standard / Enterprise guide
β βββ getting-started.md # First steps for new users
β βββ architecture.md # System diagram and component overview
β βββ context-engineering.md # How to bound AI context effectively
β βββ mcp.md # MCP server setup and usage
β βββ agent-skill-contract.md # Agent capability contracts
β βββ team-adoption-guide.md # Multi-phase team rollout guide
β βββ faq.md # Frequently asked questions
β
βββ prompts/ # 21 ready-to-use AI prompts
β βββ plan/ # Scoping, architecture, risk
β βββ understand/ # Codebase analysis, patterns
β βββ develop/ # Implementation, testing
β βββ optimize/ # Performance, review, refactor
β
βββ skills/ # Domain-specific PUDO variants
β βββ plan/ # Architecture & planning
β βββ code/ # Software engineering
β βββ debug/ # Troubleshooting
β βββ devops/ # CI/CD, infra tools
β βββ test/ # Test engineering
β βββ frontend/ # Frontend patterns
β βββ backend/ # Backend patterns
β βββ mobile/ # Mobile development
β
βββ quality/ # Quality enforcement
β βββ quality-gates.md # Phase gate checklists
β βββ qc-checklists.md # Product, eng, security checklists
β βββ ai-output-review.md # Reviewing AI-generated code
β βββ anti-hallucination.md # Preventing AI errors
β βββ token-budget.md # Context window management
β βββ mcp-security-checklist.md
β βββ agent-tool-security.md
β βββ edge-cases/ # Edge case catalogue
β
βββ examples/ # Real-world PUDO walkthroughs
β βββ 01-landing-page/
β βββ 02-api-integration/
β βββ 03-debug-production/
β βββ 04-quality-gate-failure/
β βββ 05-before-after-token-waste/
β
βββ templates/ # Stack-specific project scaffolds
β βββ nextjs/
β βββ react-vite/
β βββ node-express/
β βββ python-fastapi/
β βββ ...
β
βββ benchmarks/ # Measurement framework
β βββ README.md # How to benchmark
β βββ metrics-sheet.csv # Template for recording results
β βββ token-waste-calculator.md
β βββ results/ # Measured case studies
β
βββ schemas/ # JSON schemas for machine-readable output
β βββ pudo-score.schema.json
β βββ pudo-metrics.schema.json
β βββ pudo-run-trace.schema.json
β
βββ packages/
β βββ pudo-mcp-server/ # MCP server (TypeScript)
β βββ src/server.ts
β βββ tools/ # 8 callable MCP tools
β βββ tests/
β
βββ bin/
β βββ pudo.js # CLI entry point
β
βββ .pudo/ # PUDO operating-kit state
β βββ config.json
β βββ session.md # Session handoff file
β βββ checklists/
β
βββ .github/
β βββ workflows/ # CI: CLI install test, PUDO check
β βββ ISSUE_TEMPLATE/ # Bug report, feature request
β βββ pull_request_template.md
β βββ CODEOWNERS
β
βββ cursor/, claude/, codex/, # Tool-specific config dirs
kiro/, opencode/, antigravity/
Measurement Targets
These numbers are directional targets to validate with your own benchmark data, not proven PUDO-wide guarantees. Current public evidence is one measured case study β do not cite this table as a benchmark claim until you have your own data. Gains depend on task size, repo quality, and how consistently you follow PUDO.
| Task Type | Token Waste Reduction Target | Dev Time Reduction Target |
|---|---|---|
| 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% |
| Measurement target for mature usage | 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.
Philosophy
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
Onboarding Paths
| 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,gemini,opencode,kiro |
| Enterprise / security | Production, compliance, migrations, sensitive data | npx pudo-code-system init --strictness=enterprise plus Release Gate |
See Team Adoption Guide for a multi-phase team rollout plan.
When Not To Use PUDO
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.
Current Limitations
- 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.
Who Is This For?
- 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
Contributing
PUDO grows with the community. See CONTRIBUTING.md for how to add prompts, submit walkthroughs, improve docs, and report issues.
Questions? Open a Discussion or check SUPPORT.md.
Support & Funding
If you find PUDO helpful, consider supporting the project:
License
MIT β Use it, fork it, make it yours.
Stop vibing. Start PUDO-ing.
Plan β Understand β Develop β Optimize