Skip to main content

Demo Block — Developer / Team Pain

Introduction​

Context: A known tech debt item is attached to the Execute Payment service in Workbench: payment flows still contain legacy logic implemented outside the Payment Service, leading to potential inconsistencies in transaction rollbacks and error handling. To address this, an architectural decision was made that every payment method must be implemented in the Payment Service using an adapter pattern. This decision was made by the architect, documented outside any system the developer touches (Confluence, email, ...), and the developer working on the new requirement has never seen it.

Related trial experience: From Prompt to Design-Aware AI

Demo persona: Developer in a team — someone else made a decision they never knew about, but using Workbench, their code was correct anyway.

Show case: The next ticket — "Add gift card as a supported payment method" — needs to be implemented in the Payment Service.

ℹ️Preparation for this block

Clone the Payment (PAYMNT) service to your local machine, clean up code from preceding demos, check out the required branch, and open both your IDE and the Workbench. See Preparation and Clean-up. Set your AI coding assistant to appropriate settings for a smooth demo flow, e.g, "Advanced mode" with "Auto-approve" for IBM Bob.

Demo​

This block runs the same prompt twice — once against a version of the service with no design attached, once against the version with Workbench's design and skills in place — so the audience sees the difference directly.

ℹ️Short on time?

If the audience is already sold on the problem, or time is tight, you can skip straight to "With Workbench" and only show the second run. The first run exists to make the pain concrete; it's not required to make the point.

Now I'd like to show how Workbench supports developers by making architectural decisions available to the coding assistant — even if the developer doesn't know about it. We start directly in the developer's IDE, where the Payment Service has already been checked out. There's a new requirement, enhancing the Payment Service with another payment method. I'll use an AI coding assistant to generate the code.

Run 1 — Without Workbench​

  1. Open the PAYMNT service in your IDE and check out the no-src-design branch (no design, no ADR, no skills — only the already implemented code).
  2. Open the chat window and prompt: Add gift card as a supported payment option.
  3. Watch what happens in src/main/java/k5/paymnt — additional implementation code is generated there.
  4. Review the generated/changed files, especially src/main/java/k5/paymnt/services/ExecutePaymentService.java. Point out that gift card payment follows the same pattern as the existing payment methods — increasing tech debt, since it doesn't follow the adapter pattern decided by the architect.
  5. Explain: the coding assistant could only take into account what it had access to. The code is correct, implements the right feature, and compiles. But the pain surfaces later — when a payment fails mid-checkout and the transaction handler in a different service only rolls back registered adapters, not the gift card payment.
💡Reset before continuing

To undo the generated code and prepare for Run 2:

git clean -fd
git restore .

Run 2 — With Workbench​

Let's see what happens when we generate code with Workbench, where architecture, design, and all relevant context is available to the coding assistant.

  1. Go back to your IDE and check out the main branch (or a demo branch based on main) of the PAYMNT service.
  2. Repeat the prompt in a new chat window: k5-generate Add gift card as a supported payment option.
  3. Optionally allow the coding assistant to execute all commands without asking again, so you can explain the relevant ADR in Workbench while it runs.

Let's jump to Workbench to look at the design of the Payment Service and the architectural decisions we'd like to see reflected in the code.

  1. Open the Payment Service in Workbench (main or the demo branch). Go to Diagrams and select the Payment Domain diagram.

  2. Point to the Execute Payment domain service and show the relationship to the REST operation Redeem Giftcard.

    Here we see the domain service shall call the Gift Card Service to perform payments with gift cards.

  3. Point to the Technical Debt item ("Legacy logic outside Payment Service") connected to the domain service.

  4. Select Execute Payment, open the Loop tab, and open the linked ADR "Payment Providers" in a new tab. Show the relevant paragraph:

    All payment method implementations live exclusively in the Payment Service and are implemented as adapters conforming to a shared IPaymentAdapter interface. Upstream services call the Payment Service to execute payment — they never implement payment logic directly.

    Explain: someone else made this decision, documented it at the right place — the developer never saw it before.

Now let's see what the AI coding assistant did so far.

  1. Go back to your IDE. Point out that the coding assistant first checks whether all accepted ADRs are adhered to and corrects the code if not.
  2. Look at the changed implementation, e.g. src/main/java/k5/paymnt/services/ExecutePaymentService.java. Show that the code now follows the architectural decision to use an IPaymentAdapter.

Although I, as the developer, didn't know about this architectural decision, the coding assistant followed it — without me prompting for it explicitly. That was only possible because all relevant design and architecture was made available through Workbench. Using Workbench ensures that all relevant decisions and other context information is available to the coding assistant, so it's considered in the generated code.

Next: Enterprise Pain

Standards defined once by experts, inherited automatically by every new service.

Last updated on