java-clean-code

java-clean-code

Clean Code principles, applied to Java by Claude Code — every time you write or review.

20 rules · 12 references · 10 before/after pairs (35 Java files)

---

Quickstart (60 seconds)

git clone https://github.com/nxd1184/java-clean-code-skill.git
cd java-clean-code-skill && ./install.sh

Then in Claude Code:

"Review UserService.java with the java-clean-code skill."

That's it. Claude loads the 20-rule checklist and reviews your file with rule-cited fixes.

---

Contents

• Why this exists
• Quick demo: before / after
• How it works — the 20 rules
• Install
• How to invoke
• Examples gallery
• Repo layout
• Contributing & TDD discipline
• Troubleshooting
• FAQ
• Credits
• License

---

Why this exists

Clean code reads like well-written prose. — Clean Code, Ch. 1

Clean code principles work best applied inline while you're writing or reviewing, not looked up afterwards. This skill packages 20 high-ROI rules into a checklist Claude Code applies on demand — covering naming, function shape, SOLID, TDD, concurrency, and clean architecture.

You get:

• A fast 20-rule checklist (loaded in <500 words on every invocation).
• 12 topic references (naming.md, functions.md, solid.md, …) loaded on demand for depth.
• 10 before/after Java pairs (35 files) grounded in Spring Boot 3, plain Java, and pure domain logic.
• A TDD-discipline harness: every skill change starts with a failing pressure scenario and ends with a verified GREEN run.

---

Quick demo

Drop this OrderService into Claude Code with the skill loaded:

@Service
public class OrderService {
    @Autowired
    private OrderRepository repo;
    @Autowired
    private PaymentClient paymentClient;

    public void processOrder(Long orderId, boolean isExpedited,
                             boolean sendEmail, boolean auditLog,
                             String notes) {
        Order o = repo.findById(orderId).get();
        if (o.getCustomer().getAddress().getCountry().equals("US")) {
            paymentClient.charge(
                o.getCustomer().getPaymentMethod().getCard(),
                o.getTotal());
            if (isExpedited) { /* ... 30 more lines ... */ }
        }
    }
}

Then ask:

"Review this with the java-clean-code skill."

Claude responds with rule-cited fixes (excerpt):

DIP violation (@Autowired field) at line 3 — switch to constructor injection.

Args + Flags (5 args, 3 booleans) at line 8 — extract a record parameter object.

Demeter trainwreck at line 13 — o.getCustomer().getAddress()... chains through 4 objects. Move the country check onto Order as shipsToUS().

Hidden side effect / CQS at line 14 — processOrder both validates and charges. Split into validateOrder (query) and chargeOrder (command).

Then it produces the after:

@Service
public class OrderService {
    private final OrderRepository repo;
    private final PaymentClient paymentClient;
    private final OrderValidator validator;

    public OrderService(OrderRepository repo,
                        PaymentClient paymentClient,
                        OrderValidator validator) {
        this.repo = repo;
        this.paymentClient = paymentClient;
        this.validator = validator;
    }

    public void chargeOrder(OrderId id, ShipmentSpeed speed) {
        Order order = repo.findById(id);
        validator.requireShippable(order);
        paymentClient.charge(order.payment(), order.total());
    }
}

No re-reading docs. No "did I follow SOLID?" guesswork. Just rule-cited diffs.

---

How it works — the 20 rules

The skill loads a compact 20-rule checklist (under 500 words) on every invocation. Each rule links to a topic reference for depth.