Tag-Based Search

Instructions

Tag system

@FEAT:feature-name - Feature grouping @COMP:component-name - Component type @TYPE:category - Code category

Usage

Add in comments:

# @FEAT:{{feature-name}} @COMP:{{component}} @TYPE:{{type}}
class {{ClassName}}:
    pass

Search with grep:

grep -r "@FEAT:{{feature-name}}" {{src_directory}}/

Example

# @FEAT:user-auth @COMP:service @TYPE:core
class AuthenticationService:
    '''Handles user authentication'''
    pass

# @FEAT:user-auth @COMP:validator @TYPE:utility
def validate_credentials(username, password):
    return username and password

Common Tags by Domain

Generic/Universal Tags

FEAT (Feature):

• user-auth, data-processing, file-upload, notification, payment

COMP (Component):

• service, validator, route, model, controller, middleware, util, config

TYPE (Category):

• core, api, data, utility, business, integration, validation

---

E-commerce Tags

FEAT:

@FEAT:product-catalog
@FEAT:shopping-cart
@FEAT:checkout
@FEAT:payment-processing
@FEAT:order-management
@FEAT:inventory-tracking
@FEAT:shipping-integration
@FEAT:customer-reviews
@FEAT:discount-pricing

COMP:

@COMP:product-service
@COMP:cart-service
@COMP:payment-gateway
@COMP:order-processor
@COMP:inventory-manager
@COMP:shipping-calculator
@COMP:price-engine

Example:

# @FEAT:shopping-cart @COMP:service @TYPE:core
class CartService:
    def add_item(self, cart_id, product_id, quantity):
        pass

# @FEAT:checkout @COMP:validator @TYPE:validation
def validate_checkout(cart, address, payment):
    pass

---

SaaS Application Tags

FEAT:

@FEAT:user-management
@FEAT:subscription-billing
@FEAT:team-collaboration
@FEAT:role-permissions
@FEAT:audit-logging
@FEAT:api-integration
@FEAT:webhook-notifications
@FEAT:data-export
@FEAT:analytics-dashboard

COMP:

@COMP:tenant-service
@COMP:subscription-manager
@COMP:billing-processor
@COMP:permission-checker
@COMP:audit-logger
@COMP:webhook-dispatcher
@COMP:analytics-aggregator

Example:

# @FEAT:subscription-billing @COMP:service @TYPE:core
class SubscriptionService:
    def charge_customer(self, customer_id, amount):
        pass

# @FEAT:role-permissions @COMP:middleware @TYPE:integration
def require_permission(permission_name):
    pass

---

Data Platform Tags

FEAT:

@FEAT:data-ingestion
@FEAT:data-transformation
@FEAT:data-validation
@FEAT:data-pipeline
@FEAT:data-quality
@FEAT:schema-evolution
@FEAT:data-lineage
@FEAT:job-scheduling

COMP:

@COMP:extractor
@COMP:transformer
@COMP:loader
@COMP:validator
@COMP:pipeline-orchestrator
@COMP:schema-registry
@COMP:job-scheduler

Example:

# @FEAT:data-ingestion @COMP:extractor @TYPE:integration
class APIDataExtractor:
    def fetch_data(self, endpoint, params):
        pass

# @FEAT:data-validation @COMP:validator @TYPE:validation
def validate_schema(data, schema):
    pass

---

Mobile/IoT Tags

FEAT:

@FEAT:device-registration
@FEAT:device-monitoring
@FEAT:firmware-update
@FEAT:telemetry-collection
@FEAT:remote-control
@FEAT:offline-sync
@FEAT:push-notification
@FEAT:geolocation

COMP:

@COMP:device-manager
@COMP:telemetry-collector
@COMP:firmware-updater
@COMP:sync-engine
@COMP:notification-sender
@COMP:location-tracker

Example:

# @FEAT:device-monitoring @COMP:service @TYPE:core
class DeviceMonitoringService:
    def check_health(self, device_id):
        pass

# @FEAT:offline-sync @COMP:sync-engine @TYPE:core
class SyncEngine:
    def resolve_conflicts(self, local, remote):
        pass

---

CRM/Marketing Tags

FEAT:

@FEAT:contact-management
@FEAT:lead-scoring
@FEAT:email-campaign
@FEAT:workflow-automation
@FEAT:sales-pipeline
@FEAT:reporting-analytics
@FEAT:contact-import
@FEAT:activity-tracking

