Pragmatica

Java Backend Coding Technology

Version 1.8.0 | Full Changelog

A framework-agnostic methodology for writing predictable, testable Java backend code optimized for human-AI collaboration.

Why “Technology”?

In industrial manufacturing, technology is the structured method of producing goods with reliably consistent quality within reliably consistent time. It’s not just tools. It’s the engineered process that ensures stable output under defined conditions. Technology emphasizes predictability, repeatability, and control.

Traditional software development relies on “best practices.” These are subjective guidelines that often contradict each other, leaving developers to make judgment calls on every decision. Should this be a service or a helper? When is a class too complex? How should errors flow? These questions consume cognitive energy and produce inconsistent results across teams, projects, and even within the same codebase. It’s “art” more than engineering.

Java Backend Coding Technology transforms this into a technology. Less art, more engineering. It provides mechanical rules that eliminate subjective debates: unified code structure from functions to packages; clearly defined approaches to testing, logging, and interaction with external code; five objective criteria that replace “it depends” with measurable standards. The result is code that looks the same whether you wrote it, a colleague wrote it, or AI generated it. Predictable, testable, and optimized for both human and AI collaboration.

🚀 Quick Start

New to this technology? Start with the learning series:

  1. Series Index - Overview and navigation for the 6-part learning series
  2. Part 1: Foundations - Mental model and core ideas
  3. Part 2: Core Principles - Four return types, parse-don’t-validate, no business exceptions
  4. Part 3: Basic Patterns - Leaf, Condition, Iteration
  5. Part 4: Advanced Patterns - Sequencer, Fork-Join, Aspects, Testing basics
  6. Part 5: Testing Strategy - Evolutionary testing, integration-first approach, test organization
  7. Part 6: Production Systems - Complete use case walkthrough, project structure, framework integration

Need the complete reference? See CODING_GUIDE.md - comprehensive technical documentation with all patterns, principles, and examples.

📚 Documentation

For Developers

  • CODING_GUIDE.md - Complete technical reference (100+ pages)

    • Core concepts: Four Return Kinds, Parse-Don’t-Validate, No Business Exceptions
    • Pattern catalog: Leaf, Sequencer, Fork-Join, Condition, Iteration, Aspects
    • Evaluation framework: Five objective criteria for code decisions
    • Naming conventions, testing patterns, project structure
    • Complete use case walkthrough with Spring Boot and JOOQ integration

  • series/ - Progressive learning path (6 parts, ~25 pages each)

    • Part 5 covers comprehensive testing strategy
    • Designed for sequential reading
    • Builds concepts incrementally
    • Ideal for onboarding and teaching

For Managers & Decision Makers

  • MANAGEMENT_PERSPECTIVE.md - Business case for structural standardization
    • ROI of predictable code structure
    • Risk reduction through mechanical refactoring rules
    • Team velocity improvements with reduced subjective debates
    • Onboarding time reduction

Changelog & Versioning

🔧 For AI Collaboration

Claude Code Skill

skills/jbct/ - Comprehensive JBCT skill for Claude Code:

  • Design, implement, and review JBCT code
  • Progressive detalization: quick reference → detailed patterns → advanced topics
  • Covers Four Return Kinds, Parse Don’t Validate, all six structural patterns
  • Project structure, naming conventions, testing patterns
  • Installation: cp -r skills/jbct ~/.claude/skills/

Usage: Claude Code will automatically activate the skill when working with Result/Option/Promise types, value objects, use cases, or JBCT patterns.

Claude Code Subagents

Ready-to-use configurations for specialized code assistance:

  • jbct-coder.md - Code generation subagent

    • Generates JBCT-compliant code from requirements
    • Enforces Four Return Kinds, Parse Don’t Validate, structural patterns
    • Installation: Download and place in ~/.claude/agents/jbct-coder.md

  • jbct-reviewer.md - Code review subagent

    • Reviews code for JBCT compliance and best practices
    • Checks patterns, naming conventions, project structure
    • Provides actionable feedback with examples
    • Installation: Download and place in ~/.claude/agents/jbct-reviewer.md

Usage: After installation, Claude Code will automatically use these subagents when appropriate, or invoke explicitly: "Use jbct-coder to implement..." or "Use jbct-reviewer to check..."

📂 Repository Structure

coding-technology/
├── CODING_GUIDE.md              # Complete technical reference
├── series/                       # 6-part learning series
│   ├── INDEX.md                 # Series overview and navigation
│   ├── part-01-foundations.md
│   ├── part-02-core-principles.md
│   ├── part-03-basic-patterns.md
│   ├── part-04-advanced-patterns.md
│   ├── part-05-testing-strategy.md
│   └── part-06-production-systems.md
├── MANAGEMENT_PERSPECTIVE.md    # Business case and ROI
├── CHANGELOG.md                 # Version history
├── skills/                      # Claude Code skills
│   └── jbct/                    # JBCT skill
│       ├── SKILL.md             # Skill definition
│       └── README.md            # Installation instructions
├── jbct-coder.md                # Claude Code subagent: code generation
├── jbct-reviewer.md             # Claude Code subagent: code review
├── examples/                    # Java code examples
│   └── [Maven projects demonstrating patterns]
├── sources/                     # Research materials
│   ├── articles/               # Reference articles
│   ├── code/                   # Code snippets
│   └── patterns/               # Pattern documentation
├── templates/                   # Reusable templates
└── PL_IMPROVEMENTS.md          # Pragmatica Lite enhancement backlog

🤝 Contributing

This repository documents a methodology, not a software project. Contributions welcome:

  • Experience reports - How the technology worked in your project
  • Pattern discoveries - New patterns or refinements
  • Examples - Real-world use case implementations
  • Questions & discussions - Open issues for clarification

📖 Key Concepts at a Glance

Four Return Kinds: Every function returns exactly one:

  • T - Synchronous, cannot fail, always present
  • Option<T> - Synchronous, cannot fail, might be absent
  • Result<T> - Synchronous, can fail, present if success
  • Promise<T> - Asynchronous, can fail

Parse, Don’t Validate: Make invalid states unrepresentable. Validation is parsing - if construction succeeds, the object is valid.

No Business Exceptions: Business failures are expected outcomes, not exceptions. They flow through Result or Promise as typed Cause objects.

Six Patterns: All code fits one pattern:

  1. Leaf - Atomic operation (business logic or I/O adapter)
  2. Sequencer - Chain dependent steps (2-5 steps)
  3. Fork-Join - Parallel independent operations
  4. Condition - Branching as values
  5. Iteration - Functional combinators over collections
  6. Aspects - Cross-cutting concerns (retry, timeout, metrics)

Vertical Slicing: Each use case is self-contained. Business logic isolated per use case, not centralized.

  • Pragmatica Lite Core - The foundational library providing Option, Result, Promise, and functional utilities

Maven:

<dependency>
   <groupId>org.pragmatica-lite</groupId>
   <artifactId>core</artifactId>
   <version>0.8.3</version>
</dependency>

Gradle:

implementation 'org.pragmatica-lite:core:0.8.3'

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

You are free to:

  • Use this methodology in commercial and non-commercial projects
  • Modify and adapt the documentation and examples
  • Distribute and share the content
  • Create derivative works

Version: 1.8.0 | Last Updated: 2025-01-21 | Full Changelog

Copyright © 2025 Sergiy Yevtushenko. Released under the MIT License.