V4TIME/V4SKILL

系统型智能体——严谨编码实践

何时使用

每一项编码任务、修改、调试会话或实现工作。本技能是所有代码变更的基础操作系统，而非可选附加项。

所有与代码相关的任务自动调用。如果用户要求你修改、添加、修复或构建代码，请遵循本技能。

核心规则

1. 绝不假设项目事实

在触碰任何文件之前，你必须知道实际存在的内容。读取文件。检查其当前状态。不要依赖关于“应该”有什么的记忆——要读取它。

具体操作：

• 对即将修改的文件执行 read_file，包括周围上下文
• 对相关代码、导入、函数调用者和引用执行 search_files
• 在测试更改之前，检查服务器是否运行以及端点是否响应
• 验证配置文件实际包含你所认为的内容

2. 在修改任何内容之前检查相关文件

不要盲目打补丁。对于计划编辑的每个文件：

1. 读取完整文件（或具有足够上下文的相关部分）
2. 理解当前结构、导入、依赖关系和模式
3. 确定需要修改的内容及原因
4. 然后才编写补丁或编辑

打补丁时： 在 old_string 中包含足够的周围上下文，使匹配唯一。匹配多个位置的补丁会应用到错误的位置。

读取大文件时： 使用 offset/limit 增量读取。如果你只需要一个函数，不要试图在一次调用中加载一个1600行的文件——但一定要完整读取你要修改的函数，包括其签名和所有调用点。

3. 在执行之前制定简洁计划

在任何非平凡编码任务之前，编写一个简短的计划（3-7个要点），回答以下问题：

• 哪些文件需要修改
• 每个变更做什么（每个变更一行）
• 变更应按照什么顺序进行
• 哪些验证步骤能确认成功

示例：

Plan:
1. 读取 app.py 第762-770行——检查 _get_hermes_response 签名
2. 在签名中添加 image_url: str = None 参数
3. 在函数内所有5个 _call_api 调用中添加 image_url=image_url
4. 从 chat() 将 image_url 传递给 _get_hermes_response
5. 重启服务器，用 curl 图像负载测试

在陈述计划之前不要开始编码。 如果计划错了，代码也会错。

4. 使用工具验证声明，而非猜测

每一个关于代码库的声明都应以工具输出为支撑，而非回忆。

声明	如何验证
“文件X有函数Y”	对该文件执行 grep -n 或 read_file
“服务器正在运行”	用 curl 访问健康检查端点
“更改有效”	运行实际测试，不要假设
“API 密钥已配置”	读取 storage/apis.json
“CSS 已加载”	用 curl 访问静态文件，检查 HTTP 状态
“补丁正确应用”	用 grep 查找新文本，或对该区域执行 read_file

永远不要写出说“它应该能工作”而未验证它实际有效的内容。

5. 在每次重大修改之后，测试或检查结果

在任何代码变更之后：

1. 语法检查： python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" —— 在重启之前必须通过
2. 重启服务器（如果 app.py 有更改）
3. 测试修改后的行为：
   • 对于 API 更改：使用代表性负载对端点执行 curl
   • 对于前端更改：验证静态文件被正常提供（HTTP 200）
   • 对于配置更改：读取配置文件以确认
4. 检查实际输出 —— 不是你的预期，而是工具返回的内容

在看到测试结果之前，变更不算完成。 “我认为它能工作”不是验证。

6. 如果某件事失败，在尝试另一种方法之前诊断实际错误

当测试失败或补丁无法应用时：

1. 读取实际错误消息 —— 逐字复制。不要总结。
2. 确定根因 —— 具体什么失败了以及为什么
3. 形成关于修复方案的假设
4. 用工具测试假设 —— 不要只是尝试另一个补丁
5. 如果修复无效，重新读取错误 —— 它可能已改变，或者你可能误读了它

应避免的反模式：

• 连续应用三个不同的补丁，而不检查哪个有效
• 基于错误类型猜测修复方案，而非阅读错误文本
• 当错误在某个特定位置时，修改无关的代码
• 不修复阻止服务器启动的语法错误就重启服务器

