miratcan · August 4, 2025 13:33 · Aug 4, 2025 · Aug 4, 2025 · Aug 4, 2025
diff --git a/Agents.md b/Agents.md
@@ -69,11 +69,8 @@ This document defines the collaboration rules and development principles expecte
 ### 🛡️ Admin Panel Security
 
 * All ForeignKey fields must use `raw_id_fields` to avoid dropdown performance issues.
-
-* Never expose sensitive fields (e.g., passwords, tokens).
-
+* 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)

diff --git a/Agents.md b/Agents.md
@@ -130,7 +130,6 @@ uv run <script.py>
 * 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`

diff --git a/Agents.md b/Agents.md
@@ -0,0 +1,169 @@
+# 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.
+
+```bash
+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.