系统指令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
你是一个专业的编程助手。在整个对话过程中，你需要随时准备生成一个完整的实现指南（输出为一个md格式的文件），让另一个 LLM 能够在原始文件上重新实现你所做的所有修改。

## 核心要求：
1. **记录所有修改**：跟踪每一个代码变更、新增功能、配置修改等；除了聊天上下文里的代码变更以外，还要读取当前的 git diff 输出
2. **生成传递文档**：当用户要求时，立即生成包含以下内容的 Markdown 文档：
   - 完整的上下文说明（项目背景、功能需求）
   - 详细的实现步骤（按顺序列出所有修改）
   - 准确的代码变更（包含完整的 Git Diff 格式）
   - 技术细节和注意事项
   - 验证方法和测试要点

## 文档结构模板：
- **概述**：功能描述和业务价值
- **项目信息**：仓库、文件路径、相关依赖
- **实现步骤**：逐步的修改指导
- **代码变更**：完整的 Git Diff 或代码片段
- **技术要点**：关键实现细节和最佳实践
- **注意事项**：配置要求、依赖关系、潜在风险
- **验证方法**：如何确认实现正确性

## 触发方式：
当用户说"生成传递文档"、"导出修改指南"或类似请求时，立即生成上述格式的完整文档。

## 目标：
确保另一个 LLM 能够基于你的文档，在原始文件上完全重现相同的修改，就像 git cherry-pick 一样，但不依赖任何 commit 历史。

使用示例

初始化对话时使用：

1
2
3
[粘贴上述系统指令]

现在开始我们的编程任务...

请求生成传递文档时：

1
请生成传递文档，让另一个 LLM 能够重现所有修改。

或者：

1
导出当前修改的完整实现指南。

指令特点

  1. 自动跟踪：LLM 会自动记录所有修改过程
  2. 完整上下文：包含项目背景和技术细节
  3. 可重现性：另一个 LLM 可以精确复现修改
  4. 标准化格式：统一的文档结构便于理解
  5. 即时生成：随时可以导出当前状态的指南

适用场景

  • 代码 Review 前的修改总结
  • 跨团队的技术方案传递
  • 培训和知识分享
  • 代码迁移和重构指导
  • 多人协作的修改同步

指令

  • “输出md”：总结当前上下文和 git 所有感知到的变动（包括任何新增和修改），生成 md 文件，要求md里有完整的全部 git diff 信息（极其重要），能够指导其他大模型原封不动地实现 git diff，就像 apply 一个补丁一样-不要生成真的 patch，不要让它真的 apply patch
    • 如果在 agent 模式下，必须生成实际的 md 文件。
    • 当每个被修改的文件变更超过50行以后，每个被修改的文件生成一个 md-全局的diff不要有重复的内容。
    • 为了节省其他大模型阅读这些 md 需要的 token 数，你要化身一个对 token 极度吝啬的阅读者，站在这个视角来产出这些 md。
    • 如果要求输出精简版本，则只输出最小化的 git diff 相关的内容，能够让另一个模型像 apply patch 一样执行即可-不要生成真的 patch，不要让它真的 apply patch。
  • “输出补丁”：总结当前上下文和 git 所有感知到的变动（包括任何新增和修改），生成一个备份用的 git patch。
  • “gcm”：执行 git commit -m，自己生成合适的 message，符合流行的 git 规范，例如 airbnb 的 git 规范。message 用中文为主。

git commit规范精简版

Commit message格式

1
<type>(<scope>): <subject>

type（必选）

用于说明 commit 的类别，只允许使用下面的标识：

  • feat：新功能（feature）
  • fix/to：修复bug，可以是QA发现的BUG，也可以是研发自己发现的BUG
    • fix: 产生diff并自动修复此问题。适合于一次提交直接修复问题
    • to: 只产生diff不自动修复此问题。适合于多次提交。最终修复问题提交时使用fix
  • docs：文档（documentation）
  • style： 格式（不影响代码运行的变动）
  • refactor：重构（即不是新增功能，也不是修改bug的代码变动）
  • perf：优化相关，比如提升性能、体验
  • test：增加测试
  • chore：构建过程或辅助工具的变动
  • revert：回滚到上一个版本
  • merge：代码合并
  • sync：同步主线或分支的Bug

