Back to Details

code-standards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Standards

代码规范

House standards for code and the artifacts around it. Apply them while writing; check them while reviewing.
Where a standard has a canonical case (the specimen that set the rule), it is stated inline or in the standard's 
references/
file: the concrete case recalls better than the rule. The 
references/
file named under each standard carries the full detail: the why, the how-to-apply list, and the boundaries and exceptions.
内部规范适用于代码及其周边产物。编写时应用它们；审查时检查它们。
当某项标准有典型案例（确立规则的样本）时，会在正文中或该标准的 
references/
文件中说明：具体案例比规则本身更容易让人记住。每项标准下所列的 
references/
文件包含完整的细节：原因、应用方法清单、边界与例外。

The Standards

标准

Fix the class, not the instance

修复类别，而非个例

A systemic problem gets a root fix that makes recurrence impossible, never only a fix of the case at hand: the 
/never-twice
skill owns this rule and its response ladder; specimen and full detail in 
references/design.md
.
系统性问题需要根治性修复，使问题无法再次发生，而不仅仅是修复眼前的情况：该规则由 
/never-twice
skill 负责，包含其响应阶梯；样本和完整细节见 
references/design.md
。

Guard recurring problems with tests

用测试守护重复出现的问题

A problem that recurs, or plausibly will, ships with a test, tripwire, or pipeline fix that catches it at the source: rung 2 of the 
/never-twice
ladder; full detail, including the guard-outside-your-reach case, in 
references/design.md
.
重复出现或可能重复出现的问题，应附带能在源头捕获它的测试、绊线或流水线修复：这是 
/never-twice
阶梯的第 2 级；完整细节（包括超出你能力范围的守护场景）见 
references/design.md
。

General-purpose over special-case

通用方案优先于特例处理

Parameterize the axis that keeps changing instead of hardcoding today's instance.
Specimen: a safety classifier whose rulebook kept changing was built as a classifier FACTORY with the rubric as an input. Any rubric change produces a new classifier for free, and the same machinery serves uses beyond safety.
Full detail, including the one-pipeline-per-concept rule (the page that grew three visibly diverging error-band renderers) and where DRY stops: 
references/design.md
.
对持续变化的维度进行参数化，而不是硬编码当前的实例。
样本：一个规则手册不断变化的安全分类器被构建为一个以评分标准为输入的分类器工厂（classifier FACTORY）。任何评分标准变更都能自动产生新的分类器，同一套机制还能服务于安全领域之外的用途。
完整细节（包括“每概念一个流水线”的规则——某个页面最终长出了三个明显分歧的错误带渲染器——以及 DRY 的边界）：
references/design.md
。

Maintainability over effort

可维护性优先于工作量

Code quality outweighs diff size and effort spent. A big refactor is always better than a fix done the wrong way: wrong-shaped fixes compound into tech debt.
  • Take the larger refactor when it is cleaner, and reduce complexity.
  • Enforce invariants in types rather than repeated checks (see the 
    /no-invalid-states
    skill).
  • Use assertions to pin invariants the type system cannot carry: one assertion at a boundary removes whole families of downstream edge-case handling.
Specimen: a documented workaround hybrid was reworked outright rather than kept. Never preserve a workaround to keep a diff small.
Full detail: 
references/design.md
.
代码质量比 diff 大小和投入的工作量更重要。大型重构永远好过用错误方式完成的修复：错误形态的修复会累积成技术债务。
  • 当更大的重构更清晰时，选择它，并降低复杂度。
  • 在类型中强制不变量，而不是反复检查（见 
    /no-invalid-states
    skill）。
  • 使用断言来固定类型系统无法承载的不变量：在边界处的一个断言可以消除整类下游边界情况处理。
样本：一个记录在案的变通混合方案被直接重构而非保留。永远不要为了保持 diff 小而保留变通方案。
完整细节：
references/design.md
。

Prefer a library over hand-rolling

优先使用库而非手写

