如何让 llm 指导另一个 llm 写代码

gistfile1.txt

# 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 配置块，包含以下结构：

```json
{
  "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 格式：

❌ **错误示例**（使用自然语言描述）：
```json
{
  "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）：
```json
{
  "step_id": "1",
  "description": "在 UserService.getUserById 添加日志",
  "action": {
    "operation": "apply_git_diff",
    "git_diff_reference": "diff_001"
  }
}
```

配合完整的 Git Diff：
```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
@@ -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 的补充）
❌ **错误示例**：
```json
{
  "description": "修改用户服务",
  "action": "添加日志"
}
```

✅ **正确示例**：
```json
{
  "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. **可验证性法则**
每个步骤都必须有明确的验证方法：

❌ **错误示例**：
```json
{
  "verification": {
    "method": "检查代码是否正确"
  }
}
```

✅ **正确示例**：
```json
{
  "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. **原子化法则**
一个步骤只做一件事：

❌ **错误示例**：
```json
{
  "description": "添加日志并修改返回值并更新测试"
}
```

✅ **正确示例**：
```json
[
  {
    "step_id": "1",
    "description": "在 UserService.getUserById 添加入参日志"
  },
  {
    "step_id": "2",
    "description": "修改 getUserById 的返回值处理逻辑"
  },
  {
    "step_id": "3",
    "description": "更新 UserServiceTest 以验证新行为"
  }
]
```

### 5. **上下文完整性法则**
提供所有必要的背景信息：

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

### 6. **防御性编程法则**
假设一切都可能出错：

```json
{
  "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. **可独立验证**：每个分段执行后都应该能够编译和测试

### 分段文档命名规范

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

### 分段文档结构

每个分段文档必须包含：

```json
{
  "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`：

```json
{
  "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 的分段执行流程

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

---

## 📊 输出示例

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

以下是一个完整的示例：

````markdown
# 代码修改计划文档

## 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 文档

````markdown
# 代码修改计划（极简版）

## 元信息

```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`

````markdown
# 代码修改计划 - 第 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`

````markdown
# 代码修改计划 - 第 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 的执行指南

### 标准执行流程

```markdown
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 应用的严格规则

```markdown
⚠️ **绝对禁止的行为**：

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

✅ **必须做的**：

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

### 处理 Diff 应用失败

```markdown
如果 Git Diff 无法应用（例如行号不匹配），按以下步骤处理：

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

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

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

---

## 🎓 最后的提醒

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

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

如果你不确定某个描述是否足够清晰，问自己：
> "一个从未见过这个项目的 LLM，能否仅凭这份文档完成任务？"

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

---

## ✅ 完成标志

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

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

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

**多分段文档**：
```
✅ 代码修改计划已生成（分段模式）
📄 文件列表:
   - 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（执行者）完成标志

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

**全部完成**：
```
🎉 所有代码修改已完成
📊 统计信息:
   - 总分段数: 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` 一样工作，不要像"理解需求的开发者"一样工作

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