db-migrate（数据库迁移）

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

AI Mistake Prevention — Failure modes to avoid on every task: - Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal. - Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing. - Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain. - Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path. - When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site. - Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code. - Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks. - Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis. - Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly. - Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

Prerequisites: MUST ATTENTION READ before executing:

Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code. 1. Search 3+ similar patterns (grep/glob) — cite file:line evidence 2. Read existing files in target area — understand structure, base classes, conventions 3. Run python.claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists 4. Map dependencies via connections or callers_of — know what depends on your target 5. Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files) 6. Re-read analysis file before implementing — never work from memory alone 7. NEVER invent new patterns when existing ones work — match exactly or document deviation BLOCKED until: - [] Read target files - [] Grep 3+ patterns - [] Graph trace (if graph.db exists) - [] Assumptions verified with evidence

• docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) (content auto-injected by hook — check for [Injected:...] header before reading)

Quick Summary

Goal: Create or run database migrations (EF Core migrations, MongoDB data migrations) following platform patterns.

Workflow:

1. Identify — Determine migration type (EF schema vs data migration)
2. Create — Generate migration using dotnet ef or project data migration executor (see docs/project-reference/backend-patterns-reference.md)
3. Verify — Run migration and confirm schema/data changes

Key Rules:

• Follow platform migration patterns from CLAUDE.md
• Always backup data before destructive migrations
• Use project data migration executor for MongoDB data migrations (see docs/project-reference/backend-patterns-reference.md)

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Database migration: $ARGUMENTS

Instructions

1. Parse arguments:

- add <name> → Create new EF Core migration - update → Apply pending migrations - list → List all migrations and status - rollback → Revert last migration - No argument → Show migration status

1. Identify database provider from project:

- SQL Server: Search for *.Persistence projects - PostgreSQL: Search for *.Persistence.PostgreSql projects - MongoDB: Uses project Mongo migration executor (code-based, see docs/project-reference/backend-patterns-reference.md)

1. For EF Core (SQL Server/PostgreSQL): Add migration: cd src/{ExampleApp}/{ExampleApp}.TextSnippet.Persistence dotnet ef migrations add <MigrationName> --startup-project../{ExampleApp}.TextSnippet.Api Update database: dotnet ef database update --startup-project../{ExampleApp}.TextSnippet.Api List migrations: dotnet ef migrations list --startup-project../{ExampleApp}.TextSnippet.Api
2. For MongoDB migrations:

- MongoDB uses code-based migrations via project Mongo migration executor (see docs/project-reference/backend-patterns-reference.md) - Location: *.Persistence.Mongo/Migrations/ - Migrations run automatically on application startup - To create: Generate new migration class following existing patterns

1. Safety checks:

- Warn before applying migrations to production - Show what changes will be applied - Recommend backup before destructive operations

1. Migration Safety Review (MANDATORY for non-local environments):

- Before applying to staging/production, spawn database-admin sub-agent (subagent_type: "database-admin") for safety review - Review criteria: locking behavior on large tables, index creation impact under concurrent writes, rollback strategy, zero-downtime feasibility - Present findings and get explicit user approval before running dotnet ef database update or applying MongoDB migrations on non-local environments

Sub-Agent Type Override

MANDATORY for non-local migration apply: Spawn database-admin sub-agent (subagent_type: "database-admin") for safety review BEFORE applying to staging or production. Rationale: database-admin specializes in query plans, index impact analysis, locking behavior, backup/restore, and replication — context the main agent lacks for production-safe migration decisions.

Sub-Agent Selection — Full routing contract: .claude/skills/shared/sub-agent-selection-guide.md Rule: NEVER use code-reviewer for specialized domains (architecture, security, performance, DB, E2E, integration-test, git).

Closing Reminders

• MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting
• MANDATORY IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
• MANDATORY IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)
• MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:
• MANDATORY IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists.
• MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact.
• MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction.

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.

[IMPORTANT] Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.

Prompt-Enhance Closing Anchors

• IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval
• IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution
• IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence
• IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses