candid-validate-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical.md Validator

Technical.md 验证器

Analyze a Technical.md file and identify rules that may be ineffective, vague, or redundant with existing tooling.

分析Technical.md文件，识别可能无效、模糊或与现有工具重复的规则。

Workflow

工作流程

Step 1: Locate Technical.md

步骤1：定位Technical.md文件

Find the Technical.md file to validate:

If path argument provided → use that path
Check
```
./Technical.md
```
Check
```
./.candid/Technical.md
```

If no file found:

❌ No Technical.md found.

Looked in:
- ./Technical.md
- ./.candid/Technical.md

Create one with: /candid-init

找到需要验证的Technical.md文件：

若提供了路径参数 → 使用该路径
检查
```
./Technical.md
```
检查
```
./.candid/Technical.md
```

如果未找到文件：

❌ 未找到Technical.md文件。

已在以下位置查找：
- ./Technical.md
- ./.candid/Technical.md

可使用以下命令创建：/candid-init

Step 2: Detect Linter Configs

步骤2：检测Linter配置

Check for existing linter configurations:

bash

undefined

检查现有的Linter配置：

bash

undefined

JavaScript/TypeScript

ls .eslintrc* eslint.config.* .prettierrc* biome.json 2>/dev/null

Python

ls .flake8 pyproject.toml setup.cfg .ruff.toml ruff.toml 2>/dev/null

Go

ls .golangci.yml .golangci.yaml 2>/dev/null

Ruby

ls .rubocop.yml 2>/dev/null


Store detected linters for Step 4.

ls .rubocop.yml 2>/dev/null


存储检测到的Linter，用于步骤4。

Step 3: Parse Technical.md

步骤3：解析Technical.md文件

Read the Technical.md file and extract rules.

Rule detection:

Lines starting with
```
-
```
or
```
*
```
(list items)
Lines starting with numbers (numbered lists)
Lines following a
```
##
```
heading

Skip:

