AGENTS.md · Tour Mate 项目 AI 协作工作流 SOP
这是 你（独立开发者）+ N 个 AI 实例（产品 / 前端 / 后端 / UI）协作 的标准操作手册。 适用于三个姊妹项目：
tour-mate-platform-web（本仓库）/tour-mate-platform-uni-app/tour-mate-platform（后端）。 三个项目根目录均放一份内容一致的 AGENTS.md；修改时三处同步。Cursor 会自动加载本文件作为 agent 上下文。每次新会话开场无需再粘贴这段。
〇、核心心法（3 条铁律 · 任何会话不可违背）
- API 契约是真源头 — api-docs/ 是合同；mock / 前端 TS / 后端 DTO 都是它的衍生物。字段不一致永远改衍生物，不改文档。
- 单接口验证 > 批量切模块 — 后端 Service 完成一个再切一个，不要"一次切 14 个"导致 80% 是空数组。
- AI 健忘 → 上下文必须文档化 — 累计约束（backend-devlog/11 §四）、踩坑（§三）、契约（api-docs/）是 AI 的"外存"，每次新会话开场必装备。
一、五阶段开发流程
阶段一 · 需求讨论
| 项 | 内容 |
|---|---|
| 输入 | 业务想法（一句话 / 用户故事 / 竞品截图） |
| AI 角色 | 产品 AI（在 Plan 模式下） |
| 你的动作 | 当 PM，提需求，让 AI 复述 + 列假设清单 |
| 输出 | 需求摘要（不超过 1 页）+ 假设清单（≥ 3 条） |
| 验证 | 你 review 假设清单，纠偏后让 AI 重新复述确认 |
反模式：你心里有图，直接让 AI 写代码 — AI 会按它脑补的假设跑偏。
阶段二 · 契约设计（最关键阶段）
| 项 | 内容 |
|---|---|
| 输入 | 阶段一的需求摘要 |
| AI 角色 | 契约设计 AI（仍在 Plan 模式） |
| 工具 | 模板参考 api-docs/00-通用规范.md + api-docs/web-admin/01-认证与管理员.md |
| 输出 | api-docs/<端>/<模块>.md（接口路径 / 方法 / 参数 / 响应字段 / 错误码 / 敏感操作标记） |
| 验证 | 对照 api-docs/00-通用规范.md §1–§10 + 累计约束 §四 逐条 checklist |
契约必含字段：
- 接口归属（app / web-admin / common）
- 复用关系（独立 / 复用 Service / 复用 Repository）
- 是否敏感操作（决定是否需要
X-Confirm-Password） - 时间字段格式（统一 ISO 8601）
- 分页 page 起点（App=0 / Web Admin=1）
- 业务子码（如 U001 / G002）
阶段三 · 并行开发
关键转变：前端 AI 和后端 AI 可以同时跑，不再串行等待。
| 项 | 前端 AI | 后端 AI |
|---|---|---|
| 输入 | 阶段二 API 文档 | 阶段二 API 文档 |
| 输出 | mock + TS 类型 + API 模块 + 页面骨架 | Controller + DTO + Service 接口骨架（Service 实现先返 mock 数据 + TODO） |
| 验证 | pnpm tsc --noEmit + pnpm test | mvn compile + Postman 调用骨架 |
| 共同约束 | 字段名、枚举值、错误码 逐字符对齐契约 |
反模式：让前端 AI 看后端代码出 mock，或反过来 — 两端必须只看契约，不互相参考实现。
阶段四 · 联调（单接口验证，不是批量切模块）
| 项 | 内容 |
|---|---|
| 触发条件 | 后端 Service 实现完成（不是 Controller，是 Service 真业务可用） |
| 工具 | 「模块成熟度看板」（见 §三） |
| 你的动作 | 按看板「真接口可用 ✅」的接口逐个切，每切一个点击页面验证一次 |
| 输出 | mock toggle 移除 + devlog 记录 |
| 验证 | 页面跑通且字段无报错；toast 错误 ≤ 0 |
反模式：
- ❌ 切完整模块（14 个接口）才验证 → 出问题排查成本指数上升
- ❌ 切了就标 ✅ → 必须点击验证
阶段五 · 沉淀
| 项 | 内容 |
|---|---|
| 输入 | 联调中发现的所有问题 |
| 工具 | backend-devlog/11 §三 联调问题清单 + §四 累计约束 |
| 输出 | 问题表追加、跨模块规律提炼到 §四 |
| 验证 | 下一模块开始前先读 §四（AI prompt 装备） |
沉淀原则：只记"跨模块"的规律，不记"本模块特有"的细节。
二、Prompt 装备模板（每次新会话开场粘贴）
AI 跨会话不记忆。每次开新对话先丢这段，省下 80% 的"AI 跑偏"。
我在做 [tour-mate-platform-web / uni-app / backend]，分支 [branch]。
本次任务：[一句话描述]
必读上下文（按顺序）：
- 工作流总纲：AGENTS.md（已自动加载）
- 累计约束：backend-devlog/11-Web管理后台数据联调.md §四
- 已踩坑：同文件 §三
- 接口契约：api-docs/<端>/<模块>.md
- 通用规范：api-docs/00-通用规范.md（时间 / 分页 / 鉴权 / 枚举）
严格约束：
- 文档为真源，字段不一致改前端不改文档
- 时间字段统一 dayjs() 解析，禁 new Date()
- 敏感操作走 axios interceptor 自动注入 X-Confirm-Password（不在业务层手动写）
- 不确定的字段先列疑问清单，禁止假设
- Web Admin page 从 1 起，App page 从 0 起
- 一次只改一个文件，禁止一次性大改不让人审
执行方式：先列 Step 1 输出
(a) 计划修改的文件清单
(b) 字段差异清单（前端 vs 文档）
(c) 疑问清单
(d) 与累计约束的冲突检查
等我确认后再开始改代码。三、模块成熟度看板（决策一个模块该做什么）
每个待开发的模块在 backend-devlog/11 §二 联调进度 维护 4 列状态：
后端 Service×前端 mock 对齐×前端 TS 对齐×真接口可用
决策矩阵：
| 后端 Service | mock | TS | 该做什么 |
|---|---|---|---|
| ❌ 未实现 | ⏳ | ⏳ | 仅做 mock 对齐 + TS 对齐；不切真接口；提单给后端 |
| ⚠️ 内存占位 | ⏳ | ⏳ | mock 对齐 + TS 对齐；临时可切真接口验证；上线前回退到 mock 等 DB 落地 |
| ✅ 完整 | ⏳ | ⏳ | 全套对齐 + 单接口切换 + 点击验证 |
| ✅ 完整 | ✅ | ✅ | 逐个接口切换，每切一个 toast 验证 |
反模式：看到后端 Controller 暴露就以为可用 — Controller 暴露 ≠ Service 实现。
四、Cursor 三种模式怎么选
| 任务 | 模式 | 原因 |
|---|---|---|
| 大改、有歧义、要列假设 | Plan | 强制先问 + 列计划，避免 AI 凭印象写代码 |
| 已有清晰目标、改 ≤ 5 文件 | Agent | 直接动手最快 |
| 只想问问题、了解代码、讨论思路 | Ask | 不会动文件，思考期保护 |
强信号触发 Plan：
- 涉及 ≥ 3 个文件
- 出现"重构"、"迁移"、"对接"、"切换" 等动词
- 你不确定 AI 会按什么思路做
五、反模式禁区（这 6 件事永远不要做）
- ❌ "mock 倒推 API 文档" — 顺序反了，必然丢业务规则
- ❌ "批量切模块" — 后端业务实现度不一，全切容易看空白
- ❌ "跨会话凭印象" — AI 不记得，每次必装备累计约束
- ❌ "AI 说完成 = 真完成" — 必须自己抽检 +
tsc --noEmit+ 单测 - ❌ "在业务代码里写 X-Confirm-Password / token refresh / Toast" — 走全局 axios interceptor 统一处理
- ❌ "AI 提了疑问你拍脑袋回答" — 重要决策必须先读对应文档（api-docs/ / 需求文档）再回答
六、文档体系导航（不知道改哪里时查这里）
| 想做的事 | 改这里 |
|---|---|
| 改/查 API 契约 | api-docs/ |
| 改/查 通用规范（时间 / 分页 / 鉴权 / 枚举） | api-docs/00-通用规范.md |
| 改/查 接口归属规则（app / web-admin / common 怎么分） | api-docs/建议.md |
| 记录本次联调问题 | backend-devlog/11 §三 |
| 沉淀跨模块约束 | backend-devlog/11 §四 |
| 记录踩坑事故 | backend-devlog/11 §八 |
| 记录架构决策（ADR） | docs/decisions/（后端项目） |
| 改/查 需求文档 | docs/Web管理后台开发需求文档.md |
七、跨项目同步规则
三个项目 AGENTS.md 必须逐字一致。修改流程：
1. 在任一项目修改 AGENTS.md
2. 同步到另外两个项目（复制粘贴 / diff 比对）
3. 在 backend-devlog/<n>-xxx.md 记录修改原因项目专属规则不放本文件，放各自的 README.md / CONTRIBUTING.md / api-docs/README.md。
八、健康度自检（每周做一次）
每周问自己 5 个问题，任何一个答"否"就修：
- [ ] 上周写的代码，每个文件改动都对应了 devlog 里的一条记录？
- [ ] 上周遇到的字段不一致 / 路径错，都进了 §三 联调问题清单？
- [ ] 上周发现的跨模块规律，都沉淀到 §四 累计约束？
- [ ] api-docs/ 和实际代码字段是否同步（抽检 2 个模块）？
- [ ] AI 抛出的疑问清单，自己有没有"懒得查文档随便答"？
九、一句话总结
慢即是快。 阶段二（契约）多花 30 分钟，阶段四（联调）省 3 小时。 AI 是放大器，不是兜底。 你的 review 质量 = 项目质量上限。
最后更新：2026-06-01 维护者：你（独立开发者） 关联文档：