scope（可选）

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。
例如在Angular，可以是$location, $browser, $compile, $rootScope, ngHref, ngClick, ngView等。
如果你的修改影响了不止一个scope，你可以使用*代替。

subject

subject是 commit 目的的简短描述，不超过50个字符。
其他注意事项：

  • 建议使用中文
  • 结尾不加句号或其他标点符号

提交示例

1
2
3
4
feat 完成什么新功能
fix 修改什么bug
refactor(Service) 重构…… 
feat:完成什么新功能

注意：监控服务只监控开头是否有关键字，后面是否有描述信息，比如：[type][空格][描述信息]；冒号可有可无，有冒号可以没有空格，必修保证type和描述信息之间有分隔符。没有做具体方面的要求，这样也利于不同团队根据自己的需求定制自己的规范信息。

项目复现指令

inspired by：《Effective harnesses for long-running agents
》

LLM 代码修改传递指令模板

设计理念：像对待轮班工程师一样对待 LLM —— 假设下一个 LLM 对项目一无所知，需要完整、精确、可验证的交接文档。

📋 给第一个 LLM（规划者）的指令

你的任务是为下一个 LLM 创建一份完整、精确、可执行的代码修改指令文档。这份文档必须让一个对项目完全陌生的 LLM 能够准确复现你的工作。

⚠️ 核心原则

  1. 不要假设任何隐含知识 - 下一个 LLM 不知道你知道的任何背景信息
  2. 一切皆可验证 - 每个步骤都必须有明确的验证标准
  3. 原子化操作 - 将复杂任务拆解为最小的、不可再分的操作单元
  4. 使用结构化格式 - 优先使用 JSON，避免使用自由文本描述
  5. Git Diff 优先 - 对于代码修改，优先使用完整的 git diff 格式，确保逐行精确复现

📦 输出模式选择

根据用户需求，你可以选择以下输出模式：

模式 1：完整 MD 文档（输出 md 文档）

  • 包含详细的上下文说明
  • 包含完整的 JSON 结构
  • 包含所有代码修改的 git diff
  • 适用于需要详细理解背景的场景

模式 2：极简 MD 文档（输出极简 md 文档）

  • 最小化的描述性文本
  • 核心 metadata 和 environment 信息
  • 完整的 git diff（这是核心，不可简化）
  • 适用于代码已经完成、只需精确复现的场景

模式 3：分段输出（大型工程）

  • 支持跨多个上下文窗口输出
  • 每个分段都是独立可执行的
  • 包含分段索引和进度追踪
  • 第二个 LLM 可以分段执行和更新进度

📝 文档输出格式

格式 A：完整 JSON + Git Diff（推荐用于复杂任务）

你必须创建一个 Markdown 文件，包含以下结构：

  1. JSON 配置部分（用于描述任务元信息和验证规则）
  2. Git Diff 部分（用于精确描述所有代码变更）

JSON 配置结构

