Browse Source
* feat: add pro-upgrade skill for AI-assisted project upgrades Add a Claude Code skill and Codex-compatible instructions that enable AI agents to upgrade Ant Design Pro projects by diffing the latest template and intelligently merging framework changes while preserving business code. Works for any version gap (v5→v6, v6.x→latest, etc.). Closes ant-design/ant-design-pro#11800 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore: revert AGENTS.md to simple link to CLAUDE.md CLAUDE.md already contains the Upgrading section, no need to duplicate in AGENTS.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore: replace AGENTS.md with symlink to CLAUDE.md Avoid duplicating content — Codex reads AGENTS.md which now points directly to CLAUDE.md where all guidance (including the pro-upgrade skill reference) lives. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: add upgrade FAQ to cheatsheets Add guidance for upgrading Ant Design Pro projects using the pro-upgrade skill in both Chinese and English cheatsheets. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: add skill install instructions to upgrade FAQ Users upgrading from older versions won't have the skill file, so provide a curl command to download it from the latest template. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs: use npx skills add for skill installation Replace curl command with `npx skills add ant-design/ant-design-pro` in both cheatsheets. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix: address PR review feedback - Preflight warning: change from Chinese-only to English - Dependency merging: preserve user deps not found in template by default - antd migrate: use version placeholders instead of hardcoded "5 6" - Business files: use recursive glob src/services/**/*.ts - Cheatsheet: temper "upgrade" to "assist" to avoid overpromising Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>pull/11803/head
afc163
4 months ago
committed by
GitHub
GitHub
5 changed files with 185 additions and 5 deletions
@ -0,0 +1,166 @@ |
|||
--- |
|||
name: pro-upgrade |
|||
description: > |
|||
Use when the user wants to upgrade their Ant Design Pro project to the latest version. |
|||
Triggers on: upgrade pro, pro upgrade, migrate pro, update pro, 升级, 迁移项目, |
|||
"how to upgrade", "update to latest", "keep project up to date". |
|||
allowed-tools: |
|||
- Bash(git clone *) |
|||
- Bash(diff *) |
|||
- Bash(npm install) |
|||
- Bash(npm run lint*) |
|||
- Bash(npm run build*) |
|||
- Bash(npm run tsc*) |
|||
- Bash(npx antd *) |
|||
- Bash(rm -rf /tmp/ant-design-pro-upgrade*) |
|||
- Read |
|||
- Edit |
|||
- Write |
|||
- Glob |
|||
- Grep |
|||
--- |
|||
|
|||
# Ant Design Pro Upgrade Skill |
|||
|
|||
You are an Ant Design Pro upgrade assistant. Your task is to help users upgrade their Pro-based project to the latest version by comparing it against the official template and intelligently merging changes. |
|||
|
|||
## Preflight |
|||
|
|||
Before starting, confirm: |
|||
|
|||
1. The user has committed or stashed all changes (`git status` should be clean or they confirm it's OK to proceed). |
|||
2. If not clean, remind them to commit or stash their changes first (e.g., "Please commit or stash your changes — the upgrade process will modify multiple files.") and wait for them to confirm. |
|||
|
|||
## Upgrade Flow |
|||
|
|||
### Step 1 — Fetch the latest template |
|||
|
|||
```bash |
|||
rm -rf /tmp/ant-design-pro-upgrade |
|||
git clone --depth=1 https://github.com/ant-design/ant-design-pro.git /tmp/ant-design-pro-upgrade |
|||
``` |
|||
|
|||
Read the template's `package.json` to confirm its version. |
|||
|
|||
### Step 2 — Classify files |
|||
|
|||
Separate the user's project files into **framework files** (Pro-owned, rarely customized) and **business files** (user-written, must be preserved). |
|||
|
|||
**Framework files** — diff these against the template: |
|||
|
|||
| Path | Notes | |
|||
|---|---| |
|||
| `package.json` | dependencies, scripts, devDependencies only | |
|||
| `config/config.ts` | framework config | |
|||
| `config/routes.ts` | structure only — preserve user-added routes | |
|||
| `config/defaultSettings.ts` | layout/theme defaults | |
|||
| `config/proxy.ts` | structure only — preserve user targets | |
|||
| `src/app.tsx` | runtime config | |
|||
| `src/access.ts` | permission definitions | |
|||
| `src/global.tsx` | global side effects | |
|||
| `src/loading.tsx` | loading component | |
|||
| `src/requestErrorConfig.ts` | request interceptor | |
|||
| `src/typings.d.ts` | global type declarations | |
|||
| `tsconfig.json` | TypeScript config | |
|||
| `biome.json` or `biome.jsonc` | linter config | |
|||
| `.husky/` | git hooks | |
|||
| `commitlint.config.*` | commit lint config | |
|||
| `src/services/ant-design-pro/` | auto-generated — do NOT manually edit; regenerate with `npm run openapi` | |
|||
|
|||
**Business files** — preserve these, only adjust imports/APIs if needed: |
|||
|
|||
- `src/pages/**` — user pages |
|||
- `src/components/**` — user components |
|||
- `src/models/**` — user models |
|||
- `src/services/**/*.ts` — custom service files (NOT the `ant-design-pro/` subdirectory) |
|||
- `src/locales/**` — user translations (framework keys may need updating) |
|||
- `src/utils/**` — user utilities |
|||
- `mock/**` — user mocks |
|||
- Any other files not listed above |
|||
|
|||
### Step 3 — Diff framework files |
|||
|
|||
For each framework file, read both the user's version and the template version. Identify: |
|||
|
|||
- **New dependencies** or version bumps in `package.json` |
|||
- **New/changed config options** in `config/` files |
|||
- **Import path changes** (e.g., `from 'umi'` → `from '@umijs/max'`) |
|||
- **API changes** in `src/app.tsx`, `src/access.ts`, etc. |
|||
- **New files** that exist in template but not in user's project |
|||
|
|||
### Step 4 — Merge intelligently |
|||
|
|||
Apply changes with these rules: |
|||
|
|||
**Framework files — adopt template structure, preserve user customizations:** |
|||
- `package.json`: update dependency versions to match template. Keep any extra deps the user added. If a dependency exists in the user's project but not in the template, assume it is a user customization and preserve it. |
|||
- `config/routes.ts`: adopt the template's route structure for framework pages, but keep all user-added routes intact. |
|||
- `config/proxy.ts`: adopt structure, preserve user's proxy targets. |
|||
- Other framework files: adopt the template version, preserving any user customizations that are clearly intentional (comments, extra exports, business logic mixed in). |
|||
|
|||
**Business files — minimal changes only:** |
|||
- Update import paths if framework modules moved (e.g., `'umi'` → `'@umijs/max'`). |
|||
- Update deprecated API calls if the template shows a new pattern. |
|||
- Never rewrite business logic, restructure components, or change styling approaches unless the old approach is broken. |
|||
|
|||
**Auto-generated files:** |
|||
- `src/services/ant-design-pro/`: do NOT edit. Tell the user to run `npm run openapi` after upgrade. |
|||
|
|||
### Step 5 — Antd-specific migration checks |
|||
|
|||
Run these commands to catch antd API changes: |
|||
|
|||
```bash |
|||
npx antd env --format json |
|||
npx antd lint ./src --format json --only deprecated |
|||
``` |
|||
|
|||
If the user is upgrading across major antd versions, also run: |
|||
|
|||
```bash |
|||
npx antd migrate <current_major> <target_major> --format json |
|||
``` |
|||
|
|||
Detect the current major version from the user's `package.json` and the target from the template's. |
|||
|
|||
Address any findings by updating the flagged code. |
|||
|
|||
### Step 6 — Install and verify |
|||
|
|||
```bash |
|||
npm install |
|||
npm run lint |
|||
npm run build |
|||
``` |
|||
|
|||
Fix any errors. Common post-upgrade issues: |
|||
- Type errors from changed APIs → check `npx antd info <Component>` for current APIs |
|||
- New lint rules from Biome config changes → run `npm run biome` to auto-fix |
|||
- Missing peer dependencies → check `npm install` warnings |
|||
|
|||
### Step 7 — Cleanup and summarize |
|||
|
|||
```bash |
|||
rm -rf /tmp/ant-design-pro-upgrade |
|||
``` |
|||
|
|||
Output a summary of all changes made, grouped by category: |
|||
|
|||
1. **Dependencies updated** — list version changes |
|||
2. **Config changes** — what changed in config files |
|||
3. **Code patterns migrated** — import path changes, API updates |
|||
4. **New files added** — any files from the template that didn't exist before |
|||
5. **Manual review needed** — anything you're unsure about or that requires user action |
|||
|
|||
Remind the user to: |
|||
- Run `npm run openapi` if they use the auto-generated API services |
|||
- Test their application thoroughly |
|||
- Commit the changes |
|||
|
|||
## Key Principles |
|||
|
|||
- **No hardcoded versions** — this skill works regardless of the version gap between the user's project and the latest template. |
|||
- **Preserve business code** — only modify what's necessary for framework compatibility. |
|||
- **Conservative merging** — when uncertain whether a change is a user customization or an outdated pattern, ask the user instead of guessing. |
|||
- **Leverage `@ant-design/cli`** — use `antd migrate`, `antd lint`, `antd info` for antd-specific checks; don't guess APIs from memory. |
|||
- **Clean up** — always remove the temporary clone directory. |
|||
@ -1,5 +0,0 @@ |
|||
# AGENTS.md |
|||
|
|||
This file provides guidance for AI coding agents when working with code in this repository. |
|||
|
|||
For full project guidance, see [CLAUDE.md](./CLAUDE.md). |
|||
@ -0,0 +1 @@ |
|||
CLAUDE.md |
|||
Loading…
Reference in new issue