Never hand-roll what a good library already does: the hand-rolled version is maintained for as long as the code lives, the library by its authors. A large library, or a fit that is unclear, is a question to the owner before the work; otherwise the library wins.
Specimen: an audit of one repository's CI scripts found five whose whole job existing tooling already did. A published package covered four (two schema fetchers, an events enum, generated action docs); a build followed by 
git diff --exit-code
covered the drift check.
Full detail, including what makes a library good and the one exception (a library that needs a runtime or API the repository has dropped): 
references/design.md
.
永远不要手写一个好库已经能做的事情：手写版需要在代码存续期间一直维护，库则由其作者维护。使用大型库或适配关系不明确时，应在动手前向负责人确认；否则，库胜出。
样本：对某仓库 CI 脚本的审计发现，五个脚本的全部工作已有现成工具可以完成。一个已发布的包覆盖了其中四个（两个 schema 抓取器、一个事件枚举、生成的 action 文档）；构建后跟 
git diff --exit-code
覆盖了漂移检查。
完整细节（包括什么构成好库，以及唯一例外——需要仓库已弃用的运行时或 API 的库）：
references/design.md
。

Minimum standard for tests

测试的最低标准

A floor every test clears, not a recipe for which tests to write: fuzzing, property-based, integration, and other richer tests are welcome, and each of them still meets this bar. A test asserts a whole outcome, not one field of it. Agents drift toward many small weak tests; the fix is tests that each pin a whole outcome, which leaves fewer of them as a side effect, not a goal.
  • Every test answers "what would drift silently without this?" in its name or first line. Three answers count: an external fact the platform does not enforce for us, a cross-file consistency the source cannot express, or a regression with a named incident. "The source says so" means no test.
  • A test of a single constant, or of a variable that is itself the source of its value (a default, a key name, an argv literal, a path), restates the source and grows with it. Pin the value where it leaves the program (the bytes written to a file, the line printed, the request sent), and only when that boundary is an external contract.
  • Delete tests that only assert a shape, a type, or that something exists. If that fact matters, assert it inside a test that also checks the value.
  • When hand-written cases differ only along one input axis, replace them with one parametrized case list.
  • Prove each guard test: show it failing on the bug it guards, and for that reason. Reintroducing the bug is the standard form; a pre-fix red run is the same control. Run that test file alone, not the suite.
  • Red-then-green is for behavior changes, a fix made by deleting code included. A deletion with no behavior of its own (an unused setting, a dead path) proves itself with a census (grep counts before and after) in the PR body, or in the landing report with no PR, never with a test manufactured so that something goes red.
  • Fixtures are hand-authored, never recorded from real data: a file measured or copied from the author's real environment identifies the author with no name in it. A tool that measures real data requires an explicit output path outside the repository and refuses one inside it.
