菜单
Create, review, and apply database schema changes with Alembic. Use whenever a SQLAlchemy model is added or changed, a column/index/constraint needs to change, or a data backfill is required — anything that alters the PostgreSQL schema.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Add a new tool/function the AI agent can call (e.g. look something up, hit an external API, perform an action). Use when extending the assistant's capabilities, wiring a new function into the agent, or when the model needs a new action. This project uses {{ cookiecutter.ai_framework }}.
Add or modify work that runs outside the request/response cycle — emails, document ingestion, webhooks, cleanups, scheduled jobs. Use when something is slow or fire-and-forget, or when adding a periodic/cron task. This project's queue is {{ cookiecutter.background_tasks }}.
Work with Stripe billing — subscriptions, plans/prices, the Customer Portal, credits, usage metering, invoices, and webhook events. Use when changing plans, handling a new Stripe webhook, debugging a payment/subscription flow, or touching credit balances and usage.
Work with messaging-channel bots (Telegram / Slack) — register a bot, route inbound messages through the AI agent, handle webhooks vs polling, or add a new channel adapter. Use when wiring chat into a messaging platform or debugging bot delivery.
Build a new page, view, or data-driven feature in the Next.js frontend. Use when adding a route under the dashboard/marketing area, wiring UI to a backend endpoint, adding client state, or creating a localized page. Covers App Router, data fetching, Zustand stores, and i18n.
Write or extend the backend test suite following this project's conventions. Use when adding tests for a new service/route/repository, when coverage is missing, or when asked to test a feature. Knows the mocked-session + httpx AsyncClient setup so tests run with no database.
| name | alembic-migration |
| description | Create, review, and apply database schema changes with Alembic. Use whenever a SQLAlchemy model is added or changed, a column/index/constraint needs to change, or a data backfill is required — anything that alters the PostgreSQL schema. |
This project uses async SQLAlchemy 2.0 + Alembic on PostgreSQL. Migrations live in backend/alembic/versions/ and are numbered (0001_…, 0002_…).
Change the model first in backend/app/db/models/ (Mapped[...] + mapped_column(), __repr__, relationships with ondelete="CASCADE"). Make sure the model is imported in backend/app/db/models/__init__.py so autogenerate sees it.
Autogenerate the migration:
cd backend && uv run alembic revision --autogenerate -m "add <thing>"
# or: make db-migrate
ALWAYS review the generated file. Autogenerate is a draft, not the truth:
upgrade() matches your intent and downgrade() actually reverses it.down_revision chains onto the current head (uv run alembic heads).Apply and verify:
cd backend && uv run alembic upgrade head # or: make db-upgrade
uv run alembic current # confirm at head
Then round-trip once to prove downgrade() works: alembic downgrade -1 && alembic upgrade head.
For backfills, add explicit op.execute(...) or a small data-loop in upgrade() (see the existing *_backfill_*.py migrations for the pattern). Keep schema and data changes in separate, well-named revisions when practical.
make dev / make bootstrap run alembic upgrade head automatically; you don't need a separate step in dev.