These rules ensure maintainability, performance, security, and developer velocity in modern web applications. MUST rules are enforced by CI/CD; SHOULD rules are strongly recommended; CONSIDER rules are situational best practices.
type UserId = Brand<string, 'UserId'> // ✅ Good
type ProductId = Brand<string, 'ProductId'> // ✅ Good
type UserId = string // ❌ Badimport type { … } for type-only imports.type over interface; use interface only for extensibility or declaration merging.*.test.ts or __tests__ folder next to source.e2e/ or tests/integration/. // ✅ Good - tests behavior
expect(screen.getByText('Welcome')).toBeInTheDocument();
// ❌ Bad - tests implementation
expect(mockSetState).toHaveBeenCalledWith('welcome'); src/
features/
auth/
components/
hooks/
services/
types/
dashboard/
...
shared/
components/
hooks/
utils/
types/shared/ only if used by ≥ 2 features.index.ts) for clean imports.prettier --check passes on all files.eslint --fix passes with zero warnings.tsc --noEmit passes with strict TypeScript checks.When evaluating function quality, use this checklist:
IMPORTANT: Only extract separate functions when:
import fc from 'fast-check';
test('addition is commutative', () => {
fc.assert(
fc.property(fc.integer(), fc.integer(), (a, b) =>
add(a, b) === add(b, a)
)
);
});src/
components/
ui/ # Reusable UI components
layout/ # Layout components
features/
auth/
dashboard/
profile/
hooks/ # Custom hooks
services/ # API and external services
utils/ # Pure utility functions
types/ # Shared TypeScript types
constants/ # Application constantssrc/
app/ # App Router pages
components/ # Shared components
features/ # Feature modules
lib/ # Utilities and configurations
hooks/ # Custom hooks
types/ # TypeScript definitions
middleware.ts # Next.js middlewareUnderstand all BEST PRACTICES in this guide.
Your code MUST ALWAYS follow these web development standards.
Focus on performance, accessibility, and user experience.Analyze the existing codebase architecture and determine if your plan:
- Follows established patterns and conventions
- Minimizes complexity and dependencies
- Reuses existing components and utilities
- Maintains performance and accessibility standards
- Considers mobile and cross-browser compatibilityImplement your plan following these steps:
1. Create/update components with proper TypeScript types
2. Implement comprehensive tests (unit + integration)
3. Ensure accessibility compliance
4. Test responsive behavior
5. Run prettier, eslint, and type checking
6. Verify performance impactYou are a SENIOR FRONTEND ARCHITECT performing a thorough code review.
Analyze every major change using:
1. Function Quality Checklist
2. Component Quality Checklist
3. Test Quality Checklist
4. Performance implications
5. Accessibility compliance
6. Security considerationsYou are a FRONTEND EXPERT reviewing component architecture.
For each major component added/modified, evaluate:
1. Component Quality Checklist
2. Reusability and composition patterns
3. Performance optimization opportunities
4. Accessibility implementationYou are a QA ENGINEER reviewing test coverage.
For each test suite added/modified, check:
1. Test Quality Checklist
2. Coverage of user workflows
3. Edge case handling
4. Performance test considerationsImagine you are a real user testing this feature across different devices.
Create a comprehensive test plan including:
- Happy path scenarios
- Error conditions
- Accessibility testing
- Mobile/tablet behavior
- Cross-browser compatibility
- Performance under load
Sort by business impact and user frustration potential.Prepare for deployment:
1. Run full test suite and ensure 100% pass rate
2. Check bundle size impact and performance metrics
3. Verify accessibility compliance
4. Test in multiple browsers/devices
5. Add all changes to staging
6. Create conventional commit with proper scope
7. Push to feature branch for review
Commit message format:
<type>[optional scope]: <description>
Types: feat, fix, docs, style, refactor, test, chore
Scopes: ui, api, auth, dashboard, etc.Analyze performance implications of your changes:
1. Bundle size impact
2. Runtime performance (rendering, interactions)
3. Network requests and caching
4. Core Web Vitals impact
5. Mobile performance considerations
Suggest optimizations if needed.