From 2cb8151b4bcbf0afc7764f7e67a425ca38f647a4 Mon Sep 17 00:00:00 2001 From: Jim Mochel Date: Fri, 6 Mar 2026 16:15:25 -0500 Subject: [PATCH] chore/removed unused rules --- .cursor/rules/000-execution-context.mdc | 22 -- .../rules/001-task-execution-overrides.mdc | 9 - .../rules/002-testing-first-principles.mdc | 17 - .cursor/rules/360-java-general-coding.md.txt | 354 ------------------ .cursor/rules/java-general-coding.mdc.txt | 96 ----- .cursor/rules/java-unit-test-coding.mdc.txt | 25 -- .cursor/rules/mdc-template.md | 112 ------ .cursor/rules/sdd-system.mdc | 79 ---- 8 files changed, 714 deletions(-) delete mode 100644 .cursor/rules/000-execution-context.mdc delete mode 100644 .cursor/rules/001-task-execution-overrides.mdc delete mode 100644 .cursor/rules/002-testing-first-principles.mdc delete mode 100644 .cursor/rules/360-java-general-coding.md.txt delete mode 100644 .cursor/rules/java-general-coding.mdc.txt delete mode 100644 .cursor/rules/java-unit-test-coding.mdc.txt delete mode 100644 .cursor/rules/mdc-template.md delete mode 100644 .cursor/rules/sdd-system.mdc diff --git a/.cursor/rules/000-execution-context.mdc b/.cursor/rules/000-execution-context.mdc deleted file mode 100644 index 6e8c1b4..0000000 --- a/.cursor/rules/000-execution-context.mdc +++ /dev/null @@ -1,22 +0,0 @@ ---- -alwaysApply: true ---- - -# Execution Context Rule - -- Always assume the project root is the working directory. -- When generating scripts or tasks, prefix commands with paths relative to the repo root (e.g., `./cmd/foo`, `./internal/...`). -- Do not hardcode `$HOME` paths; always use relative-to-root. -- When showing a `make` or `go` command, assume execution from the root: - - `make test` - - `go run ./cmd/myapp` - - `go generate ./...` -# Execution Context Rule - -- Always assume the project root is the working directory. -- When generating scripts or tasks, prefix commands with paths relative to the repo root (e.g., `./cmd/foo`, `./internal/...`). -- Do not hardcode `$HOME` paths; always use relative-to-root. -- When showing a `make` or `go` command, assume execution from the root: - - `make test` - - `go run ./cmd/myapp` - - `go generate ./...` diff --git a/.cursor/rules/001-task-execution-overrides.mdc b/.cursor/rules/001-task-execution-overrides.mdc deleted file mode 100644 index 369efa6..0000000 --- a/.cursor/rules/001-task-execution-overrides.mdc +++ /dev/null @@ -1,9 +0,0 @@ -# Task Execution Overrides (Project Rule) - -## When running `/task` on any item: -- If the task is a code/config change, **also create**: - - A **Unit Test sub-task** with file paths and test names. - - An **Integration Test sub-task** (or a short rationale if N/A). - - - diff --git a/.cursor/rules/002-testing-first-principles.mdc b/.cursor/rules/002-testing-first-principles.mdc deleted file mode 100644 index 01d3ebb..0000000 --- a/.cursor/rules/002-testing-first-principles.mdc +++ /dev/null @@ -1,17 +0,0 @@ -# Planning/Test Culture Overrides (Project Rule) - -## Global Planning Requirements -1) After “Set up development environment & framework”, the **next task MUST be**: - **“Set up the test framework & test environment”**. - - Pin test runner (e.g., `go test`), structure (`/internal/...`, `/pkg/...`), fixtures folder, golden files, and CI entrypoints. - -2) For **every task in the plan that produces code or config**, add two sibling tasks: - - **Unit Tests:** “Add/extend unit tests for ” - - **Integration Tests (if feasible):** “Add/extend integration tests for ” - - If integration testing is **not applicable**, add a sub-bullet: “State why integration test is not applicable and what observable we will monitor instead.” - -3) Keep tests **in the same PR** as the code unless explicitly labeled `[defer-tests]`. - -## Plan Formatting Rules -- Numbered tasks. Each code task is immediately followed by its test tasks. -- Each task includes: **Goal**, **Definition of Done**, **Artifacts**, **Owner(optional)**. diff --git a/.cursor/rules/360-java-general-coding.md.txt b/.cursor/rules/360-java-general-coding.md.txt deleted file mode 100644 index 272efdd..0000000 --- a/.cursor/rules/360-java-general-coding.md.txt +++ /dev/null @@ -1,354 +0,0 @@ ---- -globs: *.java -alwaysApply: false -title: Java General Coding Guidelines -description: General Java rules for this project -scope: project -tags: [java, guidelines, style] -priority: high ---- - -# Java Coding Guidelines - - -- Use .equals for object comparison -- Do not use Vector or Hashtable -- Use StringBuilder for composing strings -- Only use java.time package for times and dates -- Do not use Serializable -- Do not use Boolean or boolean in parameter lists -- Use Objects.equals(x,y) -- @Override -public int hashCode() { - return Objects.hash(id, name, email); -} --@Override -public String toString() { - return Objects.toString(name, "Unknown"); ? -} -- this.value = Objects.requireNonNull(value, "value is required"); -- Use Collections.emptyList() Instead of new ArrayList<>() for Defaults -- Replace null Checks with Collections.singletonList() -- Prefer EnumSet Over HashSet for Enums -- Create Unmodifiable Collections with One Line: List names = List.of("Alice", "Bob", "Charlie"); -- Iterate with forEachRemaining on Iterators -- Use Collectors.toUnmodifiableList() for Safe Streams: List names = users.stream() - .map(User::getName) - .collect(Collectors.toUnmodifiableList()); - -- to use double brace initialization - - List fruits = new ArrayList<>() {{ - add("Apple"); - add("Banana"); - add("Mango"); -}}; - -- Do not use assert keyword -- - -## Interfaces -- USe when Multiple Implementations Exist -- Use When injecting including multiple inmpls -- Use when You’re Writing a Library or SDK - - -## General Principles - -- Use "Effective Java 3rd Edition" as the primary coding guidelines -- Prefer immutability wherever possible. -- Apply SOLID principles but do not apply Interface Segregatioon - -## Naming Things - -- Use meaningful names (no abbreviations). Standard acronyms are used in the same case as they are defined (i.e.XML is all caps) -- Do not use the meaningless suffixes: Helper, Utils, Manager, Data, -- Use business domain nouns and verbs. A method should do something, and its name should say so -- - -## Handling No-Things (NULLs etc) - -- Do not initialize variables to null -- Do not return nulls, return Optional or empty collections instead -- Option1: Return Optional for Explicit Absence -- Option2: Don’t use Optional In DTOs or method parameters (especially in performance-critical code). -- Option3: Return a Default or Empty Object (The Null Object Pattern) -- Option4: Java 21 using pattern matching and sealed classes -```java -// Using sealed classes and pattern matching (Java 21+) -public sealed interface UserResult permits ValidUser, InvalidUser {} -record ValidUser(String name, String email) implements UserResult {} -record InvalidUser(String reason) implements UserResult {} - -public String processUserModern(UserResult result) { - return switch (result) { - case ValidUser(var name, var email) -> name + " - " + email; - case InvalidUser(var reason) -> "Invalid: " + reason; - }; -} -``` - -Performance: -- Traditional null checking: 45.2 ns/op -- Optional-based approach: 38.7 ns/op (14% faster) -- Pattern matching: 29.3 ns/op (35% faster) - -```plaintext -Traditional Approach: -┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ -│ Controller │───▶│ Service │───▶│ Repository │ -│ │ │ │ │ │ -│ if (user != null)│ │ if (result != null)│ │ if (data != null)│ -│ process() │ │ validate() │ │ return data │ -│ else throw... │ │ else return null │ │ else return null│ -└─────────────────┘ └──────────────────┘ └─────────────────┘ - │ - ▼ - Null propagation creates - defensive programming everywhere - -Modern Approach: -┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ -│ Controller │───▶│ Service │───▶│ Repository │ -│ │ │ │ │ │ -│ Optional │ │ Result │ │ Optional │ -│ .map(process) │ │ .flatMap(valid) │ │ .orElse(empty) │ -│ .orElseThrow() │ │ .recover(error) │ │ │ -└─────────────────┘ └──────────────────┘ └─────────────────┘ - │ - ▼ - Type-safe error handling - with explicit control flow -``` - - -## Javadoc Comments - -- Comments Explain “Why”, Not “What” -- - -## Contructors and creating objects - -- Use static factory methods when - - You need a descriptive name. - - You want to validate/invariant-check before creation. - - You want to return a cached, shared, or flyweight instance. - - You want to control or hide the concrete type. - - You need subtype selection. - - You want to vary the returned object per input or environment. - - You want better type inference or generic helpers. - - You want singletons or scoped lifecycles. - - You want expressive conversions. - - You need API stability across versions. - - You’re wrapping records. -- Use constructors when - - You want the simplest, most discoverable API for “just build the thing.” -- Use builders when faced with many constructor parameters -- Enforce the singleton property with a private constructor or an enum type -- -## Enumerations - -- Use enumerations instead of constants for ....???? -- Frameworks/reflection require a no-arg or visible constructor. -- You explicitly support subclassing by users. -- You want constructor method references. -- You don’t need any of the flexibility above. - -## Value Objects - -## Exceptions - -## Try Catch - -- Use try with resources - -## Streams - -- Use filter() Before map() to Avoid Nulls -- Use peek() for Debugging (But Don’t Leave It In) -- - -## Instantiate Generics - - - -## Sorting Lists involving nulls - -```java -list.sort(Comparator.nullsFirst(Comparator.naturalOrder())); -// or -list.sort(Comparator.nullsLast(Comparator.naturalOrder())); -``` - -## When to use loop labels - -Use them only when they significantly simplify nested loop logic — and alternatives would be uglier or introduce artificial flags. - -Typical valid uses: - -1. **Early exit from nested loops** — e.g., searching a 2D array or grid: - -```java -search: for (int row = 0; row < rows; row++) { for (int col = 0; col < cols; col++) { if (matrix[row][col] == target) { - foundRow = row; - foundCol = col; break search; - } - } -} -``` - → This is cleaner than managing a `found` flag or throwing a dummy exception. - -2. **Early continue of outer loop** when an inner condition invalidates the outer iteration: - -```java -outer: for (Order order : orders) { for (Item item : order.getItems()) { if (item.isInvalid()) continue outer; - } - process(order); -} -``` - -## JVM Shutdown Hooks - -You Can Add Shutdown Hooks to JVM -Want to gracefully close resources when your Java app is killed? - -```java -Runtime.getRuntime().addShutdownHook(new Thread(() -> - System.out.println("Shutting down cleanly...") -)); -``` - -# List recommendations for when and how to use 'JVM Shutdown Hooks' in Java - -- List pros and cons of the feature -- List recommendations for when to use this feature and when not to use this feature focusing on maintainability and testability -- List practices for using ' -lock -AI Prompt: List range of recommendations and practices for using a Java feature' in Java broken into 3 groupings - - "common industry practices" : what’s actually done in the wild - - "best current practices" : emphasize what experienced engineers recommend for maintainability and robustness - - "thought-leader practices" : These are the “pundit-level” or thought-leader-endorsed standards — typically promoted in books, conference talks, or advanced frameworks. - -- Answer in terse, direct language - - - - - - -## Java 11 or greater - -- Use `var` for local variables whenever possible - -## Java 17 or greater - - -- Make variables `final` whenever possible -- Use records for immutable DTS or Value Objects -- Switch Expressions -- Records -- ??? USe sealed classes and pattern matching ???? -- Multiline Text Blocks: Multiline String Sanity - -```java -// The instanceof Operator Can Bind a Variable (Pattern Matching) -Object obj = "Hello"; -if (obj instanceof String s) { - System.out.println(s.toUpperCase()); -} -``` - - -## Java 21 or greater - -- ??? Virtual Threads -- pattern matching for swicth ???? -- Record Patterns - - -## Java 24 or greater - -- MArkdown Javadoc -- Primitive types in patterns -- Nullabel vs non-nullable value types - -- Sequenced collections -```java -SequencedMap counts = new LinkedHashMap<>(); -counts.put("a",1); -counts.put("b",2); - -// Clear intent -var first = counts.firstEntry(); -var last = counts.lastEntry(); -counts.putLast("c", 3); -counts.pollFirstEntry(); -``` - -- Scoped values to pass context without thread-locals - -Request context leaks through thread-locals on virtual threads. -Scoped values let me pass keys safely and read them deep in the stack. I stop worrying about accidental retention. - -```plaintext -\+ request \-> \[Scope.open\] -| traceId=abc123 -| v v -| handler \-> service \-> repo -| ^ closes with scope -\+ done \-> \[Scope.close\] -``` - -```java -static final ScopedValue TRACE_ID = ScopedValue.newInstance(); - -void handle(HttpRequest req) { - ScopedValue.where(TRACE_ID, req.header("X-Trace")) - .run(() -> service(req)); -} -void service(HttpRequest req) { - log.info("trace={}", TRACE_ID.get()); -} -``` - -- Use record patterns where you unwrap structured data then decide behavior - -```java -sealed interface Event permits OrderCreated, OrderPaid {} -record OrderCreated(long id, Customer c) implements Event {} -record Customer(String name, Address addr) {} -record Address(String city) {} - -String city = switch (event) { - case OrderCreated(long id, Customer(var n, Address(var c))) -> c; - default -> "NA"; -}; -``` -- Pattern matching for switch that reads like policy - -I used instanceof ladders around DTOs and enums with state. Pattern matching folds it into one readable switch. The team reads the rules without jumping lines. - -```java -String label = switch (obj) { - case String s when s.isBlank() -> "empty"; - case String s -> s; - case Number n -> "num:" + n.longValue(); - default -> "other"; -}; -``` - - - -# List recommendations for when and how to use 'volatile' in Java - -- List pros and cons of using 'volatile' -- List recommendations for when to use 'volatile' and when not to use 'volatile' focusing on maintainability and testability -- List practices for using 'volatile' in Java broken into 3 groupings - - "common industry practices" : what’s actually done in the wild - - "best current practices" : emphasize what experienced engineers recommend for maintainability and robustness - - "thought-leader practices" : These are the “pundit-level” or thought-leader-endorsed standards — typically promoted in books, conference talks, or advanced frameworks. - -- Answer in terse, direct language - - - - diff --git a/.cursor/rules/java-general-coding.mdc.txt b/.cursor/rules/java-general-coding.mdc.txt deleted file mode 100644 index cb72b98..0000000 --- a/.cursor/rules/java-general-coding.mdc.txt +++ /dev/null @@ -1,96 +0,0 @@ ---- -globs: *.java -alwaysApply: false -title: Java General Coding Guidelines -description: General Java rules for this project -scope: project -tags: [java, guidelines, style] -priority: high ---- - -# Java Coding Guidelines - - -## General Principles - -- Use "Effective Java 3rd Edition" as the primary coding guidelines -- Prefer immutability wherever possible. -- Apply SOLID principles but do not apply Interface Segregatioon -- Use Objects.equals for object comparison -- Do not use Vector or Hashtable -- Use StringBuilder for composing strings -- Only use java.time package for times and dates -- Do not use Serializable -- Do not use Boolean or boolean in parameter lists -- Do not use assert keyword - -## Interfaces - -- Use when Multiple Implementations Exist -- Use When injecting including multiple inmpls -- Use when You’re Writing a Library or SDK - -## Naming Things - -- Use meaningful names (no abbreviations). Standard acronyms are used in the same case as they are defined (i.e.XML is all caps) -- Do not use the meaningless suffixes: Helper, Utils, Manager, Data, -- Use business domain nouns and verbs. A method should do something, and its name should say so - - -## Handling No-Things - -- Do not initialize variables to null -- Return empty collections -- Option1: Return Optional for Explicit Absence -- Option2: Don’t use Optional In DTOs or method parameters (especially in performance-critical code). -- Option3: Return a Default or Empty Object (The Null Object Pattern) - -## Javadoc Comments - -- Comments Explain “Why”, Not “What” - - -## Contructors and creating objects - -- Use static factory methods when - - You need a descriptive name. - - You want to validate/invariant-check before creation. - - You want to return a cached, shared, or flyweight instance. - - You want to control or hide the concrete type. - - You need subtype selection. - - You want to vary the returned object per input or environment. - - You want better type inference or generic helpers. - - You want singletons or scoped lifecycles. - - You want expressive conversions. - - You need API stability across versions. - - You’re wrapping records. -- Use constructors when - - You want the simplest, most discoverable API for “just build the thing.” -- Use builders when faced with many constructor parameters -- Enforce the singleton property with a private constructor or an enum type - -## Try Catch - -- Use try with resources - -## Java 17 or greater - -- Make variables `final` whenever possible -- Use records for immutable DTS or Value Objects -- Switch Expressions -- Records -- Use sealed classes and pattern matching -- Use Multiline Text Blocks - -## Java 21 or greater - -- Use Virtual Threads -- pattern matching for switch -- Record Patterns - -## Java 24 or greater - -- MArkdown Javadoc -- Primitive types in patterns -- Nullabel vs non-nullable value types - diff --git a/.cursor/rules/java-unit-test-coding.mdc.txt b/.cursor/rules/java-unit-test-coding.mdc.txt deleted file mode 100644 index 14e1c10..0000000 --- a/.cursor/rules/java-unit-test-coding.mdc.txt +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: General Java rules for this project -globs: *Test.java,*IT.java -alwaysApply: false ---- -# Java Unit Test Coding Guidelines - -## General Principles - -- Test for the Wrong Path — Not the Happy Path -- - -## Test Names - - - -## Junit - -## Assertions - - -## Mocks - -- Mock only what is impossible to run (slow external calls, payment gateways). -- But for services, DBs, and logic — use real in-memory or test containers. \ No newline at end of file diff --git a/.cursor/rules/mdc-template.md b/.cursor/rules/mdc-template.md deleted file mode 100644 index 376a549..0000000 --- a/.cursor/rules/mdc-template.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: "RULE TITLE HERE" -slug: "XXX-rule-slug" -version: "0.1.0" -status: "draft" -owners: - - "team-or-guild-name" -tags: - - "java" - - "rules" - - "best-practices" -applies_to: - - "Java 17+" -last_updated: "2025-10-24" -visibility: "public" -lintable: true ---- - -# RULE TITLE HERE (.mdc) - - - -## 1) Context / Scope -- What this file covers (scope). -- What is out of scope. -- Normative language: **MUST / SHOULD / MAY**. - ---- - - - -## 2) Principles -- High-level durable principles. -- These rarely change. - ---- - - - -## 3) Design Decisions / Philosophy -- Why we prefer certain practices over alternatives. -- References to industry standards or key texts. - ---- - - - -## 4) General Approaches / Patterns -- Broad recommended practices. -- Example: “Package by feature, not by layer.” - ---- - - - -## 5) Specific Topics (Rules) -### 5.1 Construction -- Rules with short rationale + code snippet. - -### 5.2 Exceptions -- Rules with short rationale + code snippet. - -### 5.3 Other sections -- Add more topical sections as needed. - ---- - - - -## 6) Technical Details / Tooling -- Maven/Gradle dependencies. -- Specific annotations or APIs. - ---- - - - -## 7) Lintable / Automatable Rules -- Machine-enforceable constraints (ArchUnit, Checkstyle, Sonar). - ---- - - - -## 8) Checklist (PR / Code Review) -- A quick bullet list for reviewers. -- “Did you preserve causes when wrapping exceptions?” - ---- - - - -## 9) Examples -**Good Example** -```java -// minimal example here -``` - -**Bad Example** -```java -// anti-pattern here -``` - ---- - - - -## 10) Anti-Patterns & Smells -- Common pitfalls to avoid. -- Why they are harmful. - - \ No newline at end of file diff --git a/.cursor/rules/sdd-system.mdc b/.cursor/rules/sdd-system.mdc deleted file mode 100644 index f8e9771..0000000 --- a/.cursor/rules/sdd-system.mdc +++ /dev/null @@ -1,79 +0,0 @@ ---- -alwaysApply: true ---- - -# SDD (Spec-Driven Development) System Overview - -This project implements a comprehensive **Spec-Driven Development** workflow using three core commands that work together to transform ideas into structured implementation plans. - -## Core Philosophy -Spec-Driven Development emphasizes creating detailed, executable specifications **before** writing code, ensuring: -- Requirements are clear before implementation -- Technical decisions are well-planned and documented -- Development tasks are structured and manageable -- Team collaboration is enhanced through shared understanding - -## SDD 2.5: Agile-Compatible Lightweight Workflow (Default) - -### Primary Approach (80% of features) - -#### `/brief` - 30-Minute Planning -Transform ideas into actionable development plans in 30 minutes -- **Time**: 30 minutes total planning before coding -- **Output**: Single [feature-brief.md](mdc:specs/active/[task-id]/feature-brief.md) with essential context -- **Philosophy**: "Just enough" planning to start coding confidently -- **Key Elements**: Problem/users, quick research, requirements, next actions - -#### `/evolve` - Living Documentation -Keep specifications aligned with reality during development -- **Purpose**: Continuous updates as discoveries are made during coding -- **Output**: Updates existing feature-brief.md with changelog -- **Philosophy**: Specifications as living documents that evolve with code - -### Advanced Approach (20% of complex features) - SDD 2.0 - -For complex, high-risk, or multi-team features requiring comprehensive planning: - -#### Full Workflow: `/research` → `/specify` → `/plan` → `/tasks` → `/implement` -- **Use When**: Feature complexity high, multiple stakeholders, significant architectural impact -- **Time Investment**: 4-6 hours upfront planning -- **Output**: Complete documentation suite (research.md, spec.md, plan.md, tasks.md) - -## Decision Framework - -**Start with `/brief`** unless feature meets ANY of these criteria: -- Multiple teams involved -- Architectural changes required -- High business risk/compliance needs -- Uncertain technical approach -- 3+ week development timeline - -**Upgrade from brief to full SDD** if complexity discovered during implementation - -## File Organization - -The system uses a context-engineering approach with: -- **Active tasks**: [specs/active/[task-id]/](mdc:specs/active/) - Tasks currently in development -- **Task artifacts**: research.md, spec.md, plan.md, tasks.md, todo-list.md, progress.md -- **Templates**: [.sdd/templates/](mdc:.sdd/templates/) - Reusable document templates -- **Configuration**: [.sdd/config.json](mdc:.sdd/config.json) - System settings and preferences -- **Guidelines**: [.sdd/guidelines.md](mdc:.sdd/guidelines.md) - Development methodology guide - -## Task ID Convention -- Use semantic slugs: `user-auth-system`, `payment-integration`, `dashboard-redesign` -- Avoid generic numbering: `feat-001` (legacy approach) -- Focus on meaningful, searchable identifiers - -## Quality Assurance -Each phase includes comprehensive review checklists and validation rules to ensure: -- Specifications are clear and testable -- Plans are technically sound and scalable -- Tasks are actionable and properly estimated -- Documentation maintains consistency across the project - -## Collaboration Support -The system supports multi-developer workflows with: -- Assignee tracking for features and tasks -- Progress monitoring through status updates -- Review workflows with feedback integration -- Audit trails for change management \ No newline at end of file