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

核心原则

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

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

适用场景

执行流程

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-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 影响范围分析

使用模板 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。

Phase 3: 测试策略

3.1 测试环境判断

digraph test_strategy {
    rankdir=LR;
    "开始" -> "可直接测试?";
    "可直接测试?" -> "编写单元测试" [label="是"];
    "可直接测试?" -> "可隔离?" [label="否"];
    "可隔离?" -> "提取代码到测试" [label="是"];
    "可隔离?" -> "Mock外部依赖" [label="需Mock"];
    "可隔离?" -> "集成测试" [label="集成环境"];
    "可隔离?" -> "手动验证" [label="无法自动化"];
    "提取代码到测试" -> "编写单元测试";
    "Mock外部依赖" -> "编写单元测试";
}

3.2 代码提取策略

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

Phase 4: 最小化修改实现

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

Phase 5: 自愈循环验证

5.1 验证器

5.2 自愈循环规则

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

Phase 6: 全量关联检查

6.1 关联影响矩阵

6.2 蝴蝶效应检查方法

1. AST 搜索：ast-grep-mcp find_code 按方法名/字段名搜索所有引用点
2. 静态分析：IDE"查找用法"
3. 调用链追踪：追踪方法调用链
4. 字段追踪：追踪字段所有读写点
5. 接口追踪：追踪接口所有调用点

ast-grep-mcp 蝴蝶效应检查示例：

搜索方法所有调用点：

find_code(pattern: '$OBJ.targetMethod($$$ARGS)', language: java, project_folder: "<dir>")

搜索字段所有读写点：

find_code(pattern: 'this.targetField', language: java, project_folder: "<dir>")

搜索接口所有实现类：

find_code_by_rule(
  project_folder: "<dir>",
  yaml: '''
    id: interface-impl
    language: java
    rule:
      pattern: 'class $NAME implements $IFACE $$$REST'
    constraints:
      IFACE:
        regex: 'TargetInterface'
  '''
)

使用模板 templates/association-checklist.md 与 templates/butterfly-check.md，产物写入 docs/code-part-modification/task-{yyyymmdd}-{seq}/。

Phase 7: 输出文档

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

文件结构

docs/code-part-modification/
└── task-{yyyymmdd}-{seq}/
    ├── requirement.md
    ├── impact-analysis.md
    ├── tasks.md
    ├── test-cases.md
    ├── changes.md
    ├── verification.log
    ├── butterfly-check.md
    └── report.md

最佳实践

与其他技能集成

常见问题

检查清单

开始前：需求已明确 / 修改点已定位 / 影响范围已分析

修改中：修改遵循最小化原则 / 测试已覆盖修改点 / 自愈循环验证通过

完成后：全量关联检查完成 / 蝴蝶效应检查通过 / 文档已更新 / 任务报告已输出