Agents.md

AGENTS.md (Generalized)

This document defines the collaboration rules and development principles expected of all AI agents and contributors across projects. Originally designed for a scalable content-sharing platform, these guidelines are now abstracted for universal use.

---

🔧 General Code Style (Universal)

• Prioritize simplicity, readability, and maintainability.
• Avoid code duplication; reuse logic and components.
• Respect environment separation (dev, test, prod). Never hardcode values.
• Keep commits and changes scoped — avoid mixing concerns.
• Eliminate all build-time warnings.
• Exclude throwaway/debug scripts from version control.
• Break large files or functions into smaller, coherent parts.
• Use descriptive names (no cryptic abbreviations).
• Favor early returns (guard clauses) over nested logic.
• Never swallow exceptions silently; document decisions.
• Do not overwrite shared configuration files like .env without consent.

---

📁 Codebase Management

📊 CI/CD & Repo Standards

• Use branch naming conventions (feature/*, bugfix/*, hotfix/*).
• Block PRs unless lint, test, and build steps pass.

🛠️ Backend Guidelines (General)

📊 CI/CD & Repo Standards

• Use branch naming conventions (feature/*, bugfix/*, hotfix/*).
• Block PRs unless lint, test, and build steps pass.

---

🛠️ Backend Guidelines (Django)

See shared standards under “Backend Guidelines (General)” for common practices like API design, logging, secrets, and performance.

🔑 Authentication & Authorization

• Use token-based or session-based auth depending on context; prefer JWT for APIs.
• Avoid reinventing auth flows — reuse Django’s built-in features when possible.
• Never expose sensitive fields in serializers.
• Use permission classes for all views — avoid AllowAny in production.

🧪 Testing Best Practices

• Use pytest with factory_boy for test data.
• Target minimum 80% test coverage; CI should fail below that.
• Prefer factories over fixtures.
• Use pytest-django’s transactional_db fixtures for reliable isolation.

🧵 Asynchronous Task Safety

• Ensure Celery tasks are idempotent (running multiple times doesn’t break logic).
• Configure retry behavior explicitly (max_retries, retry_backoff, etc).
• Use acks_late=True and task_acks_on_failure_or_timeout=False for reliability.

📥 Upload Security Enhancements

• Check file size, MIME type, and content.
• Sanitize SVG, PDF, and other scriptable formats.
• Enforce extension+type matching.

🛡️ Admin Panel Security

• All ForeignKey fields must use raw_id_fields to avoid dropdown performance issues.
• Never expose sensitive fields (e.g., passwords, tokens)
• Use readonly_fields or exclude for security-critical data.
• Remove unused admin classes — keep it clean.

🔁 Deployment Standards (Cross-functional)

• Production deploys should come only from main or release/* branches.
• Ensure deployment steps (migrations, static collection, service reload) are automated.
• Rollbacks should be possible via tagged versions or container history.

General

• Business logic belongs in services/ or usecases/, not in views or serializers.
• Use explicit exception handling; never use bare except: blocks.
• Define choices enums at the top of model files.

📦 Python Package Management

• Use uv exclusively (or project-defined alternative). Avoid pip, poetry, pip-tools unless specified.

uv add <package>
uv remove <package>
uv sync
uv run <script.py>

🧱 API View Conventions

• Prefer ModelViewSet or equivalent CRUD abstractions.
• Use separate serializers for input/output when needed.
• Use strict permission classes.
• Annotate views for auto-documentation (e.g. drf-spectacular).

🔔 Background Tasks

• Use Celery or an async queue.
• Offload heavy work to tasks.py or background workers.
• Log and track all errors.

📡 WebSockets (Optional)

• Use Channels or socket servers under /ws/....
• Require token-based auth.

---

🎨 Frontend Guidelines

• Use TypeScript.
• Do not use Tailwind CSS.
• Use semantic HTML and well-structured, scoped CSS.
• Prefer CSS Modules or SCSS with logical separation.
• Avoid inline styles and overuse of utility classes.
• Ensure class names are meaningful and reusable.
• Use functional components and Hooks.
• Each component folder must contain:
  • index.tsx
  • types.ts
  • styles.module.css or .scss
• Use a central API client (api.ts).
• Use SWR, React Query, or equivalent.
• Global state should be managed with Zustand, Jotai, or Redux Toolkit.
• Avoid prop drilling.
• Stick to a consistent design system, but not utility-based class libraries like Tailwind.
• No inline styles or magic numbers.
• Ensure accessibility in all components.

---

✅ Testing Guidelines

• Backend: use pytest or appropriate framework.
• Frontend: use jest and @testing-library/react.
• Remove debugging code before commit (console.log, print, etc).
• Mocks should exist only inside test files.

---

🔍 Code Review

• All PRs require review.
• Separate features, bugfixes, and refactors into different commits/PRs.
• Use squashed commits to maintain clean history.

---

🧠 Philosophy

• Read before you write.
• Isolate refactors.
• Be boring — predictable, testable, understandable code wins.
• Think of your future teammates. Or your future self at 2am.