Specimen: an extractor had fifteen tests each asserting one key of the returned dict. Folded into one parametrized test pinning the whole dict per scenario, the file went from 81 test functions to 44 while every one of the seven bugs the suite existed to catch still failed when reintroduced. A test that ignores a column cannot catch a regression in it.
Specimen: builders on a workflows repository shipped shape tests that restated the yaml they had just read (a census that no workflow sets 
cancel-in-progress: false
, a pin that a job's 
needs
equals the list in the file), eleven PRs of them in one day. Such a test changes in the same commit as the source, so nothing can drift under it: delete it.
Specimen: a test audit found 
expect(DEFAULT_HOME).toBe("~/.local/share/app")
. Deleted; its replacement runs the installer with no home override and reads back the file it wrote under that path, because the path is where the value reaches the user's disk.
Specimen: a statistical profile measured from its author's real sessions sat committed as a test fixture with a comment saying so. Replaced by a hand-written fixture; every figure of the old file was grepped out of the replacing PR, and the history was rewritten to drop the original.
Full detail: 
references/tests.md
.
这是每项测试都要达到的下限，而非该写哪些测试的配方：模糊测试、基于属性的测试、集成测试以及其他更丰富的测试都欢迎，而且它们每一项仍然要达到这个标准。一项测试应断言完整的结果，而非其中的单个字段。Agent 往往趋向于大量弱小的测试；解决方法是让每项测试都固定一个完整的结果，测试数量变少只是副作用，而非目标。
  • 每项测试都要在名称或首行回答“没有这个，什么会悄悄漂移？”。三种答案算数：平台不会为我们强制的外部事实、源码无法表达的跨文件一致性、或有名称事件关联的回归。“源码就是这样说的”意味着不需要测试。
  • 对单个常量、或对本身就是其值来源的变量（默认值、键名、argv 字面量、路径）的测试，只是在复述源码并随它一起膨胀。应在值离开程序的地方（写入文件的字节、打印的行、发送的请求）固定该值，且仅当该边界是外部契约时才这样做。
  • 删除只断言形状、类型或某物存在的测试。如果该事实很重要，请在同时检查值的测试中断言它。
  • 当手写用例仅在一个输入维度上有差异时，用一个参数化用例列表替换它们。
  • 证明每个守护测试：展示它在所守护的 bug 上失败，并且是因该原因失败。重新引入 bug 是标准形式；修复前的红跑是同样的对照组。单独运行该测试文件，而不是整个测试套件。
  • 红绿流程适用于行为变更，包括通过删除代码完成的修复。本身没有行为的删除（未使用的设置、死路径）通过在 PR 描述中提供普查（前后 grep 计数）来证明自己，或在没有 PR 的合入报告中证明，绝不能用在某物上人为制造红跑的测试。
  • 测试夹具是手工编写的，绝不能从真实数据录制：从作者真实环境测量或复制的文件会以无署名的方式暴露作者身份。测量真实数据的工具要求明确的输出路径位于仓库之外，并拒绝仓库内的路径。
样本：一个提取器有十五个测试，每个断言返回字典的一个键。合并为一个按场景固定整个字典的参数化测试后，文件从 81 个测试函数减为 44 个，而套件存在的目的是捕获的七个 bug 在重新引入时仍然会失败。忽略某一列的测试无法捕获该列中的回归。
样本：一个 workflows 仓库的构建者发布了复述刚读取的 yaml 的形状测试（一个“没有 workflow 设置 
cancel-in-progress: false
”的普查、一个“job 的 
needs
等于文件中列表”的固定），一天之内发了十一个 PR。这样的测试与源码在同一个提交中变更，因此其下不会有任何东西漂移：删除它。
样本：一次测试审计发现了 
expect(DEFAULT_HOME).toBe("~/.local/share/app")
。已删除；替代方案在不覆盖 home 的情况下运行安装器，并读回它在该路径下写入的文件，因为该路径是值到达用户磁盘的地方。
样本：一个从作者真实会话中测量的统计配置文件被作为测试夹具提交，并附有说明此事的注释。已替换为手工编写的夹具；旧文件的每个数字都被从替换的 PR 中 grep 清除，历史也被重写以删除原始文件。
完整细节：
references/tests.md
。

Comments carry only what the code cannot show

注释只承载代码无法展示的内容

A comment is read by humans and agents, the human first; the code is the single source of truth.
  • Content, the kinds a comment may carry:
    • the reason a choice was made when the obvious choice was rejected
    • an invariant another file relies on; name the file
    • an external system's quirk and what breaks without the workaround
    • a consequence of changing the line that is not visible here
    • the one input that motivated a guard
  • Never a comment: what the code does, its types, its control flow, its history, the alternatives. History and alternatives go in the commit message.
  • Tell first, then show. One or two sentences say what the code cannot show; a block follows only when it shows the fact faster: an arrow flow for a sequence, aligned rows for facts that share a shape.
  • Uniform shape is the wall: a paragraph, or every fact as its own line with nothing shown. Past the two sentences, a fact is shown or cut.
  • No limits here. Length and width caps are the fleet's file-size check. Never pack prose to fit a cap; cut honestly.
  • Test, before writing or keeping one: "What does this say that the code does not?" and "Could a tired human read it in one pass?" Fail either: rewrite or delete.
