From ab23d491457ef422a83d8de5871765af1523349f Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Tue, 19 Aug 2025 03:48:53 +0000 Subject: [PATCH] docs(rules): enhance development guidelines with type safety and dependency management - Add comprehensive Type Safety Enforcement section with core rules and patterns - Include Type Guard Patterns for API, Database, and Axios error handling - Add Implementation Guidelines for avoiding type assertions and proper type narrowing - Enhance software development ruleset with dependency management best practices - Add pre-build validation workflows and environment impact assessment - Include dependency validation strategies and common pitfalls guidance - Add build script enhancement recommendations for early validation Improves development workflow consistency and type safety enforcement --- .../rules/development/type_safety_guide.mdc | 17 +++ .cursor/rules/software_development.mdc | 118 +++++++----------- 2 files changed, 59 insertions(+), 76 deletions(-) diff --git a/.cursor/rules/development/type_safety_guide.mdc b/.cursor/rules/development/type_safety_guide.mdc index 507e3f23..6dba1416 100644 --- a/.cursor/rules/development/type_safety_guide.mdc +++ b/.cursor/rules/development/type_safety_guide.mdc @@ -40,6 +40,23 @@ Practical rules to keep TypeScript strict and predictable. Minimize exceptions. - Avoid `(obj as any)[k]`. +## Type Safety Enforcement + +### Core Type Safety Rules +- **No `any` Types**: Use explicit types or `unknown` with proper type guards +- **Error Handling Uses Guards**: Implement and reuse type guards from `src/interfaces/**` +- **Dynamic Property Access**: Use `keyof` + `in` checks for type-safe property access + +### Type Guard Patterns +- **API Errors**: Use `isApiError(error)` guards for API error handling +- **Database Errors**: Use `isDatabaseError(error)` guards for database operations +- **Axios Errors**: Implement `isAxiosError(error)` guards for HTTP error handling + +### Implementation Guidelines +- **Avoid Type Assertions**: Replace `as any` with proper type guards and interfaces +- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely +- **Document Type Decisions**: Explain complex type structures and their purpose + ## Minimal Special Cases (document in PR when used) - **Vue refs / instances**: Use `ComponentPublicInstance` or specific component diff --git a/.cursor/rules/software_development.mdc b/.cursor/rules/software_development.mdc index f84bd5a2..745317cd 100644 --- a/.cursor/rules/software_development.mdc +++ b/.cursor/rules/software_development.mdc @@ -1,6 +1,3 @@ ---- -alwaysApply: true ---- # Software Development Ruleset @@ -89,90 +86,59 @@ Specialized guidelines for software development tasks including code review, deb - [ ] Solution complexity justified by evidence - [ ] Simpler alternatives considered and documented - [ ] Impact on existing systems assessed -# Software Development Ruleset +- [ ] Dependencies validated and accessible +- [ ] Environment impact assessed for team members +- [ ] Pre-build validation implemented where appropriate -## Purpose -Specialized guidelines for software development tasks including code review, debugging, architecture decisions, and testing. +## Additional Core Principles -## Core Principles +### 4. Dependency Management & Environment Validation +- **Pre-build Validation**: Always validate critical dependencies before executing build scripts +- **Environment Consistency**: Ensure team members have identical development environments +- **Dependency Verification**: Check that required packages are installed and accessible +- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues -### 1. Evidence-First Development -- **Code Citations Required**: Always cite specific file:line references when making claims -- **Execution Path Tracing**: Trace actual code execution before proposing architectural changes -- **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" +## Additional Required Workflows -### 2. Code Review Standards -- **Trace Before Proposing**: Always trace execution paths before suggesting changes -- **Evidence Over Inference**: Prefer code citations over logical deductions -- **Scope Validation**: Confirm the actual scope of problems before proposing solutions +### Dependency Validation (Before Proposing Changes) +- [ ] **Dependency Validation**: Verify all required dependencies are available and accessible -### 3. Problem-Solution Validation -- **Problem Scope**: Does the solution address the actual problem? -- **Evidence Alignment**: Does the solution match the evidence? -- **Complexity Justification**: Is added complexity justified by real needs? -- **Alternative Analysis**: What simpler solutions were considered? +### Environment Impact Assessment (During Solution Design) +- [ ] **Environment Impact**: Assess how changes affect team member setups -## Required Workflows +## Additional Competence Hooks -### Before Proposing Changes -- [ ] **Code Path Tracing**: Map execution flow from entry to exit -- [ ] **Evidence Collection**: Gather specific code citations and logs -- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred -- [ ] **Scope Validation**: Confirm the actual extent of the problem +### Dependency & Environment Management +- **"What dependencies does this feature require and are they properly declared?"** +- **"How will this change affect team member development environments?"** +- **"What validation can we add to catch dependency issues early?"** -### During Solution Design -- [ ] **Evidence Alignment**: Ensure solution addresses proven problems -- [ ] **Complexity Assessment**: Justify any added complexity -- [ ] **Alternative Evaluation**: Consider simpler approaches first -- [ ] **Impact Analysis**: Assess effects on existing systems +## Dependency Management Best Practices -## Software-Specific Competence Hooks +### Pre-build Validation +- **Check Critical Dependencies**: Validate essential tools before executing build scripts +- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to avoid PATH issues +- **Environment Consistency**: Ensure all team members have identical dependency versions -### Evidence Validation -- **"What code path proves this claim?"** -- **"How does data actually flow through the system?"** -- **"What am I assuming vs. what can I prove?"** +### Common Pitfalls +- **Missing npm install**: Team members cloning without running `npm install` +- **PATH Issues**: Direct command execution vs. npm script execution differences +- **Version Mismatches**: Different Node.js/npm versions across team members -### Code Tracing -- **"What's the execution path from user action to system response?"** -- **"Which components actually interact in this scenario?"** -- **"Where does the data originate and where does it end up?"** +### Validation Strategies +- **Dependency Check Scripts**: Implement pre-build validation for critical dependencies +- **Environment Requirements**: Document and enforce minimum Node.js/npm versions +- **Onboarding Checklist**: Standardize team member setup procedures -### Architecture Decisions -- **"What evidence shows this change is necessary?"** -- **"What simpler solution could achieve the same goal?"** -- **"How does this change affect the existing system architecture?"** - -## Integration with Other Rulesets - -### With base_context.mdc -- Inherits generic competence principles -- Adds software-specific evidence requirements -- Maintains collaboration and learning focus - -### With research_diagnostic.mdc -- Enhances investigation with code path tracing -- Adds evidence validation to diagnostic workflow -- Strengthens problem identification accuracy - -## Usage Guidelines +### Error Messages and Guidance +- **Specific Error Context**: Provide clear guidance when dependency issues occur +- **Actionable Solutions**: Direct users to specific commands (`npm install`, `npm run check:dependencies`) +- **Environment Diagnostics**: Implement comprehensive environment validation tools -### When to Use This Ruleset -- Code reviews and architectural decisions -- Bug investigation and debugging -- Performance optimization -- Feature implementation planning -- Testing strategy development - -### When to Combine with Others -- **base_context + software_development**: General development tasks -- **research_diagnostic + software_development**: Technical investigations -- **All three**: Complex architectural decisions or major refactoring +### Build Script Enhancements +- **Early Validation**: Check dependencies before starting build processes +- **Graceful Degradation**: Continue builds when possible but warn about issues +- **Helpful Tips**: Remind users about dependency management best practices -## Self-Check (model, before responding) -- [ ] Code path traced and documented -- [ ] Evidence cited with specific file:line references -- [ ] Assumptions clearly flagged as proven vs. inferred -- [ ] Solution complexity justified by evidence -- [ ] Simpler alternatives considered and documented -- [ ] Impact on existing systems assessed +- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely +- **Document Type Decisions**: Explain complex type structures and their purpose