Skip to content

AGENTS.md

Latest commit

 

History

History
163 lines (136 loc) · 5.39 KB

AGENTS.md

File metadata and controls

163 lines (136 loc) · 5.39 KB

Agent Instructions for Contrast2 Project

Before You Start

IMPORTANT: Before implementing features or exploring the codebase, read the knowledgebase.md file to understand:

  • Technology stack (Django 5.1.8, Python 3.11, PostgreSQL)
  • Project structure (studies, uncontrast_studies apps)
  • API architecture (DRF, JWT, multi-SPA)
  • Testing framework (pytest, Django Testing)
  • CI/CD pipeline (GitHub Actions, Heroku)
  • Deployment configuration (Docker, Heroku)
  • Development practices (ruff, service layers)

Testing Requirements

When implementing changes, always run tests with the Testing configuration:

DJANGO_CONFIGURATION=Testing python manage.py test

Django Admin Best Practices

When working with Django admin files (**/admin.py, **/admin/*.py), follow these standards:

1. Base Admin Classes

  • Create and use base admin classes for shared functionality
  • Use mixins (e.g., ImportExportMixin) for specific features
  • Inherit from ModelAdmin for standard admin functionality
  • Use custom base classes for project-wide admin features

2. Model Registration

  • Register all models in their respective app's admin.py
  • Use descriptive admin class names (e.g., UserAdmin, ProductAdmin)
  • Group related models together in the admin file
  • Use consistent ordering of model registrations
  • Prefer the @admin.register(Model) decorator for cleaner registration

3. Admin Class Structure

  • Define list_display first
  • Follow with list_filter
  • Then define search_fields
  • Add filter_horizontal for many-to-many fields
  • Define inlines at the end
  • Use consistent field ordering in list_display
  • Group related attributes together
  • Refrain from using properties in list_display unless they are part of a select_related query

4. Inline Classes

  • Create base inline classes for common inline patterns
  • Set show_change_link = True for inlines when appropriate
  • Set extra = 0 for inlines to prevent empty forms
  • Use StackedInline or TabularInline as appropriate
  • Define fk_name when needed for complex relationships
  • Use min_num and max_num for inline limits

5. List Filters

  • Create custom filters by inheriting from admin.SimpleListFilter
  • Use RelatedOnlyFieldListFilter for foreign key fields
  • Use NumericRangeFilter for numeric fields
  • Group related filters together
  • Use descriptive filter titles
  • Implement efficient queryset methods

6. Form Classes

  • Create custom forms for complex validation
  • Define form fields in the Meta class
  • Add custom validation in clean()
  • Use consistent field ordering
  • Add helpful help_text for fields
  • Use appropriate widgets for field types

7. Import/Export Functionality

  • Use django-import-export for data import/export
  • Create custom resource classes for complex models
  • Define export formats (e.g., CSV, XLSX)
  • Implement custom export logic when needed
  • Handle related model exports properly
  • Add export actions to admin classes

8. QuerySet Optimization

  • Override get_queryset() for performance optimization
  • Use select_related() for foreign key relationships
  • Use prefetch_related() for many-to-many relationships
  • Document complex queryset modifications
  • Implement efficient filtering
  • Use database indexes appropriately

9. Custom Actions

  • Define admin actions as functions with @admin.action decorator
  • Use descriptive action names
  • Add confirmation for destructive actions
  • Handle bulk operations efficiently
  • Implement proper error handling
  • Add action permissions when needed

10. Display Methods

  • Use @admin.display decorator for custom display methods
  • Handle empty values appropriately
  • Keep display methods simple and focused
  • Document complex display logic
  • Use consistent formatting
  • Implement efficient display methods

Implementation Patterns

Model-Specific Example

@admin.register(Model)
class ModelAdmin(BaseAdmin):
    list_display = ('id', 'name', 'related_field')
    list_filter = ('field1', 'field2')
    search_fields = ('name', 'description')
    filter_horizontal = ('many_to_many_field',)
    inlines = [RelatedInline]

Inline Example

class RelatedInline(admin.StackedInline):
    model = RelatedModel
    fields = ('field1', 'field2')
    show_change_link = True
    extra = 0
    min_num = 1
    max_num = 5

Filter Example

class CustomFilter(admin.SimpleListFilter):
    title = "Filter Title"
    parameter_name = "filter_name"

    def lookups(self, request, model_admin):
        return [
            ('value1', 'Label 1'),
            ('value2', 'Label 2'),
        ]

    def queryset(self, request, queryset):
        if self.value():
            return queryset.filter(field=self.value())
        return queryset

General Best Practices

  • Optimize database queries (use select_related, prefetch_related)
  • Use readonly_fields and permission checks for security
  • Keep admin classes focused and well-documented
  • Use type hints and write unit tests
  • Provide helpful help_text and clear error messages
  • Use consistent formatting and naming
  • Group related models and imports together
  • Follow PEP 8 guidelines (120-char line length via ruff)
  • Regularly review and update admin code

Code Quality

  • Run ruff check . --fix before committing
  • Run ruff format for consistent formatting
  • Ensure all tests pass with DJANGO_CONFIGURATION=Testing python manage.py test