best-practices
Use when refactoring or implementing features - validation, component design, API research
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for maintaining high-quality codebases through a structured checklist of engineering best practices. It assists developers during feature implementation and refactoring by enforcing standards for unit testing, performance optimization, component encapsulation, and API integration, ensuring code is not only functional but also maintainable and performant.
Use Cases
- Refactoring legacy code: Use the guidelines to ensure that logic extraction follows established patterns and maintains existing API contracts without unnecessary file creation.
- Component Design: Apply encapsulation principles to React components to prevent prop drilling and ensure internal dependency management via hooks.
- API Integration & Research: Verify actual API behavior against official documentation to avoid defensive coding based on assumptions and to create realistic test mocks.
- Performance Auditing: Evaluate the impact of new dependencies on bundle size and identify unnecessary re-renders or inefficient data handling during development.
- Configuration Management: Identify duplicated configurations across multiple files and extract them into centralized constants to maintain a single source of truth.
| name | best-practices |
|---|---|
| description | Use when refactoring or implementing features - validation, component design, API research |
Best Practices
Use this skill when implementing features or refactoring code to follow established patterns.
Checklist
Validation Before Claiming Success
- Unit tests passing ≠ code is correct
- Check application logs for warnings and timing issues
- Test with real workloads when possible
- Verify behavior matches requirements, not just tests
- Performance matters
- Check for unnecessary re-renders (React DevTools)
- Verify bundle size impact for new dependencies
- Test with realistic data volumes
Question Patterns Before Copying
When copying code from elsewhere in the codebase:
- What problem does this solve?
- Understand the original use case
- Verify it applies to your situation
- Does this pattern apply here?
- Consider the context differences
- Don't blindly copy without understanding
- What's the performance impact?
- Understand computational cost
- Consider alternative approaches
Refactoring Guidelines
- Update tests when behavior/API contracts change
- Don't keep tests passing by mocking new behavior
- Update assertions to match new contracts
- Prefer editing existing files over creating new ones
- Don't create new files for minor changes
- Keep related code together
- Component Encapsulation
- Use hooks internally instead of passing derived values as props
- Avoid unnecessary prop drilling
Examples:
// ✅ Good - component encapsulates its own dependencies
export const ImageGrid: FC<{ images: Image[] }> = ({ images }) => {
const baseURL = useBackendUrl()
return <div>{/* render images with baseURL */}</div>
}
// ❌ Avoid - unnecessary prop drilling
export const ImageGrid: FC<{ images: Image[]; baseURL: string }> = ({
images,
baseURL
}) => {
return <div>{/* render images */}</div>
}
Extract Duplicated Configuration
- Identical configs in multiple files → Extract to constants
- Look for repeated option objects
- Look for repeated configuration values
- Create shared constants file
- Import from single source of truth
Example:
// ❌ Bad - duplicated configuration
// file1.ts
const options = { timeout: 5000, retries: 3 }
// file2.ts
const options = { timeout: 5000, retries: 3 }
// ✅ Good - extracted to shared constant
// constants.ts
export const API_OPTIONS = { timeout: 5000, retries: 3 }
// file1.ts & file2.ts
import { API_OPTIONS } from './constants'
Verify API Behavior Before Refactoring
- Read official documentation for the API
- Don't assume behavior based on naming
- Check for version-specific differences
- Understand return types and possible values
- Don't add defensive code based on assumptions
- Only add guards/checks if behavior actually differs
- Test edge cases to verify actual behavior
- Test cases should match real API behavior
- Don't test for imagined edge cases
- Mock realistic responses, not theoretical ones
Example:
// ❌ Bad - defensive code based on assumptions
const value = api.getValue()
if (value === null || value === undefined || value === '') {
// Assuming getValue() can return null/undefined/empty
}
// ✅ Good - verified that getValue() only returns string or throws
try {
const value = api.getValue() // Documentation: returns string or throws
// Use value directly
} catch (error) {
// Handle error case
}
Research First
- Check official documentation before implementing
- Libraries: Read the official docs, not blog posts
- APIs: Check the specification/documentation
- Frameworks: Follow official guides and examples
- Check existing patterns in the codebase
- Search for similar implementations
- Follow established conventions
- Ask if unsure about approach
Common Pitfalls
Over-validation:
- Don't add checks for impossible states
- Trust internal APIs and framework guarantees
- Only validate at system boundaries (user input, external APIs)
Premature abstraction:
- Don't create helpers for one-time operations
- Don't design for hypothetical future requirements
- Three similar lines is better than premature abstraction
Ignoring performance:
- Tests passing ≠ code is performant
- Check re-render count, bundle size, load times
- Profile before and after changes
Reference
See @docs/CODING_STYLE.md for detailed coding standards.