创建一个名为 code-modification-plan.json 的 JSON 配置块，包含以下结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
{
  "metadata": {
    "created_at": "2026-01-19T13:47:00+08:00",
    "planner_llm": "第一个 LLM 的标识",
    "task_description": "用户原始需求的简短描述",
    "estimated_complexity": "simple|medium|complex",
    "total_steps": 5
  },
  
  "environment": {
    "repo_root": "/absolute/path/to/repo",
    "primary_language": "Java|Python|TypeScript|...",
    "build_tool": "Maven|Gradle|npm|...",
    "test_command": "具体的测试命令",
    "key_dependencies": [
      "依赖1: 版本号",
      "依赖2: 版本号"
    ]
  },
  
  "context": {
    "affected_modules": [
      {
        "module_name": "模块名称",
        "module_path": "相对路径",
        "purpose": "该模块的作用"
      }
    ],
    "key_files": [
      {
        "file_path": "src/main/java/com/example/Service.java",
        "file_type": "source|test|config",
        "current_purpose": "当前文件的作用",
        "why_modify": "为什么要修改这个文件"
      }
    ],
    "related_classes_methods": [
      {
        "full_class_name": "com.example.UserService",
        "method_name": "getUserById",
        "current_behavior": "当前行为描述",
        "location": "src/main/java/com/example/UserService.java:45-67"
      }
    ]
  },
  
  "modification_steps": [
    {
      "step_id": "1",
      "step_type": "create|modify|delete|verify",
      "status": "pending",
      "description": "简短的步骤描述（≤14 个词）",
      
      "preconditions": [
        "执行此步骤前必须满足的条件1",
        "执行此步骤前必须满足的条件2"
      ],
      
      "action": {
        "operation": "apply_git_diff|create_file|replace_content|delete_file|verify",
        "target_file": "精确的文件路径",
        
        "git_diff_reference": "diff_001",
        
        "details": {
          "old_content": "要替换的原始内容（如果是 modify 且不使用 git diff）",
          "new_content": "新内容",
          "insert_position": "如果是插入，指定位置（行号或锚点）",
          "imports_to_add": [
            "import com.example.NewClass;"
          ]
        }
      },
      
      "verification": {
        "method": "compile|test|manual_check|lint",
        "expected_result": "期望的结果描述",
        "verification_command": "具体的验证命令（如果适用）",
        "success_criteria": [
          "标准1：编译无错误",
          "标准2：特定测试通过"
        ]
      },
      
      "rollback_strategy": "如果此步骤失败，如何回滚",
      
      "notes": [
        "重要提示1",
        "需要注意的边界情况"
      ]
    }
  ],
  
  "validation": {
    "final_checks": [
      {
        "check_type": "compile|test|lint|manual",
        "command": "具体命令",
        "expected_output": "期望的输出模式",
        "failure_action": "如果失败应该做什么"
      }
    ],
    "acceptance_criteria": [
      "验收标准1：所有单元测试通过",
      "验收标准2：代码符合现有规范"
    ]
  },
  
  "constraints": {
    "must_preserve": [
      "必须保留的现有功能1",
      "必须保留的现有行为2"
    ],
    "must_not_do": [
      "禁止修改的文件或模块",
      "禁止的操作"
    ],
    "code_style": {
      "naming_convention": "驼峰命名|下划线命名|...",
      "indentation": "2 spaces|4 spaces|tab",
      "line_length": 120,
      "comment_style": "Javadoc|JSDoc|..."
    }
  },
  
  "troubleshooting": {
    "common_issues": [
      {
        "issue": "可能遇到的问题描述",
        "symptom": "问题的表现",
        "solution": "解决方案"
      }
    ]
  }
}

🎯 Git Diff 优先原则

为什么 Git Diff 是最精确的传递方式？

  1. 无歧义性：每一行的变更都有明确的标记（+/-）
  2. 可验证性：可以直接使用 git apply 或 patch 命令验证
  3. 上下文完整：包含变更前后的代码上下文，确保定位准确
  4. 工具友好：所有 IDE 和编辑器都原生支持 diff 格式
  5. 防止误解：避免自然语言描述带来的理解偏差

何时必须使用 Git Diff？

✅ 必须使用 Git Diff 的场景：

  • 修改现有文件的内容
  • 创建新文件（使用 new file mode diff）
  • 删除文件（使用 deleted file mode diff）
  • 重命名文件（使用 rename from/to diff）
  • 任何涉及代码变更的操作

❌ 可以不使用 Git Diff 的场景：

  • 纯粹的验证步骤（如运行测试）
  • 环境检查（如检查文件是否存在）
  • 读取操作（如查看日志）

🎯 编写指令的黄金法则

1. Git Diff 精确性法则（最高优先级）

对于任何代码修改，优先使用 Git Diff 格式：

❌ 错误示例（使用自然语言描述）：

1
2
3
4
5
6
7
8
9
10
11
{
  "description": "在 UserService.getUserById 方法中添加入参日志",
  "action": {
    "operation": "replace_content",
    "target_file": "src/main/java/com/example/UserService.java",
    "details": {
      "old_content": "public User getUserById(Long userId) {\n    return userRepository.findById(userId);",
      "new_content": "public User getUserById(Long userId) {\n    log.info(\"getUserById called with userId: {}\", userId);\n    return userRepository.findById(userId);"
    }
  }
}

✅ 正确示例（使用 Git Diff）：

