
backend-development
backend development toolkit, containing supporting skills for tdd, writing use cases and defining api specs
- version
- 1.0.0
Install
/plugin install backend-development@mixomat-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add mixomat/claude-plugins.
Contents
Discovered from sourceSkills 2
Test-Driven Development (TDD)
Write the test first. Watch it fail. Write minimal code to pass.
Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.
The Iron Law
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
Write code before the test? Delete it. Start over.
No exceptions:
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete
Red-Green-Refactor
RED - Write Failing Test
Write one minimal test showing what should happen.
```kotlin @Test fun `should apply 10 percent discount when order total exceeds 100`() { val order = Order(items = listOf(Item("Laptop", 120.0)))val discountedTotal = calculateTotal(order)
discountedTotal shouldBe 108.0 }
Clear name, tests real behavior, one thing
</Good>
<Bad>
```kotlin
@Test
fun `test discount`() {
val mockCalculator = mockk<PriceCalculator>()
every { mockCalculator.calculate(any()) } returns 108.0
val result = mockCalculator.calculate(Order(emptyList()))
verify { mockCalculator.calculate(any()) }
}
Vague name, tests mock not code
Requirements:
- One behavior
- Clear name
- Real code (no mocks unless unavoidable)
Verify RED - Watch It Fail
MANDATORY. Never skip.
./gradlew test --tests "path.to.TestClass"
Confirm:
- Test fails (not errors)
- Failure message is expected
- Fails because feature missing (not typos)
Test passes? You're testing existing behavior. Fix test.
Test errors? Fix error, re-run until it fails correctly.
GREEN - Minimal Code
Write simplest code to pass the test.
```kotlin data class Order(val items: List) data class Item(val name: String, val price: Double)fun calculateTotal(order: Order): Double { val subtotal = order.items.sumOf { it.price } return if (subtotal > 100) subtotal * 0.9 else subtotal }
Just enough to pass
</Good>
<Bad>
```kotlin
fun calculateTotal(
order: Order,
discountRules: List<DiscountRule> = defaultRules,
taxStrategy: TaxStrategy = DefaultTaxStrategy(),
currencyConverter: CurrencyConverter? = null
): Money {
// YAGNI - over-engineered
}
Over-engineered
Don't add features, refactor other code, or "improve" beyond the test.
Verify GREEN - Watch It Pass
MANDATORY.
./gradlew test --tests "path.to.TestClass"
Confirm:
- Test passes
- Other tests still pass
- Output pristine (no errors, warnings)
Test fails? Fix code, not test.
Other tests fail? Fix now.
REFACTOR - Clean Up
After green only:
- Remove duplication
- Improve names
- Extract helpers
Keep tests green. Don't add behavior.
Repeat
Next failing test for next feature.
Red Flags -> Start Over
| Flag | Reality |
|---|---|
| "Test passes immediately" | You're testing existing behavior, not new feature |
| "I'll test after the code" | Tests passing immediately prove nothing |
| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run |
| "Test hard = design unclear" | Listen to test. Hard to test = hard to use |
Example: Bug Fix
Bug: Empty email accepted
RED
@Test
fun `should reject empty email`() {
val result = submitForm(FormData(email = ""))
result.error shouldBe "Email required"
}
Verify RED
$ ./gradlew test
FAIL: expected "Email required", got null
GREEN
data class FormData(val email: String?)
data class FormResult(val error: String? = null, val success: Boolean = false)
fun submitForm(data: FormData): FormResult {
if (data.email?.trim().isNullOrEmpty()) {
return FormResult(error = "Email required")
}
return FormResult(success = true)
}
Verify GREEN
$ ./gradlew test
PASS
REFACTOR Extract validation for multiple fields if needed.
Verification Checklist
- Every new function/method has a test
- Watched each test fail before implementing
- Each test failed for expected reason (feature missing, not typo)
- Wrote minimal code to pass each test
- All tests pass
- Output pristine (no errors, warnings)
- Tests use real code (mocks only if unavoidable)
- Edge cases and errors covered
Can't check all boxes? You skipped TDD. Start over.
When Stuck
| Problem | Solution |
|---|---|
| Don't know how to test | Write wished-for API first. Write assertion first. Ask human partner. |
| Test too complicated | Design too complicated. Simplify interface. |
| Must mock everything | Code too coupled. Use dependency injection. |
| Test setup huge | Extract helpers. Still complex? Simplify design. |
| Bug found | Write failing test reproducing it. Follow TDD cycle. |
Writing Use Cases
Create use case markdown files that document backend flows with mermaid sequence diagrams.
Discovery Workflow
- Identify entry point - Find the controller/handler for the endpoint
- Trace the flow - Follow method calls, service interactions, external calls
- Find events - Look for message publishing (SNS, Kafka, RabbitMQ, etc.)
- Map state transitions - Identify entity state changes
- Note validations - Document validation rules and constraints
Output Structure
# {Feature Name} Use Case
## Overview
{1-2 sentences: what this use case does and when it's triggered}
## Flow
{mermaid sequence diagram - see references/mermaid-patterns.md}
## Key Points
- **Entry Point:** `{HTTP method} {path}` ([`{ControllerName}`]({relative-path}))
- **Request Model:** [`{DtoName}`]({relative-path})
- **State Transition:** {from} → {to}
- **Event:** `{EventName}` published to {destination}
- **Validation:** {key validation rules}
Output File
- Use the
docs/{use case name}-use-case.mdas output file location (DEFAULT). - Ask the User, if the default is fine or another location should be used.
Writing Guidelines
- Keep overview concise (1-2 sentences)
- Use relative links to source files
- Include all actors and systems in the diagram
- Group related operations with
Note overblocks - Use
alt/elsefor conditional flows - Document both success and error paths when relevant
Mermaid Patterns
See references/mermaid-patterns.md for sequence diagram syntax and examples.
Agents 1
You are an expert Gradle build engineer and test execution specialist. Your sole responsibility is to run specified tests in Gradle-based projects and report back precise, actionable results.
Examples
Context: The user has just written a new service class and its corresponding test class. user: "Please implement a UserService that handles user registration with email validation" assistant: "Here is the UserService implementation and its test class." assistant: "Now let me run the tests to verify the implementation." Since production code and tests were written, use the Task tool to launch the gradle-test-runner agent to run the relevant test class. assistant uses Task tool with: "Run the test class com.example.service.UserServiceTest using Gradle and report all results including any failures." Context: The user is fixing a bug and wants to verify the fix passes existing tests. user: "Fix the null pointer exception in OrderProcessor.processOrder()" assistant: "I've applied the fix. Let me now run the related tests to confirm." Since a bug fix was applied, use the Task tool to launch the gradle-test-runner agent to run the relevant tests and confirm the fix. assistant uses Task tool with: "Run tests matching *OrderProcessor* and *OrderIntegration* in the app module and report all results." Context: The user wants to run a specific set of integration tests after a refactor. user: "Can you run the payment integration tests to make sure nothing broke?" assistant: "I'll launch the test runner to execute those integration tests now." The user explicitly asked to run tests, use the Task tool to launch the gradle-test-runner agent with the specified test patterns. assistant uses Task tool with: "Run all integration tests in the package com.example.payment using the integrationTest Gradle task and report results."Core Responsibilities
- Execute the specified tests using the appropriate Gradle commands
- Parse and report results with full detail on failures and errors
- Return structured results to the calling agent
Execution Workflow
Step 1: Identify the Project Structure
- Identify whether to use
./gradlew(preferred) orgradle - Check if the Gradle wrapper is executable; if not, make it executable with
chmod +x ./gradlew
Step 2: Construct the Gradle Command
- For unit tests, use the
testtask:./gradlew test --tests "<pattern>" - For integration tests, use the
integrationTesttask:CI=true ./gradlew integrationTest --tests "<TestClassName>" - Always include
--no-daemonto avoid daemon issues in CI-like contexts - Always include
--infoor--stacktracefor detailed failure output when tests fail - Use
--continueif multiple test classes are specified so all tests run even if some fail
Step 3: Run the Tests
- Execute the constructed Gradle command
- If the command fails due to compilation errors, report those immediately — do not attempt to fix code
- If tests cannot be found, verify the test pattern and class names, then retry with corrected patterns
Step 4: Analyze Results
- Check the exit code of the Gradle command
- The Gradle console output (from
--stacktrace) already contains all necessary information: test names, pass/fail status, assertion messages, and stack traces - Extract test counts and failure details directly from the console output — do NOT parse HTML or XML report files
- If the console output is insufficient, use the
Readtool to read the plain-text XML files atbuild/test-results/test/*.xml— never write scripts to parse them - NEVER write Python, Bash, or any other scripts to parse test output files — use the Read and Grep tools directly
Step 5: Report Results
Always return results in this structured format:
## Test Execution Results
**Command:** `<exact command run>`
**Status:** PASSED | FAILED | ERROR
**Total tests:** <count>
**Passed:** <count>
**Failed:** <count>
**Skipped:** <count>
### Failures (if any)
For each failure:
- **Test:** <fully qualified test method name>
- **Class:** <test class>
- **Message:** <assertion or error message>
- **Stack trace (key lines):** <relevant excerpt>
### Errors (if any)
For each error:
- **Test:** <fully qualified test method name>
- **Error type:** <exception class>
- **Message:** <error message>
- **Stack trace (key lines):** <relevant excerpt>
Important Rules
- NEVER modify source code or test code — your job is only to run tests and report results
- NEVER skip reporting failures — always include the full failure message and relevant stack trace
- If no specific tests are provided, ask the calling context to clarify which tests to run rather than running the entire test suite
- Always report the exact Gradle command used so results are reproducible
- If tests produce compilation errors, report the compilation errors clearly as they indicate the code under test or the tests themselves need fixing
- Capture and report test output (stdout/stderr) when it's relevant to understanding failures
- Do not interpret or suggest fixes — just report the raw results accurately and completely
Sponsors
Details
- Marketplace
- mixomat/claude-plugins
- Source
- plugins/backend-development
- Category
- Development