refactor(cursor-rules): restructure rules architecture with meta-rule system
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
This commit is contained in:
177
.cursor/rules/development/dependency_management.mdc
Normal file
177
.cursor/rules/development/dependency_management.mdc
Normal file
@@ -0,0 +1,177 @@
|
||||
# Dependency Management — Best Practices
|
||||
|
||||
> **Agent role**: Reference this file for dependency management strategies and
|
||||
best practices when working with software projects.
|
||||
|
||||
## Dependency Management Best Practices
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
## Environment Setup Guidelines
|
||||
|
||||
### Required Tools
|
||||
|
||||
- **Node.js**: Minimum version requirements and LTS recommendations
|
||||
|
||||
- **npm**: Version compatibility and global package management
|
||||
|
||||
- **Platform-specific tools**: Android SDK, Xcode, etc.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
- **NODE_ENV**: Development, testing, production environments
|
||||
|
||||
- **PATH**: Ensure tools are accessible from command line
|
||||
|
||||
- **Platform-specific**: Android SDK paths, Xcode command line tools
|
||||
|
||||
### Validation Commands
|
||||
|
||||
```bash
|
||||
|
||||
# Check Node.js version
|
||||
|
||||
node --version
|
||||
|
||||
# Check npm version
|
||||
|
||||
npm --version
|
||||
|
||||
# Check global packages
|
||||
|
||||
npm list -g --depth=0
|
||||
|
||||
# Validate platform tools
|
||||
|
||||
npx capacitor doctor
|
||||
|
||||
```
|
||||
|
||||
## Dependency Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Permission Errors**: Use `sudo` sparingly, prefer `npm config set prefix`
|
||||
|
||||
2. **Version Conflicts**: Use `npm ls` to identify dependency conflicts
|
||||
|
||||
3. **Cache Issues**: Clear npm cache with `npm cache clean --force`
|
||||
|
||||
4. **Lock File Issues**: Delete `package-lock.json` and `node_modules`,
|
||||
|
||||
then reinstall
|
||||
|
||||
### Resolution Strategies
|
||||
|
||||
- **Dependency Audit**: Run `npm audit` to identify security issues
|
||||
|
||||
- **Version Pinning**: Use exact versions for critical dependencies
|
||||
|
||||
- **Peer Dependency Management**: Ensure compatible versions across packages
|
||||
|
||||
- **Platform-specific Dependencies**: Handle different requirements per platform
|
||||
|
||||
## Best Practices for Teams
|
||||
|
||||
### Onboarding
|
||||
|
||||
- **Environment Setup Script**: Automated setup for new team members
|
||||
|
||||
- **Version Locking**: Use `package-lock.json` and `yarn.lock` consistently
|
||||
|
||||
- **Documentation**: Clear setup instructions with troubleshooting steps
|
||||
|
||||
### Maintenance
|
||||
|
||||
- **Regular Updates**: Schedule dependency updates and security patches
|
||||
|
||||
- **Testing**: Validate changes don't break existing functionality
|
||||
|
||||
- **Rollback Plan**: Maintain ability to revert to previous working versions
|
||||
|
||||
**See also**:
|
||||
`.cursor/rules/development/software_development.mdc` for core development principles.
|
||||
|
||||
**Status**: Active dependency management guidelines
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: software_development.mdc
|
||||
**Stakeholders**: Development team, DevOps team
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Dependency Changes
|
||||
|
||||
- [ ] **Current State Review**: Check current dependency versions and status
|
||||
- [ ] **Impact Analysis**: Assess impact of dependency changes on codebase
|
||||
- [ ] **Compatibility Check**: Verify compatibility with existing code
|
||||
- [ ] **Security Review**: Review security implications of dependency changes
|
||||
|
||||
### During Dependency Management
|
||||
|
||||
- [ ] **Version Selection**: Choose appropriate dependency versions
|
||||
- [ ] **Testing**: Test with new dependency versions
|
||||
- [ ] **Documentation**: Update dependency documentation
|
||||
- [ ] **Team Communication**: Communicate changes to team members
|
||||
|
||||
### After Dependency Changes
|
||||
|
||||
- [ ] **Comprehensive Testing**: Test all functionality with new dependencies
|
||||
- [ ] **Documentation Update**: Update all relevant documentation
|
||||
- [ ] **Deployment Planning**: Plan and execute deployment strategy
|
||||
- [ ] **Monitoring**: Monitor for issues after deployment
|
||||
Reference in New Issue
Block a user