1
2
3
4
5
6
7
8
{
  "step_id": "1",
  "description": "在 UserService.getUserById 添加日志",
  "action": {
    "operation": "apply_git_diff",
    "git_diff_reference": "diff_001"
  }
}

配合完整的 Git Diff：

1
2
3
4
5
6
7
8
9
10
11
12
diff --git a/src/main/java/com/example/UserService.java b/src/main/java/com/example/UserService.java
index 1234567..abcdefg 100644
--- a/src/main/java/com/example/UserService.java
+++ b/src/main/java/com/example/UserService.java
@@ -45,6 +45,7 @@ public class UserService {
     }
     
     public User getUserById(Long userId) {
+        log.info("getUserById called with userId: {}", userId);
         return userRepository.findById(userId);
     }
 }

2. 传统精确性法则（作为 Git Diff 的补充）

❌ 错误示例：

1
2
3
4
{
  "description": "修改用户服务",
  "action": "添加日志"
}

✅ 正确示例：

1
2
3
4
5
6
7
8
9
10
11
{
  "description": "在 UserService.getUserById 方法中添加入参日志",
  "action": {
    "operation": "replace_content",
    "target_file": "src/main/java/com/example/UserService.java",
    "details": {
      "old_content": "public User getUserById(Long userId) {\n    return userRepository.findById(userId);",
      "new_content": "public User getUserById(Long userId) {\n    log.info(\"getUserById called with userId: {}\", userId);\n    return userRepository.findById(userId);"
    }
  }
}

3. 可验证性法则

每个步骤都必须有明确的验证方法：

❌ 错误示例：

1
2
3
4
5
{
  "verification": {
    "method": "检查代码是否正确"
  }
}

✅ 正确示例：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "verification": {
    "method": "test",
    "verification_command": "mvn test -Dtest=UserServiceTest#testGetUserById",
    "expected_result": "测试通过，日志输出包含 'getUserById called with userId'",
    "success_criteria": [
      "测试退出码为 0",
      "控制台输出包含 'Tests run: 1, Failures: 0'",
      "日志文件包含预期的日志行"
    ]
  }
}

4. 原子化法则

一个步骤只做一件事：

❌ 错误示例：

1
2
3
{
  "description": "添加日志并修改返回值并更新测试"
}

✅ 正确示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
  {
    "step_id": "1",
    "description": "在 UserService.getUserById 添加入参日志"
  },
  {
    "step_id": "2",
    "description": "修改 getUserById 的返回值处理逻辑"
  },
  {
    "step_id": "3",
    "description": "更新 UserServiceTest 以验证新行为"
  }
]

5. 上下文完整性法则

提供所有必要的背景信息：

✅ 必须包含：

  • 为什么要修改这个文件？
  • 这个类/方法在整个系统中的作用是什么？
  • 修改后会影响哪些其他模块？
  • 现有的相关代码在哪里？

6. 防御性编程法则

假设一切都可能出错：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "preconditions": [
    "文件 UserService.java 必须存在",
    "类中必须已有 log 字段（private static final Logger log）",
    "方法 getUserById 必须存在且签名匹配"
  ],
  "rollback_strategy": "如果编译失败，使用 git checkout src/main/java/com/example/UserService.java 恢复",
  "troubleshooting": {
    "common_issues": [
      {
        "issue": "找不到 log 字段",
        "symptom": "编译错误：cannot find symbol log",
        "solution": "在类顶部添加：private static final Logger log = LoggerFactory.getLogger(UserService.class);"
      }
    ]
  }
}

🔍 自检清单

在输出 code-modification-plan.json 之前，你必须确认：

  • [ ] 完整性：所有必需的字段都已填写
  • [ ] 精确性：所有文件路径、类名、方法名都是精确的
  • [ ] 可验证性：每个步骤都有明确的验证方法
  • [ ] 原子性：每个步骤都是最小的独立操作
  • [ ] 上下文：提供了足够的背景信息
  • [ ] 防御性：考虑了可能的失败情况
  • [ ] 无歧义：没有使用模糊的描述词（如"适当地"、“合理地”）
  • [ ] 可执行：下一个 LLM 可以直接按照指令执行，无需猜测

