🔁 Method PDCA-T — AI Coding Quality Framework

🎯 What Does Method PDCA-T Do?

🚀 Quick Start

Install — 3 options

npm install -g @exchanet/enet
enet install pdca-t

npm install -g github:exchanet/enet
enet install pdca-t

📖 The Method Explained

Why PDCA-T Works

🔄 The Complete 8-Phase Cycle

PHASE 1: PLANNING
│ → Clear objective · exact scope · questions resolved · success criteria
│
PHASE 2: REQUIREMENTS ANALYSIS
│ → Functional requirements · Non-functional requirements · Risks
│
PHASE 3: ARCHITECTURE DESIGN ★ NEW
│ → ADRs · Interface contracts · Module structure
│
PHASE 4: MICRO-TASK CYCLE (for each task ≤ 50 lines)
│ ┌────────────────────────────────────────────────┐
│ │ 4.1 Check available skills and context │
│ │ 4.2 Write tests FIRST (strict TDD) │
│ │ 4.3 Implement code (≤ 50 lines) │
│ │ 4.4 Self-review checklist │
│ │ 4.5 Execute tests — show REAL results │
│ │ 4.6 If coverage < 99% → refine and repeat │
│ └────────────────────────────────────────────────┘
│
PHASE 5: INTEGRAL VALIDATION WITH METRICS
│ → Security · Tests · Code quality · Performance · Architecture
│
PHASE 6: TECHNICAL DEBT MANAGEMENT ★ NEW
│ → Register · Prioritize · Plan
│
PHASE 7: REFINEMENT TO ≥ 99%
│ → Identify → Fix → Verify → Confirm
│
PHASE 8: DELIVERY WITH FULL REPORT
│ → Summary · Tests · Decisions · CI/CD checklist · Next steps

📋 Phase Detail

Phase 1: Planning

Questions to answer before proceeding:
 What exactly should this code do?
 Who will use it and in what context?
 What is explicitly OUT of scope?
 What already exists that can be reused?
 What is the acceptance criterion?

Phase 2: Requirements Analysis

Functional Requirements (FR):
 FR-01: Calculate VAT at 21% on base price
 FR-02: Handle prices with up to 4 decimals
 FR-03: Return error if price is negative
Non-Functional Requirements (NFR):
 NFR-01: Response time < 100ms for single calculations
 NFR-02: Decimal precision using Decimal, not float
 NFR-03: Thread-safe for concurrent use
Risk Register:
 RISK-01: Float rounding errors → Mitigation: use Decimal
 RISK-02: Overflow with large prices → Mitigation: validate limits

Phase 3: Architecture Design ★ NEW

## ADR-001: Decimal precision library
- Context: Financial calculations require exact precision
- Decision: Use native Python decimal.Decimal
- Alternatives: float (rejected — imprecision), mpmath (overkill)
- Consequences: More verbose, but correct

def calculate_vat(
 base_price: Decimal,
 vat_rate: Decimal = Decimal("0.21"),
 currency: str = "EUR"
) -> VATResult:
 """
 Calculate VAT on a base price.

 Args:
 base_price: Pre-tax price (must be > 0)
 vat_rate: VAT rate as decimal (0.21 = 21%)
 currency: ISO currency code

 Returns:
 VATResult with base, vat_amount and total

 Raises:
 ValueError: If base_price <= 0
 ValueError: If vat_rate not in [0, 1]
 """
 ...

src/
├── domain/ # Pure business logic (no external deps)
│ ├── models.py
│ └── services.py
├── infrastructure/ # External adapters (DB, APIs, etc.)
└── interfaces/ # Controllers, CLI, API endpoints
tests/
├── unit/ # Tests with no I/O
├── integration/ # Tests with real infrastructure
└── e2e/ # End-to-end flow tests

Phase 4: Micro-Task Cycle

4.2 — Write Tests FIRST (Mandatory TDD)

