Toco AI 模型驱动开发最佳实践指南

💡 实操案例均基于《民宿系统》需求（房间预订、会员管理、积分下单等核心业务）。

上下文工程

解决跨会话失忆与幻觉

场景问题：AI 遗忘早期架构指令，或在大量旧代码中定位问题时产生错误输出。

高精度切片挂载

提问前先输入 @：

必须依赖系统内置的上下文凝练机制，严禁人工全量粘贴代码。

自动化记忆更新

• .toco/global/common_framework.md → 存放项目通用技术规格概要（TocoAI 会自动更新，也可手动修改）
• .toco/current_task.md → 任务锚点，仅在复杂、多步骤的跨会话任务时强制要求 AI 写入：
  • 已完成事项
  • 核心架构决策及原因
  • 当前设计/代码状态
  • 阻碍/悬而未决的问题
  • 给下个会话的禁止规则（DO NOT）

及时重置会话

大模型存在注意力衰减缺陷（“迷失中间”效应）。极端情况下，2-3 次对话就可能超出上下文窗口。

出现以下任一情况，立即新开会话（Fresh Chat）：

• AI 出现遗忘或偏离方向
• 刚完成一个微任务

⚠️ 新开会话前不要审批 TocoAI 的 Changed List，审批后无法回滚当前会话前面的快照。

💡 确定审批时，如当前会话生成的主流程无问题，可直接接受全部，否则应拒绝全部。

重构分片流水线

对大量旧代码强行全量扫描，会导致 Token 超载与注意力衰减，极易引发上下文污染及错误输出。

① 审计  →  Standard 模型扫描依赖，输出影响清单
② 分片  →  人工按高内聚原则拆分，单次核心文件 5-10 个（或代码总量 ≤ 1000 行）
③ 执行  →  Premium 模型串行重构
④ 压缩  →  单片完成后强制生成状态快照存入任务锚点，清空会话再开启下一分片

提示词工程

分级策略与解耦

场景问题：AI 生成代码不符合团队规范，或跳过逻辑设计直接生成无法运行的代码。

分层规则提示词

在 .toco/ 目录下按 Agent 角色严格隔离，建立 Markdown 规则提示词库（如 .toco/coding/rules.md），包含：角色定义、核心原则、标准规范、禁止模式。

Agent 与规则目录对应关系：

• 强制纳入 Git 版本控制，确保团队基线一致
• 遇到 AI 犯错，及时将正例/反例补充进规则
• 规则尽量精炼，避免占用过多上下文

提示词分级解耦

指令必须清晰、准确、具体。

面对大型重构，直接告知 AI 时间压力与规模限制（显式 Token 预算）。

示例：本次重构仅涉及 OrderService.java 和 PaymentService.java，核心文件不超过 5 个，代码总量控制在 800 行以内，请在此范围内完成重构。

优质示例：【用户提示词】伪代码优先的积分下单

@Toco Design Elements(Order, Member) @Files(PointService.java) @Agents(Developer)
 
**任务**：实现"基于购物车创建订单及积分支付"的业务逻辑。
 
**约束**：
🔴 先不要写具体 Java 代码！
 
**步骤 1：逻辑推演 (Chain of Thought)**
请分析并发扣减库存的情况，以及"会员生日当天 9.5 折"的判断边界。
 
**步骤 2：输出伪代码**
用结构化的伪代码写出处理主干，明确事务处理范围与锁的粒度。
 
**步骤 3：等待审查**
等待我回复"逻辑通过"后，再生成完整的 Java 实现代码，并为该逻辑生成 3 个单元测试用例（正常、边界、异常）。

智能体分工与动态算力路由

场景问题：高成本模型用于简单任务造成浪费，低成本模型处理架构设计频繁出错；各 Agent 职能不清晰。

核心职能分工

动态算力路由

Standard 模型 — 高吞吐、极低成本

• 日常 CRUD、单元测试、基础逻辑、简单文档/注释等

Premium 模型 — 强逻辑推理

• 架构顶层设计、复杂并发事务推演、复杂核心业务逻辑、循环问题解决等

⚠️ 若模型陷入循环（解决方案在 A、B 间反复切换），必须中断并切换模型重试。

架构设计与变更同步

场景问题：需求变更后代码与设计文档脱节；多任务并行导致代码冲突。

以可视化设计模型为唯一设计基准

保存即触发全局级联同步变更，确保设计模型与骨架代码严格一致。若有报错，直接在可视化界面或与 AI 协作修复。

规划审批与会话隔离

• Planner 输出任务拆解后，必须人工审阅并选择点击添加到待办
• 复杂待办：强烈建议从待办清单为每个复杂待办（如”基于购物车创建订单”）开启独立会话串行开发，避免上下文失焦与设计/代码冲突
• 简单待办合并：逻辑紧密关联的简单待办（如针对”客房”实体的增、删、改 API），可合并 2-3 个在一个会话中执行

三审验收防线

防范 AI 错误输出与技术债

场景问题：盲目信任 AI 产出，直接一键全量应用，导致上线后报错或引入未知第三方包。

专注业务逻辑审查

Toco 的 M2C 引擎基于可视化设计模型确定性生成的 80% 架构骨架代码（遵循 DDD 与 CQRS 规范），准确性有保障，可直接免检。重点审查 Developer Agent 填充的 20% 业务逻辑代码。

三审验收底线

一审  →  设计模型差异：核对设计模型层面变更（字段名、类型、结构调整等）是否精准

二审  →  代码差异（重点审查区）：在 Changed List 面板中，100% 精力审查 20% 业务逻辑代码
         重点关注：校验规则 / 核心业务流程和分支 / 性能和稳定性治理代码 / 边界空值处理等

三审  →  结构化测试结果：审查单元测试及 RPC/API Mock 测试执行日志，确保核心业务分支断言全部通过

数据库 Schema 同步

ER 变更后，需同步数据库 Schema 变更。

防虚假依赖引入

大模型极易生成虚假库名。对于 Agent 引入的任何非主流包名，必须手动前往 Maven 官方源 核实其真实性、发布时间与实际下载量。

附录：模型驱动开发者核心素养

从”代码编写者”转变为”系统架构师”：