principles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex

$principles

. Claude Code, Cursor, and Antigravity

/principles

Codex

$principles

. Claude Code、Cursor 和 Antigravity

/principles

Principles

原则

Read the matching file under

references/

in full before you apply a principle. Cite only files you read this session.

应用某项原则前，应完整阅读

references/

下对应的文件。仅引用本次会话中读过的文件。

Index

索引

Attack the Premise (
```
principle-attack-the-premise
```
). Apply when two or more fixes that share one premise have failed the same gate. Take a census of which actors hold the imbalance before the next fix, then question the premise instead of writing another fix that assumes it.
Boundary Discipline (
```
principle-boundary-discipline
```
). Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions.
Build the Lever (
```
principle-build-the-lever
```
). Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun.
Encode Lessons in Structure (
```
principle-encode-lessons-in-structure
```
). Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text.
Exhaust the Design Space (
```
principle-exhaust-the-design-space
```
). Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare side by side before committing.
Experience First (
```
principle-experience-first
```
). Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over more rough ones.
Fix Root Causes (
```
principle-fix-root-causes
```
). Apply when debugging. Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes.
Foundational Thinking (
```
principle-foundational-thinking
```
). Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious.
Guard the Context Window (
```
principle-guard-the-context-window
```
). Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads.
Laziness Protocol (
```
principle-laziness-protocol
```
). Apply when refactoring, evaluating diff size, tempted to add abstractions, layers, or signal threading, or reaching for a new helper or dependency. Bias toward deletion, reuse, and the smallest change that solves the problem.
Make Operations Idempotent (
```
principle-make-operations-idempotent
```
). Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs.
Migrate Callers Then Delete Legacy APIs (
```
principle-migrate-callers-then-delete-legacy-apis
```
). Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserving compatibility layers.
Minimize Reader Load (
```
principle-minimize-reader-load
```
). Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope.
Model the Domain (
```
principle-model-the-domain
```
). Apply when writing stateful logic, or when code branches a lot or repeats a shape assumption across files. Encode the domain in a structure instead of scattered conditionals.
Never Block on the Human (
```
principle-never-block-on-the-human
```
). Apply when tempted to ask 'should I do X?' on reversible work. Proceed, present the result, let the human course-correct after the fact; reserve confirmation for irreversible actions.
Outcome-Oriented Execution (
```
principle-outcome-oriented-execution
```
). Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code.
Prove It Works (
```
principle-prove-it-works
```
). Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'
Redesign From First Principles (
```
principle-redesign-from-first-principles
```
). Apply when integrating a new requirement into an existing design. Redesign as if the requirement had been a foundational assumption from day one, instead of bolting it on.
Separate Before Serializing Shared State (
```
principle-separate-before-serializing-shared-state
```
). Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant.
Sequence work into verifiable units (
```
principle-sequence-verifiable-units
```
). Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer.
Subtract Before You Add (
```
principle-subtract-before-you-add
```
). Apply when sequencing an addition, refactor, or rewrite. Remove dead code, redundant validators, and stub references first, then build on the simpler base.
Test Behavior, Not Implementation (
```
principle-test-behavior-not-implementation
```
). Apply when you write, change, or keep a test. Call the code the way its users do and assert the result they observe against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite the assertion or delete the test.
Type System Discipline (
```
principle-type-system-discipline
```
). Apply when designing types, reviewing a function signature, or writing code in any statically-typed language. Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, refuse to lie to the compiler, exhaust variants, derive from authoritative schemas.

