legacy-code-risk-control

一、强制触发规则（AI 自检）

生成任何代码之前，AI 必须先判断用户请求是否命中以下场景：

1.1 自动触发条件（命中任意一条即触发）

用户输入中出现以下关键词或意图时，必须立即调用本技能：

• 新增/添加功能："新增功能"、"添加功能"、"加一个功能"、"基于现有项目新增"、"在现有基础上新增"、"扩展功能"
• 修改/调整功能："修改功能"、"改一下"、"调整逻辑"、"优化一下"、"把...改成..."
• 修复问题："修复Bug"、"修个问题"、"排查问题"、"解决...问题"、"改个问题"
• 存量/现有项目语境："现有项目"、"存量代码"、"已有代码"、"老代码"、"不要影响现有"、"避免回归"
• 变更 Controller/Service/Mapper/公共类/对外接口：任何涉及已有 Java 类、已有接口、已有方法签名的变更

1.2 强制检查点

• 只要用户提到"基于现有""在现有项目""不要影响现有""已有功能"，无论后续要做什么，一律先走本技能。
• 即使需求看起来"很小"、"只改一行"，只要涉及已有文件/已有方法，也必须先输出影响范围清单并等待确认。
• 严禁在步骤4用户确认前输出任何实现代码、SQL、配置文件片段。

二、核心执行铁则（禁止突破）

执行全程必须严格遵守，任何情况下都不得违反：

1. 开闭原则优先：永远优先选择「新增扩展」而非「修改存量」，最小化对原有代码的侵入；
2. 最小变更原则：只修改必须改动的代码块，禁止顺手重构、重命名、优化无关代码、调整格式；
3. 先确认再动手：AI必须先输出完整的文件变更清单与影响范围，用户确认（可修改）后，才能开始写代码。禁止在确认前输出任何一行实现代码。如果用户要求修改范围，修改后重新输出清单再次确认；

三、标准化执行流程（严格按顺序执行，禁止跳过）

步骤1：信息补全与边界确认

首先核对以下信息，信息不全时主动向用户询问确认，禁止臆测。

本步骤的"变更类型"和"禁区清单"使用可勾选选项：

1.1 变更类型（单选，必须确认一项）：

• [ ] 新增功能
• [ ] 修改原有功能
• [ ] 修复Bug
• [ ] 扩展公共组件

1.2 已知的绝对禁止修改清单（多选，可勾选多项）：

• [ ] 公共工具类
• [ ] 核心实体 / POJO
• [ ] 对外接口 / API 契约
• [ ] 历史兼容逻辑
• [ ] 数据库表结构
• [ ] 其他（请在下方补充）

1.3 涉及的业务模块，以及预计修改的文件/方法范围（文本输入）

1.4 变更过程采用的技术栈与存量项目技术栈，技术架构，统一编码规范严格一致

向用户询问确认之前，AI 必须先用轻量方式定位本次需求相关的现有代码位置。 两阶段扫描规则：

阶段一：搜索找范围（Glob/Grep，几乎不消耗 token）

• 用关键词搜索所有相关文件路径和匹配行，获取调用点总数和分布
• Grep 返回 50 个匹配行不消耗上下文，放心搜

阶段二：抽样读确认（只 Read 关键文件）

• 如果搜索结果 ≤ 5 个文件：全部 Read
• 如果搜索结果 > 5 个文件：按类别抽样 Read 2~3 个代表性文件，确认调用模式一致
• 剩下的同类文件只报告数量和分布，不逐个读取。模式一致则无需重复确认

最后输出给用户：

Grep 发现 23 处引用你的目标方法，分布在 3 个模块：
  空域模块 8 处、知识模块 10 处、对话模块 5 处
已抽样读取各模块 1 个代表调用，调用模式一致，均为 xxx。
剩余 20 处（如果模式相同，此处可省略逐个列表）

• 用户明确知道代码位置时，直接用用户提供的信息，跳过搜索
• 禁止全量遍历项目目录，禁止模式相同的文件逐个读取

步骤2：变更策略选型

根据变更类型，匹配唯一最优实现策略，输出明确的实现路径：

• 新增功能：优先新增类、新增方法、新增策略分支，通过配置开关隔离新老逻辑，不触碰原有业务代码；
• 修改功能：优先使用方法重载、新增带默认值的参数、新增独立条件分支，原有逻辑代码原封不动保留；
• 删除功能：优先删除功能所对应的最小代码块，禁止调整周边代码逻辑；
• 修复Bug：优先修改Bug对应的最小代码块，禁止调整周边逻辑；

步骤3：生成编码红线清单

输出本次变更必须遵守的所有强制规则，分为通用红线，专属红线和风格约束：

• 通用红线：方法签名不可改、对外接口不可破、依赖版本不可升、无关代码不可动；
• 专属红线：将用户提供的禁止修改清单逐条列入，明确到类名、方法名、字段名；
• 风格约束：严格遵循项目现有编码风格，不得发明新的写法、新的分层、新的异常处理方式。

步骤4：影响范围分析 —— 计算 + 输出 + 等待用户确认（关键卡点，禁止跳过）

这是整个流程中最重要的环节。AI 必须先算出完整的变更范围，交给用户审核确认（用户可以修改），确认通过后才能进入步骤5，绝对禁止在确认前写任何代码。

4.1 计算影响范围