# tests/unit/test_vat_calculator.py
class TestCalculateVAT:
 # HAPPY PATH
 def test_standard_vat_calculation(self):
 result = calculate_vat(Decimal("100.00"))
 assert result.base == Decimal("100.00")
 assert result.vat_amount == Decimal("21.00")
 assert result.total == Decimal("121.00")
 # ERROR CASES
 def test_negative_price_raises_error(self):
 with pytest.raises(ValueError, match="base_price must be positive"):
 calculate_vat(Decimal("-10.00"))
 def test_invalid_vat_rate_raises_error(self):
 with pytest.raises(ValueError, match="vat_rate must be between 0 and 1"):
 calculate_vat(Decimal("100.00"), vat_rate=Decimal("1.5"))
 # EDGE CASES
 def test_minimum_valid_price(self):
 result = calculate_vat(Decimal("0.0001"))
 assert result.base == Decimal("0.0001")
 def test_zero_vat_rate(self):
 result = calculate_vat(Decimal("100.00"), vat_rate=Decimal("0"))
 assert result.vat_amount == Decimal("0")
 # SECURITY
 def test_type_validation_rejects_float(self):
 with pytest.raises(TypeError):
 calculate_vat(10.0) # float not accepted
 # PERFORMANCE
 def test_bulk_calculation_performance(self, benchmark):
 prices = [Decimal(str(i)) for i in range(1, 10001)]
 benchmark(lambda: [calculate_vat(p) for p in prices])

4.3 — Implement the Code (≤ 50 lines)

# src/domain/services.py
from decimal import Decimal
from dataclasses import dataclass
@dataclass(frozen=True)
class VATResult:
 base: Decimal
 vat_amount: Decimal
 total: Decimal
 currency: str
def calculate_vat(
 base_price: Decimal,
 vat_rate: Decimal = Decimal("0.21"),
 currency: str = "EUR"
) -> VATResult:
 if not isinstance(base_price, Decimal):
 raise TypeError("base_price must be Decimal, not float")
 if base_price <= Decimal("0"):
 raise ValueError("base_price must be positive")
 if not Decimal("0") <= vat_rate <= Decimal("1"):
 raise ValueError("vat_rate must be between 0 and 1")
 vat_amount = base_price * vat_rate
 return VATResult(
 base=base_price,
 vat_amount=vat_amount,
 total=base_price + vat_amount,
 currency=currency
 )

4.4 — Self-Review Checklist

CODE QUALITY:
 □しろいしかく Complete type hints on all functions?
 □しろいしかく Docstring explaining the contract?
 □しろいしかく Single responsibility per function?
 □しろいしかく Semantic names (no a, b, x)?
 □しろいしかく No unnecessary code duplication?
SECURITY:
 □しろいしかく ALL inputs validated?
 □しろいしかく Outputs sanitized before display?
 □しろいしかく No hardcoded credentials?
 □しろいしかく Safe types used (Decimal instead of float for money)?
MAINTAINABILITY:
 □しろいしかく Can another dev understand this in 2 minutes?
 □しろいしかく Consistent abstraction level?
 □しろいしかく Errors logged appropriately?

4.5 — Execute Tests and Show Results

$ pytest tests/unit/test_vat_calculator.py -v --cov=src --cov-report=term-missing
tests/unit/test_vat_calculator.py::TestCalculateVAT::test_standard_vat_calculation PASSED
tests/unit/test_vat_calculator.py::TestCalculateVAT::test_negative_price_raises_error PASSED
tests/unit/test_vat_calculator.py::TestCalculateVAT::test_invalid_vat_rate_raises_error PASSED
tests/unit/test_vat_calculator.py::TestCalculateVAT::test_minimum_valid_price PASSED
tests/unit/test_vat_calculator.py::TestCalculateVAT::test_zero_vat_rate PASSED
tests/unit/test_vat_calculator.py::TestCalculateVAT::test_type_validation_rejects_float PASSED
tests/unit/test_vat_calculator.py::TestCalculateVAT::test_bulk_calculation_performance PASSED
Name Stmts Miss Cover
-------------------------------------------
src/domain/services.py 14 0 100%
-------------------------------------------
TOTAL 14 0 100%
7 passed in 0.43s

Phase 5: Integral Validation with Metrics

Phase 6: Technical Debt Management ★ NEW

## DEBT-001
- Type: Technical (code)
- Description: calculate_vat does not support multi-currency conversion
- Impact: Medium — works correctly for single currency
- Estimated effort: 2 hours
- Priority: Low — not blocking for v1.0
- Plan: Implement in v1.1 with exchange rate service

Phase 7: Refinement to ≥ 99%

If any metric does not reach 99%:
1. IDENTIFY — What specifically is below 99%?
2. CLASSIFY — High / Medium / Low priority
3. PLAN — What action will fix the problem?
4. EXECUTE — Implement the correction
5. VERIFY — Re-run all tests
6. CONFIRM — ≥ 99% now? If not → back to step 1
⚠ Never advance to delivery without confirming ≥ 99%.

