Agent Skills 与 AI 辅助开发
让 agent 写一个 CRUD 模块，代码多半能跑，却不太像这个仓库里其它模块的写法。两组约定就是拿来消这个差的，分界线是你要它改谁的代码：
- 参与 SmartAdmin 本体开发：docs/agents/ 下的一组文档，规定 agent 怎么读 issue、打分诊标签、读领域背景。
- 在 SmartAdmin 之上开发业务模块：
skills/下的一组开发规范文档，教 agent 按项目既定模式建实体、建 CRUD、替换服务，内核维护者加系统模块和消费方在自己项目里二开走的是同一套。
两组都不是代码生成器，而是规则加参考模板：agent 读完它们，写出你需求要的代码，这些约定只管这段代码长什么样。
Issue / PRD：走 GitHub Issues
仓库的 issue 和 PRD 都是 GitHub issue，约定详见 docs/agents/issue-tracker.md。agent 读写 issue 走 gh CLI，不用脱离浏览器另找接口。
PR 目前不当作请求入口
issue-tracker.md 里这条开关当前是「否」：外部 PR 不会走和 issue 一样的标签流程。如果哪天改成「是」，PR 会套用同一组标签和状态，在 GitHub 的 PR 页面上打。
Triage 标签
Issue 分诊用五个规范化标签，标签串就是角色名本身，取值和用法在 docs/agents/triage-labels.md 定死：
| 标签 | 含义 |
|---|---|
needs-triage | 维护者还没评估过 |
needs-info | 等报告人补充信息 |
ready-for-agent | 需求已经描述清楚，可以丢给 AFK agent 直接做 |
ready-for-human | 需要人工实现 |
wontfix | 不会处理 |
想找能自动化跑掉的任务，挑 ready-for-agent 标签的 issue 最省心。
领域文档：CONTEXT.md + docs/adr
docs/agents/domain.md 要求 agent 动代码之前先看两样：
- 仓库根目录的
CONTEXT.md。多上下文场景下换成CONTEXT-MAP.md，它指向各上下文各自的CONTEXT.md。 docs/adr/下和当前改动区域相关的 ADR。
词条和 ADR 都是按需补的
仓库根的 CONTEXT.md 按模块懒创建词条，docs/adr/ 只记将来会被重新提起的取舍。只有当 /domain-modeling 之类的 skill 真的需要落地某个术语或某条决策时，才往里加。某个术语查不到不代表约定不存在，也不需要因此要求先补文档。
如果你的产出里用到领域名词，比如 issue 标题、重构提案、测试名，就要和 CONTEXT.md 里的术语保持一致，别在文档已经明确定义的地方随意换用近义词。这些内容和已有 ADR 冲突时，要显式指出来，不能悄悄用新方案覆盖旧决策。
业务开发 Skills(skills/)
这组文档面向「在 SmartAdmin 上面接着写业务」的场景。内核维护者加系统模块，消费方在自己项目里二开，走的是同一套模式。索引在 skills/README.md：
| Skill | 用途 | 适用场景 |
|---|---|---|
new-module | 新增完整业务模块的全流程编排 | 从零做一个模块（实体 → 后端 → 前端 → 菜单/权限） |
create-entity | 创建 SqlSugar 实体类 | 新建表、新建实体 |
create-crud-backend | 创建后端 CRUD 全套 | Models + Interface + Service + ErrorCode + DI + Controller |
create-crud-frontend | 创建前端 CRUD 页面 | Types + API + Vue 页面（SmartTable + FormContainer） |
replace-service | 替换/扩展内置服务 | 定制登录流程、换密码哈希、覆写服务步骤 |
wire-import-export | 给自己的实体接导入导出 | 装 SmartAdmin.Excel、档案、六个端点、菜单取号 |
create-job | 给自己的模块加定时任务 | 写 IAdminJob、注册一行，后台建任务或写种子；HTTP/SQL 任务与五个常见坑 |
create-page-variant | 非标准页面模板 | 树表、主从分栏、侧栏筛选、详情页、上下分栏定高 + 放大 |
Claude Code 下这些 skill 已经包装成 .claude/skills/ 下的斜杠命令，直接输入 /new-module、/create-entity、/create-crud-backend、/create-crud-frontend、/replace-service、/wire-import-export、/create-job、/create-page-variant 即可。也支持自然语言自动触发，比如直接说「帮我创建一个产品实体」。其它 AI 工具没有斜杠命令机制，在对话里直接引用文件路径就行，比如「参考 skills/create-entity.md，帮我创建一个 BizProduct 实体」。
新增一个完整 CRUD 模块，标准顺序是下面三步。/new-module 会把它们串起来一次跑完，想分步来就单独调用：
/create-entity：建实体/create-crud-backend：建后端（含菜单种子数据）/create-crud-frontend：建前端（含 i18n）
上面这三步连同 new-module，都会区分两种模式：系统模块是内核维护者用的，业务模块是消费方二开用的。两种模式生成的代码位置和命名规则不一样，用之前先说清楚是哪种场景。replace-service 只面向消费方，create-page-variant 只按页面形态分变体，都没有这条分叉。