rules-refresh

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rules Refresh

规则更新

Audit a rules document and propose a tighter version. Writes only after a single explicit confirmation.

审核规则文档并提出更严谨的版本。仅在获得一次明确确认后才会写入内容。

Input

输入

Optional path argument (e.g.,

plugins/react/skills/react-review/SKILL.md

CLAUDE.md

docs/conventions/frontend.md

Optional
```
--interactive
```
flag: run the guided per-rule session (see Interactive Mode) instead of the batch audit.
If omitted: scan the repo for candidate files (any
```
SKILL.md
```
,
```
CLAUDE.md
```
,
```
AGENTS.md
```
,
```
docs/conventions/*.md
```
,
```
docs/contracts/*.md
```
) and ask the operator which one to refresh.

可选路径参数（例如：

plugins/react/skills/react-review/SKILL.md

、

CLAUDE.md

、

docs/conventions/frontend.md

）。

可选
```
--interactive
```
标志：运行引导式逐条规则会话（参见交互式模式），而非批量审核。
若省略参数：扫描仓库以查找候选文件（所有
```
SKILL.md
```
、
```
CLAUDE.md
```
、
```
AGENTS.md
```
、
```
docs/conventions/*.md
```
、
```
docs/contracts/*.md
```
），并询问操作者要更新哪一个。

Steps (batch — default)

步骤（批量模式——默认）

Read the target file in full. Preserve frontmatter boundaries, section headings, and non-rule content — they will not be rewritten.

Classify each rule into exactly one of five buckets:

Bucket	Signal	Action
Keep	Rule is valuable, actionable, non-obvious.	Leave unchanged.
Sharpen	Valuable but vague or un-checkable ("write clean code").	Propose a version with explicit, checkable criteria.
Add rationale	Concrete rule, missing the why.	Propose adding a one-line `Why: <reason>` so edge cases can be reasoned about.
Redundant	Claude handles this natively today (naming, formatting, trivial hygiene).	Propose removal with a one-line reason.
Stale	References deprecated APIs, old model behavior, abandoned patterns.	Propose replacement or removal.

Classification heuristics:

Redundant signal: would I do this without being told? If yes → redundant.
Sharpen signal: rule interpretable two ways, or no checkable criterion. Turn "Keep functions small" into "Flag functions > 40 lines or > 3 nesting levels".
Rationale signal: a hidden constraint, past incident, or non-obvious trade-off. If removing the rule would make a junior engineer's code subtly wrong → add rationale.
Stale signal: mentions
```
React.FC
```
as recommended,
```
useMemo
```
everywhere, old lifecycle methods, old Claude version behaviors.
When unsure between Redundant and Sharpen, prefer Sharpen. Do not delete rules whose rationale you can't reconstruct.

Diff against the baseline. When the target is a project rules doc (
```
CLAUDE.md
```
,
```
AGENTS.md
```
,
```
docs/conventions/*.md
```
— not a
```
SKILL.md
```
), read
```
references/rules-baseline.md
```
and list baseline rules with no equivalent in the target as Missing proposals. Skip any rule the project has documented a tradeoff against. Missing proposals come from the baseline verbatim or sharpened for the repo's stack, never free-form.
Emit a single audit report with all buckets visible. Format below.
Ask once: "Apply all proposed changes? [y/n]". Never apply without explicit yes. Never apply partial subsets — the audit is all-or-nothing from the operator's perspective. If they want partial, they decline and rerun on a narrower scope.
On yes: rewrite the target file in place. Preserve frontmatter, headings, and non-rule prose. Commit is NOT automatic — the operator commits after manual verification.

完整读取目标文件。保留前置元数据边界、章节标题和非规则内容——这些内容不会被重写。

将每条规则分类到以下五个类别中的恰好一个：

类别	特征	操作
保留	规则有价值、可执行、非显而易见。	保持不变。
优化	规则有价值但模糊或无法验证（例如“编写整洁的代码”）。	提出一个具备明确、可验证标准的版本。
补充理由	规则具体，但缺少“原因”说明。	建议添加一行 `Why: <原因>` ，以便能对边缘情况进行推理。
冗余	Claude当前可原生处理该规则（命名、格式、基础规范）。	建议移除并附上一行理由。
过时	引用已弃用的API、旧模型行为、已废弃的模式。	建议替换或移除。

分类启发式规则：

冗余特征：*无需告知我就会这么做吗？*如果是→冗余。
优化特征：规则有两种解读方式，或无可验证标准。将“保持函数简短”改为“标记行数>40或嵌套层级>3的函数”。
补充理由特征：存在隐藏约束、过往事件或非显而易见的权衡。如果移除该规则会导致初级工程师的代码出现细微错误→补充理由。
过时特征：提及
```
React.FC
```
为推荐用法、到处使用
```
useMemo
```
、旧生命周期方法、旧Claude版本行为。
若在冗余和优化之间不确定，优先选择优化。不要删除无法重构其理由的规则。

与基线对比。当目标文件是项目规则文档（
```
CLAUDE.md
```
、
```
AGENTS.md
```
、
```
docs/conventions/*.md
```
——而非
```
SKILL.md
```
）时，读取
```
references/rules-baseline.md
```
，并将目标文件中无等效内容的基线规则列为缺失建议。跳过项目已记录权衡的规则。缺失建议直接来自基线，或针对仓库技术栈进行优化，绝不随意生成。
生成一份审核报告，展示所有类别内容。格式如下。
询问一次：“是否应用所有提议的更改？[是/否]”。未经明确同意绝不能应用。绝不能应用部分子集——从操作者角度看，审核是全有或全无的。如果他们想要部分更改，应拒绝并在更窄范围内重新运行。
若同意：原地重写目标文件。保留前置元数据、标题和非规则文本。不会自动提交——操作者需手动验证后再提交。

Interactive Mode (

--interactive

)

交互式模式（

--interactive

）

Guided per-rule session over a project rules doc. Batch stays the default; this mode replaces its all-or-nothing confirmation with one decision per rule.

State of play. Resolve the target doc (path argument, else
```
.turkit.yaml → rules.docs
```
, else the Input scan). Summarize in ≤5 lines: docs found, rule count, baseline coverage by section (e.g. "6/10 sections covered; missing: Simplification, Types, Boundaries, Error Handling").

Menu. Offer the applicable paths, omitting empty ones:

text

1. Add missing baseline rules (<n> sections)
2. Sharpen existing rules (<n> candidates)
3. Add a project rule (operator describes, skill formulates)
4. Record a documented tradeoff (reviews stop flagging it)
5. Prune (<n> redundant/stale candidates)

Use the platform's structured-question UI when available; plain text otherwise. When a path completes, return to the menu until the operator stops.

Per-rule loop. For each item on the chosen path, show one concrete proposal, then ask: accept / rephrase / skip.
- accept → apply immediately to the doc (unstaged), move on.
- rephrase → the operator adjusts or dictates; reformulate as one checkable line plus
```
Why:
```
  , confirm once more, apply.
- skip → record it; never re-propose in this session.
Proposal sources — these three, nothing else:
- Baseline — Missing rules from
```
references/rules-baseline.md
```
  , section by section.
- Repo evidence — a dominant convention not yet written down, proposed only with cited evidence (files and occurrence counts, e.g. "14 files import via
```
@/lib
```
  , 2 use deep relative paths → alias rule?"). Never propose from impression alone.
- Operator free-form — the operator asks for a rule; formulate it as one checkable line plus
```
Why:
```
  . Explicit operator request replaces the baseline requirement.
Session recap. Added / sharpened / tradeoffs recorded / pruned / skipped, then the manual-commit reminder.

Tradeoffs (path 4) land where the target doc keeps them — a

Tradeoffs

section, or an inline

Why:

on the overridden rule. Reviews suppress documented tradeoffs, so recording one here is the legitimate way to silence a recurring finding.

针对项目规则文档的引导式逐条规则会话。批量模式为默认；此模式将其全有或全无的确认方式替换为逐条规则决策。

当前状态。确定目标文档（路径参数，否则为
```
.turkit.yaml → rules.docs
```
，否则为输入扫描结果）。用≤5行总结：找到的文档、规则数量、各章节的基线覆盖情况（例如“6/10个章节已覆盖；缺失：简化、类型、边界、错误处理”）。

菜单。提供适用选项，省略空选项：

text

1. 添加缺失的基线规则（<n>个章节）
2. 优化现有规则（<n>个候选）
3. 添加项目规则（操作者描述，由skill制定）
4. 记录已记录的权衡（审核将不再标记）
5. 清理（<n>个冗余/过时候选）

若平台支持结构化问题UI则使用；否则使用纯文本。完成一个选项后返回菜单，直到操作者停止。

逐条规则循环。对于所选选项中的每个条目，展示一个具体提议，然后询问：接受/改写/跳过。
- 接受 → 立即应用到文档（未暂存），继续下一个。
- 改写 → 操作者调整或口述；重新制定为一行可验证的内容加
```
Why:
```
  ，再次确认后应用。
- 跳过 → 记录该条目；本次会话中不再提议。
提议来源——仅限以下三种，无其他：
- 基线 — 来自
```
references/rules-baseline.md
```
  的缺失规则，按章节划分。
- 仓库证据 — 尚未成文的主流规范，仅在提供引用证据（文件和出现次数，例如“14个文件通过
```
@/lib
```
  导入，2个使用深层相对路径→是否添加别名规则？”）时提出。绝不能仅凭印象提出建议。
- 操作者自定义 — 操作者要求添加规则；将其制定为一行可验证的内容加
```
Why:
```
  。明确的操作者请求可替代基线要求。
会话总结。添加/优化/记录的权衡/清理/跳过的规则数量，然后提醒手动提交。

权衡内容（选项4）会放在目标文档对应的位置——

Tradeoffs

章节，或被覆盖规则的内联

Why:

中。审核会忽略已记录的权衡，因此在此处记录是合理消除重复提示的方式。

Audit report format

审核报告格式

Rules refresh — <path>
<N> rules total: Keep=<k> Sharpen=<s> Add-rationale=<a> Redundant=<r> Stale=<st> Missing=<m>

KEEP
- <rule snippet>
- ...

SHARPEN
- Before: <vague rule>
  After:  <sharpened rule>
  Why: <one-line rationale for the change>

ADD RATIONALE
- Rule: <rule snippet>
  Proposed addition: "Why: <reason>"

REDUNDANT
- Rule: <rule snippet>
  Reason: <why Claude handles this natively now>

STALE
- Rule: <rule snippet>
  Problem: <what changed>
  Proposed replacement: <new rule> | REMOVE

MISSING (from rules-baseline.md — project rules docs only)
- Baseline rule: <rule>
  Proposed addition: <verbatim or sharpened for this repo>

Apply

references/output-preferences.md

for operator-facing language/style.

Rules refresh — <path>
<N> rules total: Keep=<k> Sharpen=<s> Add-rationale=<a> Redundant=<r> Stale=<st> Missing=<m>

KEEP
- <rule snippet>
- ...

SHARPEN
- Before: <vague rule>
  After:  <sharpened rule>
  Why: <one-line rationale for the change>

ADD RATIONALE
- Rule: <rule snippet>
  Proposed addition: "Why: <reason>"

REDUNDANT
- Rule: <rule snippet>
  Reason: <why Claude handles this natively now>

STALE
- Rule: <rule snippet>
  Problem: <what changed>
  Proposed replacement: <new rule> | REMOVE

MISSING (from rules-baseline.md — project rules docs only)
- Baseline rule: <rule>
  Proposed addition: <verbatim or sharpened for this repo>

面向操作者的语言/风格请遵循

references/output-preferences.md

。

Guardrails

防护规则

Read-only until confirmation. Never write before the operator says yes.
Self-audit footgun. If the operator points
```
rules-refresh
```
at its own
```
SKILL.md
```
(the file you are reading now), refuse and ask for an explicit confirmation naming the file. Auditing the auditor risks breaking the audit logic.
No partial apply (batch mode). All or nothing; a subset means decline and rerun. In
```
--interactive
```
, consent is per rule — partial is the design.
Commit discipline. Do not commit the rewrite. Leave it for the operator to verify and commit via
```
/turkit:ship
```
or manually.
Never invent rules. Every proposal traces to the input file,
```
references/rules-baseline.md
```
, cited repo evidence, or an explicit operator request (interactive mode). No silent free-form rules.
Interactive writes are per-confirmation. Nothing lands before its own accept; a skip is final for the session.

确认前只读。在操作者同意前绝不能写入内容。
自我审核风险。如果操作者将
```
rules-refresh
```
指向其自身的
```
SKILL.md
```
（即您正在阅读的文件），请拒绝并要求明确确认该文件名。审核审核工具可能会破坏审核逻辑。
批量模式下不支持部分应用。全有或全无；若要部分更改，需拒绝并重新运行。在
```
--interactive
```
模式下，同意是逐条规则的——部分应用是设计的一部分。
提交规范。不要提交重写内容。留给操作者验证后通过
```
/turkit:ship
```
或手动提交。
绝不凭空创建规则。每个提议都必须追溯到输入文件、
```
references/rules-baseline.md
```
、引用的仓库证据，或明确的操作者请求（交互式模式）。禁止随意创建规则。
交互式写入需逐条确认。在获得接受前不会写入任何内容；跳过的条目在本次会话中不再处理。

rules-refresh

Original

Translation

Rules Refresh

规则更新

Input

输入

Steps (batch — default)

步骤（批量模式——默认）

Interactive Mode (
`--interactive`
)

交互式模式（
`--interactive`
）

Audit report format

审核报告格式

Guardrails

防护规则

rules-refresh

Original

Translation

Rules Refresh

规则更新

Input

输入

Steps (batch — default)

步骤（批量模式——默认）

Interactive Mode (--interactive)

交互式模式（--interactive）

Audit report format

审核报告格式

Guardrails

防护规则

Interactive Mode (
`--interactive`
)

交互式模式（
`--interactive`
）