docs(agent-docs): added

2026-02-08 12:46:48 +07:00
parent c2e0510759
commit 1eb0f7f3b0
8 changed files with 14274 additions and 0 deletions
--- a/docs/code-standards.md
+++ b/docs/code-standards.md
@@ -0,0 +1,883 @@
+# Code Standards & Development Guidelines
+
+---
+
+## 1. Python Code Standards (Search Engine & Design System)
+
+### 1.1 General Style
+
+**Compliance:** PEP 8 with pragmatism
+**Tools:** Black (code formatter), flake8 (linter), mypy (type checking)
+**Min Python:** 3.8+
+
+### 1.2 File Structure
+
+```python
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Module docstring (purpose, usage, examples)
+"""
+
+import <stdlib>
+from <stdlib> import <specific>
+import <third-party>
+from <third-party> import <specific>
+
+# ============ CONFIGURATION ============
+CONSTANT_NAME = value
+DICT_CONFIG = {...}
+
+# ============ CLASS DEFINITIONS ============
+class ClassName:
+    """Class docstring"""
+
+    def __init__(self):
+        """Initialize"""
+        pass
+
+    def method_name(self):
+        """Method docstring"""
+        pass
+
+# ============ FUNCTION DEFINITIONS ============
+def function_name(param1, param2):
+    """Function docstring with Args, Returns, Raises"""
+    pass
+
+# ============ MAIN ENTRY ============
+if __name__ == "__main__":
+    main()
+```
+
+### 1.3 Naming Conventions
+
+| Type | Format | Example |
+|------|--------|---------|
+| **Constants** | UPPER_SNAKE_CASE | `MAX_RESULTS = 3` |
+| **Functions** | snake_case | `def _load_csv():` |
+| **Classes** | PascalCase | `class BM25:` |
+| **Private** | _snake_case prefix | `def _internal_function():` |
+| **Dunder** | __name__ (avoid custom) | `__init__, __str__` |
+| **Variables** | snake_case | `query_result = []` |
+
+### 1.4 Docstring Format
+
+```python
+def search(query, domain=None, max_results=MAX_RESULTS):
+    """
+    Main search function with auto-domain detection.
+
+    Args:
+        query (str): Search query string
+        domain (str, optional): Specific domain to search. If None, auto-detect.
+        max_results (int): Maximum number of results (default: 3)
+
+    Returns:
+        dict: Result dictionary with keys: domain, query, file, count, results
+
+    Raises:
+        FileNotFoundError: If CSV file not found
+        ValueError: If domain is invalid
+
+    Example:
+        >>> result = search("minimalism", "style", 5)
+        >>> print(result['count'])  # 3
+    """
+    pass
+```
+
+### 1.5 Imports & Dependencies
+
+**Rule:** Minimize external dependencies for portability
+
+```python
+# Good
+import csv
+from pathlib import Path
+from math import log
+
+# Avoid
+import numpy  # Not in stdlib, adds weight
+import requests  # Use only if absolutely necessary
+```
+
+**Organization:**
+1. Stdlib imports first
+2. Third-party imports next (none for search engine)
+3. Local imports last
+4. Blank line between groups
+
+### 1.6 Error Handling
+
+```python
+# Good
+try:
+    result = _search_csv(filepath, columns, query, max_results)
+except FileNotFoundError:
+    return {"error": f"File not found: {filepath}", "domain": domain}
+except Exception as e:
+    logger.error(f"Unexpected error: {e}")
+    raise
+
+# Avoid
+try:
+    # code
+except:
+    pass  # Silent failures are bad
+```
+
+### 1.7 Type Hints
+
+**Required for:**
+- Public function signatures
+- Class methods with complex logic
+- Design system generator (all methods)
+
+**Format:**
+```python
+def _search_csv(
+    filepath: Path,
+    search_cols: list[str],
+    output_cols: list[str],
+    query: str,
+    max_results: int
+) -> list[dict]:
+    """Search CSV and return results."""
+    pass
+
+# Return types
+def get_results(self) -> dict[str, any]:
+    pass
+```
+
+### 1.8 Code Comments
+
+**Good comments explain WHY, not WHAT:**
+
+```python
+# Good
+# BM25 uses k1=1.5 and b=0.75 (standard tuning for document length normalization)
+idf = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+# Avoid
+# Calculate log
+idf = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+
+# Good
+# Exclude words < 3 chars to reduce noise (and, the, a, etc.)
+return [w for w in text.split() if len(w) > 2]
+
+# Avoid
+# Filter words
+return [w for w in text.split() if len(w) > 2]
+```
+
+### 1.9 Line Length
+
+- **Maximum:** 100 characters (flexible for URLs/strings)
+- **Readability:** Break long lines at logical operators
+
+```python
+# Good
+if (config_exists and
+    permission_granted and
+    not already_installed):
+    proceed()
+
+# Avoid
+if config_exists and permission_granted and not already_installed and something_else: proceed()
+```
+
+### 1.10 CSV Handling
+
+**Rules:**
+1. Always use UTF-8 encoding
+2. Handle missing fields gracefully
+3. Preserve field order for consistency
+4. Use DictReader/DictWriter for clarity
+
+```python
+# Good
+with open(filepath, 'r', encoding='utf-8') as f:
+    reader = csv.DictReader(f)
+    data = list(reader)
+
+# Handle missing
+value = row.get('Column', 'default_value')
+
+# Avoid
+open(filepath)  # No encoding specified
+row['Column']  # KeyError if missing
+```
+
+### 1.11 Windows Compatibility
+
+```python
+# Good - UTF-8 for emoji/special chars on Windows
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+# Good - Use pathlib for cross-platform paths
+from pathlib import Path
+filepath = Path(__file__).parent / "data" / "styles.csv"
+
+# Avoid
+filepath = f"{os.getcwd()}\\data\\styles.csv"  # Windows-specific
+```
+
+---
+
+## 2. TypeScript Code Standards (CLI)
+
+### 2.1 General Style
+
+**Compliance:** ESLint (airbnb config) + Prettier
+**Min TypeScript:** 4.8+
+**Target:** Node 18+
+
+### 2.2 File Structure
+
+```typescript
+/**
+ * Module purpose and usage
+ */
+
+import type { TypeName } from './types/index';
+import { functionName } from './utils/logger';
+
+// ============ TYPES ============
+interface ConfigOptions {
+  platform: string;
+  offline?: boolean;
+}
+
+// ============ CONSTANTS ============
+const PLATFORMS = ['claude', 'cursor', 'windsurf'] as const;
+const DEFAULT_TIMEOUT = 30000;
+
+// ============ EXPORTED FUNCTIONS ============
+export async function initCommand(options: ConfigOptions): Promise<void> {
+  // implementation
+}
+
+// ============ PRIVATE FUNCTIONS ============
+function detectPlatform(): string {
+  // implementation
+}
+
+// ============ MAIN ENTRY ============
+export default function main() {
+  // entry point
+}
+```
+
+### 2.3 Naming Conventions
+
+| Type | Format | Example |
+|------|--------|---------|
+| **Constants** | UPPER_SNAKE_CASE | `const MAX_RETRIES = 3` |
+| **Functions** | camelCase | `function detectPlatform()` |
+| **Classes** | PascalCase | `class TemplateRenderer` |
+| **Interfaces** | PascalCase | `interface ConfigOptions` |
+| **Types** | PascalCase | `type Platform = 'claude' \| 'cursor'` |
+| **Variables** | camelCase | `let platformName = 'claude'` |
+| **Private** | leadingUnderscore | `_internalFunction()` |
+| **Files** | kebab-case | `template-renderer.ts`, `detect.ts` |
+
+### 2.4 Type Definitions
+
+**Rules:**
+1. Always export types from `types/index.ts`
+2. Use `type` for unions/aliases, `interface` for objects
+3. Strict null checking enabled
+
+```typescript
+// types/index.ts
+export interface InitOptions {
+  platform: 'claude' | 'cursor' | 'windsurf';
+  offline?: boolean;
+  outputDir?: string;
+}
+
+export type Platform = InitOptions['platform'];
+
+// Usage
+export async function init(options: InitOptions): Promise<void> {
+  const platform: Platform = options.platform;
+}
+```
+
+### 2.5 Async/Await
+
+```typescript
+// Good
+async function downloadAssets(): Promise<void> {
+  try {
+    const data = await fetchFromGitHub(url);
+    await writeFiles(data);
+  } catch (error) {
+    logger.error(`Download failed: ${error.message}`);
+    throw new Error('Failed to download assets');
+  }
+}
+
+// Avoid
+function downloadAssets() {
+  return new Promise((resolve, reject) => {
+    // callback hell
+  });
+}
+```
+
+### 2.6 Error Handling
+
+```typescript
+// Good - Custom error types
+class InstallerError extends Error {
+  constructor(message: string, public platform?: string) {
+    super(message);
+    this.name = 'InstallerError';
+  }
+}
+
+// Usage
+try {
+  await installSkill(platform);
+} catch (error) {
+  if (error instanceof InstallerError) {
+    logger.error(`Installation failed for ${error.platform}: ${error.message}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+### 2.7 Comments & Documentation
+
+```typescript
+/**
+ * Detects the current AI coding assistant platform.
+ *
+ * @returns The detected platform name, or 'unknown' if not detected
+ *
+ * @example
+ * const platform = detectPlatform();
+ * console.log(platform); // 'claude'
+ */
+function detectPlatform(): string {
+  // implementation
+}
+```
+
+### 2.8 Module Exports
+
+```typescript
+// Good - Named exports for tree-shaking
+export { initCommand } from './commands/init';
+export { updateCommand } from './commands/update';
+export type { ConfigOptions } from './types/index';
+
+// Avoid
+export default { initCommand, updateCommand };  // Default export
+export * from './types';  // Wildcard exports (less clear)
+```
+
+---
+
+## 3. CSV Data Format Standards
+
+### 3.1 Structure Requirements
+
+**Rules:**
+1. UTF-8 encoding (no BOM)
+2. Unix line endings (LF, not CRLF)
+3. Comma-separated values
+4. Header row with descriptive names
+5. Consistent data types per column
+
+### 3.2 CSV Header Naming
+
+```csv
+# Good - Clear, no special chars
+Style Category,Type,Keywords,Best For,Performance,Accessibility
+
+# Avoid
+StyleCat,T,KW,BF,Perf,A11y  # Unclear abbreviations
+style_category,type,keywords  # snake_case in CSV (use PascalCase)
+```
+
+### 3.3 Field Requirements
+
+**All Fields:**
+- Non-empty unless explicitly optional
+- Properly escaped if containing quotes/commas
+- Consistent data type per column
+
+```csv
+Style Category,Keywords,Best For
+"Glassmorphism","glass, frosted, transparency, modern",SaaS apps
+"Claymorphism","clay, soft, rounded, tactile",Educational apps
+```
+
+### 3.4 Data Consistency
+
+| Domain | Requirement | Example |
+|--------|------------|---------|
+| **Styles** | Consistent capitalization | "Glassmorphism" not "glassmorphism" |
+| **Colors** | Valid hex format | #E8B4B8 not E8B4B8 or #e8b4b8 (case-insensitive OK) |
+| **Products** | Consistent categories | "SaaS" not "saas" or "SAAS" |
+| **URLs** | Absolute, http/https | https://fonts.google.com/... |
+| **Lists** | Comma-separated, consistent | "item1, item2, item3" |
+
+### 3.5 Search Column Selection
+
+**Rules:**
+1. Include searchable columns in config
+2. Exclude very long text (use truncation in output)
+3. Prioritize frequently-searched fields
+
+```python
+# In core.py CSV_CONFIG
+"style": {
+    "file": "styles.csv",
+    "search_cols": ["Style Category", "Keywords", "Best For", "Type", "AI Prompt Keywords"],
+    "output_cols": ["Style Category", "Type", "Keywords", ..., "Design System Variables"]
+}
+```
+
+### 3.6 Size Guidelines
+
+| File | Max Rows | Max Size | Rationale |
+|------|----------|----------|-----------|
+| styles.csv | 100 | 100KB | Most important, larger acceptable |
+| typography.csv | 100 | 50KB | Detailed font information |
+| products.csv | 150 | 50KB | Comprehensive product coverage |
+| colors.csv | 150 | 50KB | Industry-specific palettes |
+| Others | 50 | 20KB | Specialized domains |
+
+---
+
+## 4. Git & Version Control
+
+### 4.1 Branching Strategy
+
+**Pattern:** `<type>/<description>`
+
+```bash
+# Feature development
+git checkout -b feat/add-design-system-caching
+git checkout -b feat/support-droid-platform
+
+# Bug fixes
+git checkout -b fix/windows-unicode-emoji
+git checkout -b fix/version-mismatch-plugin
+
+# Documentation
+git checkout -b docs/update-codebase-summary
+
+# Refactoring
+git checkout -b refactor/modularize-design-system
+
+# Never commit directly to main
+```
+
+### 4.2 Commit Message Format
+
+**Standard:** Conventional Commits
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation
+- `refactor:` - Code restructuring
+- `perf:` - Performance improvement
+- `test:` - Test additions
+- `chore:` - Build, CI, dependencies
+
+**Examples:**
+```bash
+git commit -m "feat(design-system): add caching for repeated queries"
+git commit -m "fix(cli): resolve Windows emoji encoding issue"
+git commit -m "docs(readme): update installation instructions"
+git commit -m "refactor(search): extract reasoning rules to separate module"
+```
+
+### 4.3 Code Review Checklist
+
+Before pushing, verify:
+- [ ] Code follows style standards (Python PEP 8, TypeScript ESLint)
+- [ ] No hardcoded values or secrets
+- [ ] Tests pass (if applicable)
+- [ ] Linting passes
+- [ ] Documentation updated
+- [ ] Version numbers correct
+- [ ] Commit message is descriptive
+- [ ] No unnecessary files committed
+
+### 4.4 Release Process
+
+```bash
+# 1. Update version numbers
+# - cli/package.json
+# - .claude-plugin/marketplace.json
+# - .claude-plugin/plugin.json
+
+# 2. Update CHANGELOG
+# - Note what changed, list new features/fixes
+
+# 3. Sync CLI assets
+cp -r src/ui-ux-pro-max/data/* cli/assets/data/
+cp -r src/ui-ux-pro-max/scripts/* cli/assets/scripts/
+cp -r src/ui-ux-pro-max/templates/* cli/assets/templates/
+
+# 4. Build and test
+cd cli && bun run build
+node dist/index.js init --ai claude --offline
+
+# 5. Publish
+npm publish
+
+# 6. Tag release
+git tag -a v2.2.3 -m "Release v2.2.3"
+git push origin v2.2.3
+```
+
+---
+
+## 5. Testing Standards
+
+### 5.1 Python Tests (pytest)
+
+**Location:** `tests/test_*.py`
+**Target Coverage:** ≥ 70%
+
+```python
+# tests/test_core.py
+import pytest
+from core import BM25, search
+
+class TestBM25:
+    """Test BM25 ranking algorithm"""
+
+    def test_tokenize_removes_short_words(self):
+        bm25 = BM25()
+        tokens = bm25.tokenize("the quick brown fox jumps")
+        assert "the" not in tokens
+        assert "quick" in tokens
+
+    def test_search_returns_top_results(self):
+        result = search("minimalism", "style", max_results=3)
+        assert result['count'] <= 3
+        assert 'Minimalism' in [r.get('Style Category') for r in result['results']]
+
+@pytest.mark.skip(reason="Requires CSV files")
+def test_design_system_generation():
+    """Design system generation test"""
+    pass
+```
+
+### 5.2 TypeScript Tests (vitest)
+
+**Location:** `cli/src/__tests__/test_*.ts`
+**Target Coverage:** ≥ 70%
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { detectPlatform } from '../utils/detect';
+
+describe('Platform Detection', () => {
+  it('should detect Claude Code', () => {
+    process.env.CLAUDE_CODE = 'true';
+    const platform = detectPlatform();
+    expect(platform).toBe('claude');
+  });
+
+  it('should return unknown for undetected platform', () => {
+    delete process.env.CLAUDE_CODE;
+    const platform = detectPlatform();
+    expect(platform).toMatch(/unknown|fallback/);
+  });
+});
+```
+
+### 5.3 Integration Tests
+
+```python
+# Integration test: Full design system generation
+def test_design_system_beauty_spa():
+    """Test design system generation for beauty spa"""
+    result = generate_design_system(
+        "beauty spa wellness",
+        "Serenity Spa",
+        format="ascii"
+    )
+
+    # Assertions
+    assert "Serenity Spa" in result
+    assert "STYLE:" in result
+    assert "COLORS:" in result
+    assert "TYPOGRAPHY:" in result
+    assert "ANTI-PATTERNS:" in result
+```
+
+### 5.4 Linting & Formatting
+
+**Python:**
+```bash
+# Install
+pip install black flake8 mypy
+
+# Format
+black src/ui-ux-pro-max/scripts/
+
+# Lint
+flake8 src/ui-ux-pro-max/scripts/
+
+# Type check
+mypy src/ui-ux-pro-max/scripts/
+```
+
+**TypeScript:**
+```bash
+# Install
+npm install --save-dev eslint prettier @typescript-eslint/parser
+
+# Format
+prettier --write cli/src/
+
+# Lint
+eslint cli/src/
+
+# Type check
+tsc --noEmit
+```
+
+---
+
+## 6. Documentation Standards
+
+### 6.1 Markdown Style
+
+**File Structure:**
+```markdown
+# Main Title (H1)
+
+Brief intro (1-2 sentences)
+
+## Section (H2)
+
+Content with `code inline`
+
+### Subsection (H3)
+
+- Bullet point
+- Another point
+
+| Column 1 | Column 2 |
+|----------|----------|
+| Data | More data |
+
+## Code Blocks
+
+\`\`\`python
+# Language-specified
+def example():
+    pass
+\`\`\`
+
+## Links
+
+[Text](relative/path.md) or [Text](https://example.com)
+```
+
+### 6.2 README Requirements
+
+- [ ] One-sentence project description
+- [ ] Installation instructions (quick start)
+- [ ] Basic usage examples
+- [ ] Supported platforms/stacks
+- [ ] Contributing guidelines
+- [ ] License information
+- [ ] Links to detailed docs in `docs/`
+
+**Max Length:** 300 lines (link to docs/ for details)
+
+### 6.3 Code Example Standards
+
+**All examples must:**
+1. Be runnable (copy-paste and work)
+2. Show expected output
+3. Include comments explaining WHY
+4. Use realistic data
+
+```python
+# Good example with explanation
+def example_search():
+    """Example: Search for minimalism style"""
+    result = search("minimalism", "style", max_results=3)
+
+    # Result contains metadata + top matches
+    print(f"Domain: {result['domain']}")  # 'style'
+    print(f"Found: {result['count']} results")  # 3
+    print(result['results'][0]['Style Category'])  # 'Minimalism & Swiss Style'
+```
+
+---
+
+## 7. Accessibility Standards
+
+### 7.1 Design System Accessibility
+
+**All generated designs must:**
+1. WCAG AA compliance minimum
+2. Text contrast ≥ 4.5:1 (normal text)
+3. Focus states visible for keyboard nav
+4. Respect `prefers-reduced-motion`
+5. No information conveyed by color alone
+
+### 7.2 UI Component Accessibility
+
+```html
+<!-- Good -->
+<button class="cta" aria-label="Subscribe to newsletter">
+  Subscribe
+</button>
+
+<!-- Avoid -->
+<div class="button" onclick="...">Subscribe</div>
+```
+
+### 7.3 Color Palette Guidelines
+
+**Rules:**
+1. Check contrast ratios (WebAIM Contrast Checker)
+2. Include colorblind-safe palettes
+3. Don't rely on color alone for meaning
+4. Test with Lighthouse/axe DevTools
+
+---
+
+## 8. Performance Standards
+
+### 8.1 Python Performance
+
+| Operation | Target | Limit |
+|-----------|--------|-------|
+| CSV load | < 50ms | 100ms |
+| BM25 index | < 100ms | 200ms |
+| Single search | < 200ms | 500ms |
+| Design system | < 2s | 3s |
+
+**Optimization Strategies:**
+- Load CSVs once, cache in memory
+- Use generators for large datasets
+- Profile with `cProfile` before optimizing
+
+### 8.2 CLI Performance
+
+| Operation | Target | Limit |
+|-----------|--------|-------|
+| Platform detection | < 100ms | 200ms |
+| Template rendering | < 50ms | 100ms |
+| File generation | < 1s | 2s |
+| Full installation | < 5s | 10s |
+
+---
+
+## 9. Security Standards
+
+### 9.1 Code Security
+
+**Rules:**
+1. No hardcoded API keys/secrets
+2. No eval() or dynamic code execution
+3. Sanitize user input (file paths, queries)
+4. Validate CSV data before use
+
+```python
+# Good
+filepath = Path(__file__).parent / "data" / filename
+if not filepath.is_file():
+    raise ValueError(f"File not found: {filename}")
+
+# Avoid
+filepath = f"./data/{user_input}"  # Path traversal vulnerability
+exec(user_query)  # Code injection
+```
+
+### 9.2 Dependency Security
+
+```bash
+# Regular audits
+npm audit
+pip audit
+
+# Only add necessary dependencies
+# No "just in case" packages
+```
+
+### 9.3 Data Privacy
+
+- No telemetry without consent
+- Generated design systems stay local
+- No tracking of user queries
+
+---
+
+## 10. File Organization Best Practices
+
+### 10.1 Project Structure Enforcement
+
+**Rule:** Always edit in `src/ui-ux-pro-max/`, sync to CLI/skill
+
+```
+CORRECT:
+  1. Edit src/ui-ux-pro-max/data/styles.csv
+  2. Run sync: cp -r src/ui-ux-pro-max/data/* cli/assets/data/
+  3. Test in CLI
+  4. Commit both src/ and cli/assets/
+
+WRONG:
+  1. Edit cli/assets/data/styles.csv directly
+  2. Changes lost on next sync
+```
+
+### 10.2 CSV File Organization
+
+```
+data/
+├── styles.csv              # Must exist
+├── colors.csv              # Must exist
+├── typography.csv          # Must exist
+├── products.csv            # Must exist
+├── charts.csv              # Must exist
+├── landing.csv             # Must exist
+├── ui-reasoning.csv        # Must exist (v2.0+)
+├── ux-guidelines.csv       # Required
+├── icons.csv               # Optional
+├── react-performance.csv   # Optional
+├── web-interface.csv       # Optional
+└── stacks/                 # 13 stack CSVs
+    ├── html-tailwind.csv
+    ├── react.csv
+    └── ... (11 more)
+```
+
+---
+
+## 11. Unresolved Questions
+
+1. **Test Framework:** Should we use pytest + vitest, or add coverage tools like coverage.py?
+2. **CI/CD:** Should we add GitHub Actions for linting/testing on PR?
+3. **Python Version:** Drop support for Python 3.8 and require 3.9+ for better type hints?
+4. **Linting Config:** Should we enforce strict mypy mode or keep pragmatic?
+5. **API Stability:** How to version the Python API (core.py/design_system.py) for external users?