跨前后端的一个 AGENTS.md 分享

这版已经过时了，发出来分享讨论，隐藏了业务信息，现在用来做跨前后端开发的调度，运行良好（暂时）



我自己的评价是 这个版本有太多 该做什么 不该做什么，对于模型的限制较大，在扩充能力边界时显得有些力不从心。下个版本准备从哲学、方法论层面给一些引导，尽量少下约束。

主要约束：

1.先动文档再执行

2.子模块描述优于父模块

3.涉及联动的，先做契约

Parent 指代顶层项目

Frontend 指代客户端

Backend 指代后端

# AGENTS.md



本文件定义 `parent` 的代理协作基线，适用于：



- `Frontend`：Tauri 2 + Vue 3 + TypeScript 桌面端



- `Backend`：后端与后台治理平台



若子项目内存在更细粒度的 `AGENTS.md`，子项目规则优先。



## 工作范围



1. 默认只修改 `Frontend`、`Backend` 及其直接相关文档。



2. 涉及跨端联动时，先对齐字段级契约，再分别落地实现。



3. 未经明确要求，不新增第三个独立子项目或并行技术栈。



## 强制流程



1. 文档先行：任何架构、接口、数据模型、流程行为变化，先更新文档，再改代码。



2. 规则同步：如果变更影响协作方式、验证方式、包管理器、目录职责，必须同步更新规则文件。



3. 验证收口：提交前按 `文档一致性 -> 代码实现 -> 构建/测试验证` 的固定顺序执行。



## 文档更新矩阵



### `Frontend` 变更至少检查这些文件



1. 架构/模块职责变化：`Frontend/ARCHITECTURE.md`



2. 本地 X 项目 / HTTP Bridge / 结果回传契约变化：`Frontend/api.md`



3. 用户可见交互、产品约束变化：`Frontend/PRODUCT.md`



4. 协作方式、验证门禁、目录规范变化：`Frontend/AGENTS.md`



### 工作区级变化至少检查这些文件



1. 项目边界、当前阶段定位变化：`WORKSPACE_ARCHITECTURE.md`



2. 工作区协作原则变化：`AGENTS.md`



3. 快速入口或规则索引变化：`agent.md`



### `Backend` 变更至少检查这些文件



1. 后端契约/设计变化：`Backend/docs/*.md`



2. 涉及桌面端联调的，还要同步更新 `Frontend/api.md` 与相关前端文档



## 当前协作判断



PM 的记忆 xxx AI 自行补充



## 包管理与验证



1. `Frontend` 默认命令以 `yarn` 为主：`yarn install`、`yarn build`、`yarn tauri dev`



2. 若要切换 `Frontend` 的包管理器，必须在同一任务内统一锁文件、命令文档与规则文档；不要只改其中一部分。



3. `Frontend` 至少完成 `yarn build` 或明确说明为何无法完成，并补充关键手测或 `cargo check`



4. `Backend` 至少完成受影响模块的 `test`、`verify` 或启动验证



## 前后端联调原则



1. 改接口时同时更新前端调用、后端实现和契约文档，避免单边变更。



2. 新增配置项时，明确默认值、环境变量名、存储位置和生效边界。



3. 联调验收至少保留一条完整记录：请求 -> 响应 -> 事件/结果。



4. 与 x 对接时，要明确请求路径、参数名、鉴权方式、回写字段、`主键` 关联策略。



## 并行开发约定



1. 默认目标仍是“契约先对齐，再并行实现前后端”。



2. 如果当前运行环境支持并且任务已明确授权，可拆为 Backend Agent / Frontend Agent 并行推进。



3. 如果当前运行环境不支持子代理，或任务本身只涉及单端，也必须遵守同样的契约先行和双端一致性要求，由单代理顺序完成。



## 提交前检查



1. 文档与实现一致：字段、流程、入口、窗口形态、回写行为一致。



2. 规则与实现一致：`AGENTS.md`、`agent.md`、子项目规则不再引用已删除模块或过期流程。



3. 受影响模块已验证：前端构建/手测、后端测试/启动验证至少命中一项。



4. 如存在未完成验证、环境阻塞或已知风险，必须在交付说明中明确写出。