docs(agents): API 参考文档纳入开发规范

- AGENTS.md：新增 Controller/Service 前必读 API_REFERENCE.md + 接口规范补充
- cfc-backend/AGENTS.md：新增接口前三步检查流程（复用→修改→新增）+ 废弃接口 410 处理

AGENTS.md

@@ -44,6 +44,8 @@
 - **认证:** JWT Bearer Token，`Authorization` Header；`JwtInterceptor` 拦截 `/api/**`（8个公开路径除外）
 - **DI:** `@Resource` 替代 `@Autowired`，字段名匹配默认 Bean Name
 - **角色控制:** 控制器内手动检查 `@RequestAttribute("role")`
+- **新增接口前:** 必须先查阅 `docs/superpowers/api/API_REFERENCE.md`，确认无重复/相似接口才新增
+- **废弃接口:** 标记 `410 Gone` 并注释说明，不直接删除；清理时机确认无前端调用后
 - **AI 服务统一走 LangGraph:** 所有 AI 能力（对话/问卷/画像/推荐/解析）基于 `cfc-langgraph` Python 服务（FastAPI + LangGraph + ChromaDB RAG，端口 9000，生产 `ai.etotem.com.cn`）；Java 侧通过 `AiGateway` 调用（熔断 + 超时 + Fallback），禁止绕过 AiGateway 直接对接第三方 LLM；新增 AI 功能优先以 LangGraph graph 形式实现
 - **小程序限制:** 禁止可选链 `?.`（用 `&&` 替代）、禁止 CSS Grid（用 flexbox）、禁止 `:key` 表达式（用方法调用代替）、禁止直接 `new Date(string)`（用 `parseDate()`）
 - **新增Controller/Service:** 检查类名是否与其他包重名（Spring Bean Name 冲突）

cfc-backend/AGENTS.md

@@ -40,7 +40,11 @@ Spring Boot 2.7.18 后端服务，MyBatis-Plus ORM，JWT 认证。
 - **控制器分组:** 按功能模块分为 admin, auth, assessment, family, guide, task, reward 等子目录
 - **DI注解:** 使用 `@Resource` 代替 `@Autowired`，字段名必须与类型默认 Bean Name 一致（如 `PaymentService` 的字段名必须为 `paymentService`）
 - **接口方法:** 所有接口统一使用 `@PostMapping`（POST 方法），禁止使用 `@GetMapping`/`@PutMapping`/`@DeleteMapping`
-- **新增接口前:** 必须运行 mvn clean compile 并启动项目验证无冲突；使用以下命令检查重复路由：
+- **新增接口前:** 必须查阅 `docs/superpowers/api/API_REFERENCE.md`，确认：
+  1. 是否有已具备该功能的接口 → 直接使用
+  2. 是否有相似接口需简单修改 → 评估修改成本
+  3. 实在没有 → 才新增，并在 `docs/superpowers/api/API_REFERENCE.md` 同步记录
+- **废弃接口处理:** 标记 `@Deprecated` + 返回 `Result.error(410, "该接口已废弃，请使用 xxx")`，待确认无调用后清理
   ```
   grep -rn '@GetMapping\|@PostMapping\|@PutMapping\|@DeleteMapping' src/main/java/com/etotem/cfc/controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u
   ```