Specimen, a stack of eight one-fact sentences rewritten as tell, then rows:
ts
/**
 * The ONE "entry uses this credential field" judgment; it judges the ENTRY alone, so it errs toward "uses it".
 * Wire narrowing still drops what cannot ride, so consumers gate refusals, never the send.
 *
 * Authorization-named header resolved  -> skips the OAuth exchange
 * X-API-Key-named header resolved      -> owns that carrier
 * declared header, value unknown       -> lowers no other field's judgment
 */
Full detail, the before/after specimens, and the TODO ban: 
references/comments.md
.
注释被人和 agent 阅读，人优先；代码是唯一的事实来源。
  • 内容，注释可以承载的种类：
    • 当显而易见的选择被否决时，做出该选择的原因
    • 另一个文件依赖的不变量；指明该文件
    • 外部系统的怪癖以及没有变通方案时会破坏什么
    • 更改该行在此处不可见的后果
    • 促成某守护的唯一输入
  • 绝不写成注释： 代码做了什么、它的类型、它的控制流、它的历史、备选方案。历史与备选方案应写入提交信息。
  • 先说明，再展示。 用一两句话说明代码无法展示的内容；只有当块能更快展示事实时才跟一个块：序列用箭头流向，共享形状的事实用对齐的行。
  • 统一形状是底线： 要么是一个段落，要么每个事实单独成行且不展示任何内容。超过两句话后，一个事实要么展示要么删掉。
  • 这里没有限制。 长度和宽度上限由 fleet 的文件大小检查来把关。永远不要为了凑上限而堆砌文字；诚实地删减。
  • 在编写或保留注释前测试： “它说了什么代码没有说的内容？”以及“一个疲惫的人能一次读完吗？”任一失败：重写或删除。
样本，八条单事实句子堆叠，重写为先说明再展示行：
ts
/**
 * The ONE "entry uses this credential field" judgment; it judges the ENTRY alone, so it errs toward "uses it".
 * Wire narrowing still drops what cannot ride, so consumers gate refusals, never the send.
 *
 * Authorization-named header resolved  -> skips the OAuth exchange
 * X-API-Key-named header resolved      -> owns that carrier
 * declared header, value unknown       -> lowers no other field's judgment
 */
完整细节、前后对比样本、TODO 禁令：
references/comments.md
。

No barrel files or pass-through functions

禁止桶文件（barrel file）或透传函数

Delete these and repoint the importers or callers at the defining module or real function:
  • an import-only index file
  • a "keep old importers compiling" re-export left after a move
  • a function whose whole body forwards to another function without adding anything
A wrapper earns its existence only by adding something real (a default, a conversion, error mapping, an injected dependency, a narrowed type). In Python, 
__init__.py
stays EMPTY unless absolutely necessary: re-exports there are the same barrel.
Full detail, including the migration-staging exception and what is not a barrel: 
references/structure.md
.
删除这些，并让导入方或调用方指向定义模块或真实函数：
  • 仅用于导入的 index 文件
  • 移动后留下的“让旧导入方保持编译”的再导出
  • 函数体完全转发给另一个函数且不增加任何内容的函数
包装器只有通过增加真实内容（默认值、转换、错误映射、注入的依赖、收窄的类型）才能证明自身存在的价值。在 Python 中，
__init__.py
除非绝对必要否则保持为空：那里的再导出同样是桶文件。
完整细节（包括迁移暂存例外和什么不算桶文件）：
references/structure.md
。

No planning references in code

代码中禁止规划引用

Code and comments never reference planning artifacts: work-package names, spike or phase labels, plan codenames, audit finding numbers. The next reader has the code, not the plan.
Specimen: a comment like "WP-B spike, part 2:" has no meaning outside the planning; comments describe purpose and constraints, not where the code came from.
Full detail: 
references/comments.md
.
代码和注释永远不要引用规划产物：工作包名称、spike 或阶段标签、计划代号、审计发现编号。下一位读者拥有的是代码，而不是计划。
样本：像 "WP-B spike, part 2:" 这样的注释在规划之外毫无意义；注释描述的是目的和约束，而不是代码的来历。
完整细节：
references/comments.md
。