逐文件、逐方法列出本次变更涉及的全部内容，区分「新建」和「修改」：

📁 文件变更清单：

  ── 新建文件（安全，不破坏旧功能）──
  1. com/xxx/tool/TranslateTool.java          [新建，~120行]
     作用：翻译工具实现
  2. com/xxx/config/TranslateConfig.java      [新建，~30行]
     作用：翻译 API 配置

  ── 需修改的旧文件（⚠️ 有回归风险）──
  3. com/xxx/tool/ToolRegistry.java           [修改，+1行]
     位置：第 42 行 registerTools() 方法内
     内容：新增一行 toolRegistry.register(new TranslateTool());
     影响：仅影响工具注册流程，不影响已有工具
  4. com/xxx/controller/ChatController.java   [修改，+3行]
     位置：第 88 行 handleToolCall() 方法内
     内容：新增一个 case 分支处理 translate 工具调用
     影响：仅影响工具调度，不影响已有对话逻辑

  ── 调用链影响分析 ──
  TranslateTool.java（新）
    → 被 ToolRegistry 调用 （已有逻辑，注册阶段自动发现）
    → 被 ChatController 调度（已有 switch-case，新增一个分支）
    → 无其他调用方

  ── 回归风险提示 ──
  ⚠️ 修改 ChatController.java 第 88 行：
     该文件同时被天气、对话、知识管理三个模块依赖
     风险：若 case 分支遗漏 break，会导致 fall-through 到天气逻辑
     规避：只加 case 和 break，不调整已有 case 的顺序和内容

4.2 硬性约束检查

以下为分级约束——触发不同级别采取不同动作：

| 红线 | 触发条件 | 动作 | |------|---------|------| | ⚠️ 修改文件数偏高 | 需修改的旧文件 ≥ 5 个 | 不禁止，但在 4.3 确认时用 ⚠️⚠️ 特别标注，让用户格外关注 | | 🛑 修改文件数超标 | 需修改的旧文件 ≥ 10 个 | 强制暂停，必须改用「新建文件 + 适配器」方案 | | ⚠️ 修改点偏高 | 同一旧文件需修改 ≥ 6 处 | 不禁止，但在 4.3 确认时用 ⚠️⚠️ 特别标注，让用户格外关注 | | 🛑 修改点超标 | 同一旧文件需修改 ≥ 10 处 | 强制暂停，新建一个文件专门处理，只留 1 处调用入口 | | 🛑 禁区触碰 | 变更范围包含公共工具类/核心实体/对外接口 | 立即停止，让用户确认是否豁免 |

4.3 输出给用户确认（必须，使用可勾选选项）

将以上 4.1 和 4.2 的结果完整呈现给用户，然后以可勾选形式让用户确认：

以上是本次变更的完整影响范围。

请选择你要执行的操作（可多选）：
- [ ] ✅ 确认 — 我同意以上范围，继续进入步骤5
- [ ] ✏️ 修改范围 — 请说明要调整的项
- [ ] ➕ 追加禁区 — 请补充禁止修改的类/方法/字段
- [ ] ❌ 取消 — 本次变更超出预期，终止流程

同时，请对以下变更项逐一确认（可多选，未勾选代表不同意该项）：
── 新建文件（安全）──
- [ ] 1. com/xxx/tool/TranslateTool.java
- [ ] 2. com/xxx/config/TranslateConfig.java

── 需修改的旧文件（⚠️ 有回归风险）──
- [ ] 3. com/xxx/tool/ToolRegistry.java
- [ ] 4. com/xxx/controller/ChatController.java

确认规则：

• 如果勾选了 ✅ 确认，且所有变更项均已勾选，直接进入步骤5；
• 如果未勾选 ✅ 确认，或部分变更项未勾选，必须根据用户反馈重新调整范围，重新输出 4.1 并再次确认；
• 如果同时勾选了 ✅ 确认 和 ➕ 追加禁区，需先让用户补充禁区内容，再基于新禁区调整范围并重新确认；
• 如果勾选了 ❌ 取消，立即终止流程，不再输出任何代码。

用户确认后，才能进入步骤5。如果用户要求修改范围，修改后重新输出 4.1，再次确认。

步骤5：输出代码生成专用约束指令

基于步骤 4 确认后的变更范围，输出一段完整的约束指令，包含：

• 步骤 4 确认的完整文件清单（新建功能/修改功能分别列出）；
• 步骤 3 生成的所有编码红线清单（通用红线，专属红线分别列出）；
• 每个需修改的旧文件的具体修改位置和修改方式（精确到方法名和行号范围）
• 硬性约束：不得超出步骤 4 确认的范围，禁止顺手重构，格式化或其它额外改动；
• 执行顺序：首先新建所有新文件 → 用户确认新文件没问题 → 再逐个修改旧文件；

代码生成专用约束指令既是 AI 自己执行的铁律，也可直接复制给其他代码生成工具使用。

四、输出自检规则（输出前必须自行校验，不通过禁止输出）

1. 步骤 4 是否列出了每一个受影响的文件和方法，精确到行号；
2. 步骤 4 是否明确区分了「新建文件」和「需修改的旧文件」；
3. 步骤 4 是否已以可勾选形式触发用户确认流程，未确认前不得输出步骤 5；
4. 代码生成指令是否只覆盖步骤 4 确认后的范围，无遗漏、无越界；