用 backendskills 给编码 Agent 装上后端防坑技能：npx skills add 三技能落地与 bench 验收实操

# 前置：确认 Node 与 npx 可用
node --version
npx --version

# 在线审阅仓库结构（浏览器打开也可以）
# https://github.com/globalmpc/backendskills
# 重点看：README.md、LICENSE、skills/、dist/、bench/

# 准备一个可回滚的练习仓库
git status --short
git log -1 --oneline

# 记下当前 Agent 的规则文件位置，避免待会被覆盖
# Claude Code 用 .claude/skills/，Codex 类看 AGENTS.md，Cursor 看 .cursor/rules/

# 安装（官方 README 原样）
npx skills add globalmpc/backendskills

# 安装后核对落盘位置
# Claude Code：.claude/skills/ 下出现三份技能
# 生成物：仓库 dist/AGENTS.md 与 dist/cursor/

# 用 git 看清楚这次改动了哪些文件
git status --short

# 若项目里已有同名技能，先备份再决定合并方式
cp -r .claude/skills .claude/skills.bak

# Claude Code：安装器已写入 .claude/skills/，核目录即可
# 三份技能分别是 api-endpoint、data-integrity、db-migration

# Codex 及其它 AGENTS.md 类 Agent：把生成物追加到项目规则
cat dist/AGENTS.md >> AGENTS.md

# Cursor：把生成物复制进规则目录
mkdir -p .cursor/rules
cp -r dist/cursor/* .cursor/rules/

# 验收：在对应客户端里问一句
# 「列出你当前读到的后端约定，包含哪些技能？」
# 预期：能说出上面三份技能各自的关注点

# 确认改动范围
git diff --stat

# 逐份读源技能（三个文件）
# skills/api-endpoint/SKILL.md
# skills/data-integrity/SKILL.md
# skills/db-migration/SKILL.md

# 在每份末尾的 Make it yours 段写清团队约定，例如：
# 错误响应格式：统一用 RFC 7807 problem+json
# 接口文档：新增或修改路由时同步更新 docs/api.md
# 迁移回滚：每个 up 迁移必须配一个可执行的 down

# 改完源文件后重建生成物（官方 Contributing 说明）
node scripts/build-dist.mjs

# 重新挂载生成物，并确认 Agent 读到的是新文本
git diff --stat
cat dist/AGENTS.md | head -n 20

# 先看目录与说明（浏览器或本地克隆后查看）
# bench/ 下含任务定义、overlay 技能版本与 runs.jsonl

# 每条运行记录里关注这些字段
# task 名称、使用的模型、是否带技能、error_reason
# README 说明：被 usage_limit_reached 中止的运行，原因写在 error_reason

# 用项目里已有的一个真实任务做小样本对照（示意）
# A 臂：不带技能，让 Agent 实现「限量 5 件的秒杀下单」
# B 臂：带技能，同一提示词再跑一次
# 对照点：登录与昂贵路由是否限流、读后写是否加锁或条件更新、
#        是否有 UNIQUE 约束与幂等键、改列名是否走 expand then contract

# 自己写隐藏检查，别把检查内容放进提示词里
# 例如：并发 20 个买家抢 5 件库存，检查超卖与重复扣款

# 回归清单（每次更新规则后逐条过一遍）
# 1. 三个 Agent 各自能复述三份技能的关注点
# 2. 一段登录接口提示词的输出里含限流与 4xx 处理
# 3. 一段改列名的提示词走 expand then contract 并配 down 迁移
# 4. 自己写的隐藏检查脚本通过
# 5. git diff 里没有把团队原有规则覆盖掉

# 改过源文件后重新生成并重新挂载
node scripts/build-dist.mjs
git diff --stat

# 回退：删掉本次追加的规则段与复制的 cursor 规则
# 用 Step 1 记下的 git 状态对照，确认工作树干净
git status --short

# 更新前先看仓库 README 与提交历史，别直接覆盖本地已填的 Make it yours