Back to Details

strengthen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Scan spec files for 
guidance()
rules and suggest 
enforce()
replacements backed by real linter rules.
扫描规范文件中的
guidance()
规则，并建议使用由真实代码检查工具规则支持的
enforce()
替代方案。

Instructions

操作说明

Step 0: Choose Mode

步骤0：选择模式

Ask the user:
Auto or interactive?
  • Auto — I'll apply all safe changes (direct replacements where the rule is already enabled), commit, and show you the diff. Risky changes (require config edits or plugin installs) go in a summary for you to review.
  • Interactive — I'll present each suggestion and you pick which ones to apply.
Default to interactive if the user doesn't specify.
询问用户：
自动模式还是交互模式？
  • 自动模式 —— 我将应用所有安全变更（规则已启用情况下的直接替换），提交变更并展示差异。风险变更（需要修改配置或安装插件）会汇总成列表供你审核。
  • 交互模式 —— 我会逐个展示建议，由你选择要应用的内容。
若用户未指定，默认使用交互模式。

Step 1: Discover What's Installed

步骤1：检测已安装工具

Run 
npx vigiles generate-types
to get the full list of enabled linter rules in the project. Read 
.vigiles/generated.d.ts
to see every rule available across all detected linters.
Note which linter prefixes appear in the generated types (e.g., 
EslintRule
, 
RuffRule
). You'll only need reference docs for detected linters.
运行
npx vigiles generate-types
获取项目中已启用的代码检查工具规则完整列表。读取
.vigiles/generated.d.ts
文件，查看所有检测到的代码检查工具的可用规则。
记录生成类型中出现的代码检查工具前缀（例如
EslintRule
、
RuffRule
）。你只需参考已检测到的工具的文档。

Step 2: Find All Guidance Rules

步骤2：查找所有Guidance规则