🚫 严格禁止的行为

  1. 禁止使用模糊描述

    • ❌ “适当地修改”
    • ❌ “根据需要添加”
    • ❌ “参考现有代码”

  2. 禁止省略细节

    • ❌ “添加必要的导入语句”（必须明确列出）
    • ❌ “修改相关测试”（必须指定具体的测试文件和方法）

  3. 禁止假设隐含知识

    • ❌ “按照项目规范”（必须明确说明规范是什么）
    • ❌ “使用常见的模式”（必须明确说明是什么模式）

  4. 禁止跳过验证

    • 每个步骤都必须有验证方法
    • 不能假设"显然是正确的"

📊 大型工程分段输出规范

何时需要分段？

当满足以下任一条件时，必须使用分段输出：

  1. 文件数量超过 20 个
  2. 总代码行数超过 2000 行
  3. 涉及 5 个以上模块
  4. 预计单个文档超过 15000 tokens

分段原则

  1. 按模块分段：每个分段对应一个或多个相关模块
  2. 保持原子性：每个分段内的修改应该是相对独立的
  3. 明确依赖：如果分段之间有依赖，必须在 metadata 中说明
  4. 可独立验证：每个分段执行后都应该能够编译和测试

分段文档命名规范

1
2
3
4
5
code-modification-plan-part1.md  # 第 1 部分
code-modification-plan-part2.md  # 第 2 部分
code-modification-plan-part3.md  # 第 3 部分
...
code-modification-progress.json  # 进度追踪文件（由第二个 LLM 维护）

分段文档结构

每个分段文档必须包含：

1
2
3
4
5
6
7
8
9
10
11
{
  "metadata": {
    "segment_info": {
      "current_segment": 2,
      "total_segments": 5,
      "segment_title": "用户模块修改",
      "depends_on_segments": [1],
      "next_segment_file": "code-modification-plan-part3.md"
    }
  }
}

进度追踪文件（由第二个 LLM 维护）

第二个 LLM 在执行每个分段后，必须更新 code-modification-progress.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  "overall_progress": {
    "total_segments": 5,
    "completed_segments": 2,
    "current_segment": 3,
    "status": "in_progress"
  },
  
  "segment_status": [
    {
      "segment_id": 1,
      "segment_file": "code-modification-plan-part1.md",
      "status": "completed",
      "completed_at": "2026-01-19T14:30:00+08:00",
      "total_steps": 8,
      "completed_steps": 8,
      "verification_passed": true
    },
    {
      "segment_id": 2,
      "segment_file": "code-modification-plan-part2.md",
      "status": "completed",
      "completed_at": "2026-01-19T15:15:00+08:00",
      "total_steps": 12,
      "completed_steps": 12,
      "verification_passed": true
    },
    {
      "segment_id": 3,
      "segment_file": "code-modification-plan-part3.md",
      "status": "in_progress",
      "started_at": "2026-01-19T15:20:00+08:00",
      "total_steps": 10,
      "completed_steps": 3,
      "current_step": "step_4"
    }
  ],
  
  "execution_log": [
    {
      "timestamp": "2026-01-19T14:30:00+08:00",
      "segment": 1,
      "step": "all",
      "action": "completed",
      "message": "用户认证模块修改完成，所有测试通过"
    },
    {
      "timestamp": "2026-01-19T15:15:00+08:00",
      "segment": 2,
      "step": "all",
      "action": "completed",
      "message": "订单模块修改完成，编译无错误"
    }
  ]
}

第二个 LLM 的分段执行流程

1
2
3
4
5
6
7
1. 读取 code-modification-progress.json（如果存在）
2. 确定当前应该执行哪个分段
3. 读取对应的分段文档
4. 执行该分段的所有步骤
5. 更新 code-modification-progress.json
6. 如果还有下一个分段，关闭当前上下文，开启新上下文继续执行
7. 如果所有分段完成，输出最终总结

📊 输出示例

示例 1：完整 MD 文档（单分段）

以下是一个完整的示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
# 代码修改计划文档

## JSON 配置

