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、简单 MapperComposer 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 LRA[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 模式不建议设计文档OpusAsk / PlanAuto、Agent 边写边改代码实现计划Sonnet / OpusPlan无上下文引用的泛泛计划日常编码Composer 2.5AgentAuto、一次改太多文件疑难 Debug / 架构决策Opus / GPT-5.3 CodexAgent / Ask轻量模型硬扛超大上下文读仓Gemini Pro若可用Ask仅依赖短上下文片段6. 提升质量的关键杠杆比换模型更重要6.1 引用项目规则本仓库已配置.cursor/rules/与AGENTS.md生成代码或文档时应显式引用例如common_rule_layers.mdc— 分层、禁止跨域直调 Mappercommon_rule_web.mdc— Controller、URL kebab-case、RespTcommon_rule_comments.mdc— ServiceImpl 体内//步骤注释common_rule_workflow.mdc—this.前缀、行宽 150、最小变更6.2 引用同类范例代码不要只描述需求应12 个已符合规范的同类实现例如新增 BI 同步逻辑 →BiEvaluateResultServiceImpl.java加密字段处理 →BiEncryptedOriginFieldHelper.java6.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. 常见问题FAQQAuto 能不能完全不用A简单问答、单行补全仍可用 Auto详设、跨文件实现、规范严格的 Java 代码建议手动选模型。QComposer 2.5 和 Opus 差距大吗A常规多文件编码 Composer 2.5 通常足够架构推理、长文档、复杂边界Opus 更稳。遇到「能跑但不像项目规范」时先检查是否了 rules 和范例再考虑换 Opus。Q设计文档要不要 Agent 直接写到 docs/A可以。Plan 模式下让 Agent「写入docs/.../xxx-详细设计.md」你 Review 后再进入实现计划阶段。Q和AGENTS.md的关系AAGENTS.md是规则索引具体约束在.cursor/rules/*.mdc。Chat 里AGENTS.md可快速让模型加载协作约定。