Cursor-AI模型选型与协作指南
1. 背景与问题
使用Auto模式时，设计文档与生成代码质量「一般」是常见现象，主要原因如下：
现象 | 原因 |
设计文档结构松散、遗漏边界 | Auto 倾向路由到偏快、偏省的模型，长文推理与架构权衡能力不足 |
代码「像 Java」但不像本项目 | 未显式引用.cursor/rules与同类范例，模型按通用习惯生成 |
一次改动范围过大、返工多 | Agent 边设计边改代码，上下文混杂，计划与实现脱节 |
分层/Feign/注释规范不一致 | 轻量模型对项目级约束遵循度较低 |
结论：重要任务不要依赖 Auto；应手动选模型 + 选对 Cursor 模式 + 引用项目规则。
2. Cursor 模式说明
模式 | 用途 | 典型阶段 |
Ask | 只读问答、代码理解、方案讨论 | 需求澄清、读存量代码 |
Plan | 协作规划，先对齐方案再动手 | 设计文档、实现计划 |
Agent | 读写代码、执行多文件改动 | 编码、迁移脚本、单测 |
原则：设计 / 计划与编码分阶段进行，避免在同一轮对话里混写详设和大段实现。
3. 分阶段模型推荐
3.1 设计文档（架构、详设、方案评审）
推荐模型（优先级从高到低）：
- Claude Opus 4.6 / 4.7（或当前列表中最强 Opus 档）— 首选
- GPT-5 / GPT-5.5— 备选，文档结构与另一种推理视角有时更清晰
推荐模式：Ask 或 Plan（只产出文档，不写实现代码）
适用内容：
- 业务背景、方案对比、表结构、接口契约
- 风险、回滚、兼容策略、与存量模块的调用关系
避免：
- Auto 作为主力
- Agent 模式边写详设边改ServiceImpl
- 无@引用就要求「设计整个模块」
3.2 实现计划（任务拆解、文件清单、实施顺序）
推荐模型：
- Claude Sonnet 4.6— 日常计划，性价比好
- Claude Opus 4.6 / 4.7— 跨多模块、DB 迁移、加密/兼容等高风险改动
- Composer 2.5— 已熟悉仓库、计划偏「改哪些文件、调用链怎么走」时
推荐模式：Plan
计划应包含（参考本项目 `docs//实现计划.md`）：*
- Goal / Architecture / Tech Stack摘要
- 文件结构（变更一览）表格
- Task 列表（可勾选- [ ]）
- 与详设文档的引用路径
- 明确不在范围内的边界
避免：
- 空泛 TODO（如「改 Service」「加字段」）
- 未标注具体文件路径与依赖顺序
3.3 代码生成（Java 实现、多文件联动）
推荐模型：
任务类型 | 推荐模型 |
单类 CRUD、DTO、简单 Mapper | Composer 2.5 |
多文件联动（Entity + ServiceImpl + XML + 迁移） | Composer 2.5或Sonnet 4.6 |
加密、事务边界、存量兼容、复杂业务规则 | Opus或GPT-5.3 Codex |
大范围重构、全链路同步 | Opus；可用/best-of-n多模型对比 |
推荐模式：Agent
避免：
- Auto 作为主力编码模型
- Haiku 等轻量模型处理复杂 Service / 多表逻辑
- 一次 Agent 改动过多文件（建议按 Task 小步提交）
4. 推荐工作流
flowchart LR
A["Ask/Plan + Opus"] --> B["设计文档 docs/"]
B --> C["Plan + Sonnet/Opus"]
C --> D["实现计划"]
D --> E["Agent + Composer 2.5"]
E --> F{Review}
F -->|规范或逻辑问题| G["Opus/Codex 定点修复"]
F -->|通过| H["完成"]
4.1 标准四步
- 设计：Opus + Ask/Plan → 输出到docs/<版本或主题>/xxx-详细设计.md
- 计划：Sonnet/Opus + Plan → 输出xxx-实现计划.md，文件级清单
- 编码：Composer 2.5 + Agent，@规则与范例类，按 Task 逐步实现
- Review：人工或 Bugbot；复杂逻辑用 Opus 做 diff 审查
4.2 与本仓库文档结构对齐
文档类型 | 建议路径示例 |
需求 | docs/<版本>/xxx-需求.md |
详细设计 | docs/<版本>/xxx-详细设计.md |
实现计划 | docs/<版本>/xxx-实现计划.md |
详设与计划分离：详设讲「为什么、做什么」；计划讲「改哪些文件、按什么顺序」。
5. 模型速查表
阶段 | 首选模型 | Cursor 模式 | 不建议 |
设计文档 | Opus | Ask / Plan | Auto、Agent 边写边改代码 |
实现计划 | Sonnet / Opus | Plan | 无上下文引用的泛泛计划 |
日常编码 | Composer 2.5 | Agent | Auto、一次改太多文件 |
疑难 Debug / 架构决策 | Opus / GPT-5.3 Codex | Agent / Ask | 轻量模型硬扛 |
超大上下文读仓 | Gemini Pro（若可用） | Ask | 仅依赖短上下文片段 |
6. 提升质量的关键杠杆（比换模型更重要）
6.1 引用项目规则
本仓库已配置.cursor/rules/与AGENTS.md，生成代码或文档时应显式引用，例如：
- common_rule_layers.mdc— 分层、禁止跨域直调 Mapper
- common_rule_web.mdc— Controller、URL kebab-case、Resp<T>
- common_rule_comments.mdc— ServiceImpl 体内//步骤注释
- common_rule_workflow.mdc—this.前缀、行宽 150、最小变更
6.2 引用同类范例代码
不要只描述需求；应@1～2 个已符合规范的同类实现，例如：
- 新增 BI 同步逻辑 →@BiEvaluateResultServiceImpl.java
- 加密字段处理 →@BiEncryptedOriginFieldHelper.java
6.3 小步迭代
- 一次 Agent 会话：一个 Task 或一个 Service
- 迁移脚本与 Entity 先落地，再改 ServiceImpl
- 每步编译 / 单测通过后再进入下一步
6.4 卡住时换模型族
同一问题若 Opus 与 GPT 各跑一遍（Cursor/best-of-n），往往比反复 Auto 更有效。
7. 成本与效率建议
策略 | 说明 |
日常编码默认 Composer 2.5 | 多文件 IDE 内编辑性价比高 |
设计与攻坚 reserved Opus | 仅在详设、复杂 debug、大重构时使用 |
Plan 确认后再 Agent | 减少因计划偏差导致的重复生成 |
Tab 补全 vs Chat | 简单补全用 Tab；结构性改动用 Agent + 明确@ |
开启项目 Rules | 确保.cursor/rules对 Java 文件生效，减少口头重复约束 |
8. 常见问题（FAQ）
Q：Auto 能不能完全不用？
A：简单问答、单行补全仍可用 Auto；详设、跨文件实现、规范严格的 Java 代码建议手动选模型。
Q：Composer 2.5 和 Opus 差距大吗？
A：常规多文件编码 Composer 2.5 通常足够；架构推理、长文档、复杂边界Opus 更稳。遇到「能跑但不像项目规范」时，先检查是否@了 rules 和范例，再考虑换 Opus。
Q：设计文档要不要 Agent 直接写到 docs/？
A：可以。Plan 模式下让 Agent「写入docs/.../xxx-详细设计.md」，你 Review 后再进入实现计划阶段。
Q：和AGENTS.md的关系？
A：AGENTS.md是规则索引；具体约束在.cursor/rules/*.mdc。Chat 里@AGENTS.md可快速让模型加载协作约定。