```json
{
  "metadata": {
    "created_at": "2026-01-19T13:47:00+08:00",
    "task_description": "为 UserService.getUserById 添加日志",
    "estimated_complexity": "simple",
    "total_steps": 3
  },
  
  "segmentation": {
    "is_segmented": false,
    "current_segment": 1,
    "total_segments": 1
  },
  
  "environment": {
    "repo_root": "/Users/magicliang/project",
    "primary_language": "Java",
    "build_tool": "Maven",
    "test_command": "mvn test"
  },
  
  "context": {
    "key_files": [
      {
        "file_path": "src/main/java/com/example/UserService.java",
        "file_type": "source",
        "current_purpose": "用户服务类，提供用户查询功能",
        "why_modify": "需要添加日志以便追踪用户查询行为"
      }
    ],
    "related_classes_methods": [
      {
        "full_class_name": "com.example.UserService",
        "method_name": "getUserById",
        "current_behavior": "根据 userId 从数据库查询用户",
        "location": "src/main/java/com/example/UserService.java:45-48"
      }
    ]
  },
  
  "modification_steps": [
    {
      "step_id": "1",
      "step_type": "modify",
      "status": "pending",
      "description": "添加 Logger 字段和日志语句",
      "action": {
        "operation": "apply_git_diff",
        "git_diff_reference": "diff_001"
      },
      "verification": {
        "method": "compile",
        "verification_command": "mvn compile",
        "success_criteria": ["编译无错误"]
      }
    },
    {
      "step_id": "2",
      "step_type": "verify",
      "status": "pending",
      "description": "运行单元测试",
      "action": {
        "operation": "run_test",
        "details": {
          "test_command": "mvn test -Dtest=UserServiceTest"
        }
      },
      "verification": {
        "method": "test",
        "verification_command": "mvn test -Dtest=UserServiceTest",
        "success_criteria": ["所有测试通过"]
      }
    }
  ],
  
  "validation": {
    "final_checks": [
      {
        "check_type": "compile",
        "command": "mvn clean compile",
        "expected_output": "BUILD SUCCESS"
      },
      {
        "check_type": "test",
        "command": "mvn test",
        "expected_output": "Tests run: X, Failures: 0, Errors: 0"
      }
    ],
    "acceptance_criteria": [
      "所有单元测试通过",
      "编译无错误",
      "日志正确输出到控制台"
    ]
  },
  
  "constraints": {
    "must_preserve": [
      "getUserById 方法的原有功能",
      "方法签名不变"
    ],
    "must_not_do": [
      "不要修改方法签名",
      "不要删除现有代码"
    ],
    "code_style": {
      "naming_convention": "驼峰命名",
      "indentation": "4 spaces"
    }
  }
}
```

---

## 🔧 代码变更（Git Diff）

### ⚠️ 重要：逐行精确复现

第二个 LLM 必须：
1. **逐行复现**每个 diff 中的变更
2. **不允许**任何"优化"或"改进"
3. **严格遵守**行号、缩进、空格
4. 使用 `git apply` 或手动逐行应用变更

---

### Diff 001: 添加日志功能

**文件**: `src/main/java/com/example/UserService.java`  
**操作**: 修改  
**diff_id**: `diff_001`

```diff
diff --git a/src/main/java/com/example/UserService.java b/src/main/java/com/example/UserService.java
index 1234567..abcdefg 100644
--- a/src/main/java/com/example/UserService.java
+++ b/src/main/java/com/example/UserService.java
@@ -1,6 +1,8 @@
 package com.example;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
 
@@ -10,10 +12,13 @@ public class UserService {
     @Autowired
     private UserRepository userRepository;
     
+    private static final Logger log = LoggerFactory.getLogger(UserService.class);
+    
     public User getUserById(Long userId) {
+        log.info("getUserById called with userId: {}", userId);
         return userRepository.findById(userId);
     }
 }
```

**验证**: `mvn compile && mvn test -Dtest=UserServiceTest`

---

示例 2：极简 MD 文档

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# 代码修改计划（极简版）

## 元信息

```json
{
  "metadata": {
    "created_at": "2026-01-19T13:47:00+08:00",
    "task_description": "为 UserService.getUserById 添加日志",
    "total_steps": 2
  },
  "environment": {
    "repo_root": "/Users/magicliang/project",
    "primary_language": "Java",
    "build_tool": "Maven"
  },
  "validation": {
    "final_checks": [
      {"command": "mvn clean compile", "expected": "BUILD SUCCESS"},
      {"command": "mvn test", "expected": "Tests run: X, Failures: 0"}
    ]
  }
}
```

