From a72fde0739eaae7864b0f5d177e93c2c2df63d7a Mon Sep 17 00:00:00 2001 From: zuiidea Date: Sun, 18 Oct 2026 18:48:05 +0800 Subject: [PATCH] chore: consolidate agent guidance into AGENTS.md Merge scoped instructions into per-app AGENTS.md, add monorepo AGENTS.md and add-resource skill, and remove template .github Copilot files plus the Cursor app router rule. Co-authored-by: Cursor --- .cursor/rules/app.mdx | 66 ---------- .gitignore | 2 +- AGENTS.md | 23 ++++ README.md | 4 +- apps/basic/.github/instructions/README.md | 17 --- .../.github/instructions/api.instructions.md | 30 ----- .../instructions/frontend.instructions.md | 32 ----- .../instructions/refactor.instructions.md | 37 ------ .../instructions/testing.instructions.md | 30 ----- apps/basic/AGENTS.md | 104 +++++++--------- apps/basic/README.md | 2 +- .../docs/content/zh/templates/with-lingui.mdx | 2 +- .../skills/add-resource/SKILL.md} | 6 +- .../.github/instructions/README.md | 18 --- .../.github/instructions/api.instructions.md | 30 ----- .../instructions/frontend.instructions.md | 31 ----- .../instructions/refactor.instructions.md | 36 ------ .../instructions/testing.instructions.md | 31 ----- apps/with-lingui/AGENTS.md | 114 ++++++++---------- apps/with-lingui/README.md | 9 +- ...026-04-24-with-lingui-optimization-plan.md | 2 +- 21 files changed, 134 insertions(+), 492 deletions(-) delete mode 100644 .cursor/rules/app.mdx create mode 100644 AGENTS.md delete mode 100644 apps/basic/.github/instructions/README.md delete mode 100644 apps/basic/.github/instructions/api.instructions.md delete mode 100644 apps/basic/.github/instructions/frontend.instructions.md delete mode 100644 apps/basic/.github/instructions/refactor.instructions.md delete mode 100644 apps/basic/.github/instructions/testing.instructions.md rename apps/with-lingui/{.github/instructions/add-resource.instructions.md => .agents/skills/add-resource/SKILL.md} (86%) delete mode 100644 apps/with-lingui/.github/instructions/README.md delete mode 100644 apps/with-lingui/.github/instructions/api.instructions.md delete mode 100644 apps/with-lingui/.github/instructions/frontend.instructions.md delete mode 100644 apps/with-lingui/.github/instructions/refactor.instructions.md delete mode 100644 apps/with-lingui/.github/instructions/testing.instructions.md diff --git a/.cursor/rules/app.mdx b/.cursor/rules/app.mdx deleted file mode 100644 index 1531ad8..0000000 --- a/.cursor/rules/app.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -description: "Thin Cursor rules for template apps with-lingui / basic — route by path and task to each app's .github/instructions (Approach A, single source of truth)" -globs: apps/with-lingui/{src,e2e}/**/*.{ts,tsx,css},apps/basic/{src,e2e}/**/*.{ts,tsx,css},apps/with-lingui/playwright.config.ts,apps/basic/playwright.config.ts -alwaysApply: false ---- - -# Template apps — AI rules (thin rule) - -This file at the **monorepo root** is the shared **Cursor thin rule** for `apps/with-lingui` and `apps/basic`. It only maps **which files you edit → which instruction file to follow**. Do **not** duplicate long guidance here. - -**Single source of truth** (on conflict, these win): - -- `apps/with-lingui/.github/instructions/*.instructions.md` -- `apps/basic/.github/instructions/*.instructions.md` - -For full text in chat, `@`-reference the path below. - ---- - -## General - -- When editing template app source or tests matched by `globs`, pick the row in the tables below, then follow that file’s **Do / Do Not / Validation**. -- **with-lingui** includes Lingui i18n; **basic** uses plain string literals in UI (default English; no bundled locale switcher or translation catalogs). -- When **frontend** and **refactor** both apply: **refactor intent** (dedupe, naming, structure, no behavior change) is governed by `refactor.instructions.md`; UI/interaction details still follow `frontend.instructions.md`. -- If you change an instruction file’s `applyTo`, keep this file’s frontmatter `globs` aligned so both apps’ TS/TSX/CSS/E2E paths stay covered. - ---- - -## apps/with-lingui - -| Scenario | Typical paths | Instruction file | -| --- | --- | --- | -| Frontend (UI, routes, components, styles, Ant Design, i18n copy) | `apps/with-lingui/src/**/*.{ts,tsx,css}` | `apps/with-lingui/.github/instructions/frontend.instructions.md` | -| API (clients, Zod, HTTP, MSW handlers) | `apps/with-lingui/src/api/**`, `apps/with-lingui/src/mocks/handlers/**`, `createHandler.ts` | `apps/with-lingui/.github/instructions/api.instructions.md` | -| Testing (Playwright, MSW, test config) | `apps/with-lingui/e2e/**`, `apps/with-lingui/src/mocks/**`, `playwright.config.ts` | `apps/with-lingui/.github/instructions/testing.instructions.md` | -| Refactor (behavior-preserving) | `apps/with-lingui/src/**/*.{ts,tsx}` | `apps/with-lingui/.github/instructions/refactor.instructions.md` | -| Add CRUD resource | `src/api/**`, `src/mocks/**`, `src/routes/_auth/**`, `e2e/**/*.spec.ts` | `apps/with-lingui/.github/instructions/add-resource.instructions.md` (mirror `users`) | - -**@ examples:** - -- `@apps/with-lingui/.github/instructions/frontend.instructions.md` -- `@apps/with-lingui/.github/instructions/add-resource.instructions.md` - -See also `apps/with-lingui/AGENTS.md` (Vite+ / `vp` workflow). - ---- - -## apps/basic - -| Scenario | Typical paths | Instruction file | -| --- | --- | --- | -| Frontend (UI, routes, components, styles, Ant Design, English copy) | `apps/basic/src/**/*.{ts,tsx,css}` | `apps/basic/.github/instructions/frontend.instructions.md` | -| API | `apps/basic/src/api/**`, `apps/basic/src/mocks/handlers/**`, `createHandler.ts` | `apps/basic/.github/instructions/api.instructions.md` | -| Testing | `apps/basic/e2e/**`, `apps/basic/src/mocks/**`, `playwright.config.ts` | `apps/basic/.github/instructions/testing.instructions.md` | -| Refactor | `apps/basic/src/**/*.{ts,tsx}` | `apps/basic/.github/instructions/refactor.instructions.md` | - -**@ example:** `@apps/basic/.github/instructions/frontend.instructions.md` - -See also `apps/basic/AGENTS.md`. - ---- - -## Maintenance - -- Humans and agents should **edit** each app’s `.github/instructions/` first; this file only maintains the routing table and `globs`. -- Comment language is still governed by `.cursor/rules/english-only-comments.md` (not UI copy or docs). diff --git a/.gitignore b/.gitignore index 23920af..7c32fe6 100644 --- a/.gitignore +++ b/.gitignore @@ -42,7 +42,7 @@ yarn-error.log* # Git worktrees .worktrees/ -# Cursor: share project rules only (e.g. .cursor/rules/app.mdx); ignore other local Cursor data (instruction source of truth in each app’s .github/instructions) +# Cursor: share project rules only; ignore other local Cursor data (agent rules: each app’s AGENTS.md) .cursor/* !.cursor/rules/ !.cursor/rules/** diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..22d6f67 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# antd-admin (monorepo) + +Enterprise admin templates and docs. **AI and coding rules live in each app’s `AGENTS.md`**, not here. + +## Layout + +| Path | Role | +| --- | --- | +| `apps/basic` | English Vite+ template — see `apps/basic/AGENTS.md` | +| `apps/with-lingui` | Lingui i18n template — see `apps/with-lingui/AGENTS.md` | +| `apps/docs` | Nextra docs site | +| `packages/create` | `init-antd-admin` CLI | + +## Commands (repo root) + +- `pnpm install` — sets `core.hooksPath=.githooks` via `preinstall` +- `pnpm dev` / `pnpm build` / `pnpm fmt` / `pnpm lint` — turbo across workspaces + +**Template app work:** `cd apps/basic` or `cd apps/with-lingui`, then use **`vp`** (`vp install`, `vp check`, …). Do not run app `vp staged` from root without that `cd`. + +## Git hooks + +`.githooks/pre-commit` runs checks by staged paths: `pnpm exec vp staged` in `apps/basic` / `apps/with-lingui`, typecheck for `packages/create`, lint for `apps/docs`. diff --git a/README.md b/README.md index 298b1e9..22a58e4 100644 --- a/README.md +++ b/README.md @@ -61,9 +61,9 @@ pnpm dlx init-antd-admin@latest my-app --example with-lingui --skip-install For detailed CLI behavior, see `[packages/create/README.md](./packages/create/README.md)`. -### Working in this monorepo (Cursor) +### AI / agent guidance -Template apps ship scoped guidance under each app’s `.github/instructions/` (see each app’s `README.md`). **Monorepo-only:** root [`.cursor/rules/app.mdx`](./.cursor/rules/app.mdx) is a thin router to those files when editing `apps/with-lingui` or `apps/basic`; it is **not** included in `init-antd-admin` output. +Each template app keeps **`AGENTS.md`** as the single source of truth (Cursor, Claude Code, Codex, etc.). Monorepo overview: [AGENTS.md](./AGENTS.md) at the repo root. Production docs: [https://antd-admin-doc.zuiidea.top](https://antd-admin-doc.zuiidea.top) diff --git a/apps/basic/.github/instructions/README.md b/apps/basic/.github/instructions/README.md deleted file mode 100644 index 27850d7..0000000 --- a/apps/basic/.github/instructions/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# AI Instruction Files - -This directory contains scoped instruction files used by AI coding agents. - -## Files - -- `frontend.instructions.md`: UI/routes/components/style changes -- `testing.instructions.md`: Playwright/MSW/test changes -- `api.instructions.md`: API client/schema/handler changes -- `refactor.instructions.md`: behavior-preserving cleanup and deduplication - -## Authoring Rules - -- Keep each file focused on one domain. -- Put trigger phrases in `description` so agents can discover the file. -- Use narrow `applyTo` patterns to avoid unnecessary context load. -- Keep instructions executable: short Do/Do Not/Validation sections. diff --git a/apps/basic/.github/instructions/api.instructions.md b/apps/basic/.github/instructions/api.instructions.md deleted file mode 100644 index ec6151d..0000000 --- a/apps/basic/.github/instructions/api.instructions.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -applyTo: "src/api/**/*.ts,src/mocks/handlers/**/*.ts,src/mocks/createHandler.ts" -description: "Use when editing API clients, schemas, HTTP behavior, response types, or MSW endpoint handlers. Keywords: api, request, defineApi, schema, zod, handler, endpoint, auth, users." ---- - -# API Instructions - -## Purpose - -Maintain strict API contracts and a single call path: **schemas → `defineApi` resource modules → UI**. Transport lives in `src/api/request.ts` (axios + interceptors). - -## Do - -- Define APIs with `defineApi` in `src/api/.ts` (`method` defaults to `GET`; use `params` / `query` / `body` + `output`). -- Keep Zod schemas in `src/api/schemas.ts` as the single contract; parse inputs/outputs inside `defineApi`. -- Keep MSW handler envelopes consistent (`code`, `data`, `message`) and aligned with schemas. -- Co-locate React Query keys with resource modules (e.g. `userQueryKeys`). -- Use `hydrateSession` from `@/api/auth` after login/register or when restoring a session. - -## Do Not - -- Do not call `axios` or `@/api/request` transport helpers from routes/components — import resource functions only (`listUsers`, `login`, …). -- Do not return ad-hoc response shapes for one-off convenience. -- Do not bypass schema parsing in new client mutations/queries. -- Do not mix unrelated domain endpoints in the same module. - -## Validation - -- Verify TypeScript and schema parsing paths compile cleanly. -- Run: `vp check --no-fmt` diff --git a/apps/basic/.github/instructions/frontend.instructions.md b/apps/basic/.github/instructions/frontend.instructions.md deleted file mode 100644 index 4034cca..0000000 --- a/apps/basic/.github/instructions/frontend.instructions.md +++ /dev/null @@ -1,32 +0,0 @@ ---- - -## applyTo: "src/\*_/_.{ts,tsx,css}" - -description: "Use when editing React UI, route pages, components, styles, layout, copy, or Ant Design behavior. Keywords: frontend, component, page, ui, layout, style, antd, english copy." - -# Frontend Instructions - -## Purpose - -Keep frontend changes predictable, minimal, and reusable for AI-assisted edits. - -## Do - -- Preserve existing route contracts and UI behavior unless explicitly asked. -- Prefer reusable components and hooks over copy-paste logic. -- Keep styles token-driven using existing theme/store patterns. -- For Ant Design styling, follow this priority: component native API (`variant`/`type`/`size`/`styles`/`classNames`) -> `theme.useToken()` with inline `style` -> `className` + external CSS. -- Keep user-facing copy in English as plain string literals (this template has no i18n layer). -- Follow current folder conventions under src/components and src/routes. - -## Do Not - -- Do not introduce new UI libraries when Ant Design already covers the need. -- Do not bypass existing theme/store abstractions with hardcoded global state. -- Do not write CSS overrides first when props or semantic `styles` can express the same UI. -- Do not refactor unrelated files in the same change. - -## Validation - -- Run: `vp check --no-fmt` -- For UI flow changes, run focused e2e where possible. diff --git a/apps/basic/.github/instructions/refactor.instructions.md b/apps/basic/.github/instructions/refactor.instructions.md deleted file mode 100644 index 81e74f5..0000000 --- a/apps/basic/.github/instructions/refactor.instructions.md +++ /dev/null @@ -1,37 +0,0 @@ ---- - -## applyTo: "src/_/_.{ts,tsx}" - -description: "Use when refactoring existing code for deduplication, modularization, naming cleanup, or maintainability improvements without behavior changes. Keywords: refactor, cleanup, simplify, deduplicate, maintainability." - -# Refactor Instructions - -## Purpose - -Reduce duplication while preserving behavior and public contracts. - -## Do - -- Keep refactors incremental and scoped to one concern per change. -- Prefer extracting shared utilities/hooks/components over large rewrites. -- Preserve existing external behavior and route/store contracts. -- Keep diffs reviewable with minimal unrelated formatting churn. -- Add or update lightweight comments only when logic is non-obvious. - -## Do Not - -- Do not change runtime behavior unless explicitly requested. -- Do not rename broadly across the codebase without clear benefit. -- Do not delete tests that still cover unique critical scenarios. -- Do not introduce large dependencies for minor convenience; prefer composition or small utilities. - -## Considerations - -- Bundle: Main app chunk is ~135KB (gzip ~41KB). Ant Design (vendor-antd) and TanStack (vendor-tanstack) are in separate chunks for parallel loading. Avoid adding large UI libraries when Ant Design covers the need. -- Type safety: Keep validations at API boundaries (Zod schemas) rather than adding more runtime checks throughout the app. - -## Validation - -- Confirm no new diagnostics in touched files. -- Run: `vp check --no-fmt` -- For significant changes, verify bundle size impact: `vp build 2>&1 | grep "kB"` diff --git a/apps/basic/.github/instructions/testing.instructions.md b/apps/basic/.github/instructions/testing.instructions.md deleted file mode 100644 index b08d024..0000000 --- a/apps/basic/.github/instructions/testing.instructions.md +++ /dev/null @@ -1,30 +0,0 @@ ---- - -## applyTo: "tests/**/.ts,tests/**/_.tsx,src/mocks//_.ts,playwright.config.ts" - -description: "Use when adding or editing tests, Playwright cases, MSW handlers, mock data, or test configuration. Keywords: test, e2e, playwright, mock, msw, coverage." - -# Testing Instructions - -## Purpose - -Keep tests fast, deterministic, and aligned with core business flows. - -## Do - -- Prioritize core flows first (auth, users CRUD, permission gates). -- Keep assertions user-visible and behavior-focused. -- Reuse existing helper patterns in tests before adding new helpers. -- Keep mock handlers and mock data synchronized with API schemas. -- Prefer focused test runs over full-suite runs during iteration. - -## Do Not - -- Do not add brittle selectors tied to unstable DOM internals. -- Do not expand fixture data without a clear scenario need. -- Do not duplicate scenarios already covered by existing tests. - -## Validation - -- Run focused tests first, then broader checks if needed. -- Run: `vp check --no-fmt` diff --git a/apps/basic/AGENTS.md b/apps/basic/AGENTS.md index 49ea51f..d9d4eb4 100644 --- a/apps/basic/AGENTS.md +++ b/apps/basic/AGENTS.md @@ -1,84 +1,70 @@ -# Using Vite+, the Unified Toolchain for the Web +# antd-admin-basic -This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, but it invokes Vite through `vp dev` and `vp build`. +Vite+ template app (React 19, Ant Design 6, TanStack Router/Query, MSW). Default UI copy is English (no i18n). CLI details: [viteplus.dev](https://viteplus.dev). -## Vite+ Workflow +## Commands -`vp` is a global binary that handles the full development lifecycle. Run `vp help` to print a list of commands and `vp --help` for information about a specific command. +Run from **`apps/basic`** (this directory): -### Start +| Task | Command | +| ------------------------- | ---------------------------------------------------- | +| Install deps | `vp install` (after every pull) | +| Dev / build / preview | `vp dev`, `vp build`, `vp preview` | +| Format / lint / typecheck | `vp check`, `vp check --no-fmt`, `vp lint`, `vp fmt` | +| Unit tests | `vp test run` | +| E2E | `pnpm run test:e2e` (or focused spec via Playwright) | +| Add/remove deps | `vp add`, `vp remove` — not raw `pnpm`/`npm`/`yarn` | -- create - Create a new project from a template -- migrate - Migrate an existing project to Vite+ -- config - Configure hooks and agent integration -- staged - Run linters on staged files -- install (`i`) - Install dependencies -- env - Manage Node.js versions +**Pitfalls:** Do not install Vitest/Oxlint/Oxfmt/tsdown directly; use `vp`. Do not run `vp vitest` — use `vp test`. If a `package.json` script name conflicts with a built-in `vp` command, use `vp run