ai-qakit 1.0.0

package/templates/.claude/doc-templates/development-rules.md

@@ -0,0 +1,553 @@
+# Development Rules
+
+> **Senior Developer Engineering Best Practices**
+> This document defines coding standards and best practices that apply across all programming languages and platforms.
+
+---
+
+## Core Principles
+
+### YAGNI - You Aren't Gonna Need It
+- Only implement features when they are actually needed, not when you foresee they might be useful
+- Avoid overengineering and premature optimization
+- Focus on current iteration requirements in Agile workflows
+- Delete unused code rather than commenting it out "for later"
+
+### KISS - Keep It Simple, Stupid
+- Prefer the simplest solution that solves the problem
+- Complex solutions are harder to debug, test, and extend
+- If code requires extensive comments to explain, consider refactoring
+- Break complex logic into smaller, focused functions
+
+### DRY - Don't Repeat Yourself
+- Every piece of knowledge should have a single, authoritative representation
+- Extract repeated logic into reusable functions, classes, or modules
+- Create centralized services for common operations (authentication, validation, formatting)
+- Balance DRY with readability - KISS takes precedence over DRY when they conflict
+
+---
+
+## SOLID Principles (Object-Oriented Design)
+
+### Single Responsibility Principle (SRP)
+- A class/module should have only one reason to change
+- Keep each component focused on one job
+- Split large classes with multiple responsibilities
+
+### Open/Closed Principle (OCP)
+- Software should be open for extension but closed for modification
+- Add new behavior without changing existing code
+- Use interfaces, abstract classes, and composition
+
+### Liskov Substitution Principle (LSP)
+- Subclasses should be substitutable for their parent classes
+- Derived classes must honor the contracts of their base classes
+- Avoid inheritance that breaks expected behavior
+
+### Interface Segregation Principle (ISP)
+- Clients should not depend on interfaces they don't use
+- Split large interfaces into smaller, specific ones
+- Prefer many small interfaces over one large interface
+
+### Dependency Inversion Principle (DIP)
+- Depend on abstractions, not concrete implementations
+- High-level modules should not depend on low-level modules
+- Use dependency injection to promote loose coupling
+
+---
+
+## Naming Conventions
+
+### General Rules
+- Use meaningful, descriptive names that convey purpose
+- Avoid abbreviations and single-letter variables (except loop counters in small scopes)
+- Names should be pronounceable for easier code reviews
+- Be consistent throughout the codebase
+
+### Variable Naming
+```
+BAD:  x, tmp, data, val, usr, btn, idx, arr, cb, e, d, t, n
+GOOD: totalScore, temporaryFile, userData, calculatedValue, currentUser,
+      submitButton, targetIndex, activeUsers, onCompleteCallback,
+      authenticationError, currentDate, startTimestamp, itemCount
+```
+
+### Function/Method Naming
+- Use verbs for actions: `calculateTotal()`, `fetchUserData()`, `validateInput()`
+- Use `is/has/can/should` prefixes for booleans: `isActive()`, `hasPermission()`, `canEdit()`
+- Avoid functions with "and" in the name - split into multiple functions
+- Be consistent: don't mix `fetch`, `get`, and `retrieve` for similar operations
+
+### Class Naming
+- Use nouns and noun phrases: `Customer`, `OrderProcessor`, `PaymentGateway`
+- Use PascalCase/UpperCamelCase for class names
+- Avoid generic names like `Manager`, `Handler`, `Data` without context
+
+### Constants
+- Use SCREAMING_SNAKE_CASE: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT_MS`
+- Group related constants in objects/enums
+- Never use magic numbers or strings in code
+
+### Language-Specific Conventions
+| Element | Python/Ruby | JavaScript/TypeScript | Java/C# | Go |
+|---------|-------------|----------------------|---------|-----|
+| Variables | snake_case | camelCase | camelCase | camelCase |
+| Functions | snake_case | camelCase | camelCase | PascalCase (exported) |
+| Classes | PascalCase | PascalCase | PascalCase | PascalCase |
+| Constants | UPPER_SNAKE | UPPER_SNAKE | UPPER_SNAKE | PascalCase |
+| Files | snake_case | kebab-case or camelCase | PascalCase | snake_case |
+
+---
+
+## Constants & Magic Values
+
+### Rules
+- Extract ALL hardcoded values into named constants
+- Create dedicated constants files: `constants.ts`, `constants.py`, `Constants.java`
+- Group related constants logically
+- Document the purpose of non-obvious constants
+
+### Examples
+```typescript
+// BAD - Magic numbers and strings
+if (user.age >= 18) { /* ... */ }
+if (status === 'active') { /* ... */ }
+setTimeout(callback, 3600000);
+if (items.length > 100) { /* ... */ }
+
+// GOOD - Named constants
+export const MINIMUM_ADULT_AGE = 18;
+export const USER_STATUS = {
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+  PENDING: 'pending',
+} as const;
+export const ONE_HOUR_MS = 60 * 60 * 1000;
+export const MAX_ITEMS_PER_PAGE = 100;
+
+if (user.age >= MINIMUM_ADULT_AGE) { /* ... */ }
+if (status === USER_STATUS.ACTIVE) { /* ... */ }
+setTimeout(callback, ONE_HOUR_MS);
+if (items.length > MAX_ITEMS_PER_PAGE) { /* ... */ }
+```
+
+---
+
+## 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();
+}
+```
+
+---
+
+## Function Design
+
+### 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
+
+### 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
+```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...
+}
+```
+
+---
+
+## 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
+
+### 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()
+});
+```
+
+---
+
+## Testing
+
+### 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
+
+### 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
+
+---
+
+## 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 Organization & Architecture
+
+### 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
+
+---
+
+## 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
+
+---
+
+## Version Control & Git
+
+### Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- Write in imperative mood: "Add feature" not "Added feature"
+- Keep subject line under 50 characters
+- Reference issue numbers when applicable
+
+```
+feat(auth): add OAuth2 login support
+
+- Implement Google OAuth2 provider
+- Add session management for OAuth users
+- Update user model with OAuth fields
+
+Closes #123
+```
+
+### Branch Strategy
+- Use feature branches
+- Keep branches short-lived
+- Rebase or merge regularly from main
+- Delete branches after merging
+
+### Pre-commit/Push Rules
+- Run linting before commit
+- Run tests before push
+- Never commit sensitive data
+- Keep commits focused and atomic
+
+---
+
+## 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
+
+---
+
+## Quick Reference Checklist
+
+Before committing code, verify:
+
+- [ ] No magic numbers or strings - all values in constants
+- [ ] Descriptive variable and function names
+- [ ] Functions follow single responsibility principle
+- [ ] Proper error handling with meaningful messages
+- [ ] Sensitive data not logged or exposed
+- [ ] Tests written and passing
+- [ ] No code duplication - utils extracted
+- [ ] Code is readable without excessive comments
+- [ ] Security considerations addressed
+- [ ] Performance implications considered
+
+---
+
+## Sources & Further Reading
+
+- [Clean Code Principles - Caltech](https://pg-p.ctme.caltech.edu/blog/coding/clean-code-principles)
+- [Software Engineering Best Practices 2025](https://zencoder.ai/blog/software-engineering-best-practices)
+- [SOLID, DRY, KISS Principles](https://scalastic.io/en/solid-dry-kiss/)
+- [Naming Conventions Guide](https://www.theserverside.com/feature/A-guide-to-common-variable-naming-conventions)
+- [Error Handling & Logging Checklist](https://www.iansresearch.com/resources/all-blogs/post/security-blog/2023/08/17/error-handling-and-logging-checklist)
+- [Logging Best Practices](https://betterstack.com/community/guides/logging/logging-best-practices/)
+- [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)
+- [Unit Testing Best Practices - IBM](https://www.ibm.com/think/insights/unit-testing-best-practices)
+- [Code Documentation Best Practices](https://blog.codacy.com/code-documentation)
+- [SQL Query Optimization - DataCamp](https://www.datacamp.com/blog/sql-query-optimization)
+- [Clean Code by Robert C. Martin](https://www.freecodecamp.org/news/how-to-write-clean-code/)

package/templates/.claude/doc-templates/feature-spec-template.md

@@ -0,0 +1,167 @@
+# Feature Specification Template
+
+## Overview
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | [MODULE]-[NUMBER] |
+| **Feature Name** | [Feature name] |
+| **Module** | [Module name] |
+| **Priority** | P0 / P1 / P2 / P3 |
+| **Status** | Draft / Ready for QA / In Testing / Done |
+| **Jira Epic** | [PROJ-XXX](https://jira.company.com/browse/PROJ-XXX) |
+| **Confluence** | [Link](https://confluence.company.com/...) |
+| **Created** | YYYY-MM-DD |
+| **Last Updated** | YYYY-MM-DD |
+| **Author** | [Name] |
+
+---
+
+## Description
+
+[Mô tả tổng quan feature - mục đích, scope, và context]
+
+---
+
+## User Stories
+
+### US-001: [Story Title]
+
+| Field | Value |
+|-------|-------|
+| **Jira** | [PROJ-101](https://jira.company.com/browse/PROJ-101) |
+| **Priority** | P0 / P1 / P2 / P3 |
+| **Sprint** | Sprint XX |
+| **Assignee** | [Dev name] |
+
+**As a** [role/persona]
+**I want** [feature/capability]
+**So that** [benefit/value]
+
+#### Acceptance Criteria
+
+| ID | Criteria | Type | Testable |
+|----|----------|------|----------|
+| AC-001 | WHEN [trigger] THEN [expected result] | Functional | ✅ |
+| AC-002 | WHEN [trigger] THEN [expected result] | Functional | ✅ |
+| AC-003 | WHEN [error condition] THEN [error handling] | Error | ✅ |
+
+#### UI/UX Notes
+
+- [UI behavior notes]
+- [Design link if available]
+
+---
+
+### US-002: [Story Title]
+
+| Field | Value |
+|-------|-------|
+| **Jira** | [PROJ-102](https://jira.company.com/browse/PROJ-102) |
+| **Priority** | P1 |
+| **Sprint** | Sprint XX |
+
+**As a** [role]
+**I want** [feature]
+**So that** [benefit]
+
+#### Acceptance Criteria
+
+| ID | Criteria | Type | Testable |
+|----|----------|------|----------|
+| AC-004 | WHEN [trigger] THEN [expected result] | Functional | ✅ |
+
+---
+
+## Business Rules
+
+| Rule ID | Description | Source |
+|---------|-------------|--------|
+| BR-001 | [Business rule description] | [Jira/Confluence link] |
+| BR-002 | [Business rule description] | [Jira/Confluence link] |
+
+---
+
+## Technical Details
+
+### API Endpoints
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| POST | `/api/xxx` | [Description] | Required |
+| GET | `/api/xxx/:id` | [Description] | Required |
+
+### Database Changes
+
+| Table | Change | Description |
+|-------|--------|-------------|
+| [table_name] | Add column | [Description] |
+
+### UI Pages/Components
+
+| Page/Component | URL/Location | Description |
+|----------------|--------------|-------------|
+| [Page name] | `/path` | [Description] |
+
+---
+
+## Test Scope
+
+| Test Type | In Scope | Priority | Notes |
+|-----------|----------|----------|-------|
+| Functional | ✅ / ❌ | P0 | [Notes] |
+| API | ✅ / ❌ | P0 | [Notes] |
+| UI/E2E | ✅ / ❌ | P1 | [Notes] |
+| Integration | ✅ / ❌ | P1 | [Notes] |
+| Performance | ✅ / ❌ | P2 | [Notes] |
+| Security | ✅ / ❌ | P1 | [Notes] |
+| Accessibility | ✅ / ❌ | P2 | [Notes] |
+
+---
+
+## Dependencies
+
+### Prerequisites
+
+- [ ] [Dependency 1 - e.g., API deployed]
+- [ ] [Dependency 2 - e.g., Test data ready]
+- [ ] [Dependency 3 - e.g., Environment configured]
+
+### Related Features
+
+| Feature | Relationship | Status |
+|---------|--------------|--------|
+| [Feature name] | Depends on / Blocks | Done / In Progress |
+
+---
+
+## Test Cases (Generated)
+
+| Test Case ID | Title | Priority | Status |
+|--------------|-------|----------|--------|
+| [MODULE-FEATURE-001] | [Title] | P0 | Not Created |
+| [MODULE-FEATURE-002] | [Title] | P1 | Not Created |
+
+---
+
+## Risks & Mitigations
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| [Risk description] | High/Medium/Low | High/Medium/Low | [Mitigation plan] |
+
+---
+
+## Notes
+
+- [Additional context, assumptions, or constraints]
+- [Links to related documents]
+
+---
+
+## Change History
+
+| Date | Author | Changes |
+|------|--------|---------|
+| YYYY-MM-DD | [Name] | Initial version |
+