Find all 
.spec.ts
files in the project (
**/*.md.spec.ts
). For each file, identify every 
guidance()
rule.
查找项目中所有
.spec.ts
文件（
**/*.md.spec.ts
）。针对每个文件，识别所有
guidance()
规则。

Step 3: Match Against Generated Types (Fast Path)

步骤3：匹配生成类型（快速路径）

For each guidance rule, check if an enabled rule in 
.vigiles/generated.d.ts
directly matches. This is the fast, deterministic path — no doc reading needed.
Look for:
  • Exact rule name in text — guidance says "no-console" and 
    no-console
    is in EslintRule
  • Semantic match — guidance says "don't use console.log" and 
    no-console
    is available
  • Rule description match — guidance says "unused variables" and 
    no-unused-vars
    or 
    @typescript-eslint/no-unused-vars
    is available
If a match is found and the rule is in the generated types (meaning it's already enabled), this is a direct replacement — no config changes needed.
针对每个guidance规则，检查
.vigiles/generated.d.ts
中是否有已启用的规则直接匹配。这是快速、确定的路径——无需查阅文档。
查找以下匹配情况：
  • 文本中的精确规则名称 —— guidance规则内容为"no-console"，且
    no-console
    存在于EslintRule中
  • 语义匹配 —— guidance规则内容为"不要使用console.log"，且
    no-console
    可用
  • 规则描述匹配 —— guidance规则内容为"未使用的变量"，且
    no-unused-vars
    或
    @typescript-eslint/no-unused-vars
    可用
如果找到匹配项且该规则存在于生成类型中（意味着已启用），则为直接替换——无需修改配置。

Step 4: Read Linter Docs (Slow Path)

步骤4：查阅代码检查工具文档（慢速路径）

For guidance rules that didn't match in Step 3, read the linter reference docs for the project's detected linters:
  • ESLint → 
    ../linter-docs/eslint.md
  • Stylelint → 
    ../linter-docs/stylelint.md
  • Ruff → 
    ../linter-docs/ruff.md
  • Pylint → 
    ../linter-docs/pylint.md
  • RuboCop → 
    ../linter-docs/rubocop.md
  • Clippy → 
    ../linter-docs/clippy.md
Only read docs for linters the project actually uses. Skip docs for linters with no rules in generated types.
Check the plugin tables and decision matrices. The guidance text may describe a pattern covered by:
  • A plugin rule that's installed but not enabled
  • A plugin that's not installed yet
  • A 
    no-restricted-*
    config pattern (see Step 4b)
对于步骤3中未匹配到的guidance规则，查阅项目已检测到的代码检查工具的参考文档：
  • ESLint → 
    ../linter-docs/eslint.md
  • Stylelint → 
    ../linter-docs/stylelint.md
  • Ruff → 
    ../linter-docs/ruff.md
  • Pylint → 
    ../linter-docs/pylint.md
  • RuboCop → 
    ../linter-docs/rubocop.md
  • Clippy → 
    ../linter-docs/clippy.md
仅查阅项目实际使用的工具文档。跳过生成类型中无规则的工具文档。
查看插件表格和决策矩阵。guidance文本描述的模式可能对应：
  • 已安装但未启用的插件规则
  • 尚未安装的插件
  • no-restricted-*
    配置模式（见步骤4b）

Step 4b: 
no-restricted-*
Patterns

步骤4b：
no-restricted-*
模式

Many guidance rules can be enforced via built-in linter config without a custom rule. This is the most common strengthen pattern — "don't do X" maps to a restriction config.
ESLint:
js
// "Don't import from internal modules"
"no-restricted-imports": ["error", {
  patterns: [{ group: ["src/internal/*"], message: "Use the public API." }]
}],

// "Don't call console.log"
"no-restricted-syntax": ["error", {
  selector: 'CallExpression[callee.object.name="console"]',
  message: "Use the project logger."
}],

// "Don't use moment.js"
"no-restricted-imports": ["error", {
  paths: [{ name: "moment", message: "Use dayjs instead." }]
}],
Ruff:
toml
undefined
许多guidance规则无需自定义规则，即可通过代码检查工具的内置配置强制执行。这是最常见的强化模式——“不要做X”对应到一个限制配置。
ESLint：
js
// "不要从内部模块导入"
"no-restricted-imports": ["error", {
  patterns: [{ group: ["src/internal/*"], message: "使用公开API。" }]
}],

// "不要调用console.log"
"no-restricted-syntax": ["error", {
  selector: 'CallExpression[callee.object.name="console"]',
  message: "使用项目日志工具。"
}],

// "不要使用moment.js"
"no-restricted-imports": ["error", {
  paths: [{ name: "moment", message: "改用dayjs。" }]
}],
Ruff：
toml
undefined

"Don't use os.system"

"不要使用os.system"

[tool.ruff.lint.flake8-tidy-imports.banned-api] "os.system".msg = "Use subprocess.run instead."

**RuboCop:**

```yaml
[tool.ruff.lint.flake8-tidy-imports.banned-api] "os.system".msg = "改用subprocess.run。"

**RuboCop：**

```yaml

"Don't use puts in production" — if Rails/Output doesn't fit

"生产环境不要使用puts" —— 如果Rails/Output不适用

Custom/NoPuts: Enabled: true

When suggesting a `no-restricted-*` change:

1. Show the exact config edit needed (which file, which section)
2. Show the `enforce()` rule that references it
3. Note that this changes linter config, not just the spec
Custom/NoPuts: Enabled: true

建议`no-restricted-*`变更时：

1. 展示所需的精确配置修改（哪个文件、哪个部分）
2. 展示引用该配置的`enforce()`规则
3. 注意这会修改代码检查工具配置，而不仅仅是规范文件

Step 5: Present Suggestions

步骤5：展示建议

Group the output into tiers:
Tier 1: Direct replacements (rule already enabled — zero risk)
typescript
// Before
"no-console": guidance("Use structured logger instead of console.log"),
// After
"no-console": enforce("eslint/no-console", "Use structured logger instead of console.log"),
Tier 2: Config-backed (rule exists but needs config options)
typescript
// Spec change:
"no-moment": enforce("eslint/no-restricted-imports", "Use dayjs instead of moment."),

// Config change needed (eslint.config.mjs):
"no-restricted-imports": ["error", {
  paths: [{ name: "moment", message: "Use dayjs instead." }]
}],
Tier 3: Plugin install needed
"cognitive-complexity": guidance("Keep functions simple")
→ Install eslint-plugin-sonarjs, enable sonarjs/cognitive-complexity
→ enforce("eslint/sonarjs/cognitive-complexity", "Keep functions simple")
Tier 4: No match (stays as guidance, or candidate for 
/pr-to-lint-rule
)
"research-first": guidance("Google unfamiliar APIs first.")
→ No linter rule can enforce this. Stays as guidance.
→ Want me to run /pr-to-lint-rule to create a custom rule?
将输出分为以下层级：
层级1：直接替换（规则已启用——零风险）
typescript
// 变更前
"no-console": guidance("使用结构化日志工具替代console.log"),
// 变更后
"no-console": enforce("eslint/no-console", "使用结构化日志工具替代console.log"),
层级2：配置支持（规则存在但需要配置选项）
typescript
// 规范文件变更：
"no-moment": enforce("eslint/no-restricted-imports", "改用dayjs替代moment。"),

// 需要修改配置（eslint.config.mjs）：
"no-restricted-imports": ["error", {
  paths: [{ name: "moment", message: "改用dayjs。" }]
}],
层级3：需要安装插件
"cognitive-complexity": guidance("保持函数简洁")
→ 安装eslint-plugin-sonarjs，启用sonarjs/cognitive-complexity
→ enforce("eslint/sonarjs/cognitive-complexity", "保持函数简洁")
层级4：无匹配项（保留为guidance，或作为
/pr-to-lint-rule
的候选）
"research-first": guidance("先搜索不熟悉的API。")
→ 没有代码检查工具规则可以强制执行此要求。保留为guidance。
→ 是否需要我运行`/pr-to-lint-rule`来创建自定义规则？

Step 6: Apply Changes

步骤6：应用变更

In auto mode:
  1. Apply all Tier 1 changes (edit spec files, replace 
    guidance()
    with 
    enforce()
    )
  2. Run 
    npm run build && npx vigiles compile
    to verify each change compiles
  3. If any compilation fails, revert that specific change and report the error
  4. Commit all successful changes
  5. Present Tier 2-4 as a summary for the user to review
In interactive mode:
  1. Present all tiers
  2. Ask the user which suggestions to apply
  3. For approved Tier 2 changes: edit the linter config, then edit the spec
  4. Run 
    npm run build && npx vigiles compile
    to verify
  5. If compilation fails, report the error and revert
For Tier 4 (no match): Ask the user if they want to run 
/pr-to-lint-rule
for any of the unmatched rules to create custom rules.
自动模式下：
  1. 应用所有层级1的变更（编辑规范文件，将
    guidance()
    替换为
    enforce()
    ）
  2. 运行
    npm run build && npx vigiles compile
    验证每个变更是否可编译
  3. 如果任何编译失败，回滚该特定变更并报告错误
  4. 提交所有成功的变更
  5. 将层级2-4的内容汇总展示给用户审核
交互模式下：
  1. 展示所有层级的建议
  2. 询问用户要应用哪些建议
  3. 对于已批准的层级2变更：先编辑代码检查工具配置，再编辑规范文件
  4. 运行
    npm run build && npx vigiles compile
    验证
  5. 如果编译失败，报告错误并回滚
**对于层级4（无匹配项）：**询问用户是否要为任何未匹配的规则运行
/pr-to-lint-rule
来创建自定义规则。