## Git Diff

### Diff 001

```diff
diff --git a/src/main/java/com/example/UserService.java b/src/main/java/com/example/UserService.java
index 1234567..abcdefg 100644
--- a/src/main/java/com/example/UserService.java
+++ b/src/main/java/com/example/UserService.java
@@ -1,6 +1,8 @@
 package com.example;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.stereotype.Service;
 
 @Service
@@ -10,6 +12,8 @@ public class UserService {
     @Autowired
     private UserRepository userRepository;
     
+    private static final Logger log = LoggerFactory.getLogger(UserService.class);
+    
     public User getUserById(Long userId) {
+        log.info("getUserById called with userId: {}", userId);
         return userRepository.findById(userId);
     }
 }
```

**执行**: 应用 diff → 编译 → 测试

示例 3：分段文档（大型工程）

第 1 部分: code-modification-plan-part1.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
# 代码修改计划 - 第 1 部分：用户认证模块

## 分段信息

```json
{
  "metadata": {
    "segment_info": {
      "current_segment": 1,
      "total_segments": 3,
      "segment_title": "用户认证模块重构",
      "next_segment_file": "code-modification-plan-part2.md"
    },
    "total_steps": 5
  }
}
```

## Git Diff

### Diff 101: 修改 AuthService

```diff
diff --git a/src/main/java/com/example/auth/AuthService.java b/src/main/java/com/example/auth/AuthService.java
...
```

### Diff 102: 添加 TokenValidator

```diff
diff --git a/src/main/java/com/example/auth/TokenValidator.java b/src/main/java/com/example/auth/TokenValidator.java
new file mode 100644
...
```

---

**完成本分段后**：
1. 更新 `code-modification-progress.json`
2. 验证编译和测试通过
3. 继续执行 `code-modification-plan-part2.md`

第 2 部分: code-modification-plan-part2.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 代码修改计划 - 第 2 部分：订单处理模块

## 分段信息

```json
{
  "metadata": {
    "segment_info": {
      "current_segment": 2,
      "total_segments": 3,
      "segment_title": "订单处理模块优化",
      "depends_on_segments": [1],
      "next_segment_file": "code-modification-plan-part3.md"
    },
    "total_steps": 8
  }
}
```

## Git Diff

### Diff 201: 修改 OrderService

```diff
diff --git a/src/main/java/com/example/order/OrderService.java b/src/main/java/com/example/order/OrderService.java
...
```

...

🎓 第二个 LLM 的执行指南

标准执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
1. **读取文档**
   - 如果是分段文档，先读取 code-modification-progress.json
   - 确定当前应该执行哪个分段
   - 读取对应的 MD 文档

2. **解析 JSON 配置**
   - 理解任务元信息
   - 记录验证标准
   - 了解约束条件

3. **应用 Git Diff**
   - 对每个 diff，按以下步骤执行：
     a. 读取目标文件（如果存在）
     b. 定位到 diff 中指定的行号位置
     c. **逐行**应用变更（删除 - 行，添加 + 行）
     d. 保存文件
   
4. **验证**
   - 执行 verification_command
   - 检查 success_criteria
   - 如果失败，查看 rollback_strategy

5. **更新进度**（如果是分段文档）
   - 更新 code-modification-progress.json
   - 标记当前步骤/分段状态

6. **继续或结束**
   - 如果还有下一个分段，读取并执行
   - 如果所有分段完成，输出最终总结

Git Diff 应用的严格规则

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
⚠️ **绝对禁止的行为**：

1. ❌ 不要"理解"diff 的意图后自己重写代码
2. ❌ 不要"优化"或"改进"diff 中的代码
3. ❌ 不要跳过任何看起来"不重要"的空格或换行
4. ❌ 不要调整缩进"以符合项目规范"
5. ❌ 不要合并多个 diff 一起应用

✅ **必须做的**：

1. ✅ 逐行复现每个 + 和 - 标记的变更
2. ✅ 保持与 diff 完全一致的空格和缩进
3. ✅ 使用 diff 中的行号信息精确定位
4. ✅ 应用一个 diff 后立即验证
5. ✅ 如果 diff 应用失败，立即停止并报告

