ai-qakit 1.0.0

package/templates/.claude/rules/03-function-design.md

@@ -0,0 +1,167 @@
+# Function Design
+
+> Well-designed functions are small, focused, and self-documenting.
+
+---
+
+## Size & Complexity
+
+- Functions should do ONE thing well (Single Responsibility)
+- Keep functions under 20-30 lines when possible
+- Maximum 3 parameters; use objects for more
+- Avoid deep nesting (max 2-3 levels)
+- Extract nested logic into well-named helper functions
+- **Key tip:** If you need more than 3 levels of indentation, your function needs to be split up
+- Each function should fit on your screen without scrolling
+
+### Parameters
+
+```typescript
+// BAD - Too many parameters
+function createUser(name, email, age, role, department, manager, startDate) {}
+
+// GOOD - Use an options object
+interface CreateUserOptions {
+  name: string;
+  email: string;
+  age: number;
+  role?: string;
+  department?: string;
+  manager?: string;
+  startDate?: Date;
+}
+function createUser(options: CreateUserOptions) {}
+```
+
+### Return Early (Guard Clauses)
+
+```typescript
+// BAD - Deep nesting
+function processOrder(order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.paymentValid) {
+        // process...
+      }
+    }
+  }
+}
+
+// GOOD - Guard clauses
+function processOrder(order) {
+  if (!order) return;
+  if (order.items.length === 0) return;
+  if (!order.paymentValid) return;
+  // process...
+}
+```
+
+---
+
+## Utility Functions & Reusability
+
+### When to Create Utils
+
+- Logic is used in 2+ places
+- Function is generic and not business-specific
+- Operation can be tested in isolation
+- Improves readability of calling code
+
+### Organization
+
+```
+utils/
+  string-utils.ts      # formatFullName, truncate, slugify
+  date-utils.ts        # formatDate, parseISO, getRelativeTime
+  validation-utils.ts  # isEmail, isPhoneNumber, isURL
+  array-utils.ts       # chunk, unique, groupBy
+  number-utils.ts      # formatCurrency, roundToDecimal
+  file-utils.ts        # getExtension, sanitizeFilename
+```
+
+### Examples
+
+```typescript
+// BAD - Duplicated logic
+// file1.ts
+const fullName = `${user.firstName} ${user.lastName}`.trim();
+// file2.ts
+const displayName = `${person.firstName} ${person.lastName}`.trim();
+
+// GOOD - Utility function
+// utils/string-utils.ts
+export function formatFullName(firstName: string, lastName: string): string {
+  return `${firstName} ${lastName}`.trim();
+}
+```
+
+---
+
+## Strong Types - Be Explicit
+
+### Why Strong Types Matter
+
+- Prevents runtime type errors at compile time
+- Clarifies function contracts and data structures
+- Enables better IDE support (autocomplete, refactoring)
+- Makes code self-documenting
+
+### Best Practices
+
+- Use TypeScript or type hints in Python to catch type-related bugs early
+- Define interfaces for data structures
+- Avoid `any` type - be specific about what you expect
+- Use union types for values with multiple valid types
+
+```typescript
+// BAD - Generic and error-prone
+function processUser(data: any) {
+  return data.name; // No type safety
+}
+
+// GOOD - Explicit and safe
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+function processUser(user: User): string {
+  return user.name; // Type-safe access
+}
+```
+
+---
+
+## Clear Return Values
+
+### Principles
+
+- Functions should have clear, consistent return values
+- Be explicit about return types
+- Avoid multiple return types when possible
+- Avoid returning `null` when possible - use optional types or result objects
+
+### Best Practices
+
+```typescript
+// BAD - Unclear return type
+function findUser(id: number) {
+  // Could return User, null, undefined, or throw
+  return users.find(u => u.id === id);
+}
+
+// GOOD - Explicit return structure
+interface Result<T> {
+  data: T | null;
+  error: string | null;
+}
+
+function findUser(id: number): Result<User> {
+  const user = users.find(u => u.id === id);
+  if (!user) {
+    return { data: null, error: 'User not found' };
+  }
+  return { data: user, error: null };
+}
+```

package/templates/.claude/rules/04-error-handling.md