Lean AGENTS.md

精简的 AGENTS.md

AGENTS.md (and CLAUDE.md) holds the project's guiding principles and nothing an agent can deduce elsewhere. Code is the source of truth; implementation detail lives there. README, CONTRIBUTING, and the rest of the repository's documentation are the 
/docs-discipline
skill's pages.
  • Keep: what the project is, the conventions the owner wants kept, safety constraints, the toolchain entry points, and pointers.
  • Cut: anything a specific file answers, even when essential: layout trees, the commands block (the manifest and hooks are the source), naming conventions a linter carries, checklists a test enforces, per-module behavior. A one-line pointer replaces each.
  • Shape: short bullets a human skims; no long paragraphs, no walls of text.
  • No tests pin it. A test asserting AGENTS.md text turns guidance into a fixture; delete it.
  • No review loop. A change touching only AGENTS.md or CLAUDE.md gets no codex or Copilot round and is committed with 
    git commit --no-verify
    ; the PR opens ready and its CI is the only gate.
  • Already lean: leave it alone and say so.
Specimen: a tail of 66 lines (a layout tree, a 17-item authoring checklist the smoke test enforced, release notes) became 15: one line on what the repo is, five principles, two working rules; the checklist moved to the authoring doc it was duplicating.
Full detail: 
references/artifacts.md
.
AGENTS.md（和 CLAUDE.md）只承载项目的指导原则，不承载 agent 可以从其他地方推断出的任何内容。代码是唯一的事实来源；实现细节属于代码。README、CONTRIBUTING 以及仓库的其余文档都是 
/docs-discipline
skill 的页面。
  • 保留： 项目是什么、负责人想保持的约定、安全约束、工具链入口和指针。
  • 删掉： 任何由特定文件回答的内容，即使必不可少：布局树、命令块（manifest 和 hooks 才是来源）、linter 承载的命名约定、测试强制执行的清单、逐模块行为。每项用一行指针替代。
  • 形态： 人能快速浏览的短要点；不要长段落，不要文字墙。
  • 没有测试固定它。 断言 AGENTS.md 文本的测试会把指导变成夹具；删除它。
  • 无审查循环。 只涉及 AGENTS.md 或 CLAUDE.md 的变更不需要 codex 或 Copilot 轮次，直接用 
    git commit --no-verify
    提交；PR 一打开即可用，其 CI 是唯一的门禁。
  • 已经很精简：保持原样并说明。
样本：一个 66 行的尾部（布局树、smoke 测试强制执行的 17 项编写清单、发布说明）变成了 15 行：一行说明仓库是什么，五条原则，两条工作规则；清单移到了它原本在重复的编写文档中。
完整细节：
references/artifacts.md
。

Commit messages carry content only

提交信息只承载内容