7. 在结果得到验证之前，不要说任务已完成

任务完成仅当：

• 代码变更已编写并通过语法检查 ✓
• 服务器正在运行新代码 ✓
• 修改后的行为产生了预期结果（通过工具输出验证） ✓
• 你可以指出证明这一点的具体测试/命令/输出 ✓

永远不要仅仅因为补丁成功应用就宣布“完成”。 补丁可能应用到错误位置、引入语法错误，或实际上并未解决问题。补丁应用是验证的第一步，而非终点。

流程

对于任何代码变更：

1. 读取 —— 检查将要修改的文件。了解当前状态。
2. 计划 —— 编写3-7个要点：什么变更、按什么顺序、如何验证。
3. 修改 —— 进行编辑。对于多文件工作，一次一个原子变更。
4. 语法检查 —— py_compile 或等效工具。在继续之前修复错误。
5. 重启 —— 如果运行中的服务器需要新代码。
6. 测试 —— curl、运行或检查。验证实际行为与意图匹配。
7. 报告 —— 说明变更了什么、测试显示了什么、以及是否已验证。

对于调试：

1. 重现 —— 获取实际错误输出。逐字复制。
2. 定位 —— 在代码中找到错误起源的位置。使用 grep、read_file、堆栈跟踪。
3. 理解 —— 完整阅读失败的代码。不要猜测它的作用——要读取它。
4. 假设 —— 哪个具体的变更可以修复这个特定的错误？
5. 修复 —— 进行最小化的更改，解决根因。
6. 验证 —— 重新运行失败的测试。确认错误已消失，并且没有破坏其他任何内容。
7. 如果仍然失败 —— 回到步骤1。错误可能已改变。重新读取它。

对于多步骤任务：

• 一次执行一步。在进入下一步之前验证每一步。
• 如果步骤3依赖于步骤2的正确性，首先验证步骤2。
• 不要批量处理未经验证的更改——如果步骤2错了，步骤3的“修复”也会错。

陷阱

• 反复读取相同的几行而不采取行动。 如果你已经读取一个函数3次却还没有编辑它，你陷入了僵局。要么进行更改，要么说明是什么在阻碍你。
• 猜测文件内容。 始终读取文件。经过多次补丁后，对“曾经有什么”的记忆不可靠。
• 跳过语法检查。 补丁可以干净地应用但仍然破坏语法。始终验证。
• 不重启就测试。 如果 app.py 已更改，运行中的服务器有旧代码。在测试之前重启。
• 在补丁成功时宣布完成。 “补丁已应用” ≠ “任务完成。”验证行为。
• 不读取错误消息。 错误文本告诉你什么失败了。阅读它。不要仅从错误类型推断。
• 过度打补丁。 应用修复特定问题的最小化更改。当一行错误时，不要重写整个函数。

验证检查清单

在报告编码任务完成之前，确认每一项：

• 修改前已读取文件（了解当前状态）
• 已编写计划（什么变更、按什么顺序）
• 语法检查通过（py_compile 或等效工具）
• 如果 app.py 更改，已重启服务器
• 已执行测试（curl、运行或检查）——已看到实际输出
• 输出与预期行为匹配
• 未引入新错误

本技能如何与其他技能交互

• 这是基线技能——适用于所有编码工作，无论哪个其他技能处于活动状态
• 当 test-driven-development 处于活动状态时，TDD是测试方法；本技能管理整体纪律
• 当 systematic-debugging 处于活动状态时，调试有自己详细的流程；本技能的规则6仍然适用
• 当 spike 处于活动状态时（一次性实验），“修改前检查”和“修改后验证”规则仍然适用——快速原型可以混乱但不能粗心
• 当 human-first-ui 或 webmxerz 处于活动状态进行设计工作时，本技能管理实现设计的代码变更——设计技能告知构建什么，本技能管理如何安全地构建它
• 技能通过 skill_view(name) 按需加载——它们不是持续活动的后台进程。一个技能仅在其加载的会话轮次中生效。设计辅助技能（webmxerz, human-first-ui）在特定UI任务时被咨询；本技能仍然是实现设计的代码工作的基线。