roadmap.md

业务逻辑护栏路线图

当前判断

当前方向继续推进。

但这里的“方向正确”不是指已经确定最终产品形态，而是指已经找到一个值得继续验证的切入点：先验证业务逻辑护栏能否帮助 AI Agent 在遗留项目中少写错业务逻辑。

现阶段不要急着把项目做成 skill、CLI、索引服务、MCP 或 IDE 插件。项目最大的风险不是工具能不能做出来，而是做出来以后是否真的能降低真实遗留项目里的业务误判。

已观察到的信号

已经完成两轮真实任务实验，得到这些阶段性信号：

• Agent 的主要失败点不只是找不到文件，而是容易理解错业务规则、框架返回结构、历史特殊分支和可修改范围。
• 护栏增强组相对普通基线组出现了可观察改善，说明护栏不是纯文档流程。
• 更强模型可以改善业务正确性，但不能替代明确的工程产物约束。
• 当前护栏还偏“提示型”，需要升级为包含业务规则、禁止事项、工程产物要求和改后审查的强约束任务包。

因此，MVP 信号暂时为正，但还不足以进入复杂工具开发阶段。

阶段一：固化第二轮实验教训（已完成）

目标：把实验中暴露的问题写回模板和评估方法，避免后续重复犯错。

需要完成：

• 更新 templates/task-guardrail-pack.md。
  • 增加“必须产物”区。
  • 增加“类型 / model 要求”区。
  • 增加“禁止修改范围”区。
  • 增加“框架返回结构必须确认”区。
  • 增加“旧代码删除条件”区。
• 更新 templates/post-change-review.md。
  • 检查业务规则是否被破坏。
  • 检查是否满足任务明确要求的工程产物。
  • 检查是否误改公共 API、是否全部使用 any、是否遗漏应有 model/type。
• 更新 docs/evaluation.md。
  • 将评分维度扩展为业务正确性、工程完整性、修改范围控制、验证证据、时间和 token 成本。

完成标准：护栏包从“提醒 Agent 注意什么”升级为“Agent 必须满足哪些验收条件”。

完成记录：

• templates/task-guardrail-pack.md 已增加禁止修改范围、必须产物、类型 / model 要求、框架返回结构确认和旧代码删除条件。
• templates/post-change-review.md 已增加修改范围、必须产物、类型 / model、框架返回结构和旧代码清理审查。
• docs/evaluation.md 已将评分维度扩展为业务正确性、工程完整性、修改范围控制、验证证据、方案可信度、时间和 token 成本。

阶段二：继续做 1 到 2 个真实任务实验

目标：验证增强后的护栏是否能在不同任务类型中稳定复现收益。

优先选择不同类型的任务：

• 业务规则改造任务：重点观察特殊分支、业务条件、流程兼容。
• 技术迁移任务：重点观察范围控制、接口类型、旧代码清理。
• 缺少测试的修 bug 任务：重点观察隐含约束识别和人工验证设计。

每个实验尽量保持对照结构：

• 普通 Agent 基线组。
• 护栏增强组。
• 人工参考实现或熟悉业务的人评审。

完成标准：至少能说明护栏在不同任务中是否持续减少业务规则遗漏，或者暴露出哪些边界条件。

阶段三：整理最小可复用工作流

目标：把人工流程整理成可重复执行的 SOP。

建议工作流：

1. 确认目标项目、目标分支和目标 commit。
2. 阅读任务描述，识别任务风险类型。
3. 扫描相关代码，提取业务规则卡。
4. 生成 Task Guardrail Pack。
5. 让 coding agent 基于护栏实施。
6. 用 Post-change Review 审查结果。
7. 记录对照实验结论。
8. 把新发现反哺模板和评估标准。

完成标准：后续人类或其他 agent 可以按同一套步骤复现实验，而不依赖某一次聊天上下文。

阶段四：判断是否包装成 skill

目标：决定是否把稳定流程产品化为轻量 skill。

只有当以下问题多数为“是”时，才进入 skill 包装：

• 每次实验是否都在重复执行同一套步骤？
• 模板是否已经稳定？
• 护栏增强组是否持续优于普通基线组？
• 人工准备护栏包是否已经成为明显成本？
• 是否已经出现清晰、低风险的自动化切入点？

如果进入这一阶段，优先考虑 agent-agnostic skill，而不是复杂 CLI 或索引服务。

原因：

• 当前核心价值在流程、判断和验收，不在复杂代码分析。
• skill 成本低，适合跨 Codex、Claude Code、OpenCode 等不同 Agent 使用。
• skill 可以先规范如何读代码、如何写护栏、如何审查，再逐步引入脚本辅助。

完成标准：形成可被其他 agent 独立使用的 SKILL.md 草案或技能包设计。

阶段五：考虑半自动化工具

目标：在工作流稳定后，只自动化已经被反复验证有价值的环节。

候选自动化点：

• 分支和 commit 校验。
• 相关文件候选扫描。
• 调用关系和引用检查。
• 护栏包骨架生成。
• 改后审查辅助。

这一阶段才讨论 CLI、索引器、预处理器、自动审查器或 IDE 集成。

完成标准：每个自动化能力都有明确输入、输出、收益假设和失败风险，而不是为了工具化而工具化。

近期优先级

近期优先级是阶段二。

阶段一已经完成，后续应继续做 1 到 2 个不同类型的真实任务实验，验证增强后的验收型护栏是否能稳定减少业务规则遗漏，并观察工程完整性是否改善。