claude-git-hooks/templates/presets/fullstack/PRE_COMMIT_GUIDELINES.md

Git hooks with Claude CLI for code analysis and automatic commit messages

# Fullstack Code Quality Guidelines

## Cross-Layer Consistency (PRIORITY)

### API Contracts
✅ DTOs (backend) match TypeScript interfaces (frontend)
✅ Field names use same casing (camelCase recommended)
✅ Required/optional fields consistent
✅ Data types match (String↔string, Integer↔number, etc.)

### Error Handling
✅ Backend returns consistent error format
✅ Frontend handles all backend error codes
✅ User-friendly error messages in frontend
✅ No sensitive info in error messages

### Authentication Flow
✅ JWT token format consistent
✅ Token storage secure (httpOnly cookies preferred)
✅ Token expiration handled properly
✅ Refresh token logic works end-to-end

### Validation
✅ Server-side validation always present
✅ Client-side validation matches server rules
✅ Clear validation error messages
✅ Never trust client validation alone

## Backend Standards (Spring Boot)

### Controllers
- Proper HTTP methods and status codes
- Input validation with `@Valid`
- Exception handling with `@ExceptionHandler`
- Use DTOs, never expose entities
- Return consistent response format

### Services
- Use `@Transactional` appropriately
- Handle exceptions properly
- Keep business logic here (not in controllers)
- Avoid N+1 queries

### Security
- Never hardcode credentials
- Use parameterized queries
- Validate all input
- Implement proper authorization checks

## Frontend Standards (React)

### Components
- Keep components small and focused
- Use proper hooks (useState, useEffect, etc.)
- Implement error boundaries
- Handle loading and error states
- Ensure accessibility

### API Integration
- Validate API responses
- Handle all error scenarios
- Show appropriate loading states
- Implement proper error recovery

### Security
- Never use `dangerouslySetInnerHTML` without sanitization
- Store tokens securely
- Validate user input
- Don't expose API keys

## Common Full-Stack Issues

### Backend-Frontend Mismatches
❌ DTOs don't match frontend types
❌ Different field names or casing
❌ Frontend expects fields backend doesn't send
❌ Error responses not handled in frontend

### Security Issues
❌ SQL injection vulnerabilities (backend)
❌ XSS vulnerabilities (frontend)
❌ Exposed secrets or credentials
❌ Missing authentication/authorization
❌ Insecure token storage

### Data Flow Problems
❌ Missing validation on either layer
❌ Inconsistent error handling
❌ Breaking API changes without frontend update
❌ Frontend not handling all backend states

### Performance Issues
❌ N+1 queries (backend)
❌ Unnecessary re-renders (frontend)
❌ Large API payloads
❌ Missing pagination
❌ Unoptimized database queries

## Testing

### Backend
- Unit tests for services
- Integration tests for repositories
- API endpoint tests
- Security tests

### Frontend
- Component unit tests
- Integration tests for API calls
- User interaction tests
- Error scenario tests

### End-to-End
- Critical user flows
- Authentication flows
- Error handling
- Edge cases

## Commit Best Practices

When modifying both backend and frontend:
1. Ensure API contract changes are compatible
2. Update both layers together if breaking change
3. Test the complete flow locally
4. Document any API changes in commit message