fable-native-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fable Native Code

Fable 原生代码

Your diff should read like the file's longtime owner wrote it. The file has a style — naming, error handling, comment density, formatting. Write in it. Your personal preferences are not improvements; they're an accent.

你的 diff 读起来应该像是这个文件的长期所有者所写。文件有其自身的风格——命名、错误处理、注释密度和格式。遵循它。你的个人偏好不是改进，而是一种口音。

Purpose

目的

Enforce codebase idioms and suppress foreign AI patterns. Eliminate defensive bloat, excessive comments, unnecessary try/catch blocks, unrequested logging, and conversational justification of coding style.

强制遵循代码库惯例，并抑制外来的 AI 模式。消除防御性冗余、过度注释、不必要的 try/catch 块、未经请求的 logging，以及在回复中以对话式方式为编码风格进行辩解。

When to Use

使用时机

When writing or editing code in an existing repository.
Before adding docstrings, comments, type annotations, or validations to a file that lacks them.
When choosing naming conventions, error-handling patterns, or import structures.
When reviewing a completed diff before finalizing the turn.

在现有 repository 中编写或编辑代码时。
在向缺少这些内容的文件添加 docstring、注释、类型注解或验证之前。
在选择命名约定、错误处理模式或 import 结构时。
在最终完成本轮工作前审查已完成的 diff 时。

When NOT to Use

不应使用的场景

When bootstrapping a brand new project from scratch with no established idioms (use
```
fable-architecture
```
or
```
fable-execute
```
).
Refactoring architectural boundaries or decoupling modules (use
```
fable-simplify
```
).
Performance benchmarking and algorithmic optimization (use
```
fable-review
```
).

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

Inputs

输入

```
source_diff
```
: The proposed code modification.
```
target_file
```
: The existing source file, its surrounding conventions, and neighboring modules.

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

Expected Outputs

预期输出

```
idiomatic_code
```
: Clean, minimal, idiom-matched code edits that blend seamlessly with surrounding style.
```
clean_diff
```
: A diff free of cosmetic churn, gratuitous comments, and defensive wrapping.

```
idiomatic_code
```
：干净、简洁、符合惯例并与周边风格无缝融合的代码修改。
```
clean_diff
```
：不含表面性改动、无谓注释和防御性包装的 diff。

Procedure

操作步骤

Match the File: Follow naming, error-handling idiom, comment density, formatting, and import organization. If the file has one comment per 200 lines, your addition almost certainly has zero.
Comment Invariants Only: Comments state only constraints the code cannot show — invariants, gotchas, why-not-the-obvious-way. Never what the next line does, never narration of your change ("now correctly handles X"), never justification aimed at a reviewer.
Suppress Defensive Bloat: No try/catch around code that works, no validating invariants the types or callers already guarantee, no logging, config, or flags nobody asked for.
Don't Narrate Restraint: The urge to explain what you didn't add ("note: I deliberately left out the doc comment because…") is the same urge that adds it — displaced into the reply. Deliver the code; mention style only if the user asks.
Clean Exit: No debug prints, no commented-out code, no TODO crumbs you created.
Codebase Vocabulary: Names come from the codebase's existing vocabulary. Don't coin a second name for an existing concept.

匹配文件风格：遵循命名、错误处理惯例、注释密度、格式和 import 组织方式。如果该文件每 200 行才有一条注释，那么你的新增内容几乎肯定不应包含注释。
仅注释不变量：注释只能说明代码本身无法体现的限制——不变量、易错点，以及为何不采用显而易见的做法。绝不复述下一行所做的事，绝不叙述你的修改（“现在能正确处理 X”），也绝不为 reviewer 进行辩解。
抑制防御性冗余：不要给本可正常工作的代码添加 try/catch；不要验证类型或调用方已经保证的不变量；不要添加无人要求的 logging、config 或 flag。
不要为克制作解释：想解释你没有添加什么（“注意：我故意省略了 docstring，因为……”）的冲动，与想添加它的冲动是一回事，只不过被转移到了回复中。直接交付代码；只有用户询问时才提及风格。
干净收尾：不得留下 debug print、被注释掉的代码，或由你引入的 TODO 痕迹。
代码库词汇：名称应来自代码库现有词汇。不要为已有概念另造一个名称。

Decision Rules

决策规则

Contrast Example: Terse Go File

对比示例：简洁的 Go 文件

Task: add

clampWindow

to a terse Go file whose only comment in 200 lines marks a sorting invariant; callers guarantee

max >= 0

Foreign (AI habits, not the file's):

// 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
    }
    ...
}

Native (what the file's owner would write):

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
}

If surrounding code uses early returns, use early returns.
If surrounding code lets errors bubble up, bubble them up; do not swallow or wrap them in unrequested custom errors.
Never add a docstring unless the enclosing interface or file strictly enforces docstrings on all exported symbols.

任务：向一个简洁的 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
}

如果周边代码使用提前返回，就使用提前返回。
如果周边代码让错误向上冒泡，就让错误向上冒泡；不要吞掉错误，也不要用未经请求的自定义错误进行包装。
除非外围接口或文件严格要求所有导出符号都包含 docstring，否则绝不添加 docstring。

Tool Policy

工具策略

Read neighboring functions before editing to absorb file conventions.
Use precise line replacement tools (
```
replace_file_content
```
) to prevent whitespace and indentation drift.
Do not reformat untouched lines in the same file.

编辑前阅读相邻函数，以吸收文件约定。
使用精确的行替换工具（
```
replace_file_content
```
），防止空格和缩进发生偏移。
不要重新格式化同一文件中未改动的行。

Evidence Requirements

证据要求

Provide the exact diff showing changes integrate natively with the file.
Passing test suite and linter confirming zero stylistic or typing violations.

提供确切的 diff，显示修改如何与文件原生融合。
提供通过的测试套件和 linter 结果，确认不存在风格或类型违规。

Failure Handling

失败处理

If linter flags a style mismatch, conform strictly to the project's linter rules.
If an unneeded comment or debug print slipped into the diff, remove it immediately before completing the turn.

如果 linter 标记出风格不匹配，严格遵循项目的 linter 规则。
如果 diff 中混入了不必要的注释或 debug print，请在完成本轮工作前立即移除。

Completion Criteria

完成标准

Diff reads as if authored by the repository's primary maintainer.
Zero defensive bloat, zero unrequested logging, zero artificial comments.
Code compiles, passes existing style checks, and passes all unit tests.

Diff 读起来就像由该 repository 的主要维护者编写。
零防御性冗余、零未经请求的 logging、零刻意添加的注释。
代码能够编译，通过现有风格检查和所有单元测试。