code-part-modification

Files (9)

• SKILL.md
• association-checklist.md · templates/
• butterfly-check.md · templates/
• changes.md · templates/
• impact-analysis.md · templates/
• report.md · templates/
• requirement.md · templates/
• tasks.md · templates/
• test-cases.md · templates/

SKILL.md (first lines)

# 局部代码修改技能（code-part-modification）

## 核心原则

> 本文件中的 `templates/...` 均指本技能目录下的 `templates/` 子目录。

- **最小化修改**：只修改完成目标功能所需的最小代码范围，避免"顺手优化"
- **无蝴蝶效应**：确保修改不影响其他功能，不引入隐性依赖，不破坏现有契约

## 适用场景

| 场景 | 说明 |
| ------ | ------ |
| Bug修复 | 修复特定缺陷，确保不影响其他功能 |
| 功能增加 | 添加新功能，最小化对现有代码的影响 |
| 功能修改 | 修改现有功能，保持向后兼容 |
| 功能封闭 | 废弃或关闭功能，清理相关代码 |

## 执行流程

```dot
digraph code_part {
    rankdir=TB;
    "理解需求" -> "定位修改点";
    "定位修改点" -> "影响范围分析";
    "影响范围分析" -> "分解子任务";
    "分解子任务" -> "有可测试环境?";
    "有可测试环境?" -> "编写单元测试" [label="是"];
    "有可测试环境?" -> "提取代码到测试" [label="否"];
    "编写单元测试" -> "实现最小修改";
    "提取代码到测试" -> "实现最小修改";
    "实现最小修改" -> "验证修改";
    "验证修改" -> "验证通过?";
    "验证通过?" -> "全量关联检查" [label="是"];
    "验证通过?" -> "自愈修复" [label="否"];
    "自愈修复" -> "验证修改";
    "全量关联检查" -> "关联检查通过?";
    "关联检查通过?" -> "修改完成" [label="是"];
    "关联检查通过?" -> "关联细节修复" [label="否"];
    "关联细节修复" -> "全量关联检查";
}
```

---

## Phase 1: 需求理解与修改点定位

### 1.1 需求理解

明确修改目标：

- **Bug修复**：复现路径、错误信息、期望行为
- **功能增加**：新功能描述、输入输出、边界条件
- **功能修改**：修改前行为、修改后行为、兼容性要求
- **功能封闭**：关闭范围、保留功能、清理范围

使用模板 `templates/requirement.md`，产物写入 `docs/code-part-modification/task-{yyyymmdd}-{seq}/requirement.md`。

### 1.2 定位修改点

| 方法 | 工具 | 适用场景 |
| ------ | ------ | ---------- |
| AST 精准搜索 | ast-grep-mcp `find_code_by_rule` | 按方法签名、调用模式精准定位 |
| 简单模式搜索 | ast-grep-mcp `find_code` | 按方法名/字段名快速搜索引用点 |
| 关键字搜索 | grep/rg | 根据错误信息定位（兜底） |
| 调用链追踪 | IDE/代码分析 | 理解数据流 |
| 日志追踪 | 日志文件 | 定位运行时位置 |
| 堆栈分析 | 异常堆栈 | Bug修复定位 |

**ast-grep-mcp 用法**：

按方法签名定位：
```
find_code(pattern: 'void $METHOD($$$ARGS)', language: java, project_folder: "<dir>")
```

按方法调用点定位（蝴蝶效应检查用）：
```
find_code(pattern: '$OBJ.methodName($$$ARGS)', language: java, project_folder: "<dir>")
```

按字段读写点定位：
```
find_code(pattern: '$OBJ.fieldName', language: java, project_folder: "<dir>")
```

> **注意**：MCP 不支持 `--globs` 排除目录，需限定 `project_folder` 或人工过滤。大型项目（>10k 文件）可能超时。

输出：修改点清单（文件、行号、修改类型、说明）

### 1.3 影响范围分析

| 检查维度 | 检查项 | 方法 |
| ---------- | -------- | ------ |
| 内部调用 | 谁调用了这个方法/函数？ | grep 调用点 |
| 上游系统 | 哪些外部系统调用此接口？ | 接口文档、日志 |
| 下游系统 | 此代码调用了哪些外部系统？ | 代码分析 |
| 数据库 | 涉及哪些表、字段？ | SQL 分析 |
| UI界面 | 界面显示哪些字段？ | 前端代码分析 |
| 配置 | 依赖哪些配置项？ | 配置文件分析 |

使用模板 `templates/impact-analysis.md`，产物写入 `docs/code-part-modification/task-{yyyymmdd}-{seq}/impact-analysis.md`。

---

## Phase 2: 任务分解

将修改任务分解到**可独立验证**的粒度：

| 粒度   | 标准                 | 示例                         |
|--------|----------------------|------------------------------|
| 太大   | 无法独立验证         | "重构订单模块"               |
| 合适   | 有明确的验证器       | "修改订单状态字段校验逻辑"   |
| 太小   | 验证成本高于修改成本 | "修改变量名"                 |

使用模板 `templates/tasks.md`，产物写入 `docs/code-part-modification/task-{yyyymmdd}-{seq}/tasks.md`。

---

From hellyguo/self-ai-spec, Apache-2.0.

More from hellyguo/self-ai-spec