Code blocks (between ```)
Empty lines
Comments (HTML or markdown)
Heading lines themselves

Store each rule with:

Line number
Section heading it belongs to
Full rule text

读取Technical.md文件并提取规则。

规则检测：

以
```
-
```
或
```
*
```
开头的行（列表项）
以数字开头的行（有序列表）
位于
```
##
```
标题之后的行

跳过内容：

代码块（位于 ``` 之间）
空行
注释（HTML或Markdown格式）
标题行本身

存储每条规则的以下信息：

行号
所属的章节标题
完整规则文本

Step 4: Validate Each Rule

步骤4：验证每条规则

Check each rule against these issue categories:

针对以下问题类别检查每条规则：

4.1 Vague Language (🌫️)

4.1 模糊表述（🌫️）

Flag rules containing vague terms without specifics:

Vague Term	Why It's Vague
"clean"	Subjective, no definition
"good"	Subjective
"proper" / "appropriate"	Undefined standard
"well-designed" / "well-structured"	No criteria
"readable" / "maintainable"	Without metrics
"best practices"	Circular reference
"when necessary" / "when appropriate"	Undefined trigger
"avoid" (alone)	No guidance on alternatives
"consider"	Not a requirement

Exception: Terms are OK if followed by specific criteria:

"readable (functions under 50 lines)" ✓
"maintainable" ✗

标记包含模糊术语且无具体说明的规则：

模糊术语	模糊原因
"clean"	主观表述，无明确定义
"good"	主观表述
"proper" / "appropriate"	标准未定义
"well-designed" / "well-structured"	无判断标准
"readable" / "maintainable"	无衡量指标
"best practices"	循环引用
"when necessary" / "when appropriate"	触发条件未定义
"avoid"（单独使用）	未提供替代方案指导
"consider"	非强制性要求

例外情况： 若术语后附带具体标准，则视为有效：

"readable (functions under 50 lines)" ✓
"maintainable" ✗

4.2 Missing Thresholds (📏)

4.2 缺失阈值（📏）

Flag rules that imply quantity without numbers:

Pattern	Issue
"small functions"	How small?
"short methods"	How short?
"limit parameters"	To how many?
"minimal dependencies"	What's minimal?
"few levels of nesting"	How few?
"reasonable timeout"	What's reasonable?

Fix pattern: Add specific numbers (e.g., "functions under 50 lines")

标记隐含数量但未给出具体数字的规则：

模式	问题
"small functions"	多大才算小？
"short methods"	多短才算短？
"limit parameters"	限制到多少个？
"minimal dependencies"	什么程度才算最少？
"few levels of nesting"	多少层才算少？
"reasonable timeout"	什么时长才算合理？

修复方式： 添加具体数字（例如："functions under 50 lines"）

4.3 Linter Overlap (🔧)

4.3 与Linter重叠（🔧）

Flag rules that linters typically handle (based on Step 2):

If ESLint/Prettier detected:

Semicolon usage
Quote style (single vs double)
Indentation rules
Trailing commas
Import ordering
Unused variables
No console.log

If Flake8/Ruff detected:

Line length
Import sorting
Whitespace rules
Naming conventions (snake_case)

If any linter detected:

Formatting rules in general
Basic syntax style

标记通常由Linter处理的规则（基于步骤2的检测结果）：

若检测到ESLint/Prettier：

分号使用规范
引号风格（单引号vs双引号）
缩进规则
尾随逗号
导入排序
未使用变量
禁止console.log

若检测到Flake8/Ruff：

行长度限制
导入排序
空白字符规则
命名规范（snake_case）

若检测到任意Linter：

通用格式化规则
基础语法风格

4.4 Multiple Concerns (🎯)

4.4 多关注点混杂（🎯）

Flag rules that try to do too much:

Rules with "and" connecting unrelated concerns
Rules over 2 lines long
Rules with multiple "must" statements

Example:

❌ "Functions should be small, well-documented, and handle errors properly"
✓ Split into three rules

标记试图涵盖过多内容的规则：

使用"and"连接不相关关注点的规则
超过2行的规则
包含多个"must"语句的规则

示例：

❌ "函数应简洁、文档完善且能正确处理错误"
✓ 拆分为三条规则

4.5 Unverifiable Rules (❓)

4.5 无法验证的规则（❓）

Flag rules that can't be checked by reading code:

"Think about edge cases"
"Be consistent"
"Follow team conventions"
"Use common sense"
References to external documents without specifics

标记无法通过阅读代码进行检查的规则：

"考虑边界情况"
"保持一致性"
"遵循团队规范"
"运用常识"
引用外部文档但未给出具体内容

Step 5: Generate Report

步骤5：生成报告

Present findings organized by severity:

markdown

undefined

按严重程度整理并呈现检测结果：

markdown

undefined

Technical.md Validation Report

Technical.md 验证报告

File: ./Technical.md Rules analyzed: [N] Issues found: [M]

文件路径： ./Technical.md 分析规则数量： [N] 发现问题数量： [M]

🔴 Critical Issues

🔴 严重问题

Rules that won't be effective in reviews.

这些规则在代码评审中无法发挥有效作用。

🌫️ Vague Language

🌫️ 模糊表述

Line	Rule	Issue
12	"Write clean code"	"clean" is subjective
24	"Use appropriate error handling"	"appropriate" undefined

行号	规则内容	问题说明
12	"编写clean代码"	"clean"属于主观表述
24	"使用appropriate错误处理"	"appropriate"未定义

📏 Missing Thresholds

📏 缺失阈值

Line	Rule	Issue
18	"Keep functions small"	No size specified
31	"Limit nesting depth"	No depth specified

行号	规则内容	问题说明
18	"保持函数small"	未指定大小标准
31	"限制嵌套深度"	未指定深度标准

🟡 Warnings

🟡 警告

Rules that may have issues.

这些规则可能存在问题。

🔧 Linter Overlap

🔧 与Linter重叠

Line	Rule	Linter
8	"Use semicolons"	ESLint handles this
15	"Sort imports alphabetically"	Prettier/ESLint handles this

行号	规则内容	对应Linter
8	"使用分号"	该规则由ESLint处理
15	"按字母顺序排序导入"	该规则由Prettier/ESLint处理

🎯 Multiple Concerns

🎯 多关注点混杂

Line	Rule	Suggestion
22	"Functions should be pure, small, and documented"	Split into 3 rules

行号	规则内容	建议方案
22	"函数应纯函数、简洁且有文档说明"	拆分为3条规则

✅ Good Rules

✅ 有效规则

[List of rules that passed validation]

undefined

[通过验证的规则列表]

undefined

Step 6: Suggest Fixes (if --fix flag)

步骤6：建议修复方案（若使用--fix参数）

--fix

argument provided, include specific rewrites:

markdown

undefined

若提供了

--fix

参数，包含具体的重写建议：

markdown

undefined

💡 Suggested Rewrites

💡 建议重写方案

Line 12: "Write clean code"

第12行："编写clean代码"

Original: Write clean code Suggested:

Functions must be under 50 lines
No single-letter variable names except loop counters
Maximum 3 levels of nesting

原规则： 编写clean代码 建议方案：

函数行数必须少于50行
除循环计数器外，禁止使用单字母变量名
嵌套层级最多为3层

Line 18: "Keep functions small"

第18行："保持函数small"

Original: Keep functions small Suggested: Functions must be under 50 lines (warning at 30)

原规则： 保持函数small 建议方案： 函数行数必须少于50行（30行时发出警告）

Line 24: "Use appropriate error handling"

第24行："使用appropriate错误处理"

Original: Use appropriate error handling Suggested:

All async functions must have try/catch or .catch()
Errors must be logged with context before re-throwing
User-facing errors must not expose stack traces

undefined

原规则： 使用appropriate错误处理 建议方案：

所有异步函数必须包含try/catch或.catch()
抛出错误前必须记录包含上下文信息的日志
面向用户的错误不得暴露堆栈跟踪

undefined

Step 7: Summary

步骤7：总结

End with actionable summary:

markdown

---

以可执行的总结收尾：

markdown

---

Summary

总结

[X] rules are effective and specific ✅
[Y] rules need thresholds or specifics 📏
[Z] rules overlap with linters 🔧
[W] rules are too vague to enforce 🌫️

[X]条规则 有效且具体 ✅
[Y]条规则 需要补充阈值或具体说明 📏
[Z]条规则 与Linter功能重叠 🔧
[W]条规则 过于模糊无法执行 🌫️

Recommended Actions

Output Examples

输出示例

Clean Technical.md

无问题的Technical.md文件

✅ Technical.md Validation Passed

File: ./Technical.md
Rules analyzed: 24
Issues found: 0

All rules are specific and verifiable. Nice work!

✅ Technical.md 验证通过

文件路径：./Technical.md
分析规则数量：24
发现问题数量：0

所有规则均具体且可验证。做得好！

Issues Found

检测到问题的情况

⚠️ Technical.md Validation: 8 issues found

File: ./Technical.md
Rules analyzed: 24
Issues found: 8

🌫️ Vague Language (3)
  Line 12: "clean code" - subjective term
  Line 18: "proper error handling" - "proper" undefined
  Line 31: "when necessary" - undefined trigger

📏 Missing Thresholds (2)
  Line 15: "small functions" - no size specified
  Line 22: "limit nesting" - no depth specified

🔧 Linter Overlap (3)
  Line 5: semicolons - handled by ESLint
  Line 8: quote style - handled by Prettier
  Line 11: import order - handled by ESLint

Run `/candid-validate-standards --fix` for suggested rewrites.

⚠️ Technical.md 验证：发现8个问题

文件路径：./Technical.md
分析规则数量：24
发现问题数量：8

🌫️ 模糊表述（3个）
  第12行："clean code" - 主观术语
  第18行："proper error handling" - "proper"未定义
  第31行："when necessary" - 触发条件未定义

📏 缺失阈值（2个）
  第15行："small functions" - 未指定大小标准
  第22行："limit nesting" - 未指定深度标准

🔧 与Linter重叠（3个）
  第5行：分号使用 - 由ESLint处理
  第8行：引号风格 - 由Prettier处理
  第11行：导入排序 - 由ESLint处理

运行 `/candid-validate-standards --fix` 获取建议的重写方案。

Vague Terms Reference

模糊术语参考列表

Use this list to detect vague language:

clean, good, proper, appropriate, suitable, adequate
well-designed, well-structured, well-organized, well-written
readable, maintainable, scalable, flexible, robust
best practices, industry standards, conventions
simple, straightforward, intuitive, obvious
reasonable, sensible, meaningful, significant
when necessary, when appropriate, when needed, as needed
avoid, prefer, consider, try to, should (without specifics)
minimal, few, some, many, several, various

使用此列表检测模糊表述：

clean, good, proper, appropriate, suitable, adequate
well-designed, well-structured, well-organized, well-written
readable, maintainable, scalable, flexible, robust
best practices, industry standards, conventions
simple, straightforward, intuitive, obvious
reasonable, sensible, meaningful, significant
when necessary, when appropriate, when needed, as needed
avoid, prefer, consider, try to, should (无具体说明时)
minimal, few, some, many, several, various

Threshold Patterns Reference

阈值模式参考列表

Patterns that need numbers:

small/short/brief + (function|method|class|file|module)
limit/restrict/cap + (parameters|arguments|nesting|depth|complexity)
maximum/minimum + (without number following)
too many/too few + (without threshold)
keep ... under/below + (without number)
no more than + (without number)

需要补充数字的模式：

small/short/brief + (function|method|class|file|module)
limit/restrict/cap + (parameters|arguments|nesting|depth|complexity)
maximum/minimum + (后面未跟数字)
too many/too few + (无阈值说明)
keep ... under/below + (无数字)
no more than + (无数字)

Remember

注意事项

The goal is to help users write Technical.md files that:

Candid can actually enforce
Don't duplicate existing tooling
Focus on what matters (architecture, security, patterns)
Are specific enough to be useful

A validated Technical.md leads to better code reviews.

本工具的目标是帮助用户编写满足以下要求的Technical.md文件：

Candid可实际执行
不重复现有工具的功能
聚焦关键内容（架构、安全、模式）
足够具体，具备实用价值

经过验证的Technical.md文件能带来更优质的代码评审。

candid-validate-standards

Original

Translation

Technical.md Validator

Technical.md 验证器

Workflow

工作流程

Step 1: Locate Technical.md

步骤1：定位Technical.md文件

Step 2: Detect Linter Configs

步骤2：检测Linter配置

JavaScript/TypeScript

JavaScript/TypeScript

Python

Python

Go

Go

Ruby

Ruby

Step 3: Parse Technical.md

步骤3：解析Technical.md文件

Step 4: Validate Each Rule

步骤4：验证每条规则

4.1 Vague Language (🌫️)

4.1 模糊表述（🌫️）

4.2 Missing Thresholds (📏)

4.2 缺失阈值（📏）

4.3 Linter Overlap (🔧)

4.3 与Linter重叠（🔧）

4.4 Multiple Concerns (🎯)

4.4 多关注点混杂（🎯）

4.5 Unverifiable Rules (❓)

4.5 无法验证的规则（❓）

Step 5: Generate Report

步骤5：生成报告

Technical.md Validation Report

Technical.md 验证报告

🔴 Critical Issues

🔴 严重问题

🌫️ Vague Language

🌫️ 模糊表述

📏 Missing Thresholds

📏 缺失阈值

🟡 Warnings

🟡 警告

🔧 Linter Overlap

🔧 与Linter重叠

🎯 Multiple Concerns

🎯 多关注点混杂

✅ Good Rules

✅ 有效规则

Step 6: Suggest Fixes (if --fix flag)

步骤6：建议修复方案（若使用--fix参数）

💡 Suggested Rewrites

💡 建议重写方案

Line 12: "Write clean code"

第12行："编写clean代码"

Line 18: "Keep functions small"

第18行："保持函数small"

Line 24: "Use appropriate error handling"

第24行："使用appropriate错误处理"

Step 7: Summary

步骤7：总结

Summary

总结

Recommended Actions

推荐行动

Output Examples

输出示例

Clean Technical.md

无问题的Technical.md文件

Issues Found

检测到问题的情况

Vague Terms Reference

模糊术语参考列表

Threshold Patterns Reference

阈值模式参考列表

Remember

注意事项