From c1e71afff309a79115193aed008bb1f3b4d0b82f Mon Sep 17 00:00:00 2001 From: Jen Hamon Date: Wed, 14 Jan 2026 13:46:39 -0500 Subject: [PATCH] Add Cursor configuration --- .cursor/BUGBOT.md | 85 ++++++++++ .cursor/commands/create-bug.md | 31 ++++ .cursor/commands/create-improvement.md | 31 ++++ .cursor/commands/create-subplan.md | 15 ++ .cursor/commands/github-triage.md | 141 +++++++++++++++++ .cursor/commands/investigate-github-issue.md | 158 +++++++++++++++++++ .cursor/commands/list-github-issues.md | 57 +++++++ .cursor/rules/best-practices.mdc | 42 +++++ 8 files changed, 560 insertions(+) create mode 100644 .cursor/BUGBOT.md create mode 100644 .cursor/commands/create-bug.md create mode 100644 .cursor/commands/create-improvement.md create mode 100644 .cursor/commands/create-subplan.md create mode 100644 .cursor/commands/github-triage.md create mode 100644 .cursor/commands/investigate-github-issue.md create mode 100644 .cursor/commands/list-github-issues.md create mode 100644 .cursor/rules/best-practices.mdc diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md new file mode 100644 index 00000000..24e512ff --- /dev/null +++ b/.cursor/BUGBOT.md @@ -0,0 +1,85 @@ +# Code Review Guidance + +## Quick Reference + +Verify: code compiles, tests pass, JavaDoc updated, no generated code edits, proper exception handling, input validation, adequate test coverage. + +## Code Quality Review + +### Documentation +- Update JavaDoc near changed code. Include `@throws` for all exceptions. Use `
{@code ... }
` for public API examples. Document parameter constraints and validation rules. JavaDoc must describe actual behavior, not intended behavior. +- All public methods/classes/interfaces need complete JavaDoc. Provide examples for complex APIs. Document parameters and return values clearly. + +### Exception Handling +- Use custom exceptions from `io.pinecone.exceptions`: `PineconeValidationException` for invalid inputs, `PineconeBadRequestException` for bad requests. Avoid generic exceptions. +- Error messages must be descriptive, actionable, and reference docs when appropriate. When wrapping exceptions, preserve cause: `new Exception(message, cause)`. +- Map HTTP status codes to exceptions using `HttpErrorMapper` patterns. Ensure consistent error handling. + +### Validation +- Validate inputs early in public methods. Throw `PineconeValidationException` with clear messages. Use static validation methods (e.g., `validatePodIndexParams`) for reusable logic. Explicitly check null and empty strings. +- Handle edge cases (null, empty, max values) with appropriate error messages. + +### Code Generation +- Never edit `org.openapitools.*` files directly. Update source OpenAPI/Proto files in `codegen/` and regenerate. Verify regeneration results. + +### Testing +- Capture all major requirements as tests. Unit tests cover validation and error paths. Integration tests cover end-to-end workflows (sparingly). Test success and failure scenarios including edge cases. Use descriptive test method names. +- Tests must be readable, maintainable, follow coding standards, avoid unnecessary complexity, use mocks appropriately. + +### Thread Safety +- Identify shared mutable state (e.g., `ConcurrentHashMap` for connections). Document thread-safety guarantees in JavaDoc. Use thread-safe collections for shared data. Verify concurrent access is safe. + +### Resource Management +- Reuse `OkHttpClient` instances. Document resource lifecycle in JavaDoc. Ensure cleanup in error scenarios. Verify no resource leaks in normal and error paths. + +### Code Style +- Code must be readable, follow Java idioms, prefer clarity over cleverness. Use descriptive names. Break up files over 800 lines. Classes should have single responsibility. +- Avoid breaking public interfaces. If unavoidable, provide migration path and deprecation strategy. Document breaking changes in PR description. + +## Pull Request Review + +### PR Title and Description +- Title: Use Conventional Commits 1.0.0 format (e.g., `fix: handle null pointer exception in query method`). Clearly describe PR purpose. +- Description: Problem and solution, GitHub/Linear issue references, usage examples, value summary (concise), relevant links. + +### Code Changes +- Scope: Single concern per PR. Focused changes. Separate unrelated changes. +- Backward compatibility: Maintain when possible. Document and justify breaking changes. Add deprecation warnings for removed functionality. +- Dependencies: No unnecessary additions. Justify and document new dependencies. Ensure version compatibility. + +## Common Issues + +- Missing null checks (especially public APIs) +- Incomplete error handling +- Missing tests for new functionality +- Outdated JavaDoc +- Resource leaks (use try-with-resources, not manual close()) +- Thread safety violations +- Breaking changes without notice +- Editing generated code directly +- String comparison with `==` (use `.equals()`) +- Exception swallowing (log or rethrow, avoid empty catch blocks) +- Incorrect `equals()/hashCode()` (implement together, critical for collections) +- Collection modification during iteration (use `iterator.remove()` or collect first) +- Mutable objects as map keys (ensure immutability or proper `hashCode()`) +- String concatenation in loops (use `StringBuilder`, not `+`) +- Raw types instead of generics (use `List`, not `List`) +- Incorrect Optional usage (don't use for null checks when null is valid; don't use as method parameters) +- Not preserving exception cause (use `new Exception(message, cause)`) +- Date/time API misuse (use `java.time.*`, not `java.util.Date`/`Calendar`) +- Boxing/unboxing overhead (prefer primitives in performance-critical code) +- Incorrect synchronization (avoid synchronizing on non-final objects or String literals) +- Memory leaks with listeners (remove listeners/callbacks/observers) +- Not validating collection contents (validate elements, not just reference) +- Object comparison with `==` (use `.equals()`) +- Ignoring checked exceptions (handle or rethrow, avoid `catch (Exception e) { /* ignore */ }`) + +## Review Focus by Change Type + +**Bug Fixes**: Address root cause, not symptoms. No regressions. Handle related edge cases. Tests demonstrate fix. + +**New Features**: Complete and functional. Well-designed public API with documentation. Tests cover happy path and errors. No breaking changes unless intentional. + +**Refactoring**: Behavior unchanged (verify with tests). More maintainable/readable. No performance regressions. Update docs if needed. + +**Performance Improvements**: Measurable and significant. No correctness regressions. Tests verify improvement. Document trade-offs. diff --git a/.cursor/commands/create-bug.md b/.cursor/commands/create-bug.md new file mode 100644 index 00000000..39a0bfb3 --- /dev/null +++ b/.cursor/commands/create-bug.md @@ -0,0 +1,31 @@ +# create-bug + +Create a Linear issue for this work in the "SDK Maintenance" project. + +Give the issue these labels: +- sdk:java +- Bug + +Include the plan and any relevant context in the issue description. + +If the plan was made to address a GitHub issue, be sure to include a link to the original GitHub issue in the description. + +Every Linear issue created should include these additional instructions at the end of the description. + +``` +When the planned code changes are complete, the agent should take the following steps: + +1. **Code Quality Review** + - Review JavaDoc strings near the changed code to ensure they are still up to date + - Ensure the code compiles and that unit tests pass + - Ensure changes are adequately tested + +2. **Create Pull Request** + - Create a PR in draft mode + - Rename the PR with a title that follows the Conventional Commits 1.0.0 format + - Update the PR description with: + - A clear description of the problem and solution + - A reference to the related Github issue, if any, as well as the Linear issue number. + - Examples showing how to use the code that was changed + - A summary of the value and approach taken in the work (without overwhelming detail - reviewers can read the code for specifics) +``` \ No newline at end of file diff --git a/.cursor/commands/create-improvement.md b/.cursor/commands/create-improvement.md new file mode 100644 index 00000000..d89e327a --- /dev/null +++ b/.cursor/commands/create-improvement.md @@ -0,0 +1,31 @@ +# create-improvement + +Create a Linear issue for this work in the "SDK Maintenance" project. + +Give the issue these labels: +- sdk:java +- Improvement + +Include the plan and any relevant context in the issue description. + +If the plan was made to address a GitHub issue, be sure to include a link to the original GitHub issue in the description. + +Every Linear issue created should include these additional instructions at the end of the description. + +``` +When the planned code changes are complete, the agent should take the following steps: + +1. **Code Quality Review** + - Review JavaDoc strings near the changed code to ensure they are still up to date + - Ensure the code compiles and that unit tests pass + - Ensure changes are adequately tested + +2. **Create Pull Request** + - Create a PR in draft mode + - Rename the PR with a title that follows the Conventional Commits 1.0.0 format + - Update the PR description with: + - A clear description of the problem and solution + - A reference to the related Github issue, if any, as well as the Linear issue number. + - Examples showing how to use the code that was changed + - A summary of the value and approach taken in the work (without overwhelming detail - reviewers can read the code for specifics) +``` \ No newline at end of file diff --git a/.cursor/commands/create-subplan.md b/.cursor/commands/create-subplan.md new file mode 100644 index 00000000..15c296e2 --- /dev/null +++ b/.cursor/commands/create-subplan.md @@ -0,0 +1,15 @@ +# create-subplan + +Create a detailed implementation plan focused on a specific feature or change. + +Make sure the plan includes: +- Consideration for performance, security, maintainability +- The proposed changes should avoid breaking changes to public interfaces +- If breaking changes are unavoidable, include a migration path and deprecation strategy +- The proposed changes should ideally preserve flexibility/extensibility for future changes +- The proposed changes should follow Java idioms and best practices +- Error handling strategy and exception design +- All changes should be thoroughly tested: + - Use unit tests for the bulk of testing, including errors and edge cases. + - Use integration tests sparingly to confirm a feature is working end-to-end but without delving into all edge cases. +- All interfaces need high-quality JavaDoc strings \ No newline at end of file diff --git a/.cursor/commands/github-triage.md b/.cursor/commands/github-triage.md new file mode 100644 index 00000000..06bcbd22 --- /dev/null +++ b/.cursor/commands/github-triage.md @@ -0,0 +1,141 @@ +# github-triage + +Quick triage and routing of GitHub issues. This is the **first step** for handling new or updated GitHub issues. + +**IMPORTANT: This command must be idempotent.** Before taking any action, check the current state to avoid duplicates: + +- Check if a Linear issue already exists for this GitHub issue (search by GitHub issue URL or number) +- Check if comments requesting information have already been posted +- Check if the issue has already been closed +- Check existing labels before adding or removing any + +**When to use this command:** +- Initial triage of new GitHub issues +- Quick assessment and routing +- Requesting missing information +- Managing issue lifecycle (labels, closing stale issues) + +**When NOT to use this command:** +- For deep code analysis or root cause investigation (use `investigate-github-issue` instead) +- When you need to understand complex technical details before routing + +## Triage Process + +1. **Categorize the issue** + - Determine if it's a bug, feature request, question, documentation issue, or other + - Assess priority based on severity, impact, and user needs (surface-level assessment) + - Check if it's a duplicate of existing issues (GitHub or Linear) + - **Update labels**: Ensure appropriate labels are applied: + - Type labels: `bug`, `enhancement`, `question`, `documentation`, etc. + - Status labels: `needs-info`, `needs-reproduction`, `needs-investigation`, `in-progress`, etc. + - Priority labels: `priority:high`, `priority:medium`, `priority:low`, etc. + - Component/area labels if applicable + - **Check first**: Review existing labels before adding new ones + - **Only add**: Labels that are missing and appropriate + - **Remove**: Incorrect or outdated labels (e.g., remove `needs-info` if information has been provided) + +2. **Extract key information** + - Summarize the problem or request clearly + - Identify affected components or areas of the codebase (high-level) + - Note any relevant context (OS, Java version, SDK version, etc.) + - Extract any code examples or error messages + +3. **Quick verification** + - **Check first**: Review existing comments to see if verification has already been attempted + - For bug reports: Do a quick check if the issue seems reproducible based on provided information + - If reproduction seems straightforward and information is complete, note this + - If the issue is complex, unclear, or needs deeper analysis, add `needs-investigation` label + - **Update labels**: + - Add `needs-reproduction` if reproduction steps are missing or unclear + - Add `needs-investigation` if deeper technical analysis is needed + - Remove `needs-reproduction` if reproduction steps are clear and complete + +4. **Request additional information (if needed)** + - **Check first**: Review existing comments to see if information has already been requested + - **Skip if**: A similar information request comment already exists from a maintainer + - If key information is missing (version, OS, code example, error logs, etc.), draft a response requesting: + - Specific details needed to reproduce or understand the issue + - Code examples or minimal reproduction cases + - Error messages or stack traces + - Environment details (Java version, SDK version, OS, etc.) + - Be polite, specific, and helpful in the request + - **Update labels**: Add `needs-info` label if not already present + +5. **Handle incomplete issues** + - **Check first**: Verify the issue is still open (don't attempt to close if already closed) + - **Check first**: Verify that an information request was made and enough time has passed + - **Skip if**: The issue has already been closed for this reason + - If an issue has been open for an extended period without the requested information: + - Check if enough time has passed since the information request + - Draft a closing comment explaining why the issue is being closed + - Offer to reopen if the information becomes available + - Close the issue with an appropriate label (e.g., "needs-info", "stale") + +6. **Route to next step** + - **Check first**: Search Linear for an existing issue linked to this GitHub issue before creating a new one + - **Skip if**: A Linear issue already exists for this GitHub issue + - **Route based on issue state:** + - **Clear bug with reproduction steps**: Create Linear bug issue using `create-bug` command + - **Clear feature request**: Create Linear improvement issue using `create-improvement` command + - **Needs investigation** (complex, unclear root cause, or needs code analysis): + - Add `needs-investigation` label + - Recommend using `investigate-github-issue` command for deep analysis + - **Question**: Provide a helpful answer or direct to documentation (only if not already answered) + - **Missing information**: Wait for user response (already handled in step 4) + +7. **Link tracking** + - Always include the GitHub issue URL when creating Linear issues + - Maintain bidirectional references between GitHub and Linear + - If a Linear issue already exists, update it with any new information rather than creating a duplicate + +## Workflow Integration + +**Typical workflow:** +1. Run `github-triage` for initial assessment and routing +2. If triage determines `needs-investigation`, run `investigate-github-issue` for deep analysis +3. Based on investigation results, create appropriate Linear issues (`create-bug`, `create-improvement`, or `create-investigation`) + +**When multiple issues are provided**, prioritize them and suggest a triage order based on: +- Severity and user impact +- Dependencies between issues +- Effort required to resolve + +## Batch Processing Workflow + +To triage all GitHub issues iteratively: + +### Option 1: Manual Iteration +1. Fetch a list of open GitHub issues (use GitHub CLI or API): + ```bash + gh issue list --state open --limit 100 + ``` +2. For each issue, invoke this command with the issue URL or number: + - Provide the GitHub issue URL: `https://github.com/owner/repo/issues/123` + - Or provide the issue number and repository context +3. Process issues one at a time, allowing the command to be idempotent (it will skip already-processed issues) + +### Option 2: Automated Batch Processing +When processing multiple issues: +1. **Fetch all open issues** first (using GitHub API or CLI) +2. **Prioritize the list** based on: + - Issues without labels (untriaged) + - Issues with `needs-info` that have received responses + - Issues with `needs-reproduction` that now have reproduction steps + - Recently updated issues + - High-priority labels +3. **Process in batches** (e.g., 5-10 at a time) to avoid overwhelming the system +4. **Review results** after each batch before proceeding + +### Option 3: Focused Triage +To triage specific subsets: +- **Untriaged issues**: `gh issue list --label "status:needs-triage" --state open` +- **Issues needing info**: `gh issue list --label "needs-info" --state open` +- **Issues needing reproduction**: `gh issue list --label "needs-reproduction" --state open` +- **Recently updated**: `gh issue list --state open --limit 20 --sort updated` + +### Best Practices for Batch Triage +- Start with untriaged issues (no status labels) +- Process high-priority issues first +- Review the command output for each issue to ensure proper routing +- If an issue needs investigation, mark it and move on (investigate separately) +- Keep a log of issues that need follow-up (e.g., waiting for user response) \ No newline at end of file diff --git a/.cursor/commands/investigate-github-issue.md b/.cursor/commands/investigate-github-issue.md new file mode 100644 index 00000000..f4cb3e50 --- /dev/null +++ b/.cursor/commands/investigate-github-issue.md @@ -0,0 +1,158 @@ +# investigate-github-issue + +Conduct a thorough, deep investigation of a GitHub issue to understand root causes, verify behavior, and produce actionable next steps. + +**When to use this command:** +- After `github-triage` has determined the issue needs investigation (has `needs-investigation` label) +- When you need to understand root causes before creating a fix plan +- When an issue is complex or unclear and needs code analysis +- When you need to assess impact and scope before prioritizing + +**When NOT to use this command:** +- For initial triage (use `github-triage` instead) +- For simple, clear-cut bugs with obvious fixes +- For straightforward feature requests that don't need technical analysis + +**IMPORTANT: This command must be idempotent.** Before starting, check: +- If a Linear investigation issue already exists for this GitHub issue +- If an investigation has already been completed and documented +- The current state of the GitHub issue (open/closed, labels, comments) +- If `github-triage` has already been run (if not, run it first for proper labeling) + +## Investigation Process + +### 1. **Understand the Issue** + - Read the GitHub issue title, description, and all comments thoroughly + - Extract key information: + - Problem description and expected vs actual behavior + - Code examples, error messages, stack traces + - Environment details (Java version, SDK version, OS, dependencies) + - Steps to reproduce (if provided) + - Related issues or PRs mentioned + - Identify what type of issue this is (bug, feature request, question, etc.) + - Note any ambiguity or missing information + +### 2. **Codebase Analysis** + - Search for relevant code using semantic search: + - Identify components/modules mentioned in the issue + - Find code paths that handle the described functionality + - Locate error handling or validation logic related to the issue + - Find tests that might be relevant + - Read and analyze the relevant source code: + - Understand the current implementation + - Identify potential root causes + - Check for similar patterns or related code + - Review error handling and edge cases + - Check test coverage: + - Find existing tests for the affected functionality + - Identify gaps in test coverage + - Review test cases that might be related + +### 3. **Reproduction and Verification** + - **Note**: This is deeper than triage-level verification. Focus on understanding the technical conditions. + - If reproduction steps are provided: + - Trace through the code paths that would be executed during reproduction + - Analyze the code to understand what conditions are required + - Identify edge cases or specific configurations needed + - Document the exact code flow that leads to the issue + - If reproduction steps are missing: + - Analyze the code to determine what minimal information would be needed + - Suggest specific reproduction cases based on code analysis + - Identify what code paths need to be exercised + - Check for similar issues: + - Search GitHub issues for similar problems + - Check Linear for related investigations or bugs + - Look for patterns across multiple issues + - Analyze if this is part of a broader problem + +### 4. **Root Cause Analysis** + - Analyze the code to identify potential causes: + - Logic errors or bugs + - Missing validation or error handling + - Race conditions or concurrency issues + - API contract violations + - Configuration or environment issues + - Consider edge cases: + - Boundary conditions + - Error scenarios + - Integration points + - Review related code: + - Dependencies and how they interact + - Recent changes that might have introduced the issue + - Design decisions that might be relevant + +### 5. **Impact Assessment** + - Determine the severity and scope: + - How many users might be affected? + - Is this a regression or a long-standing issue? + - What's the impact on functionality? + - Identify affected areas: + - Which components/modules are involved? + - Are there related features that might be affected? + - What are the dependencies? + +### 6. **Document Findings** + Create a comprehensive investigation report that includes: + + **Summary** + - Brief overview of the issue + - Type of issue (bug, feature request, etc.) + - Severity assessment + + **Analysis** + - Key findings from codebase analysis + - Root cause hypothesis (if identified) + - Relevant code references with explanations + - Related issues or patterns found + + **Reproduction Status** + - Can the issue be reproduced? (Yes/No/Needs Info) + - Reproduction steps (if available or if created) + - What information is still needed (if any) + + **Impact** + - Severity and scope + - Affected components + - User impact + + **Next Steps** + - Recommended actions: + - If bug: Create Linear bug issue with fix plan using the create-bug command + - If feature: Create Linear improvement issue with implementation plan via the create-improvement command + - If needs more info: Document what's needed and suggest follow-up + - If question: Provide answer or documentation reference + - Suggested priority + - Estimated effort (if determinable) + - Dependencies or blockers + +### 8. **Update GitHub Issue (If Appropriate)** + - If new information was discovered, consider adding a comment: + - Share key findings and root cause analysis + - Provide code references with explanations + - Suggest next steps and recommended actions + - Request additional information if needed (only if not already requested in triage) + - Update labels if investigation reveals new information: + - Remove `needs-investigation` if investigation is complete + - Add `reproduced` if reproduction was successful + - Update priority labels if impact assessment changed + - Only comment if it adds value and hasn't been covered in existing comments + +## Output Format + +The investigation should produce a structured report that can be: +- Used to create a Linear issue (if needed) +- Used as a basis for creating bug or improvement issues (preferred if investigation is complete) +- Shared with the team for decision-making +- Referenced when implementing fixes + +Focus on actionable insights and clear next steps rather than just summarizing the issue. + +## Workflow Integration + +**This command typically follows `github-triage`:** +1. `github-triage` → Quick assessment, labels issue as `needs-investigation` +2. `investigate-github-issue` → Deep analysis (this command) +3. Based on findings → Create Linear issue (`create-bug`, `create-improvement`, or `create-investigation`) + +**This command can also be used standalone** when you already know an issue needs deep investigation. + diff --git a/.cursor/commands/list-github-issues.md b/.cursor/commands/list-github-issues.md new file mode 100644 index 00000000..53905026 --- /dev/null +++ b/.cursor/commands/list-github-issues.md @@ -0,0 +1,57 @@ +# list-github-issues + +List GitHub issues for batch triage or review. This helper command fetches issues and prepares them for processing with `github-triage`. + +## Usage + +This command helps you get a list of GitHub issues to process. You can then use the issue URLs/numbers with `github-triage` for iterative processing. + +## Output Format + +The command should provide: +- Issue numbers and URLs +- Current labels (especially status labels) +- Last updated date +- Issue title +- Priority suggestion based on labels and recency + +## Filtering Options + +When listing issues, consider filtering by: +- **State**: `open`, `closed` +- **Labels**: `status:needs-triage`, `needs-info`, `needs-reproduction`, `needs-investigation` +- **Sort order**: `created`, `updated`, `comments` +- **Limit**: Number of issues to fetch (start with 20-50 for manageable batches) + +## Suggested Workflow + +1. **List untriaged issues**: + ``` + List open issues with no status labels or with "status:needs-triage" label + ``` + +2. **Prioritize the list**: + - Issues without any status labels (highest priority) + - Issues with `needs-info` that have new comments + - Issues with `needs-reproduction` that have new information + - Recently updated issues + +3. **Process iteratively**: + - Take the first N issues from the prioritized list + - For each issue, run `github-triage` with the issue URL/number + - Review results before proceeding to the next batch + +4. **Track progress**: + - Note which issues were processed + - Identify issues that need follow-up (investigation, waiting for info, etc.) + - Update your list to exclude already-processed issues + +## Integration with github-triage + +After listing issues, use the issue URLs/numbers with `github-triage`: +- Provide issue URLs: `https://github.com/owner/repo/issues/123` +- Or provide issue numbers with repository context +- Process one at a time or in small batches + +The `github-triage` command is idempotent, so you can safely re-run it on issues that have already been processed. + diff --git a/.cursor/rules/best-practices.mdc b/.cursor/rules/best-practices.mdc new file mode 100644 index 00000000..73967790 --- /dev/null +++ b/.cursor/rules/best-practices.mdc @@ -0,0 +1,42 @@ +--- +alwaysApply: true +--- + +## Documentation +- When changing code, review nearby JavaDoc strings to ensure they are up to date +- Include `@throws` tags in JavaDoc for all exceptions that methods can throw +- Provide usage examples in JavaDoc using `
{@code ... }
` blocks for public APIs +- Document parameter constraints and validation rules in JavaDoc + +## Exception Handling +- Use appropriate custom exception types from `io.pinecone.exceptions` package (e.g., `PineconeValidationException`, `PineconeBadRequestException`) +- Include descriptive error messages that help users understand what went wrong +- When wrapping exceptions, preserve the original cause using the constructor that accepts `Throwable` +- Map HTTP status codes to appropriate exception types using `HttpErrorMapper` patterns + +## Validation +- Validate input parameters early in public methods, throwing `PineconeValidationException` for invalid inputs +- Provide clear, actionable error messages that reference documentation when appropriate +- Use static validation methods (like `validatePodIndexParams`) for complex validation logic that may be reused +- Validate null and empty strings explicitly before use + +## Code Generation +- Never manually edit files in `org.openapitools.*` packages - these are auto-generated +- If changes are needed to generated code, update the source OpenAPI/Proto files in `codegen/` and regenerate + +## Testing +- Ensure all major requirements are captured as test cases +- Write unit tests for validation logic and error handling paths +- Include integration tests for end-to-end workflows +- Test both success and failure scenarios, including edge cases +- Use descriptive test method names that clearly indicate what is being tested + +## Thread Safety +- Be aware of shared mutable state (e.g., `ConcurrentHashMap` for connections) +- Document thread-safety guarantees in JavaDoc for classes that maintain shared state +- Use thread-safe collections when sharing data across threads + +## Resource Management +- Reuse `OkHttpClient` instances rather than creating new ones for each request +- Document resource lifecycle and cleanup requirements in JavaDoc +- Ensure proper cleanup of connections and resources in error scenarios