Found this idea in Telegram channel @llm_under_hood
Asked to Claude to improve idea and got this interesting approach.
Pros of this approach:
1. Leverages AI’s Natural Capabilities
AI agents (Cursor, Claude, Codex) are indeed excellent at using grep and searching for patterns. By creating standardized prefixes, you’re playing to their strengths.
2. Creates Persistent Context
Unlike external documentation that might get overlooked, these comments live directly in the code where AI agents are already looking.
3. Enables AI Self-Organization
The TODO system allows AI to break down complex tasks across multiple sessions – essentially creating its own work queue.
Tips
1. Use Only 3 Essential Prefixes
// AICODE-WHY: Business logic explanation (replaces long comments)
// AICODE-TRAP: Known gotchas or edge cases
// AICODE-LINK: References to related code/docs
// Example:
// AICODE-WHY: Payments >$10k need manual approval per compliance
// AICODE-TRAP: Stripe webhooks can arrive out of order
function processPayment(amount) {
// AICODE-LINK: Error handling in src/utils/payment-errors.js
return stripe.charge(amount);
}
2. One-Line Rule
- Each AICODE comment must be exactly one line
- No multi-line explanations
- Forces concise, high-value information
3. Location Strategy
// Put at TOP of file - module context
// AICODE-WHY: Handles all Stripe payment processing
// Put at function level - specific logic
function criticalFunction() {
// AICODE-TRAP: Must handle null userId
}
// Put at complex algorithm only
// AICODE-WHY: Custom sort for payment priority
complexList.sort((a, b) => {...});
4. Auto-Cleanup via Git Hooks
#!/bin/bash
# .git/hooks/pre-commit
# Remove old AICODE-TODO comments (convert to issues)
grep -n "AICODE-TODO" --include="*.js" . > todos.txt
if [ -s todos.txt ]; then
echo "Convert these TODOs to GitHub issues:"
cat todos.txt
exit 1
fi
# Flag duplicate AICODE comments
sort aicode.txt | uniq -d
5. Smart Placement Rules
❌ Don’t:
// AICODE-WHY: This is a function
// AICODE-NOTE: Uses JavaScript
// AICODE-TODO: Write code
✅ Do:
// AICODE-TRAP: Rate limit resets at UTC midnight, not local time
// AICODE-LINK: Rate limit docs at /docs/api-limits.md
6. Validation Script
# Run weekly to audit AICODE usage
echo "=== AICODE Comment Audit ==="
echo "Total comments: $(grep -r "AICODE-" . | wc -l)"
echo "By type:"
grep -r "AICODE-" . | cut -d: -f1 | sort | uniq -c
# Flag files with too many comments (>5)
grep -r "AICODE-" . | cut -d: -f1 | sort | uniq -c | \
awk '$1 > 5 {print "Warning: " $2 " has " $1 " AICODE comments"}'
7. Integration with AI Prompt
Instead of AI searching everywhere, create a single command for AI to use:
# ai-context.sh
#!/bin/bash
echo "=== Critical Context ==="
grep -r "AICODE-WHY\|AICODE-TRAP" --include="*.${1:-js}" ${2:-.} | \
head -20 # Limit results
echo -e "\n=== Related Links ==="
grep -r "AICODE-LINK" --include="*.${1:-js}" ${2:-.} | head -10
8. Progressive Enhancement
Start with just AICODE-TRAP for critical warnings:
// Phase 1: Only add AICODE-TRAP for actual gotchas
// AICODE-TRAP: UserID is UUID in DB but string in API response
// Phase 2: Add AICODE-WHY for non-obvious business logic
// AICODE-WHY: 3-retry policy required by payment processor SLA
// Phase 3: Add AICODE-LINK only for complex relationships
// AICODE-LINK: Webhook handler at services/stripe-webhook.js
9. Quick Reference Card
Create .aicode file in root:
AICODE Comment Guide:
- WHY: Business reason (not what the code does)
- TRAP: Non-obvious gotcha that caused real bugs
- LINK: Related file that must change together
Run: grep -r "AICODE-TRAP" . for all gotchas
Max: 5 AICODE comments per file
Review: Monthly cleanup required
10. The 80/20 Rule
- Document only the 20% of code that causes 80% of confusion
- If code is self-explanatory, no AICODE needed
- Focus on integration points, business rules, and historical bugs
This approach maintains the benefits while avoiding comment explosion and maintenance burden.
Leave a Comment