critical-rules
Use always - non-negotiable rules for TypeScript safety, socket events, and React patterns
When & Why to Use This Skill
This Claude skill acts as a rigorous automated auditor for modern web development, enforcing non-negotiable best practices for TypeScript, React, and WebSocket integration. It focuses on eliminating runtime vulnerabilities by banning 'any' types, preventing memory leaks through standardized React cleanup patterns, and ensuring resilient real-time communication with reactive socket handling. By shifting testing focus from implementation to behavior, it helps teams build more stable and maintainable software architectures.
Use Cases
- Enforcing strict TypeScript type safety by identifying and replacing 'any' types with 'unknown' or proper interfaces to catch bugs at compile-time.
- Standardizing WebSocket event management in React components to ensure connections are properly re-subscribed after network interruptions.
- Auditing React useEffect hooks to ensure cleanup functions are synchronous, preventing common memory leaks and stale state issues in complex UI logic.
- Guiding the development of robust test suites that focus on user-facing behavior rather than brittle implementation details, reducing maintenance overhead during refactoring.
| name | critical-rules |
|---|---|
| description | Use always - non-negotiable rules for TypeScript safety, socket events, and React patterns |
Critical Rules
MANDATORY rules that must NEVER be violated. These prevent common bugs and ensure code quality.
Checklist
Rule 1: TypeScript Type Safety
- NEVER use
anytype - no exceptions, including tests- ❌
const data: any = response - ✅
const data: unknown = response - ✅
const data = response as UserData - ✅ For test mocks:
as unknown as Type
- ❌
Why: any disables all type checking and hides bugs. Use proper types, unknown, or type assertions instead.
Examples:
// ❌ Bad - loses all type safety
function process(data: any) {
return data.user.name // No error if user is undefined!
}
// ✅ Good - proper typing
function process(data: unknown) {
if (isUserData(data)) {
return data.user.name
}
throw new Error('Invalid data')
}
// ✅ Good - type assertion when you know the type
const mockSocket = {
on: vi.fn(),
emit: vi.fn()
} as unknown as Socket
Rule 2: Socket Event Handling
- NEVER use
socket.on()directly in components- ❌
socket.on('event', callback)- Breaks on reconnection - ✅
useSocketEvent('event', callback, [callback])- Reactive and safe
- ❌
Why: Direct socket.on() doesn't re-subscribe when socket reconnects. Use the useSocketEvent hook which handles reconnection automatically.
Examples:
// ❌ Bad - loses events after reconnection
useEffect(() => {
const socket = useSocket.getState().socket
socket?.on(SocketEvents.DOWNLOAD_START, handleDownload)
}, [])
// ✅ Good - handles reconnection automatically
useSocketEvent(SocketEvents.DOWNLOAD_START, handleDownload, [handleDownload])
Rule 3: useEffect Cleanup
- Cleanup functions must be synchronous
- ❌
return async () => { await cleanup() }- Breaks React - ✅
return () => { cleanup().catch(console.error) }- Fire-and-forget
- ❌
Why: React expects cleanup functions to be synchronous. Async cleanup functions are ignored.
Examples:
// ❌ Bad - async cleanup is ignored
useEffect(() => {
startService()
return async () => {
await stopService() // Never runs!
}
}, [])
// ✅ Good - synchronous cleanup with fire-and-forget async
useEffect(() => {
startService()
return () => {
stopService().catch(console.error)
}
}, [])
// ✅ Good - synchronous cleanup only
useEffect(() => {
const interval = setInterval(poll, 1000)
return () => clearInterval(interval)
}, [])
Rule 4: Test Behavior, Not Implementation
- Test what the code does, not how it does it
- ❌ Testing that
socket.onwas called 3 times - ✅ Testing that component responds correctly to events
- ❌ Testing that
Why: Implementation details change frequently. Behavior tests remain stable and catch real bugs.
Examples:
// ❌ Bad - tests implementation
it('should call socket.on with download event', () => {
render(<Component />)
expect(mockSocket.on).toHaveBeenCalledWith(SocketEvents.DOWNLOAD_START, expect.any(Function))
})
// ✅ Good - tests behavior
it('should show download progress when download starts', () => {
render(<Component />)
act(() => {
handlers[SocketEvents.DOWNLOAD_START]({ id: '123', filename: 'model.bin' })
})
expect(screen.getByText('Downloading model.bin')).toBeInTheDocument()
})
Verification
Before committing code, verify these rules are followed:
- Run
pnpm run type-check- catchesanytypes - Search for
socket.on- should only appear inuseSocketEventhook - Review useEffect cleanup - must be synchronous
- Review tests - focus on behavior, not implementation
Consequences
Violating these rules leads to:
- Type safety violations → Runtime errors in production
- Socket event loss → Features stop working after reconnect
- Broken cleanup → Memory leaks and stale subscriptions
- Brittle tests → False failures during refactoring