@@ -0,0 +1,83 @@
+# Error Handling & Logging
+
+> Proper error handling makes applications robust; good logging makes them debuggable.
+
+---
+
+## Error Handling Principles
+
+- Always "fail safe" - never "fail open"
+- Use try-catch for operations that can fail
+- Implement global exception handlers for unexpected errors
+- Separate business exceptions from technical exceptions
+- **Key tip:** Create custom error classes for different types of errors - makes error handling more specific
+- Use optional chaining and null coalescing: `obj?.value ?? defaultValue`
+- Place safety nets strategically - don't wrap entire code in try-catch blocks
+
+### Best Practices
+
+```typescript
+// BAD - Silent failure
+try {
+  await saveUser(user);
+} catch (e) {
+  // nothing
+}
+
+// BAD - Exposing internal details
+catch (error) {
+  res.status(500).json({ error: error.stack });
+}
+
+// GOOD - Proper error handling
+try {
+  await saveUser(user);
+} catch (error) {
+  logger.error('Failed to save user', { userId: user.id, error });
+  throw new ApplicationError('Unable to save user. Please try again.');
+}
+```
+
+### Security Considerations
+
+- Never expose stack traces or system info to users
+- Don't reveal whether username or password is incorrect (prevents enumeration)
+- Log errors on trusted systems
+- Sanitize error messages before displaying
+
+---
+
+## Logging
+
+### Log Levels
+
+| Level | Use Case |
+|-------|----------|
+| DEBUG | Detailed debugging information (dev only) |
+| INFO | Significant business events (user login, order placed) |
+| WARN | Abnormal situations that may indicate problems |
+| ERROR | Unrecoverable errors affecting specific operations |
+| FATAL | Critical errors affecting entire application |
+
+### Best Practices
+
+- Use structured logging (JSON format) for parseability
+- Include context: user IDs, request IDs, timestamps
+- Log the "what" and "why", not just "error occurred"
+- Never log sensitive data: passwords, tokens, PII, credit cards
+- Set up alerts for ERROR/FATAL levels
+
+```typescript
+// BAD
+console.log('Error');
+console.log(error);
+
+// GOOD
+logger.error('Payment processing failed', {
+  orderId: order.id,
+  userId: user.id,
+  paymentMethod: order.paymentMethod,
+  errorCode: error.code,
+  timestamp: new Date().toISOString()
+});
+```

package/templates/.claude/rules/05-testing.md

@@ -0,0 +1,86 @@
+# Testing
+
+> Tests are your safety net - they enable confident refactoring and catch regressions early.
+
+---
+
+## Test Pyramid
+
+1. **Unit Tests** (70%) - Fast, isolated, test single units
+2. **Integration Tests** (20%) - Test component interactions
+3. **E2E Tests** (10%) - Test complete user flows
+
+---
+
+## Best Practices
+
+- Follow AAA pattern: Arrange, Act, Assert
+- One assertion concept per test
+- Tests should be independent and isolated
+- Use mocking for external dependencies
+- Aim for 70-80% code coverage
+- Write tests before code (TDD) when possible
+- **Key tip:** Write tests first (TDD) to ensure your code is naturally testable
+- Pass dependencies as parameters for testability: `process(repository)` instead of hardcoding
+
+---
+
+## Naming Test Cases
+
+```typescript
+// Pattern: should_ExpectedBehavior_When_Condition
+describe('UserService', () => {
+  it('should return user when valid ID provided', () => {});
+  it('should throw NotFoundError when user does not exist', () => {});
+  it('should hash password before saving', () => {});
+});
+```
+
+---
+
+## What NOT to Do
+
+- Don't use fake data/mocks just to pass tests
+- Don't skip tests to pass CI/CD
+- Don't test implementation details, test behavior
+- Don't ignore flaky tests - fix them
+
+---
+
+## Test Structure Example
+
+```typescript
+describe('OrderService', () => {
+  // Arrange - setup shared fixtures
+  let orderService: OrderService;
+  let mockRepository: jest.Mocked<OrderRepository>;
+
+  beforeEach(() => {
+    mockRepository = createMockRepository();
+    orderService = new OrderService(mockRepository);
+  });
+
+  describe('createOrder', () => {
+    it('should create order with valid items', async () => {
+      // Arrange
+      const items = [{ productId: 1, quantity: 2 }];
+      mockRepository.save.mockResolvedValue({ id: 1, items });
+
+      // Act
+      const result = await orderService.createOrder(items);
+
+      // Assert
+      expect(result.id).toBe(1);
+      expect(mockRepository.save).toHaveBeenCalledWith(
+        expect.objectContaining({ items })
+      );
+    });
+
+    it('should throw ValidationError when items empty', async () => {
+      // Arrange & Act & Assert
+      await expect(orderService.createOrder([]))
+        .rejects.toThrow(ValidationError);
+    });
+  });
+});
+```

