Load the rules for this repository
Use the supplied root AGENTS.md for the pinned JHipster application and a thin adapter such as CLAUDE.md when the selected agent requires it.
Meridian Engineering / Lab 3 / 120 minutes
Specify and verify
balance consistency.
JHipster’s sample can store an account operation without changing the account balance. Both records can be edited independently.
Work against the pinned JHipster repository from first trace to final review. Turn what its React, Java, database and test sources establish into a specification, a tested build and a decision you can defend.
Learning outcomes
Shared intuitionCommon languageEveryday habits
Work lifecycle
DefinePlanExecuteJudgeLearn
- Source
- Official JHipster sample
- Working surface
- Java + React/TypeScript
- Runtime
- Local H2 · no vendor account
POST /api/operationsRecords diverge
Debit operation / account 42
The endpoint saves the operation but leaves the balance unchanged.
Operation
amount = -25.00 · 201 CreatedBalance
100.00 · unchangedServer today
operationRepository.save(operation)The response confirms that the operation was saved. It does not prove balance consistency.
01 / The course premise
Use evidence
at every stage.
OutcomesAll threeLifecycleDefine → Learn
Participants learn how repository evidence becomes intent, how intent becomes testable expectations and how those expectations govern planning, execution and review.
Course rule Participants create the artifact at each stage. That artifact supplies evidence or decisions required by the next stage.
Before Stage 1 / Repository prerequisites
Make the repository’s
starting state visible.
Common languagePrepare
Begin from the same JHipster revision, repository instructions and recorded session profile. This setup stays outside the 120-minute instructional clock.
Create a reproducible baseline
Record the repository root, revision, branch and working tree alongside the visible session, memory, model, tools and permissions. Identify how each item was established.
Commission the current stage
Give the agent the pinned repository, accepted prior artifact, allowed actions, evidence expectations, success criteria and stopping conditions for this stage.
02 / Course map
Map the lab to both
course dimensions.
The outcome dimension states what participants carry into their work. The lifecycle dimension shows where they practice it.
Recognize where AI can help, where it can fail and when its output needs verification.
Explain intent, evidence, limits and decisions in terms that teammates can review.
Carry context, specifications, evidence and review into routine engineering work.
StageLearning outcomesWork lifecycle
01 / Derive context
Shared intuitionCommon language
Define
02 / Write a specification
Common languageEveryday habits
Define
03 / Write test specifications
Shared intuitionCommon languageEveryday habits
Define
04 / Audit the specifications
Shared intuitionCommon languageEveryday habits
Define
05 / Plan from the specifications
Common languageEveryday habits
Plan
06 / Execute from the specifications
Shared intuitionEveryday habits
Execute
07 / Review the build
Shared intuitionCommon languageEveryday habits
JudgeLearn
08 / What we learned
Shared intuitionCommon languageEveryday habits
Learn
03 / Why this repository fits
Study one transaction
across the application.
Shared intuitionCommon languageDefine
The sample is large enough to require context judgment. One operation journey crosses the front end, API, domain, database and three test levels.
Find the business gap
React, Redux, DTOs, mappers, resources, entities, repositories, schema and tests all participate. Participants must decide which sources explain balance behavior.
Define what posting means
Participants name the rules for signs, precision, ownership, insufficient funds, atomicity, retries and changes to posted operations.
State the evidence first
Tests must show the operation and balance change together, or remain unchanged together, while the React UI reports the server result.
04 / The learning sequence
Work from context
through review.
All outcomesDefine → Learn
Each activity begins with its purpose and ends with a test for readiness. The facilitator manages time and the gates. Participants do the work.
StagePurpose, work and evidence
OutcomeShared intuitionCommon languageLifecycleDefine
Derive context
Trace an operation from the React form through Redux and HTTP, the Java DTO and mapper, the REST resource, both repositories, the account relationship, Liquibase and the existing tests. Separate sources on that journey from unrelated generated infrastructure.
Why this step: The issue names a balance symptom. The repository shows two records that can be edited independently, along with transaction boundaries, authorization behavior and tests that verify CRUD behavior instead of balance consistency.
You produceContext brief with facts, source links, exclusions, assumptions and open questions.
Ready to continue whenA second pair can explain why an operation can be stored while its account balance stays unchanged.
Open the stage guideOutcomeCommon languageEveryday habitsLifecycleDefine
Write a specification
Define credit and debit semantics, amount precision, insufficient-funds behavior, account ownership, atomicity, retry expectations and what update or deletion means after posting. Describe observable behavior before choosing code.
Why this step: “Update the balance” leaves critical decisions unstated. A coding agent could apply an operation twice, permit an overdraft or preserve CRUD paths that later invalidate the balance.
You produceChange specification with claims, acceptance examples, exclusions and unresolved decisions.
Ready to continue whenThe specification addresses create, retry, overdraw, cross-account access, update, patch, delete and failure cases.
Open the stage guideOutcomeShared intuitionCommon languageEveryday habitsLifecycleDefine
Write test specifications
Define evidence for each claim through Java integration tests, React tests and one end-to-end journey. Observe both the operation and the account balance before and after success and failure.
Why this step: A saved operation and a changed balance form one business outcome. A test that observes only one record cannot establish consistency.
You produceTest specification that maps every claim to a stimulus, observation, expected result and covered risk.
Ready to continue whenThe proposed tests could reveal partial writes, double application, overdrafts, unauthorized posting and a misleading UI result.
Open the stage guideOutcomeShared intuitionCommon languageEveryday habitsLifecycleDefine
Audit the specifications
Exchange the context brief and specifications with another pair. Challenge sign conventions, rounding, ownership, transaction claims, concurrent requests, operation mutability and conclusions that exceed what H2 can support.
Why this step: Independent review exposes contradictions before they enter the code. It also separates evidence from the lab profile from claims about production databases.
You produceAudit record with the finding, impact, disposition, rationale and owner.
Ready to continue whenEvery material finding is resolved, accepted as a limitation or escalated.
Open the stage guideOutcomeCommon languageEveryday habitsLifecyclePlan
Plan from the specifications
Map each accepted claim to the smallest required Java, React, schema and test changes in the pinned source. Write the tests before the behavior and identify discoveries that must return to the specification.
Why this step: The plan makes scope visible and prevents a framework-wide rewrite. It also reveals whether the specification can be implemented during the lab.
You produceImplementation plan linked to claim and test-specification identifiers.
Ready to continue whenEvery planned edit supports an accepted claim. The plan excludes unrelated generated infrastructure and administration code with stated reasons.
Open the stage guideOutcomeShared intuitionEveryday habitsLifecycleExecute
Execute from the specifications
Give the coding agent the audited specifications and plan. Inspect each change, run focused back-end and front-end tests, and record deviations, discoveries and command results.
Why this step: The specifications set the boundaries for the agent. When the team finds a new fact, it updates the specification instead of allowing that fact to become unreviewed product behavior.
You produceScoped code and tests, command evidence and a deviation log.
Ready to continue whenFocused checks pass, success and failure leave consistent state, and every deviation has a disposition.
Open the stage guideOutcomeShared intuitionCommon languageEveryday habitsLifecycleJudgeLearn
Review the build
Compare the specification with the code, the specification with the tests, and the tests with the code. Inspect transaction placement, repository observations, UI state, untested CRUD paths and the limits of H2 evidence.
Why this step: Passing checks establish only what those checks observed. A person must decide whether the implementation and evidence support a decision to accept, revise or stop.
You produceAcceptance decision with a claim-to-test-to-code trace, results, limitations and owners.
Ready to continue whenThe decision addresses every material claim and does not extend local evidence to untested production conditions.
Open the stage guideOutcomeShared intuitionCommon languageEveryday habitsLifecycleLearn
What we learned
Synthesize the seven-stage evidence chain, explain what each course goal now means in practice and choose the next real repository where you will use the method.
Why this step: A completed exercise is not yet a transferable habit. The closing section turns the JHipster experience into a reusable operating model for agent-assisted delivery.
You produceA three-goal synthesis and one concrete commitment to apply the method at work.
Ready to continue whenYou can explain the method without the stage prompts and name where, when and with what evidence you will use it next.
Open the stage guide120 working minutes45 min specifications15 min peer audit40 min plan and build20 min individual reviewClosing synthesis
05 / What we provide
Start with the issue
and repository.
Shared intuitionDefine
The course supplies material an engineer could receive at work. Participants create the supporting artifacts during the lab.
Shared intuition / Define
Issue card
“Posting an operation must leave its bank account balance consistent. Failed or rejected requests must change neither record. Define and prove the remaining behavior.”
Shared intuition / Define
Pinned repository
JHipster’s official React sample at commit 8c9d248, with its generated structure and Apache 2.0 license retained.
Everyday habits / Define
Runnable baseline
H2 seed data and existing Java integration, Vitest and Cypress tests. The course supplies readiness commands, without solution tests or prepared specifications.
06 / What participants create
Create six records
for review.
Common languageEveryday habitsDefine → Learn
Six short records make the reasoning open to review. Teams can keep them in Markdown, a pull request, Jira or the Workbench.
01
Shared intuitionCommon languageDefine
Context brief
Shows what exists and how the team knows.
Facts · sources · assumptions · questions02
Common languageEveryday habitsDefine
Change specification
States what must become true.
Behavior · boundaries · acceptance · exclusions03
Shared intuitionCommon languageDefine
Test specification
States how the team will challenge each claim.
Example · level · expected result · covered risk04
Shared intuitionEveryday habitsDefine
Audit record
Records what independent review found.
Finding · impact · disposition · owner05
Common languageEveryday habitsPlan
Plan
Turns accepted intent into a scoped change.
Files · seams · sequence · tests · rollback06
Shared intuitionCommon languageEveryday habitsJudgeLearn
Build review
States whether the result is acceptable.
Specification ↔ test ↔ code · results · limits · decisionWorkbench role The Workbench can store, route or automate these records after participants understand their purpose. Participants can apply the same records through tools they already use.
07 / Review the build
Compare specifications,
tests and code.
Shared intuitionEveryday habitsJudgeLearn
Each comparison can fail even when the build passes. Reviewers must state what the evidence proves and where it stops.
Shared intuition / Judge
Specification ↔ code
Do transaction, amount, ownership and immutability rules appear at the correct boundaries without unrelated changes to generated code?
Common language / Judge
Specification ↔ tests
Does the evidence observe operation and balance state after success, rejection, retry and failure at the required test levels?
Everyday habits / Learn
Tests ↔ code
Could mocks or automatic rollback make the tests pass while a real request still permits a partial or repeated update?
08 / Assessment
Test whether participants
can apply the method.
All outcomesJudgeLearn
We assess the work participants create and the decision they make. Confidence ratings provide a secondary measure.
0
Followed Completes a step but cannot connect it to a source or decision.
1
Explained Connects the artifact to evidence and identifies a limitation.
2
Transferred Applies the method to new work and defends the trade-off.
09 / Progression to Lab 4
Apply the method
with less support.
Everyday habitsLearn
Lab 3 makes the reasoning visible. Lab 4 gives teams a different consistency boundary and asks them to rebuild and automate the method.
Lab 3 / Guided independenceCurrent
All outcomesDefine → Learn
Trust the Balance
One official full-stack sample, one consistency problem and seven participant-led stages.
- Issue card and readiness gates supplied
- Specifications and plan created by pairs
- Final decision made individually
Lab 4 / Independent transferNext
Everyday habitsLearn
Trust the Retry
Apply the method to repeated delivery, then automate one recurring evidence check.
- No prepared prompt, specification, tests or plan
- Peer audit before execution
- Independent review and work adoption plan
10 / Delivery
Reserve lab time
for participant work.
Everyday habitsDefine → Learn
Pin and test the course branch, cache Maven dependencies, run a readiness check and provide a browser workspace fallback.
Use one page for all eight sections. Demonstrate one context trace, then give the work to participants. Move environment failures to a separate support channel.
Return feedback on the artifact chain and sample one use at work. Report skill transfer separately from Workbench adoption.
Three outcomes / Five lifecycle stages
Use evidence to guide the change
from context through review.
Shared intuitionCommon languageEveryday habitsDefine → Learn