Commit and PR messages state what changed and why, following the repo's subject conventions. No AI or tool attribution lines, no hard wrapping of the body at 72 columns (a wrapped body renders as ragged mid-sentence breaks in GitHub's soft-wrapping UI), and no PII (nothing that tells a reader who the author is, how they work, or how their machine is set up; the 
/pr-and-issue-discipline
skill's rule).
Specimen of the one sanctioned attribution, human community credit in repos that take contributions: 
fix: ... (#NN, thanks @user)
in the subject, 
Co-authored-by:
trailers for humans whose code landed. Credit for people, never for tools.
Full detail, including the email-patch exception: 
references/artifacts.md
.
提交和 PR 信息说明变更内容和原因，遵循仓库的主题约定。不包含 AI 或工具署名行，正文不做 72 列硬换行（换行的正文在 GitHub 的软换行界面中会呈现为参差不齐的句中断行），不包含 PII（任何告诉读者作者是谁、他们如何工作、或他们的机器如何设置的内容；这是 
/pr-and-issue-discipline
skill 的规则）。
唯一获准的署名的样本——在接收贡献的仓库中对人类社区成员的致谢：主题中的 
fix: ... (#NN, thanks @user)
，以及为代码合入的人类贡献者添加的 
Co-authored-by:
尾注。致谢给人，永远不给工具。
完整细节（包括 email-patch 例外）：
references/artifacts.md
。

No blobs of text

禁止文字块

Anything a human skims uses scannable structure: paragraphs of 1 to 3 sentences, and when the content is enumerable, enumerate it. The shape rules and the paragraph probe live in the 
/docs-discipline
skill; PR bodies follow the 
/pr-and-issue-discipline
skill's Readability rules.
任何供人快速浏览的内容都应使用可扫描的结构：1 到 3 句的段落，当内容可枚举时使用枚举。形态规则和段落探针位于 
/docs-discipline
skill 中；PR 正文遵循 
/pr-and-issue-discipline
skill 的可读性规则。

Workflow

工作流程

  1. Writing code: apply the standards as you go; they are cheaper at write time than at review time.
  2. Reviewing: check the Review Criteria, cite the specific standard in each finding, and prefer suggesting the class fix over the instance patch.
  3. When a standard needs its boundaries (what counts, what is exempt, how far to take it), load the matching 
    references/
    file before acting on it.
  4. When a finding calls for enforcing invariants in the type system (lifecycle flags, must-call-X-before-Y ordering, fields that must appear together), apply the 
    /no-invalid-states
    skill for the refactor itself.
  5. When a standard conflicts with an explicit user or project decision, follow the decision and record which standard was consciously set aside.
  1. 编写代码：边写边应用标准；编写时应用比审查时应用成本更低。
  2. 审查：对照审查标准检查，在每个发现中引用具体标准，并优先建议类别级修复而非个案补丁。
  3. 当某项标准需要明确其边界（什么算、什么豁免、做到什么程度）时，先加载相应的 
    references/
    文件再行动。
  4. 当某个发现要求用类型系统强制不变量（生命周期标志、必须先调用 X 再调用 Y 的顺序、必须同时出现的字段）时，应用 
    /no-invalid-states
    skill 来进行重构本身。
  5. 当某项标准与明确的用户或项目决策冲突时，遵循决策并记录哪项标准被有意搁置。

Review Criteria

审查标准

  • Instance-only fixes: does the change prevent recurrence (test, type, tooling), or just patch the case at hand?
  • A recurring or recurrence-prone problem fixed again without a guard test, tripwire, or pipeline fix (or a proposal to the user when the pipeline is out of reach).
  • Tests that assert only a shape, a type, or that something exists; hand-written test functions that differ only along one input axis and should be one parametrized case list; a guard test never seen failing on the bug it guards.
  • A new test that restates the source it reads (a workflow test pinning 
    needs
    to the list in the yaml, a constant pinned to its own literal), or whose name or first line does not say what would drift silently without it.
  • A test manufactured for a deletion with no behavior of its own in place of a census in the PR body or landing report.
  • A fixture recorded from real data, a provenance comment saying so, or a tool that measures real data with a default output path or one inside the repository.
  • Special-casing: a new near-copy of existing logic where the varying axis should be a parameter.
  • Complexity added to keep a diff small: flags, nesting, or repeated checks where a cleaner refactor or a stronger type was available (the 
    /no-invalid-states
    skill covers the type-level fix).
  • Hand-rolled code whose whole job a good library already does; the finding names the library and what it covers.
  • Comments that say what the code shows: what it does, its types, its control flow, its history, the alternatives.
  • Comments a reader cannot take in one pass: uniform shape (a paragraph, or every fact as its own line with nothing shown past a two-sentence tell), several ideas in one sentence, prose packed to fit a cap.
  • Paragraph-long comments justifying workarounds (flag the underlying code, not the comment alone).
  • Barrel files, re-export shims, or pass-through functions that only forward to another function or module.
  • Planning artifacts (work packages, phases, codenames, finding numbers) referenced in code or comments.
  • AGENTS.md or CLAUDE.md carrying anything deducible from the code or another doc (layout trees, enforced checklists, module behavior), a long paragraph, or a test that pins its text.
  • Attribution lines or hard-wrapped bodies in commit messages and PR descriptions.
Triage findings against the standards above; each criterion maps to one.
  • 仅限个例的修复：变更是否防止了复发（测试、类型、工具），还是只修补了眼前的情况？
  • 重复出现或易重复出现的问题再次被修复，却没有附带守护测试、绊线或流水线修复（或当流水线超出能力范围时向用户提出的建议）。
  • 只断言形状、类型或某物存在的测试；仅在一个输入维度上不同、应合并为一个参数化用例列表的手写测试函数；从未在其守护的 bug 上看到失败的守护测试。
  • 复述其所读源码的新测试（将 
    needs
    固定为 yaml 中列表的 workflow 测试、将常量固定为其自身字面量的测试），或其名称或首行未说明没有它会悄悄漂移什么的新测试。
  • 为本身没有行为的删除而制造的测试，而不是在 PR 描述或合入报告中提供普查。
  • 从真实数据录制的夹具、说明此事的来源注释、或带有默认输出路径或仓库内路径的真实数据测量工具。
  • 特例处理：在变化的维度本应是参数的地方，新建了现有逻辑的近似副本。
  • 为保持 diff 小而增加的复杂度：在有更清晰的重构或更强类型可用时，添加标志、嵌套或重复检查（
    /no-invalid-states
    skill 涵盖类型级修复）。
  • 全部工作已被好库完成的手写代码；发现中应点名该库及其覆盖范围。
  • 评论代码已经展示的内容的注释：代码做什么、它的类型、控制流、历史、备选方案。
  • 读者无法一次读完的注释：统一形状（段落，或超过两句说明后每个事实单独成行且不展示任何内容）、一句话包含多个想法、为凑上限而堆砌的文字。
  • 为变通方案辩护的长段落注释（应标记底层代码，而非仅标记注释）。
  • 桶文件、再导出垫片、或仅转发给另一个函数或模块的透传函数。
  • 在代码或注释中引用的规划产物（工作包、阶段、代号、发现编号）。
  • AGENTS.md 或 CLAUDE.md 承载了可从代码或其他文档推断出的内容（布局树、强制执行的清单、模块行为）、长段落、或固定其文本的测试。
  • 提交信息和 PR 描述中的署名行或硬换行正文。
根据上述标准对发现进行分类；每条标准映射到一项。

References

参考

  • references/design.md
    : fix the class, general-purpose over special-case (one pipeline per concept, DRY boundaries), maintainability over effort
  • references/tests.md
    : the minimum standard for tests, what counts as weak, the drift question every test answers, proving a guard test with a negative control, the census rule for deletions, hand-authored fixtures and the output-path rule for tools that measure real data
  • references/comments.md
    : what a good comment carries, tell then show, the two-question test, the specimens, the TODO ban, planning references
  • references/structure.md
    : barrels, compatibility re-exports, escort functions, migration staging
  • references/artifacts.md
    : lean AGENTS.md, content-only commit messages and their two exceptions
  • references/design.md
    ：修复类别、通用方案优先于特例处理（每概念一个流水线、DRY 边界）、可维护性优先于工作量
  • references/tests.md
    ：测试的最低标准、什么算弱小、每项测试回答的漂移问题、用阴性对照证明守护测试、删除的普查规则、手工编写的夹具以及真实数据测量工具的输出路径规则
  • references/comments.md
    ：好注释承载什么、先说明再展示、两问测试、样本、TODO 禁令、规划引用
  • references/structure.md
    ：桶文件、兼容性再导出、护航函数、迁移暂存
  • references/artifacts.md
    ：精简的 AGENTS.md、只承载内容的提交信息及其两个例外