Phase 8: Delivery with Full Report

# Delivery Report — [Feature Name]
Date: YYYY-MM-DD
Implemented by: [AI Agent + human reviewer]
Version: X.Y.Z
## Implementation Summary
[2-3 sentences describing what was implemented and how]
## Test Report
| Category | Result |
|---------------|-----------|
| Total tests | XX |
| Passed | XX (100%) |
| Failed | 0 |
| Coverage | ≥ 99% |
| Total time | X.XXs |
## Full pytest Output
[Paste real pytest output here]
## Key Technical Decisions
1. [Decision]: [Brief justification]
2. [Decision]: [Brief justification]
## Technical Debt Registered
- DEBT-001: [description] — Priority: Low
## CI/CD Checklist
 □しろいしかく Tests pass in pipeline
 □しろいしかく Linting without errors
 □しろいしかく Type checking without errors
 □しろいしかく Security scan without critical vulnerabilities
## Suggested Next Steps
1. [What comes next in the backlog]
2. [Dependencies this unlocks]

🔒 Absolute Rules (Non-Negotiable)

RULE 1 — Tests are mandatory
 ✗ "Tests will be added later"
 ✓ Tests written BEFORE implementation code
RULE 2 — Show real results
 ✗ "Tests should pass"
 ✓ Real pytest output with exact numbers
RULE 3 — Security first
 ✗ Hardcode secrets "for now"
 ✓ Environment variables / vault from the first commit
RULE 4 — Coverage ≥ 99% or no delivery
 ✗ Deliver with 85% coverage and "almost complete"
 ✓ Iterate until ≥ 99% before marking as delivered
RULE 5 — Document decisions
 ✗ "The code is self-explanatory"
 ✓ ADRs for non-trivial decisions, docstrings for everything public
RULE 6 — Register debt ★ NEW
 ✗ Ignore known problems "for later"
 ✓ Register in DEBT-XXX format with priority and plan

🤖 Multi-Agent Support ★ NEW

🛠️ Recommended CI/CD Configuration ★ NEW

# .github/workflows/quality.yml
name: PDCA-T Quality Gate
on: [push, pull_request]
jobs:
 quality:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Setup Python
 uses: actions/setup-python@v5
 with:
 python-version: "3.11"
 - name: Install dependencies
 run: pip install -r requirements.txt
 - name: Lint (ruff)
 run: ruff check src/ tests/
 - name: Type check (mypy)
 run: mypy src/
 - name: Security scan (bandit)
 run: bandit -r src/ -ll
 - name: Tests with coverage gate
 run: |
 pytest tests/ \
 --cov=src \
 --cov-fail-under=99 \
 --cov-report=xml \
 -v

 - name: Upload coverage
 uses: codecov/codecov-action@v4

📁 Repository Structure

method_pdca-t/
├── METHOD.md ← Full method documentation
├── README.md ← This file (English)
├── README_ES.md ← Spanish version
│
├── adapters/
│ ├── cursor.md ← Cursor
│ ├── windsurf.md ← Windsurf
│ ├── copilot.md ← GitHub Copilot
│ ├── claudecode.md ← Claude Code
│ ├── claudeai.md ← Claude.ai
│ ├── openai.md ← ChatGPT / GPT-4o
│ ├── aider.md ← Aider
│ └── generic.md ← Any other agent
│
├── .cursor/
│ ├── rules/
│ │ └── METHOD-PDCA-T.md ← Cursor auto-activation rule
│ └── skills/
│ └── method-pdca-t/
│ └── SKILL.md
│
├── templates/
│ ├── delivery-report.md ← Delivery report template
│ ├── adr-template.md ← Architecture decision record
│ └── debt-register.md ← Technical debt register
│
├── examples/
│ ├── tax-calculator/ ← Full worked example
│ └── rest-api/ ← REST API example
│
├── docs/
│ ├── INSTALLATION.md
│ └── USAGE.md
│
├── .github/
│ └── workflows/
│ └── quality.yml ← CI/CD pipeline
│
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE

📊 Quality Targets at a Glance

🆚 What Changed in v3.0

📖 Related Methods

🌐 Read in Spanish

🤝 Contributing

📄 License

👤 Author