package/templates/.claude/rules/06-code-quality.md

@@ -0,0 +1,107 @@
+# Code Quality
+
+> Quality code is readable, maintainable, and consistently formatted.
+
+---
+
+## Code Documentation
+
+### Self-Documenting Code First
+
+- Use clear, descriptive names
+- Break complex logic into well-named functions
+- Keep functions small and focused
+- If code needs comments to explain, consider refactoring
+
+### When to Comment
+
+- Explain **why**, not what (the code shows what)
+- Document complex algorithms and business logic
+- Explain workarounds with issue references
+- Document public APIs and interfaces
+- Note performance considerations
+
+```typescript
+// BAD - Obvious comment
+// Increment counter by 1
+counter++;
+
+// BAD - Outdated comment
+// Check if user is admin (WRONG - now checks manager too)
+if (user.role === 'admin' || user.role === 'manager') {}
+
+// GOOD - Explains why
+// Using binary search because dataset exceeds 10k items
+// and linear search caused 2s+ response times (see #1234)
+const result = binarySearch(sortedItems, target);
+
+// GOOD - Documents public API
+/**
+ * Calculates shipping cost based on weight and destination.
+ * @param weightKg - Package weight in kilograms
+ * @param destinationCode - ISO country code
+ * @returns Shipping cost in USD
+ * @throws InvalidDestinationError if country not supported
+ */
+function calculateShipping(weightKg: number, destinationCode: string): number {}
+```
+
+---
+
+## Code Formatting - Pretty Code is Happy Code
+
+### Principles
+
+- Consistent formatting makes code more readable and professional
+- Formatting should be automatic, not manual
+- **Key tip:** Set up automatic formatting in your IDE to handle this on save
+
+### Best Practices
+
+- Use consistent indentation (spaces vs tabs - pick one)
+- Use consistent line length (80-120 characters)
+- Add blank lines to separate logical sections
+- Group related imports together
+- Use a code formatter (Prettier, Black, gofmt)
+
+### Setup Recommendations
+
+```json
+// .prettierrc
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}
+```
+
+### Linting Tools by Language
+
+| Language | Formatter | Linter |
+|----------|-----------|--------|
+| JavaScript/TypeScript | Prettier | ESLint |
+| Python | Black | Pylint, Ruff |
+| Go | gofmt | golint |
+| Rust | rustfmt | Clippy |
+| Java | google-java-format | Checkstyle |
+
+---
+
+## Code Review Standards
+
+### As a Reviewer
+
+- Review for correctness, security, and maintainability
+- Be constructive and specific
+- Ask questions rather than make demands
+- Approve when good enough, not perfect
+
+### As an Author
+
+- Keep PRs small and focused
+- Write clear PR descriptions
+- Self-review before requesting review
+- Respond to feedback professionally
+- Don't take criticism personally

package/templates/.claude/rules/07-architecture.md