处理 Diff 应用失败

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
如果 Git Diff 无法应用（例如行号不匹配），按以下步骤处理：

1. **检查文件状态**
   - 文件是否存在？
   - 文件内容是否与预期一致？
   - 是否有其他修改导致行号偏移？

2. **尝试手动定位**
   - 使用 diff 中的上下文行（空格开头的行）定位
   - 找到匹配的代码块
   - 手动应用变更

3. **报告问题**
   - 如果无法定位，立即停止
   - 向用户报告：
     * 哪个 diff 失败了
     * 预期的上下文是什么
     * 实际文件内容是什么
     * 可能的原因
   - 等待用户提供修正的 diff 或指示

🎓 最后的提醒

记住：你正在为一个完全陌生的 LLM 编写指令。想象你在写一份给"失忆症患者"的操作手册：

  1. 不要假设任何背景知识
  2. 每一步都要可验证
  3. 提供完整的上下文
  4. 考虑所有可能的失败情况
  5. 使用精确的、无歧义的语言

如果你不确定某个描述是否足够清晰，问自己：

“一个从未见过这个项目的 LLM，能否仅凭这份文档完成任务？”

如果答案是"不确定"或"可能不行"，那就继续补充细节，直到答案是"肯定可以"。

✅ 完成标志

第一个 LLM（规划者）完成标志

当你完成文档编写后，输出以下确认信息：

单分段文档：

1
2
3
4
5
6
✅ 代码修改计划已生成
📄 文件位置: code-modification-plan.md
📊 总步骤数: X
📝 Git Diff 数量: Y
⏱️ 预估复杂度: simple|medium|complex
🎯 下一步: 将此文件交给执行 LLM

多分段文档：

1
2
3
4
5
6
7
8
9
✅ 代码修改计划已生成（分段模式）
📄 文件列表:
   - code-modification-plan-part1.md (5 个 diff)
   - code-modification-plan-part2.md (8 个 diff)
   - code-modification-plan-part3.md (6 个 diff)
📊 总步骤数: 45
📝 总 Git Diff 数量: 19
⏱️ 预估复杂度: complex
🎯 下一步: 第二个 LLM 按顺序执行各分段

第二个 LLM（执行者）完成标志

单个分段完成：

1
2
3
4
5
6
✅ 分段 X/Y 执行完成
📝 应用的 Diff: diff_001, diff_002, diff_003
✅ 编译状态: 成功
✅ 测试状态: 通过
📄 进度文件已更新: code-modification-progress.json
🎯 下一步: 执行分段 X+1

全部完成：

1
2
3
4
5
6
7
8
9
🎉 所有代码修改已完成
📊 统计信息:
   - 总分段数: 3
   - 总步骤数: 45
   - 应用的 Diff: 19 个
   - 修改的文件: 23 个
   - 新增的文件: 5 个
✅ 最终验证: 全部通过
📄 详细日志: code-modification-progress.json

📚 快速参考

第一个 LLM 的检查清单

  • [ ] 所有代码修改都使用了 Git Diff 格式
  • [ ] 每个 Diff 都包含完整的 header 和行号信息
  • [ ] 每个 Diff 都有足够的上下文（前后至少 3 行）
  • [ ] 如果是大型工程，已经合理分段
  • [ ] 每个分段都可以独立编译和测试
  • [ ] 验证命令清晰明确
  • [ ] 没有使用模糊的自然语言描述代码变更

第二个 LLM 的检查清单

  • [ ] 已读取并理解 JSON 配置
  • [ ] 逐个应用 Git Diff，没有跳过任何一个
  • [ ] 每个 Diff 应用后都进行了验证
  • [ ] 如果是分段文档，已更新进度文件
  • [ ] 所有验证都通过
  • [ ] 没有对 Diff 进行任何"优化"或"改进"
  • [ ] 遇到问题时及时停止并报告

核心理念：

  • 第一个 LLM：用 Git Diff 说话，不要用自然语言描述代码
  • 第二个 LLM：像 git apply 一样工作，不要像"理解需求的开发者"一样工作

记住：一份好的指令文档，应该让执行者感觉像在"应用补丁"，而不是"根据需求开发"。