COMP:

@COMP:contact-service
@COMP:lead-scorer
@COMP:email-sender
@COMP:workflow-engine
@COMP:pipeline-manager
@COMP:report-generator

Example:

# @FEAT:lead-scoring @COMP:service @TYPE:business
class LeadScoringService:
    def calculate_score(self, lead):
        pass

# @FEAT:email-campaign @COMP:sender @TYPE:integration
class EmailCampaignSender:
    def send_campaign(self, campaign_id, recipients):
        pass

---

Multi-Language Examples

Python

# @FEAT:user-auth @COMP:service @TYPE:core
class AuthenticationService:
    '''Handles user authentication'''

    # @FEAT:user-auth @COMP:service @TYPE:core
    def authenticate(self, username, password):
        pass

# @FEAT:user-auth @COMP:validator @TYPE:utility
def validate_password_strength(password):
    return len(password) >= 8

JavaScript/TypeScript

// @FEAT:user-auth @COMP:service @TYPE:core
class AuthenticationService {
    /**
     * Handles user authentication
     */

    // @FEAT:user-auth @COMP:service @TYPE:core
    authenticate(username, password) {
        // ...
    }
}

// @FEAT:user-auth @COMP:validator @TYPE:utility
function validatePasswordStrength(password) {
    return password.length >= 8;
}

Go

// @FEAT:user-auth @COMP:service @TYPE:core
// AuthenticationService handles user authentication
type AuthenticationService struct{}

// @FEAT:user-auth @COMP:service @TYPE:core
// Authenticate validates user credentials
func (s *AuthenticationService) Authenticate(username, password string) bool {
    // ...
    return false
}

// @FEAT:user-auth @COMP:validator @TYPE:utility
// ValidatePasswordStrength checks password requirements
func ValidatePasswordStrength(password string) bool {
    return len(password) >= 8
}

Java

// @FEAT:user-auth @COMP:service @TYPE:core
/**
 * Handles user authentication
 */
public class AuthenticationService {

    // @FEAT:user-auth @COMP:service @TYPE:core
    public boolean authenticate(String username, String password) {
        // ...
        return false;
    }
}

// @FEAT:user-auth @COMP:validator @TYPE:utility
/**
 * Validates password strength
 */
public class PasswordValidator {
    public static boolean validateStrength(String password) {
        return password.length() >= 8;
    }
}

---

Search Strategies

Find all code for a feature

# Find everything related to user-auth
grep -r "@FEAT:user-auth" src/

# With line numbers
grep -rn "@FEAT:user-auth" src/

# Show file names only
grep -rl "@FEAT:user-auth" src/

Find specific component type

# Find all services
grep -r "@COMP:service" src/

# Find all validators
grep -r "@COMP:validator" src/

Find by code category

# Find all core logic
grep -r "@TYPE:core" src/

# Find all integrations
grep -r "@TYPE:integration" src/

Combined searches

# Find core services for user-auth
grep -r "@FEAT:user-auth" src/ | grep "@COMP:service" | grep "@TYPE:core"

# Find all validation code across features
grep -r "@TYPE:validation" src/

Using Claude Code's Grep tool

Pattern: "@FEAT:user-auth"
Output mode: files_with_matches
Path: src/

# Then drill down:
Pattern: "@FEAT:user-auth.*@COMP:service"
Output mode: content

---

Tag Maintenance

When to add tags

Always tag:

• New classes/functions
• Core business logic
• Integration points
• Validation logic

Optional (but recommended):

• Utility functions
• Configuration files
• Test files

Tag consistency rules

1. One tag per line (easier to grep)

   # ✅ Good
   # @FEAT:user-auth @COMP:service @TYPE:core
   
   # ❌ Avoid
   # @FEAT:user-auth
   # @COMP:service
   # @TYPE:core
   

2. Feature names lowercase with hyphens

   ✅ @FEAT:user-auth
   ❌ @FEAT:UserAuth
   ❌ @FEAT:user_auth
   

3. Component names match architecture

   ✅ @COMP:service (if you use "services" in your architecture)
   ❌ @COMP:manager (if not a standard component type)
   

Updating tags

When refactoring:

• Update @FEAT if feature name changes
• Update @COMP if component type changes
• Keep @TYPE consistent with new purpose

---

For detailed patterns, see reference.md For more examples, see examples.md