@@ -0,0 +1,105 @@
+# Code Organization & Architecture
+
+> Well-organized code is easier to navigate, understand, and maintain.
+
+---
+
+## File Structure Principles
+
+- Group by feature, not by type (prefer feature-based over layer-based)
+- Keep folder structure flat (avoid deep nesting)
+- Separate concerns: UI, business logic, data access
+- Use consistent naming across the project
+
+### Recommended Structure
+
+```
+src/
+  features/
+    auth/
+      components/
+      hooks/
+      services/
+      types/
+      index.ts
+    users/
+    orders/
+  shared/
+    components/
+    hooks/
+    utils/
+    constants/
+    types/
+  core/
+    api/
+    config/
+    errors/
+tests/
+docs/
+```
+
+### File Size Guidelines
+
+- Keep files under 200-300 lines
+- Split large files into focused modules
+- One component/class per file
+- Extract constants, types, and utilities
+
+---
+
+## Dependency Management - Less is More
+
+### Principles
+
+- Each dependency is a potential point of failure and maintenance burden
+- Choose dependencies wisely and keep them minimal
+- Regularly audit dependencies and remove unused ones
+- Prefer well-maintained, widely-used packages
+
+### Best Practices
+
+```typescript
+// BAD - Importing entire library
+import * as lodash from 'lodash';
+lodash.map(items, fn);
+
+// GOOD - Import only what you need
+import { map, filter } from 'lodash';
+map(items, fn);
+
+// BETTER - Use native methods when sufficient
+items.map(fn);
+```
+
+### Dependency Checklist
+
+- [ ] Is this dependency actively maintained?
+- [ ] Does it have known security vulnerabilities?
+- [ ] Can I achieve this with native language features?
+- [ ] Is the bundle size impact acceptable?
+- [ ] What happens if this dependency is abandoned?
+
+---
+
+## Module Boundaries
+
+### Clean Architecture Layers
+
+```
+┌─────────────────────────────────────┐
+│         Presentation Layer          │  UI, Controllers, API Routes
+├─────────────────────────────────────┤
+│         Application Layer           │  Use Cases, Services
+├─────────────────────────────────────┤
+│           Domain Layer              │  Entities, Business Rules
+├─────────────────────────────────────┤
+│        Infrastructure Layer         │  DB, External APIs, File System
+└─────────────────────────────────────┘
+```
+
+### Rules
+
+- Dependencies point inward (outer layers depend on inner)
+- Domain layer has no external dependencies
+- Use interfaces at boundaries for loose coupling
+- Keep business logic out of controllers/routes

package/templates/.claude/rules/08-performance-security.md

@@ -0,0 +1,93 @@
+# Performance & Security
+
+> Fast, secure code protects users and provides great experiences.
+
+---
+
+## Performance Best Practices
+
+### General
+
+- Measure before optimizing (avoid premature optimization)
+- Cache expensive computations
+- Use lazy loading for heavy resources
+- Minimize network requests
+- Use appropriate data structures
+
+### Database
+
+- Index frequently queried columns
+- Select only needed columns (avoid SELECT *)
+- Use WHERE clauses to filter early
+- Optimize JOIN conditions
+- Use EXPLAIN to analyze query plans
+- Consider pagination for large datasets
+- Use connection pooling
+
+### Frontend
+
+- Minimize bundle size
+- Lazy load routes and components
+- Optimize images and assets
+- Use virtualization for long lists
+- Debounce/throttle expensive operations
+
+---
+
+## Security Best Practices
+
+### OWASP Top 10 Awareness
+
+- Validate and sanitize ALL user input
+- Use parameterized queries (prevent SQL injection)
+- Encode output (prevent XSS)
+- Implement proper authentication and session management
+- Use HTTPS everywhere
+- Apply principle of least privilege
+
+### Secure Coding
+
+```typescript
+// BAD - SQL Injection vulnerable
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD - Parameterized query
+const query = 'SELECT * FROM users WHERE id = $1';
+await db.query(query, [userId]);
+
+// BAD - XSS vulnerable
+element.innerHTML = userInput;
+
+// GOOD - Safe output
+element.textContent = userInput;
+```
+
+### Secrets Management
+
+- Never commit secrets to version control
+- Use environment variables or secret managers
+- Rotate credentials regularly
+- Use different credentials per environment
+
+### Input Validation
+
+```typescript
+// Always validate at system boundaries
+function createUser(input: unknown): User {
+  // Validate structure
+  if (!isObject(input)) throw new ValidationError('Invalid input');
+
+  // Validate required fields
+  const { email, password, name } = input;
+  if (!email || !isEmail(email)) throw new ValidationError('Invalid email');
+  if (!password || password.length < 8) throw new ValidationError('Password too short');
+  if (!name || name.length < 2) throw new ValidationError('Name required');
+
+  // Sanitize before use
+  return {
+    email: sanitizeEmail(email),
+    password: hashPassword(password),
+    name: sanitizeString(name),
+  };
+}
+```