fable-native-code

Fable Native Code

你的差异应当像是由这份文件的长期维护者编写的。文件有自己的风格——命名、错误处理、注释密度和格式。请遵循这种风格。你个人的偏好并不代表改进，只是个人风格。

目的

遵循代码库的惯例，并抑制与项目风格不符的 AI 模式。消除防御性冗余、过多注释、不必要的 try/catch 块、未经请求的日志，以及对编码风格的对话式辩解。

适用场景

• 在现有仓库中编写或编辑代码时。
• 在文件本身没有文档字符串、注释、类型注解或验证逻辑时，准备添加这些内容之前。
• 选择命名约定、错误处理模式或导入结构时。
• 完成差异后、最终提交前进行检查时。

不适用场景

• 从零开始搭建全新项目，且没有既定惯例时（使用 fable-architecture 或 fable-execute）。
• 重构架构边界或解耦模块时（使用 fable-simplify）。
• 性能基准测试和算法优化时（使用 fable-review）。

输入

• source_diff：拟议的代码修改。
• target_file：现有源文件、其周边惯例及相邻模块。

预期输出

• idiomatic_code：整洁、精简且符合惯例的代码编辑，与周边风格自然融合。
• clean_diff：不包含外观性改动、无谓注释和防御性包装的差异。

流程

1. 匹配文件风格：遵循命名、错误处理惯例、注释密度、格式和导入组织。如果文件 200 行里只有一条注释，那么你新增注释的可能性几乎为零。
2. 只注释不变量：注释只说明代码本身无法表达的约束——不变量、易踩坑之处，以及不采用显而易见方案的原因。绝不描述下一行要做什么，绝不叙述你的修改（例如“现在可以正确处理 X”），也绝不为审阅者辩解。
3. 抑制防御性冗余：不要给能正常运行的代码套上 try/catch；不要验证类型或调用方已经保证的不变量；不要添加没人要求的日志、配置或标志。
4. 不要叙述克制之处：想要解释自己没有添加什么（“注意：我特意没有添加文档注释，因为……”）的冲动，和添加该内容的冲动如出一辙——只是转移到了回复里。直接交付代码；除非用户询问，否则不要提及风格。
5. 干净收尾：不要留下调试打印、注释掉的代码或你新增的 TODO 碎片。
6. 沿用代码库的词汇：名称应取自代码库现有的词汇。不要为已有概念另造名称。

决策规则

对比示例：简洁的 Go 文件

任务：在一个简洁的 Go 文件中添加 clampWindow。该文件 200 行里只有一条注释，用来标记排序不变量；调用方保证 max >= 0。

外来风格（AI 习惯，不符合文件风格）：

// clampWindow clamps start and end into the valid range [0, max] and
// normalizes inverted windows. Returns (start, start) when end < start.
func clampWindow(start, end, max int) (int, int) {
    if max < 0 {
        return 0, 0 // defensive: should never happen
    }
    ...
}

本土风格（文件维护者会写出的代码）：

func clampWindow(start, end, max int) (int, int) {
    if start < 0 {
        start = 0
    }
    if end > max {
        end = max
    }
    if end < start {
        end = start
    }
    return start, end
}

• 如果周边代码使用提前返回，就使用提前返回。
• 如果周边代码让错误向上传递，就让错误向上传递；不要吞掉错误，也不要将其包装成未经请求的自定义错误。
• 除非所在接口或文件严格要求所有导出符号都带文档字符串，否则绝不添加文档字符串。

工具策略

• 编辑前先阅读相邻函数，了解文件惯例。
• 使用精确的行替换工具（replace_file_content），避免空白和缩进发生偏移。
• 不要重新格式化同一文件中未修改的行。

证据要求

• 提供准确的差异，展示改动如何自然融入文件。
• 测试套件和 linter 均通过，确认没有风格或类型违规。

失败处理

• 如果 linter 指出风格不匹配，严格遵循项目的 linter 规则。
• 如果差异中误留了不需要的注释或调试打印，在完成前立即删除。

完成标准

• 差异内容读起来应像是由仓库的主要维护者编写的。
• 不添加冗余的防御性代码、不添加未经请求的日志，也不添加刻意编写的注释。
• 代码可编译，通过现有的风格检查，并通过所有单元测试。