@winspan/claude-forge 8.54.3 → 9.2.0

package/dist/skills/distilled/distilled-architecture-decision.md

@@ -0,0 +1,173 @@
+---
+name: distilled-architecture-decision
+version: 1.0.0-portable
+description: 'Distilled IT-universal skill: architecture decision records (portable, hand-rewritten 2026-05-27)'
+keywords:
+  - architecture
+  - adr
+  - decision
+  - design
+  - record
+  - architecture decision
+  - 架构决策
+  - 技术选型
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/winspan/claude-forge.git
+    license: MIT
+    commit: 7d96b86c
+    paths:
+      - official/official-architecture-decision.md
+distilled_at: '2026-05-27T02:11:00.000Z'
+distilled_by: hand-rewrite (D4-reverse)
+it_universal_score: 4.5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 1
+  d5: 0.5
+it_universal_rationale: ADR template + decision-record discipline; entirely process-level, stack-agnostic.
+is_stub: false
+---
+
+## Goal
+
+Capture every consequential technical decision as a short, dated, immutable record so that future maintainers can reconstruct **why** the system looks the way it does — not just what it does.
+
+## When to trigger
+
+- Choosing among multiple plausible technologies (framework, database, queue, build tool, runtime).
+- Drawing a system boundary (which service owns which data; what crosses an API).
+- Picking a protocol (REST vs gRPC vs message-bus; sync vs async).
+- A decision that will affect more than one module, team, or release cycle.
+- Reversing or superseding a prior architectural choice.
+- A design debate that has happened more than twice — write it down once and stop relitigating.
+
+Skip the ADR for: trivial style tweaks, single-file refactors, bug fixes, or anything that doesn't change the shape of the system.
+
+## Steps
+
+1. **Detect the decision moment.** When you notice yourself or a teammate weighing trade-offs that will outlive the current sprint, pause and open a new ADR file.
+
+2. **Pick the next number.** Use a monotonic counter (`ADR-0001`, `ADR-0002`, ...). Numbers are never reused, even for retired records. Store them in a known directory of the repo (a common convention is `docs/adr/`).
+
+3. **Fill the template** (see "Examples" for the canonical shape). The minimum sections are: Status, Context, Decision, Alternatives considered, Consequences. Keep each section short — usually one to four paragraphs.
+
+4. **Mark status honestly.** Start at `Proposed`. Once approved (whatever your team's bar is — a review, a meeting, a PR merge), change to `Accepted`. If later replaced, change to `Superseded by ADR-NNNN`. If retired without replacement, `Deprecated`.
+
+5. **Never edit an Accepted ADR's substance.** Typos are fine; rewriting the decision is not. If the decision changes, write a **new** ADR that supersedes the old one. The old record stays in the repo as historical context.
+
+6. **Cross-link.** When an ADR depends on, or invalidates, another, link both ways: ADR-0007 "supersedes ADR-0003"; ADR-0003 carries a note "superseded by ADR-0007".
+
+7. **Reference ADRs from code or PRs** when a non-obvious choice would otherwise confuse readers. A comment like `// see ADR-0012` is cheaper than a 20-line explanation that drifts out of date.
+
+## Anti-patterns
+
+- **Editing an Accepted ADR.** The record loses its truth value. If circumstances changed, supersede with a new ADR.
+- **ADRs that say "we chose X" without saying why.** The context and alternatives sections are the whole point — the choice itself is the cheap part.
+- **Writing an ADR after the fact** to rubber-stamp a decision already shipped. Better than nothing, but flag it as `Accepted (retroactive)` and acknowledge the alternatives were not really weighed.
+- **One giant ADR covering many decisions.** Split them. One ADR = one decision.
+- **Burying ADRs in a wiki nobody reads.** Keep them in the repo, next to the code, in a flat browsable directory.
+- **Status that lies.** A `Proposed` ADR that has been shipping for 6 months is not Proposed — fix the status.
+- **Skipping ADRs for "obvious" choices.** Often the obvious choice is obvious only to the original author; the record protects future maintainers from re-evaluating from scratch.
+
+## Success criteria
+
+- [ ] The repo has a known directory holding ADRs (e.g. `docs/adr/`), with a flat numbering scheme.
+- [ ] Every Accepted ADR has filled Context, Decision, Alternatives, and Consequences sections.
+- [ ] Status of every ADR matches reality (no stale `Proposed` records).
+- [ ] At least one ADR exists for every cross-module / cross-team choice made in the last release cycle.
+- [ ] Superseded ADRs link to their successors, and vice versa.
+- [ ] Code / PRs reference ADR numbers when explaining non-obvious choices.
+
+## Failure modes
+
+- **Decisions made in chat without a record.** When the third person asks "why are we using X?", that's the prompt — open an ADR retroactively and tag it.
+- **ADR explosion.** If you have 200 ADRs, you've blurred the line between "architecture decision" and "any decision". Tighten the trigger criteria; small decisions belong in code comments or PR descriptions, not ADRs.
+- **Two contradictory Accepted ADRs.** A symptom that nobody checked the existing record before writing the new one. Resolution: write a third ADR that explicitly supersedes the older one.
+- **Authors disagree on the decision.** Don't write a wishy-washy ADR. Record the dissent in the Alternatives section: "Option B preferred by A and C; Option A chosen because of X. See discussion thread Y."
+- **Decision turns out to be wrong.** That's fine — write a new ADR superseding the old one. The old ADR is not embarrassing; it's history. Editing it to hide the mistake is worse.
+
+## Examples
+
+### Canonical ADR template
+
+```markdown
+# ADR-0007: Use a message queue between the ingest and processor
+
+## Status
+Accepted (2026-04-12)
+
+## Context
+The ingest service produces ~10k events/min. The processor's throughput is variable
+because some events trigger expensive enrichment calls. Coupling them synchronously
+caused 99th-percentile latency spikes and cascading retries on the upstream caller.
+
+## Decision
+Insert a durable message queue between ingest and processor. Ingest writes, returns
+immediately; processor consumes at its own pace. At-least-once delivery; processor
+handles idempotency by event ID.
+
+## Alternatives considered
+- Direct HTTP with a larger thread pool in the processor: rejected — does not
+  bound memory; still vulnerable to processor outage causing data loss.
+- Persist events to the database; processor polls: rejected — DB becomes a queue,
+  and queries to drain the backlog conflict with the read workload.
+- Bounded in-process channel: rejected — does not survive process restarts.
+
+## Consequences
++ Ingest latency decoupled from processing latency.
++ Processor can be restarted / scaled independently.
+- New operational surface: queue health, lag monitoring, dead-letter handling.
+- Processor code must be idempotent; existing code is not, requiring refactor.
+- One extra hop adds ~10-30ms to end-to-end latency.
+```
+
+### A second example: superseding an earlier decision
+
+```markdown
+# ADR-0019: Switch from polling to push for cache invalidation
+
+## Status
+Accepted (2026-05-20). Supersedes ADR-0011.
+
+## Context
+ADR-0011 chose polling because the cache layer did not support push at the time.
+The cache vendor added a push API in their 4.0 release (2026-04). Polling now
+accounts for ~12% of read traffic against the cache and adds 30-second staleness.
+
+## Decision
+Subscribe to the cache push channel; remove the polling loop.
+
+## Alternatives considered
+- Keep polling, reduce interval: rejected — does not solve the staleness floor
+  and increases load.
+- Hybrid (push + slow poll as safety net): considered; reserved for ADR-0020
+  if observed push reliability drops below SLA.
+
+## Consequences
++ Staleness drops from 30s to <1s p99.
++ Read traffic to cache drops ~12%.
+- New dependency on push channel availability; requires monitoring.
+- Migration window: both polling and push run for one week before polling is
+  removed (see migration plan in PR #4421).
+```
+
+And ADR-0011 receives an edit (the only allowed kind of edit on an Accepted ADR) at the top of its Status line:
+
+```markdown
+## Status
+Accepted (2025-09-04). Superseded by ADR-0019 (2026-05-20).
+```
+
+## Adoption notes
+
+To put this into practice in any codebase:
+
+- Create the directory (commonly `docs/adr/`) and add a `README.md` explaining the convention.
+- Copy a template file as `docs/adr/template.md`. New ADRs start by copying it.
+- Add a one-liner to the project guide: "Cross-module decisions get an ADR before merging."
+- Pick a numbering policy and commit to it. Padded four-digit numbers (`ADR-0001`) sort cleanly and survive growth.
+- Optionally automate: a script that creates the next file with pre-filled date and number, or a CI check that PRs touching the design-doc directory must include an ADR when they change the architecture overview.
+- Pair this skill with the spec-driven design skill: a spec answers "what will we build"; an ADR answers "why is the building shaped this way". They are complementary, not redundant.

package/dist/skills/distilled/distilled-creator.md

@@ -0,0 +1,178 @@
+---
+name: distilled-creator
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: skill-creator (score 3.5/5)'
+keywords:
+  - creator
+  - skill
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/anthropics/skills.git
+    license: Apache-2.0
+    commit: unknown
+    paths:
+      - skill-creator/SKILL.md
+  - upstream: https://github.com/anthropics/skills.git
+    license: Apache-2.0
+    commit: unknown
+    paths:
+      - slack-gif-creator/SKILL.md
+distilled_at: '2026-05-29T08:13:11.204Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 3.5
+it_universal_dims:
+  d1: 1
+  d2: 0.5
+  d3: 0.5
+  d4: 0.5
+  d5: 1
+it_universal_rationale: >-
+  Core methodology (intent capture, three-level skill loading, parallel with/baseline eval,
+  assertion timing) is fully language-agnostic and reusable in any Claude skill ecosystem;
+  deductions only for eval-viewer script path and evals.json convention tied to one specific infra.
+---
+
+# Skill Creator: Iterative Design & Evaluation Loop
+
+## When to use
+- You want to create a new Claude skill (markdown + YAML instruction file) from scratch
+- You want to improve an existing skill with test-based evidence
+- A user shows you a workflow in conversation and says "turn this into a skill"
+- You want to optimize a skill's description to fix undertriggering
+- You want to benchmark skill quality with a with/without-skill comparison
+
+## Core idea
+A Claude skill is a markdown file with YAML frontmatter following a three-level loading hierarchy: metadata (always in context), body (loaded on trigger), and bundled resources (on demand). Good skills are built iteratively — capture intent, interview for edge cases, draft SKILL.md, run parallel test cases (with-skill vs. baseline simultaneously), draft quantitative assertions *while runs are in progress*, then evaluate, rewrite, and repeat. Skill descriptions must be slightly "pushy" to overcome Claude's tendency to undertrigger. Communication style should match the user's technical fluency — observe cues before using jargon like "assertion" or "JSON" without explanation.
+
+## Steps
+
+### 1. Capture Intent
+Extract answers from conversation history first, then ask the user to fill gaps:
+1. What should this skill enable Claude to do?
+2. When should it trigger? (specific phrases, contexts, situations)
+3. What is the expected output format?
+4. Do objectively verifiable outputs exist? → plan test cases with assertions. Subjective outputs (writing style, art) → consider qualitative-only evaluation.
+
+### 2. Interview & Research
+Before writing test prompts, ask about edge cases, input/output formats, example files, success criteria, and dependencies. Research relevant docs or analogous patterns concurrently via subagents when available.
+
+### 3. Write SKILL.md
+
+**Frontmatter:**
+```yaml
+---
+name: my-skill          # kebab-case
+description: |
+  What this skill does AND when to use it. Make it slightly pushy:
+  "Use this whenever the user mentions X, Y, or Z — even if they
+  don't explicitly ask for [skill name]."
+compatibility:          # optional — required tools/MCPs
+---
+```
+
+**Directory anatomy:**
+```
+skill-name/
+├── SKILL.md                  ← required; keep under 500 lines
+└── optional-resources/
+    ├── scripts/              ← executable code for deterministic tasks
+    ├── references/           ← docs loaded into context on demand
+    └── assets/               ← templates, icons, fonts
+```
+
+**Three-level loading:**
+
+| Level | Content | When loaded |
+|-------|---------|-------------|
+| Metadata | name + description (~100 words) | Always in context |
+| SKILL.md body | Instructions (<500 lines ideal) | Whenever skill triggers |
+| Bundled resources | Scripts / references (unlimited) | Only when referenced |
+
+**Progressive disclosure:** If approaching 500 lines, split into hierarchy levels with clear pointers to where to read next. For reference files >300 lines, add a table of contents. For multi-variant skills (e.g., AWS / GCP / Azure), one file per variant so only the relevant one loads.
+
+**Output format pattern:**
+```markdown
+## Report structure
+ALWAYS use this exact template:
+# [Title]
+## Executive summary
+## Key findings
+## Recommendations
+```
+
+**Example pattern:**
+```markdown
+## Example 1
+Input: Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+```
+
+Use imperative form. Explain *why* things matter rather than stacking MUSTs. Draft once, then read with fresh eyes and revise.
+
+**Security:** Skills must not contain malware, exploit code, or misleading content. Behavior must not surprise a user who reads the description.
+
+### 4. Draft Test Cases
+Write 2–3 realistic test prompts (the kind a real user would actually type). Share with the user for confirmation before running.
+
+Save to your project's eval file (e.g., `evals/evals.json`):
+```json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User's actual task prompt",
+      "expected_output": "Description of expected result",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}
+```
+Leave `assertions` empty for now — add them in Step 6.
+
+### 5. Spawn All Runs in One Turn (With-Skill AND Baseline)
+For each test case, launch **two subagents simultaneously in the same turn** — never sequentially:
+
+- **With-skill run:** provide skill path + prompt → save to `<workspace>/iteration-<N>/<eval-name>/with_skill/outputs/`
+- **Baseline run:**
+  - *New skill:* same prompt with no skill → `without_skill/outputs/`
+  - *Improving existing skill:* snapshot old version first, point baseline at snapshot → `old_skill/outputs/`
+
+Create `eval_metadata.json` per eval directory:
+```json
+{
+  "eval_id": 0,
+  "eval_name": "descriptive-name-of-what-is-being-tested",
+  "prompt": "The user's task prompt",
+  "assertions": []
+}
+```
+
+Name eval directories descriptively, not generically. Workspace layout: `<skill-name>-workspace/iteration-<N>/<eval-name>/`.
+
+### 6. Draft Assertions While Runs Are In Progress
+Use the wait time. Draft quantitative assertions — objectively verifiable checks with descriptive names readable at a glance in any benchmark viewer. For subjective skills, rely on qualitative review; do not force assertions.
+
+Update `eval_metadata.json` and the eval file with finalized assertions before runs complete.
+
+### 7. Review Results
+Present with-skill vs. baseline side by side. Use your project's viewer/review script if available. Report both quantitative metrics and qualitative observations to the user.
+
+### 8. Iterate
+Rewrite the skill based on user feedback and quantitative failures. Repeat from Step 5 (or Step 4 if prompts also need changing). After stabilization, expand the test set for larger-scale confidence.
+
+### 9. Optimize the Description (Final)
+Run your project's skill description improver tool (if available) to maximize triggering accuracy. This is the last step, but it's worth doing — a poorly-written description causes good skills to be ignored.
+
+## Anti-patterns
+- Spawning with-skill runs first, then circling back for baselines — always launch everything in one turn
+- Waiting for runs to finish before drafting assertions — use the time productively
+- Forcing quantitative assertions onto subjective skills (style, art quality)
+- Vague or passive descriptions — they must tell Claude *when* to proactively use the skill
+- Exceeding 500 lines in SKILL.md body without adding a hierarchy layer and forward pointers
+- Generic eval directory names (`eval-0`) instead of descriptive ones
+- Assuming `eval_metadata.json` or assertions carry over from a prior iteration without recreating them
+
+## References
+- Upstream: https://github.com/anthropics/skills.git

package/dist/skills/distilled/distilled-db-schema-design.md

@@ -0,0 +1,245 @@
+---
+name: distilled-db-schema-design
+version: 0.1.0-distilled
+description: 'Distilled IT-universal skill: db-schema-design (score 4.5/5)'
+keywords:
+  - db
+  - schema
+  - design
+  - database
+  - 数据库设计
+  - migration
+  - 迁移
+  - sql
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/winspan/claude-forge.git
+    license: MIT
+    commit: 7d96b86c
+    paths:
+      - official/official-db-schema-design.md
+distilled_at: '2026-05-27T01:55:04.825Z'
+distilled_by: claude-sonnet-4-6
+it_universal_score: 4.5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 0.5
+  d5: 1
+it_universal_rationale: DB schema + migration patterns, cross-engine.
+---
+
+## 触发条件
+
+- 新建项目需要设计初始数据库结构时
+- 现有 schema 出现性能问题、数据一致性问题或难以扩展时
+- 添加新业务实体或修改已有实体关系时
+- 需要对生产数据库执行结构变更（加列、改类型、删表等）时
+- Code review 中发现 schema 设计存在反模式需要纠正时
+
+---
+
+## 核心原则
+
+1. **先建模，再建表** — ER 图或实体关系草图能暴露设计缺陷，比直接写 DDL 的返工成本低一个数量级。
+2. **单表单实体** — 每张表只表达一个业务实体；混合多个实体的宽表会导致更新异常和冗余。
+3. **约束下沉到数据库层** — 外键、唯一约束、非空约束在 DB 层强制，而不仅依赖应用层校验；应用可以崩溃，数据库约束不会。
+4. **所有变更通过迁移文件管理** — 手动改生产库无法审计、无法回滚；迁移文件是 schema 的版本历史。
+5. **破坏性变更分阶段执行** — 直接删列或改类型会导致零停机部署失败；分步操作（加→双写→删）保证新旧代码可以同时运行。
+
+---
+
+## 工作流
+
+1. **绘制实体关系图**
+   在动手写 DDL 之前，用任意工具（纸、draw.io、dbdiagram.io 等）画出实体、属性和关系。确认每个实体的边界和基数（1:1 / 1:N / M:N）。
+
+2. **确定命名规范**
+   - 表名：`snake_case` 复数形式（`user_profiles`、`order_items`）
+   - 主键：统一用 `id`（自增整数或 UUID，按项目需求选择）
+   - 时间戳：每张表必须包含 `created_at`、`updated_at`
+   - 软删除：用 `deleted_at`（nullable）而非物理删除
+
+3. **编写 DDL / 迁移文件**
+   使用项目已有的迁移工具（Flyway、Liquibase、Alembic、golang-migrate、Prisma Migrate 等）创建迁移文件，不直接在数据库控制台执行 DDL。
+
+4. **添加必要约束**
+   - 外键列声明 `FOREIGN KEY` 约束
+   - 业务唯一性用 `UNIQUE` 约束而非仅靠应用层
+   - 非空字段显式标注 `NOT NULL`
+
+5. **规划索引**
+   - 所有外键列建索引（大多数数据库不自动创建）
+   - 高频 `WHERE` / `ORDER BY` 列建索引
+   - 复合索引按查询的列顺序排列（最左前缀原则）
+   - 避免过度索引：写多读少的表索引越多写入越慢
+
+6. **编写 down migration（回滚脚本）**
+   每个 up migration 必须有对应的 down migration，并在非生产环境验证回滚可以干净执行。
+
+7. **处理破坏性变更（三步法）**
+   ```
+   Step 1 — 加新列（新旧代码均可运行）
+   Step 2 — 双写：应用同时写旧列和新列，迁移存量数据
+   Step 3 — 确认数据一致后，删旧列（单独一次迁移）
+   ```
+
+8. **Review 检查清单**
+   在合并前对照"验证标准"逐项确认，重点关注缺失索引、缺失时间戳、以及是否绕过了迁移文件直接改库。
+
+---
+
+## 反模式
+
+1. **手动修改生产数据库**
+   直接在生产控制台执行 `ALTER TABLE` 或 `DROP COLUMN`，导致变更无法审计、无法在其他环境复现、无法回滚。所有变更必须走迁移文件。
+
+2. **滥用 `ENUM` 类型**
+   数据库原生 `ENUM` 在多数引擎中修改成本极高（MySQL 需要重建表）。用关联表（lookup table）或受约束的字符串列代替，扩展时只需插入新行。
+
+3. **用 JSON 列存结构化数据**
+   把本应规范化的字段塞进 JSON 列，导致无法建索引、无法做外键约束、查询复杂度上升。JSON 列只适合真正不定结构的数据（如用户自定义元数据）。
+
+4. **EAV 模式（Entity-Attribute-Value）**
+   用三列通用表（`entity_id`, `attribute_name`, `value`）模拟动态字段，看似灵活，实则查询性能极差、类型安全丧失、关联查询变成噩梦。优先考虑 JSONB 或宽表，极端情况才考虑文档数据库。
+
+5. **缺失时间戳或软删除字段**
+   没有 `created_at` / `updated_at` 的表在排查问题时缺乏基本的时间线信息；物理删除数据后无法审计或恢复。每张表默认加时间戳，有审计需求的加 `deleted_at`。
+
+---
+
+## 验证标准
+
+- [ ] 存在 ER 图或等效的实体关系文档，与实际 DDL 保持同步
+- [ ] 每张表有且仅有一个业务实体，无跨实体的宽表
+- [ ] 所有表包含 `created_at`、`updated_at` 字段
+- [ ] 所有外键列已建索引
+- [ ] 高频查询的过滤列已建索引，且索引顺序与查询一致
+- [ ] 无裸 `ENUM` 类型；动态枚举值使用关联表或字符串
+- [ ] JSON 列仅用于非结构化数据，结构化字段已规范化
+- [ ] 每个 schema 变更对应一个迁移文件，且 down migration 可执行
+- [ ] 破坏性变更（删列、改类型）已拆分为多步迁移
+- [ ] 迁移文件已在非生产环境验证（up 和 down 均通过）
+- [ ] 无直接在数据库控制台执行的未记录变更
+
+---
+
+## 适用范围
+
+本技能适用于任何使用关系型数据库的层次：
+
+- **后端服务（backend service）** — 业务逻辑层通过 ORM 或查询构建器与 schema 交互，需遵循命名规范和约束设计
+- **持久化层（persistence layer）** — 迁移文件、连接池配置、事务边界均在此层管理
+- **调度器 / 后台任务（scheduler）** — 批量写入任务需特别关注索引对写入性能的影响
+- **CLI 工具** — 若 CLI 直接操作数据库（如数据导入、初始化脚本），同样需要走迁移流程而非裸 DDL
+- **知识库 / 搜索层（knowledge base）** — 若使用关系型存储作为向量或文档索引的元数据层，schema 设计原则同样适用
+
+> // 项目特定，复用时跳过
+> 若项目使用特定的迁移框架（如 Alembic for Python、golang-migrate for Go、Knex for Node.js），迁移文件的目录结构和命名约定以该框架文档为准，本技能描述的原则不变。
+
+---
+
+## 上游对照
+
+本技能从单一上游的 db-schema-design 规范（来源见 frontmatter）提炼，内容已做通用化处理：移除了项目特定的路径引用和工具名称，补充了多语言生态下的迁移工具示例，并将破坏性变更的三步法展开为可操作的工作流步骤。如后续有更多上游（如针对 NoSQL 或时序数据库的 schema 设计规范）合并进来，应在"核心原则"和"反模式"中增加对应的对比说明。
+
+---
+
+## 示例（伪代码）
+
+### 场景：为"订单系统"新增 `discount_codes` 表
+
+**Step 1 — 建模**
+
+```
+实体：DiscountCode
+属性：id, code(唯一), discount_percent, expires_at, created_at, updated_at, deleted_at
+关系：Order (N) ——uses——> DiscountCode (1)
+      => orders 表加外键列 discount_code_id
+```
+
+**Step 2 — 编写迁移文件（伪代码，适用于任意迁移框架）**
+
+```
+-- UP
+CREATE TABLE discount_codes (
+    id          BIGINT PRIMARY KEY AUTO_INCREMENT,  -- 或 UUID
+    code        VARCHAR(64) NOT NULL UNIQUE,
+    discount_percent NUMERIC(5,2) NOT NULL,
+    expires_at  TIMESTAMP,
+    created_at  TIMESTAMP NOT NULL DEFAULT NOW(),
+    updated_at  TIMESTAMP NOT NULL DEFAULT NOW(),
+    deleted_at  TIMESTAMP                           -- 软删除
+);
+
+-- orders 表加外键（破坏性变更三步法 Step 1：加新列）
+ALTER TABLE orders
+    ADD COLUMN discount_code_id BIGINT,
+    ADD CONSTRAINT fk_orders_discount_code
+        FOREIGN KEY (discount_code_id)
+        REFERENCES discount_codes(id);
+
+-- 外键列建索引
+CREATE INDEX idx_orders_discount_code_id ON orders(discount_code_id);
+
+-- DOWN
+DROP INDEX idx_orders_discount_code_id ON orders;
+ALTER TABLE orders DROP FOREIGN KEY fk_orders_discount_code;
+ALTER TABLE orders DROP COLUMN discount_code_id;
+DROP TABLE discount_codes;
+```
+
+**Step 3 — 多语言迁移工具调用示意**
+
+```
+# Python (Alembic)
+alembic upgrade head
+alembic downgrade -1
+
+# Go (golang-migrate)
+migrate -path ./migrations -database $DATABASE_URL up
+migrate -path ./migrations -database $DATABASE_URL down 1
+
+# Node.js (Knex / Prisma)
+npx knex migrate:latest
+npx knex migrate:rollback
+
+# Java (Flyway)
+flyway migrate
+flyway undo          # 需要 Flyway Teams
+```
+
+**Step 4 — 验证索引覆盖（伪代码）**
+
+```
+-- 检查高频查询是否命中索引
+EXPLAIN SELECT * FROM orders
+WHERE discount_code_id = ?
+  AND deleted_at IS NULL;
+
+-- 期望输出：type = ref 或 range，key = idx_orders_discount_code_id
+-- 若 type = ALL（全表扫描），说明索引未生效，需检查列类型是否匹配
+```
+
+**Step 5 — 破坏性变更示例：将 `discount_percent` 从 `INT` 改为 `NUMERIC`**
+
+```
+-- 错误做法（直接 ALTER，可能锁表或丢精度）
+ALTER TABLE discount_codes MODIFY discount_percent NUMERIC(5,2);
+
+-- 正确做法（三步法）
+-- 迁移 A：加新列
+ALTER TABLE discount_codes ADD COLUMN discount_percent_new NUMERIC(5,2);
+
+-- 应用层双写（伪代码）
+function saveDiscount(record):
+    record.discount_percent     = toInt(value)    // 旧列，兼容旧代码
+    record.discount_percent_new = toDecimal(value) // 新列
+    db.save(record)
+
+-- 迁移 B：存量数据回填 + 删旧列（确认双写稳定后执行）
+UPDATE discount_codes SET discount_percent_new = discount_percent::NUMERIC;
+ALTER TABLE discount_codes DROP COLUMN discount_percent;
+ALTER TABLE discount_codes RENAME COLUMN discount_percent_new TO discount_percent;
+```