typescript-utility-types
Use when typeScript utility types, mapped types, and advanced type manipulation. Use when creating flexible, type-safe TypeScript code.
code-annotation-patterns
Use when annotating code with structured metadata, tags, and markers for AI-assisted development workflows. Covers annotation formats, semantic tags, and integration with development tools.
Full skill instructions
Advanced patterns for annotating code with structured metadata that supports AI-assisted development workflows.
Structured annotations for tracking technical debt:
/**
* @ai-tech-debt
* @category: Architecture
* @severity: High
* @effort: 2-3 days
* @impact: Maintainability, Performance
*
* This service class has grown to 1500+ lines and violates Single
* Responsibility Principle. Should be split into:
* - UserAuthService (authentication logic)
* - UserProfileService (profile management)
* - UserPreferencesService (settings/preferences)
*
* Blocking new features: User role management (#234), SSO integration (#245)
*/
class UserService {
// Implementation...
}
Severity levels:
Critical: Security vulnerabilities, data loss risksHigh: Significant maintainability or performance issuesMedium: Code quality concerns, testing gapsLow: Minor improvements, nice-to-haves# @ai-security
# @risk-level: High
# @cwe: CWE-89 (SQL Injection)
# @mitigation: Use parameterized queries
#
# SECURITY WARNING: This function constructs SQL queries dynamically.
# Although input is validated, parameterized queries would be safer.
# Current validation regex: ^[a-zA-Z0-9_]+$
# TODO(ai/security): Migrate to SQLAlchemy ORM or use parameterized queries
def get_user_by_username(username: str):
# Current implementation with string formatting
query = f"SELECT * FROM users WHERE username = '{username}'"
/**
* @ai-performance
* @complexity: O(n²)
* @bottleneck: true
* @profiling-data: 45% of request time when n > 100
* @optimization-target: O(n log n) or better
*
* This nested loop is the primary performance bottleneck for large
* datasets. Profiling shows:
* - n=10: 5ms avg
* - n=100: 120ms avg
* - n=1000: 11s avg (unacceptable)
*
* Optimization approaches:
* 1. Sort + binary search: O(n log n) - estimated 95% improvement
* 2. Hash map: O(n) - best performance but higher memory usage
* 3. Database-level optimization: Move logic to SQL query
*/
public List<Match> findMatches(List<Item> items) {
// O(n²) implementation
}
/**
* @ai-a11y
* @wcag-level: AA
* @compliance-status: Partial
* @issues:
* - Missing ARIA labels for icon buttons
* - Insufficient color contrast (3.2:1, needs 4.5:1)
* - Keyboard navigation incomplete
*
* Component needs accessibility improvements to meet WCAG 2.1 Level AA.
* Audit completed: 2025-12-04
* Blocking: Public sector deployment (requires AA compliance)
*/
export function SearchBar() {
// Implementation with partial a11y support
}
// @ai-testing
// @coverage: 45%
// @coverage-target: 80%
// @missing-tests:
// - Edge case: nil pointer handling
// - Edge case: Concurrent access scenarios
// - Integration: Database transaction rollback
//
// Test coverage is below target. Priority areas:
// 1. Error handling paths (currently untested)
// 2. Concurrent access (identified race condition in PR review)
// 3. Database edge cases (transaction boundaries)
func ProcessOrder(order *Order) error {
// Implementation with incomplete test coverage
}
/**
* @ai-change-impact
* @breaking-change: true
* @affects:
* - API consumers (public method signature changed)
* - Database migrations (requires schema update)
* - Dependent services (contract modified)
*
* This change modifies the public API contract. Migration guide:
* 1. Update API clients to use new parameter format
* 2. Run migration script: ./scripts/migrate_v2_to_v3.sh
* 3. Update environment variables (NEW_API_KEY required)
*
* Backward compatibility: Supported until v4.0.0 (2026-06-01)
*/
# @ai-dependency
# @external-service: PaymentAPI
# @failure-mode: graceful-degradation
# @fallback: offline-payment-queue
# @sla: 99.9% uptime
# @timeout: 5000ms
#
# This function depends on external payment service. Failure handling:
# - Timeout: Queue for retry, notify user of delayed processing
# - Service down: Queue for batch processing, store transaction locally
# - Invalid response: Log error, rollback transaction, notify monitoring
#
# Circuit breaker: Opens after 5 consecutive failures, half-open after 30s
async def process_payment(transaction: Transaction) -> PaymentResult:
# Implementation with external service dependency
/// @ai-config
/// @env-vars:
/// - DATABASE_URL (required)
/// - REDIS_URL (optional, falls back to in-memory cache)
/// - LOG_LEVEL (optional, default: "info")
/// @config-file: config/production.yaml
/// @secrets:
/// - API_SECRET_KEY (must be 32+ chars)
/// - JWT_PRIVATE_KEY (RSA 2048-bit minimum)
///
/// Configuration loading order:
/// 1. Environment variables (highest priority)
/// 2. config/{environment}.yaml files
/// 3. Default values (lowest priority)
pub struct AppConfig {
// Configuration fields
}
For single-line or small context:
// @ai-pattern: Singleton
// @ai-thread-safety: Not thread-safe, use in single-threaded context only
const cache = createCache();
For complex context:
"""
@ai-pattern: Factory Pattern
@ai-creational-pattern: true
@ai-rationale:
Factory pattern used here because:
1. Need to support multiple database backends (PostgreSQL, MySQL, SQLite)
2. Configuration determines which implementation to instantiate
3. Allows easy addition of new backends without modifying client code
@ai-extensibility:
To add new database backend:
1. Implement DatabaseBackend interface
2. Register in BACKEND_REGISTRY dict
3. Add configuration mapping in config/database.yaml
Example usage in docs/database-backends.md
"""
class DatabaseFactory:
# Implementation
/**
* @ai-metadata {
* "pattern": "Observer",
* "subscribers": ["LoggingService", "MetricsService", "AuditService"],
* "event-types": ["user.created", "user.updated", "user.deleted"],
* "async": true,
* "guaranteed-delivery": false
* }
*
* Event bus using observer pattern for loose coupling between services.
* Events are published async with fire-and-forget semantics (no delivery guarantee).
* For critical events requiring guaranteed delivery, use MessageQueue instead.
*/
class EventBus {
// Implementation
}
/**
* @ai-hook-usage
* @react-hooks: [useState, useEffect, useCallback, useMemo]
* @dependencies: {useCallback: [data, filter], useMemo: [data], useEffect: [id]}
* @optimization: useMemo prevents expensive recalculation on re-renders
*
* This component uses React hooks for state and side effects. Dependency arrays
* are carefully managed to prevent unnecessary re-renders and infinite loops.
*
* @ai-performance-note:
* - useMemo caches filtered results (reduces filtering from O(n) per render to once per data change)
* - useCallback memoizes event handlers (prevents child re-renders)
*/
export function DataTable({ data, id }: Props) {
const [filter, setFilter] = useState('');
const handleFilter = useCallback((value: string) => {
setFilter(value);
}, [data, filter]); // @ai-dependency-note: Both needed for closure
const filteredData = useMemo(() => {
return data.filter(item => item.name.includes(filter));
}, [data]); // @ai-optimization: Only recompute when data changes
// Implementation...
}
# @ai-decorator-stack
# @decorators: [retry, cache, log_execution, validate_auth]
# @execution-order: validate_auth -> log_execution -> cache -> retry -> function
#
# Decorator execution order matters:
# 1. validate_auth: Must run first to prevent unauthorized cache hits
# 2. log_execution: Log after auth but before cache to track all attempts
# 3. cache: After logging to avoid logging cache hits
# 4. retry: Innermost to retry actual function, not auth/logging
@validate_auth(roles=["admin", "operator"])
@log_execution(level="INFO")
@cache(ttl=300, key_func=lambda args: f"user:{args[0]}")
@retry(max_attempts=3, backoff=exponential)
def get_user_profile(user_id: int) -> UserProfile:
"""
@ai-caching-strategy: Time-based (TTL=300s)
@ai-invalidation: Manual invalidation on user.updated event
@ai-cache-key: user:{user_id}
"""
# Implementation
// @ai-concurrency
// @pattern: Worker Pool
// @workers: 10 (configurable via WORKER_POOL_SIZE)
// @channel-buffer: 100
// @backpressure-handling: Blocks when buffer full
//
// This implements a worker pool pattern for concurrent processing.
// Workers are started at server initialization and kept alive for
// the server lifetime (no dynamic scaling).
//
// @ai-monitoring:
// - Metric: worker_pool_queue_depth (current channel buffer size)
// - Metric: worker_pool_processing_time (histogram)
// - Alert: Queue depth > 80 for >5min (add workers)
type WorkerPool struct {
workers int
jobQueue chan Job
resultCh chan Result
// fields...
}
/// @ai-lifetime-annotations
/// @lifetimes: ['a, 'b]
/// @invariants:
/// - 'a must outlive 'b (parser must live longer than input)
/// - Output references bound to 'a (safe as long as input lives)
///
/// Lifetime relationships:
/// - Parser<'a> borrows input for 'a
/// - Output<'a> contains references to input (bounded by 'a)
/// - Temporary allocations use 'b (scoped to parsing only)
///
/// @ai-safety:
/// These lifetime constraints prevent dangling references by ensuring
/// the input buffer outlives all references derived from it.
pub struct Parser<'a> {
input: &'a str,
// fields...
}
Annotations can be extracted by IDE plugins:
# Extract all AI annotations
rg "@ai-\w+" --type ts --json | jq '.text'
# Find security-related annotations
rg "@ai-security" -A 10
# Find performance bottlenecks
rg "@bottleneck: true" --type java
Custom linters can enforce annotation standards:
// Example: ESLint rule to enforce @ai-security on auth functions
module.exports = {
rules: {
'require-security-annotation': {
create(context) {
return {
FunctionDeclaration(node) {
if (node.id.name.includes('auth') || node.id.name.includes('Auth')) {
// Check for @ai-security annotation
}
}
};
}
}
}
};
Extract annotations to generate documentation:
# doc_generator.py
import re
from pathlib import Path
def extract_ai_annotations(file_path):
"""Extract all @ai-* annotations from file"""
with open(file_path) as f:
content = f.read()
pattern = r'@ai-(\w+):\s*(.+)'
return re.findall(pattern, content)
# Generate markdown documentation from annotations
Use consistent annotation formats across codebase:
// ✅ GOOD - Consistent format
// @ai-pattern: Strategy
// @ai-alternatives: [Template Method, State Pattern]
// @ai-pattern: Observer
// @ai-alternatives: [Event Emitter, Pub/Sub]
// ❌ BAD - Inconsistent format
// @ai-pattern: Strategy (alternatives: Template Method, State)
// Pattern: Observer | Alternatives: Event Emitter, Pub/Sub
Include all relevant metadata:
# ✅ GOOD - Complete context
# @ai-security
# @risk-level: High
# @cwe: CWE-79 (XSS)
# @input-sanitization: HTML encoding applied
# @output-encoding: UTF-8
# @tested: XSS test suite in tests/security/xss_test.py
# ❌ BAD - Incomplete
# @ai-security
# Security risk here
Keep annotations up-to-date:
// ✅ GOOD - Dated and tracked
// @ai-tech-debt
// @added: 2025-12-04
// @reviewed: 2025-12-04
// @next-review: 2026-01-04
// ❌ BAD - Stale and outdated
// @ai-tech-debt
// TODO: Fix this eventually
❌ Over-annotate obvious code
// @ai-pattern: Variable Declaration
const user = getUser(); // Bad - obvious
❌ Use annotations instead of fixing code
# @ai-tech-debt: This is terrible code
# @ai-security: Has vulnerabilities
# @ai-performance: Slow
# Bad - just fix the code!
❌ Inconsistent tag naming
// @AI-PATTERN vs @ai-pattern vs @aiPattern
// Use consistent naming
✅ Annotate complex or non-obvious patterns
/// @ai-pattern: Typestate
/// @ai-compile-time-safety: true
///
/// Uses typestate pattern to enforce protocol state machine at compile time.
/// Impossible states are unrepresentable in type system.
✅ Provide actionable information
/**
* @ai-tech-debt
* @action: Extract UserValidator class
* @files-affected: [UserService.java, UserController.java, UserTest.java]
* @effort: 3-4 hours
* @priority: Medium
*/
✅ Link to external resources
# @ai-algorithm: Dijkstra's shortest path
# @reference: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
# @paper: "A Note on Two Problems in Connexion with Graphs" (1959)
# @optimization: Using binary heap for O((V+E) log V) complexity
Use when typeScript utility types, mapped types, and advanced type manipulation. Use when creating flexible, type-safe TypeScript code.
Use when writing shell scripts that need to run across different systems, shells, or environments. Covers POSIX compatibility and platform differences.
Use when optimizing Tailwind CSS for production, reducing bundle size, and improving performance. Covers PurgeCSS, JIT mode, and build optimization.
Generate production-ready code from a Figma component or frame using the Figma MCP server
Use when integrating Dialyzer into development workflows and CI/CD pipelines for Erlang/Elixir projects.
Use when ruboCop configuration including YAML config, departments, inheritance, and customization.
Use when Elixir OTP patterns including GenServer, Supervisor, Agent, and Task. Use when building concurrent, fault-tolerant Elixir applications.
Use when creating custom Ameba rules for Crystal code analysis including rule development, AST traversal, issue reporting, and rule testing.
Use when swift's optional handling patterns including optional binding, chaining, nil coalescing, and modern approaches to safely working with optional values while avoiding common pitfalls and force unwrapping.
Use when scala collections including immutable/mutable variants, List, Vector, Set, Map operations, collection transformations, lazy evaluation with views, parallel collections, and custom collection builders for efficient data processing.
Use when creating custom React Flow nodes, edges, and handles. Covers custom node components, resizable nodes, toolbars, and advanced customization.
Use when jUnit fundamentals including annotations, assertions, and test lifecycle for Java testing.
Generate, edit, and beat-sync AI video with leading models in one workspace.
The world's fastest calendar for remote work
Transform Your Design with AI Designer by ImgCreator.ai
Revolutionizing Video Production with AI-Powered Creativity
Extend an image past the frame and let AI fill the new aspect ratio.
Discover your celebrity doppelgänger with StarByFace!
ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.
Opus.ai: Revolutionize Your Web Experience