质疑前提 (
```
principle-attack-the-premise
```
). 当两个或更多基于同一前提的修复都未通过同一项检查时适用。在下一次修复前，先梳理哪些参与者导致了这种失衡，然后质疑该前提，而不是继续编写一个沿用该前提的修复方案。
边界纪律 (
```
principle-boundary-discipline
```
). 在接入 validation、error handling 或 framework adapter 时适用。将 guards 集中在系统边界（CLI、config、network、external APIs）；信任 internal types，并将 business logic 保持在 pure functions 中。
构建杠杆 (
```
principle-build-the-lever
```
). 适用于任何非简单工作，不仅是批量工作：edits、migrations、analyses、checks。构建能够完成或证明这项工作的工具（codemod、script、generator，或供 subagents 遵循的 skill），而不是手工处理。该工具就是 reviewer 能够重新运行的 artifact。
将经验固化到结构中 (
```
principle-encode-lessons-in-structure
```
). 当你发现自己第二次编写同一条指令，或发现某项修正反复出现时适用。将规则编码为 lint、metadata flag、runtime check 或 script，而不是继续增加文字。
穷尽设计空间 (
```
principle-exhaust-the-design-space
```
). 当遇到 codebase 中没有先例的全新 UI interaction 或 architecture decision 时适用。构建 2–3 个互相竞争的 prototype，并在确定方案前进行并排比较。
体验优先 (
```
principle-experience-first
```
). 当出现 product、UX 或 feature scope 的 trade-off 时适用。优先考虑用户愉悦，而不是实现便利；宁可少交付一些打磨完善的功能，也不要交付更多粗糙的功能。
修复根因 (
```
principle-fix-root-causes
```
). 调试时适用。将每个 symptom 追溯到 root cause 并在那里修复；先复现问题，持续追问原因直至找到根因，不要用只会掩盖 crash 的 nil-check guard。
奠基式思考 (
```
principle-foundational-thinking
```
). 编写 logic 前适用：选择 core types 和 data structures、安排 scaffold 与 feature 的工作顺序，以及确认 concurrent actors 共享什么。把 data structures 设计正确，使 downstream code 变得显而易见。
守护上下文窗口 (
```
principle-guard-the-context-window
```
). 当 context 即将被填满时适用，例如出现 large output、long file、repeated read 或 fan-out planning。将 bulk work 路由给 subagents；main thread 中只保留 summary，而不是 raw payload。
惰性协议 (
```
principle-laziness-protocol
```
). 在 refactoring、评估 diff size、想要新增 abstraction、layer 或 signal threading，或准备引入新的 helper 或 dependency 时适用。优先删除和复用，并采用能解决问题的最小改动。
让操作具备幂等性 (
```
principle-make-operations-idempotent
```
). 设计会在 crash、restart 和 retry 期间运行的 command、lifecycle step 或 processing loop 时适用。无论之前部分执行到何种状态，都应收敛到相同的 end state。
先迁移调用方，再删除旧 API (
```
principle-migrate-callers-then-delete-legacy-apis
```
). 引入新的 internal API，但仍有旧 caller 存在时适用。在同一批次中迁移 caller 并删除旧 API，而不是保留 compatibility layer。
降低读者认知负担 (
```
principle-minimize-reader-load
```
). 审查或塑造难以追踪的代码时适用。统计问题与答案之间的 layer，以及读者脑中的 hidden state；消除仅有一个 caller 的 wrapper，并缩小 mutable scope。
对领域建模 (
```
principle-model-the-domain
```
). 编写 stateful logic，或 code 中存在大量 branch、多个文件重复同一 shape assumption 时适用。通过结构对 domain 建模，而不是把逻辑散落在各处 conditional 中。
不阻塞等待人工 (
```
principle-never-block-on-the-human
```
). 面对 reversible work，想问“我应该做 X 吗？”时适用。继续执行并展示结果，让 human 事后纠正方向；仅为 irreversible action 保留确认环节。
以结果为导向的执行 (
```
principle-outcome-oriented-execution
```
). 在有明确 phase boundary 的 planned rewrite 和 migration 期间适用。收敛到 target architecture；不要用 throwaway compatibility code 维持平滑的 intermediate state。
证明其可用 (
```
principle-prove-it-works
```
). 完成任务后、宣布完成前适用。针对真实 artifact 进行验证（运行 feature、读取 actual value、检查 diff），而不是依赖 proxy、self-report 或“能编译”这类替代信号。
从第一性原理重新设计 (
```
principle-redesign-from-first-principles
```
). 将新 requirement 集成到 existing design 时适用。重新设计时就假设该 requirement 从第一天起就是 foundational assumption，而不是事后生硬附加。
先分离，再串行化共享状态 (
```
principle-separate-before-serializing-shared-state
```
). 当 concurrent actors 可能写入同一个 file、branch、key 或 state object 时适用。先消除共享；只有当 single shared writer 是真正的 invariant 时，才从结构层面 serialize。
将工作拆分为可验证单元 (
```
principle-sequence-verifiable-units
```
). 适用于 multi-step work（sweeps、migrations、similar edits 的多次运行），以及安排 commits 和 PRs 的堆叠方式。将工作拆分为 small units，每个 unit 都以 verifiable state 结束；在进入下一个之前检查当前 unit，并安排 delivery 顺序，让整个 sequence 能向 reviewer 证明自身。
先减后加 (
```
principle-subtract-before-you-add
```
). 安排 addition、refactor 或 rewrite 的顺序时适用。先移除 dead code、redundant validators 和 stub references，然后在更简单的 base 上构建。
测试行为，而非实现 (
```
principle-test-behavior-not-implementation
```
). 编写、修改或保留 test 时适用。像 users 一样调用 code，并针对 literal expected value 断言他们观察到的 result。如果即使每个 imported function 都返回 undefined，test 仍然能通过，请重写 assertion 或删除该 test。
类型系统纪律 (
```
principle-type-system-discipline
```
). 设计 types、审查 function signature，或使用任何 statically-typed language 编写 code 时适用。让 illegal states 不可表示，为 semantic primitives 使用 branded types，在 boundaries 解析 external data，不向 compiler 撒谎，穷尽所有 variants，并从 authoritative schemas 派生类型。