| name | code-annotation-patterns |
| description | 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. |
| allowed-tools | ["Read","Write","Edit","Bash","Grep","Glob"] |
Code Annotation Patterns for AI Development
Advanced patterns for annotating code with structured metadata that supports AI-assisted development workflows.
Annotation Categories
Technical Debt Markers
Structured annotations for tracking technical debt:
class UserService {
}
Severity levels:
Critical: Security vulnerabilities, data loss risksHigh: Significant maintainability or performance issuesMedium: Code quality concerns, testing gapsLow: Minor improvements, nice-to-haves
Security Annotations
def get_user_by_username(username: str):
query = f"SELECT * FROM users WHERE username = '{username}'"
Performance Annotations
public List<Match> findMatches(List<Item> items) {
}
Accessibility Annotations
export function SearchBar() {
}
Testing Annotations
func ProcessOrder(order *Order) error {
}
Semantic Tags
Change Impact Tags
Dependency Tags
async def process_payment(transaction: Transaction) -> PaymentResult:
Configuration Tags
pub struct AppConfig {
}
Annotation Formats
Inline Annotations
For single-line or small context:
const cache = createCache();
Block Annotations
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:
Structured Metadata
class EventBus {
}
Language-Specific Patterns
TypeScript/JavaScript
export function DataTable({ data, id }: Props) {
const [filter, setFilter] = useState('');
const handleFilter = useCallback((value: string) => {
setFilter(value);
}, [data, filter]);
const filteredData = useMemo(() => {
return data.filter(item => item.name.includes(filter));
}, [data]);
}
Python
@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}
"""
Go
type WorkerPool struct {
workers int
jobQueue chan Job
resultCh chan Result
}
Rust
pub struct Parser<'a> {
input: &'a str,
}
Integration with Tools
IDE Integration
Annotations can be extracted by IDE plugins:
rg "@ai-\w+" --type ts --json | jq '.text'
rg "@ai-security" -A 10
rg "@bottleneck: true" --type java
Static Analysis
Custom linters can enforce annotation standards:
module.exports = {
rules: {
'require-security-annotation': {
create(context) {
return {
FunctionDeclaration(node) {
if (node.id.name.includes('auth') || node.id.name.includes('Auth')) {
}
}
};
}
}
}
};
Documentation Generation
Extract annotations to generate documentation:
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)
Annotation Best Practices
Consistency
Use consistent annotation formats across codebase:
Completeness
Include all relevant metadata:
Maintainability
Keep annotations up-to-date:
Anti-Patterns
Don't
❌ Over-annotate obvious code
const user = getUser();
❌ Use annotations instead of fixing code
❌ Inconsistent tag naming
Do
✅ Annotate complex or non-obvious patterns
✅ Provide actionable information
✅ Link to external resources
Related Skills
- notetaker-fundamentals
- documentation-linking
Resources
