---
name: code-plan-first
description: 在修改、重构或实现新功能前，必须先提供技术方案并分析可行性，获得用户确认后方可编码。
---

# 代码修改先行方案 Skill (Plan-First)

> [!IMPORTANT]
> **已启用 Plan-First 模式**：检测到代码修改意图。在执行任何 `write_to_file` 或 `apply_diff` 操作前，你必须先提供技术方案并获得用户确认。

本 Skill 旨在确保所有代码变更都经过充分思考、充分讨论并获得用户授权，防止盲目编码。

## 适用场景 (Trigger Rules)

**只要任务涉及对现有代码库的任何实质性改动，就必须触发此流程。** 包括但不限于：

- 显式的修改请求：“帮我改一下...”、“重构...”、“修复...”、“现在有一个问题...”。
- 隐式的功能实现：“实现一个...功能”、“添加一个页面”。
- 涉及写操作工具的使用意图：即将调用 `apply_diff`, `write_to_file`, `insert_content` 等。
- 甚至是简单的配置调整或依赖更新。

## 强制执行流程 (Mandatory Workflow)

**本流程是循环强制的。任何时候如果你打算执行写操作，必须确保最近的一条消息是用户的明确授权。**

### 第一步：方案提案 (Proposal)

在执行任何代码写入之前，必须首先输出一个详细的技术方案。方案应包含：

1. **变更描述**：清晰解释你打算做什么，解决什么问题。
2. **涉及范围**：列出所有将要修改、创建或删除的文件路径。
3. **技术实现细节**：简述具体的逻辑变化。例如：
    - 修改了哪个接口的定义。
    - 新增了哪些 State 或 Hook。
    - 调整了哪些 CSS 类名或样式属性。
    - 逻辑判断条件的变更。

### 第二步：分析与评估 (Analysis)

对上述方案进行深度自我审查，并向用户展示分析结果：

1. **可行性评估**：该方案是否符合当前项目的技术栈？是否遵循了项目中 `AGENTS.md` 规定的规范？
2. **副作用/风险分析**：
    - 修改是否会破坏现有功能（Regression Risk）？
    - 是否有其他文件依赖于将被修改的部分？
    - 是否会引入新的 Lint 错误或类型冲突？
3. **最佳实践**：这是否是当前上下文下的最简、最优雅实现？是否有更好的替代方案？

### 第三步：展示并等待用户确认 (Confirmation)

将方案和分析以清晰的 Markdown 结构呈现，并显式请求确认。

##### 输出示例

**方案：重构 `useDutyValidate` 校验 Hook**

**1. 变更描述**：
目前 `useDutyValidate` 逻辑过于臃肿，计划将其拆分为细粒度的校验函数，提高可维护性。

**2. 涉及文件**：

- `apps/quota/src/components/duty-schedule/hooks/useDutyValidate.ts`

**3. 技术细节**：

- 将 `validateAll` 拆分为 `validateBasicInfo`, `validateSchedule` 等私有函数。
- 保持 `useDutyValidate` 导出的 API 不变。

**4. 评估分析**：

- **可行性**：高。逻辑解耦符合项目规范。
- **风险**：需要确保单元测试（如果有）或调用方逻辑不受影响。已检查 `index.tsx` 中的调用方式，API 兼容。

**确认**：
以上是我的修改方案及分析。如果您认可，请回复“确认”，我将为您执行代码变更。

**必须以如下话术结尾：**

> **“以上是我的修改方案及分析。如果您认可，请回复‘开始’或‘确认’，我将为您执行代码变更；如果有任何建议，请告诉我。”**

**严禁行为：**

1. **禁止一次性越权**：即使用户在任务开始时说“同意后续所有修改”，在每个具体的方案提出后，依然需要针对该方案获得一次明确确认。
2. **禁止静默修改**：如果用户对方案提出了修改建议，你必须更新方案并**重新请求确认**，直到用户回复“确认”或“开始”。
3. **确认时效性**：在未获得用户针对**当前最新方案**的明确“确认”、“开始”或类似肯定意向之前，严禁调用任何写操作工具。

### 第四步：执行与验证 (Execution)

只有在获得针对**当前方案**的明确授权后，方可严格按照方案执行代码变更。执行完成后，需检查是否符合预期。