---
name: cucu-python-backend
description: Best-practices cho backend Python/FastAPI của CuCu (cấu trúc, singleton agents, lint/format/test).
---

# CuCu Python Backend Skill

Skill này gói **chuẩn backend Python** cho CuCu, dựa trên cursor-skills/python.
Agent dùng skill này khi làm việc trong `backend/` (FastAPI, common, agent).

## When to Use

- Người dùng:
  - sửa code trong `backend/api`, `backend/common`, `backend/agent`,
  - hỏi về tổ chức module, singleton pattern, format, lint, type hints,
  - refactor lớn backend hoặc thêm service/agent mới.

## Cấu trúc & pattern

1. **Tổ chức thư mục**
   - `backend/api/` – chỉ chứa **routes** (FastAPI routers).
   - `backend/common/` – infra/shared:
     - `mongo_client`, `memos_core`, `conversation_manager`, `formatter_agent`,…
   - `backend/agent/` – logic LLM:
     - `graph.py`, `controller.py`, `tools/`, `system_prompt.txt`.

2. **Singleton pattern cho “agents”**
   - Đối với những class cần một instance chung (graph, formatter, conversation manager), dùng pattern:
     ```python
     _instance: list[MyClass | None] = [None]

     def get_my_class(...) -> MyClass:
         if _instance[0] is None:
             _instance[0] = MyClass(...)
         return _instance[0]

     def reset_my_class() -> None:
         _instance[0] = None
     ```
   - Ví dụ:
     - `CANIFAGraph` trong `agent/graph.py`.
     - `FormatterAgent` trong `common/formatter_agent.py`.

3. **Code style & tooling**
   - Format:
     - `black` cho toàn bộ backend.
   - Lint:
     - `ruff` cho lint + autofix.
   - Type hints:
     - Dùng cho mọi function public, class method quan trọng.
   - Testing:
     - Dùng `pytest` (kết hợp skill `cucu-testing` khi nói về test).

## Instructions (Agent phải làm gì)

1. **Khi thêm/chỉnh service/agent backend mới:**
   - Gợi ý:
     - Đặt file trong `common/` nếu là infra/shared.
     - Đặt file trong `agent/` nếu gắn với logic LLM/chatbot.
   - Nếu class có state cần reuse → đề xuất dùng singleton pattern như trên.

2. **Khi format/lint backend:**
   - Hướng user tới:
     - `cd backend && ruff check . --fix`
     - `cd backend && black .`
   - Hoặc bảo dùng command `/format-code` (đã cấu hình formatter).

3. **Khi review backend:**
   - Check:
     - Import sạch, không circular.
     - Type hints rõ ràng.
     - Logic domain tách khỏi code infra (DB, cache, HTTP).
     - Các “agent” như `FormatterAgent`, `CANIFAGraph` tuân thủ singleton rõ ràng, không tạo nhiều instance lung tung.


