Engineering the Perfect AI Developer Agent Rulebase (AGENTS.md)

I am creating the "Project Structure & Dependency Rules" section of my developer agent rulebase (AGENTS.md).
Here are my project parameters:
- Backend: [e.g. Django in backend/ / FastAPI / Express / Rails]
- Frontend: [e.g. Vue 3 + Vite in frontend/ / Next.js / SvelteKit / none]
- Allowed Root Folders: [List allowed folders, e.g. frontend/, backend/, venv/, doc/ ONLY]
- Root Files: [e.g. requirements.txt, .env, .env.example]
- Dependency Management: [e.g. python virtualenv in venv/ with strict requirements.txt updates; frontend npm install locally within frontend/]
- Deployment Architecture: [e.g. SFTP upload of pre-compiled dist/ and direct virtualenv python execution; OR Docker containers; OR Vercel/Netlify]
- Running Script: [e.g. Always create a shell script with steps: activate venv, makemigrations, migrate, runserver]

Write a dense, professional markdown rule specification following the "Explain the Why" principle. Include explicit rules preventing root clutter and enforcing lockfile synchronization.

Generate the "Environment Configuration & Secrets Management" section for my AGENTS.md.
Requirements:
- Backend Environment: [e.g. Root .env and .env.example; all secrets loaded via os.getenv() in settings.py]
- Frontend Environment: [e.g. frontend/.env.development (VITE_API_BASE_URL=http://localhost:8000/) and frontend/.env.production (VITE_API_BASE_URL=/)]
- Secret Key: [e.g. Always auto-generate a Django SECRET_KEY in .env by default]
- Allowed Hosts & CORS: [e.g. Must always be stored only in .env, never hardcoded in settings.py]
- Production Settings: [e.g. Always configure STATIC_ROOT, MEDIA_ROOT, DEBUG=False for production]
- Why Explanation: Include technical rationale for why hardcoded URLs break production and why .env.example must always mirror .env structure.

Generate the "Backend Architecture & User Permissions" section for my AGENTS.md.
Stack Specifications:
- Framework: [e.g. Django Vanilla without DRF / Express TypeScript / FastAPI / Rails]
- Forbidden Libraries: [e.g. Strictly NO Django REST Framework / NO Passport.js]
- Development Database: [e.g. SQLite]
- Custom User Model: [e.g. Inherits from AbstractUser with a JSONField named `menu_access` for granular multi-level permissions controlling modules, submodules, tabs, and actions (view, create, edit, delete, export)]
- Rights Management: When building admin management interfaces, always provide a dedicated Rights Management module where superusers configure granular rights across modules, submodules, and actions.
- Hydration Endpoint: Provide a `/users/me/` endpoint returning authenticated user, superuser status, and permission matrix.
- Auth Decorator: Forbid HTML redirect decorators; require custom decorator returning 401 JSON when unauthenticated.

Generate the "API Contracts, Pagination & Standardized JSON Signatures" section of AGENTS.md.
Requirements:
1. Standard JSON Envelopes:
   - List: `{'<entities>': data, 'pagination': pagination_meta}`
   - Create: `{'id': obj.id, 'detail': '... created successfully.'}`, status 201
   - Update: `{'detail': '... updated successfully.'}`, status 200
   - Delete: `{'detail': '... deleted successfully.'}`, status 200
   - Error: `{'error': 'Error message'}`, status 400/401/403/404
2. Reusable Pagination Utility: [e.g. Create a helper in backend/utils/pagination.py returning page_obj and metadata dict; default 50 items per page]
3. Sanitized Query Filtering: Always whitelist valid `sort_by` fields before calling .order_by() to prevent SQL injection. Use Q objects for multi-field search.
Include concrete code seed for the pagination helper.

Generate the "Data Integrity, URL Conventions & DateTime Standards" section of AGENTS.md.
Requirements:
1. Mandatory Trailing Slashes: All backend URL routes AND all client-side API requests must always include a trailing slash. Explain that [e.g. Django] issues HTTP 301 redirects when omitted, which drops POST/PUT/DELETE payloads and converts them to GETs.
2. Atomic Transactions: Mandate [e.g. transaction.atomic / database transactions] for any view or service writing to multiple tables or uploading files alongside DB records.
3. DateTime Standard: UTC ISO 8601 strings across all API boundaries (USE_TZ=True, store in UTC, serialize as isoformat).
4. Orphan Media Cleanup: Deleting model records with file/image fields must remove physical files from disk via signals or custom delete overrides.
5. Migration Safety: [e.g. The agent must never run makemigrations or migrate; only run manage.py check]

Generate the "Authentication, CSRF & API Client Configuration" section for AGENTS.md.
Specifications:
1. Auth Strategy: [e.g. Django session-based auth with HTTP-only cookies / Firebase Auth connected to Django AbstractUser / JWT with refresh tokens]
2. CSRF Handshake: [e.g. Provide a lightweight @ensure_csrf_cookie endpoint at users/csrf/ so the SPA can acquire a valid CSRF cookie on app startup]
3. Centralized HTTP Client: [e.g. Create frontend/src/axios.js configured with:
   - withCredentials: true
   - xsrfCookieName: 'csrftoken'
   - xsrfHeaderName: 'X-CSRFToken'
   - An interceptor attaching the CSRF token from cookies
   - An automatic handshake call to users/csrf/ on app startup]
4. Media URL Resolution: [e.g. Provide a getMediaUrl(path) utility that resolves /media/ paths to full URLs in dev and relative paths in production]
5. Mandatory Trailing Slashes on All API Requests: Reiterate that all Axios endpoints must include trailing slashes.

Generate the "Design System Tokens & Common Classes" section for AGENTS.md.
My Design System:
1. Color Palette:
   - Primary dark/text: [e.g. forti-black (#030302)]
   - Brand/accent: [e.g. prep-green (#6B6C62)]
   - Secondary neutrals: [list your neutral colors]
   - Backgrounds & borders: [list bg/border colors]
   - Status colors: success (#3A7D44), warning (#D4A843), danger (#C4392A), info (#4A6FA5)
2. Typography: [e.g. Inter (font-sans) for body, Outfit (font-heading) for headings]
3. CSS Framework: [e.g. Tailwind CSS with extended config / Vanilla CSS with custom properties]
4. Utility Classes: Define these under @layer components:
   - .card: [exact class list]
   - .btn-primary: [exact class list with hover, focus, transition states]
   - .btn-secondary: [exact class list]
   - .input-field: [exact class list]
   - .sticky-header: [exact class list]
Include exact tailwind.config.js color extension and style.css @layer components code.

Generate the "Layout & Navigation" section for AGENTS.md.
Specifications:
1. App Shell: [e.g. AdminLayout.vue with fixed sidebar + scrollable main content area]
2. Sidebar Structure:
   - Header: [e.g. Branded logo header with dark background]
   - Navigation Links: [e.g. Dynamic links with active state indicator, filtered by user menu_access permissions and is_superuser]
   - User Footer: [e.g. Initials avatar, truncated name/email, dedicated logout button with danger styling]
3. Mobile Drawer: [e.g. Hamburger toggle fixed top-left, backdrop overlay, drawer slides in from left]
4. Icons: [e.g. FontAwesome Free icons ONLY. NO emojis anywhere in the interface.]
5. Permission Filtering: Navigation items must be dynamically filtered based on the authenticated user's permission matrix.

Generate the "Tables, Lists & State Persistence" section for AGENTS.md.
Specifications:
1. Search: Real-time, debounced by 300ms, automatically resets pagination to page 1 on input.
2. Pagination: [e.g. 50 items per page by default]
3. Column Sorting: Clickable headers with clear sort indicator icons (active vs inactive states). Default sort: ascending by primary name field.
4. Table State Persistence: [e.g. Apply a Pinia/Zustand store to save current page, search query, and sort state per table, so navigating back from edit preserves position]
5. Clickable Entity Names: The primary name/identifier in each row must be a clickable link to the edit page.
6. Action Icons: Standardize per-row actions: edit (fa-pen, hover green), delete (fa-trash, hover red), view (fa-eye).
7. Status Badges: [e.g. Subtle tinted backgrounds with inset rings: bg-success/10 text-success ring-1 ring-inset ring-success/20]
8. Loading State: [e.g. Spinner + "Loading items..." spanning all columns]
9. Empty State: [e.g. "No records found." spanning all columns]
10. Row Hover: Subtle hover states with transition.

Generate the "Forms, Editors & Standard Header Cards" section for AGENTS.md.
Specifications:
1. Modal Ban: For editors with more than one field, never use modals. Always use a dedicated view/page.
2. Standard Header Card: Every form/editor page must feature:
   - Circular back button [e.g. w-9 h-9 rounded-full with ring styling]
   - Page title (heading font, bold) and descriptive subtitle
   - Autosave/Status Badge on edit views: saved (green), saving (spinner), unsaved (amber), error (red)
   - Primary action buttons on the right side
3. Section Grouping: Group form inputs into distinct card panels with uppercase tracking-widest section headers.
4. Responsive Layout: [e.g. 2-column input section + 1-column sidebar for metadata on large screens (grid-cols-1 lg:grid-cols-3)]
5. Custom Selects: [e.g. Native HTML select elements are forbidden; mandate custom styled dropdown components matching design tokens]

Generate the "Notifications, Dialog Bans & In-Flight Request Guards" section for AGENTS.md.
Specifications:
1. Browser Dialog Ban: Never use vanilla browser dialogs (alert(), confirm(), prompt()). Always develop custom modal components.
2. Notification System: Implement a toast/notification system to inform users about success/error/warning events.
3. Confirmation Modals: Always use custom styled confirmation dialogs for destructive actions (delete, cancel).
4. In-Flight Mutation Guards: Every button triggering an async mutation (form submit, delete, status toggle) must:
   - Bind to an isSubmitting/isLoading reactive state
   - Be disabled while the request is in flight (:disabled="isSubmitting")
   - Display a spinning icon (fa-spinner fa-spin)
   - Prevent duplicate submissions from rapid clicking or repeated Enter keypresses
Include the exact code pattern for the in-flight guard button.

Generate the "Image Upload, Search-Select & Scrollable Containers" section for AGENTS.md.
Specifications:
1. Image Uploader Component:
   - Support both single and multiple image uploads based on module needs
   - Drag and drop with hidden original file input
   - Thumbnail gallery above the drop zone: set default image, reorder, delete, view
   - If default image is deleted, auto-set a new default
   - On upload, resize to maximum [e.g. 1500x1500px] while keeping original aspect ratio
2. Search-Select Components:
   - Dedicated search component with real-time search input filtering across key properties
   - Scrollable area displaying [e.g. 20 items at a time] using infinite scroll
3. Scrollable Containers:
   - Any container with overflow scroll must implement a bottom fade/gradient that disappears when scrolled to the bottom
   - [e.g. In Vue, use @scroll listener and dynamic classes based on scroll position]

Generate the "Router Guards, Auth Sync & Mobile Webapp" section for AGENTS.md.
Specifications:
1. Navigation Guards: [e.g. Implement router.beforeEach that coordinates with auth store:
   - Check if user auth has been initialized (authStore.isInitialized)
   - If not, await /users/me/ response before evaluating route permissions
   - Routes with meta: { requiresAuth: true, permission: '...' } must verify auth and user permissions
   - Unauthorized access redirects to Access Denied or Dashboard view]
2. Component Breakdown: [e.g. Always break down modules into as many reusable components as possible]
3. Mobile Webapp: Always prepare the project for iOS/Android webapp use (viewport meta, touch optimizations, manifest).
4. DateTime Display: [e.g. Format dates exclusively at display layer using centralized helpers in utils.js that convert UTC to local timezone using Intl.DateTimeFormat. When sending dates to backend, always convert to UTC ISO 8601 strings.]

Generate the "Integrations & Third-Party Services" section for AGENTS.md.
Rules:
1. AI Features: [e.g. Always use Google Gemini. Always search for the actual model's dev docs before starting development. Model identifiers must be stored in .env, never hardcoded.]
2. Payments: [e.g. Always use Stripe when payment or subscription functionality is needed.]
3. Email: [e.g. Configure SMTP using environment variables with sensible defaults. Include example .env settings for EMAIL_HOST, EMAIL_PORT, EMAIL_USE_TLS, EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, DEFAULT_FROM_EMAIL, SITE_HOST]
4. Authentication: [e.g. Always ask the developer whether they want raw Django session-based login or Firebase Auth. If Firebase, connect it with the native AbstractUser model.]
Include concrete .env example blocks and settings.py integration code for email.

Generate the "Version Control, Testing Boundaries, Documentation & Deployment" section for AGENTS.md.
Rules:
1. Git Version Control:
   - Initial Setup: [e.g. git init, create initial commit, publish to private GitHub repo]
   - Ongoing Commits: [e.g. NEVER commit or push automatically after initial setup. Developer handles VCS.]
   - Gitignore: [e.g. Always include /media/, **/migrations/* (except __init__.py), venv/, .env]
2. Testing Boundaries:
   - Browser Testing: STRICTLY FORBIDDEN. No Playwright, Puppeteer, Selenium, or headless browsers. Human developer tests visually.
   - CLI Checks: [e.g. Permitted and encouraged: manage.py check, manage.py test, eslint, tsc --noEmit]
   - Seed Scripts: Must exercise real service methods and API endpoints, not raw database inserts.
3. Documentation:
   - Location: [e.g. Always in doc/ folder]
   - Codebase Index: [e.g. Always consult doc/codebase_index.md before writing new code]
   - Updates: [e.g. Update docs on major system changes]
4. Deployment Documentation:
   - [e.g. Describe SFTP workflow where frontend dist/ is built locally and uploaded. Include Apache config, ownership/permissions for SQLite, media, .env.]
5. Help System: [e.g. Build static HTML help system in frontend/public/help/ with contextual HelpTooltip components at the final stage of development.]