candid-validate-standards

Technical.md 验证器

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

工作流

步骤 1：定位 Technical.md

查找要验证的 Technical.md 文件：

1. 如果提供了路径参数 → 使用该路径
2. 检查 ./Technical.md
3. 检查 ./.candid/Technical.md

如果未找到文件：

❌ No Technical.md found.

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

Create one with: /candid-init

步骤 2：检测 Linter 配置

检查现有的 Linter 配置：

# 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

保存检测到的 Linter，供步骤 4 使用。

步骤 3：解析 Technical.md

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

规则检测：

• 以 - 或 * 开头的行（列表项）
• 以数字开头的行（编号列表）
• ## 标题后面的行

跳过：

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

为每条规则保存以下信息：

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

步骤 4：验证每条规则

根据以下问题类别检查每条规则：

4.1 含糊的措辞（🌫️）

标记包含含糊词语但没有具体说明的规则：

含糊词语	含糊原因
“干净”	主观，没有定义
“良好”	主观
“恰当” / “合适”	标准未定义
“设计良好” / “结构良好”	没有评判标准
“可读” / “可维护”	没有衡量指标
“最佳实践”	循环引用
“必要时” / “适当时”	触发条件未定义
单独使用“避免”	没有说明替代做法
“考虑”	不是要求

同时标记：合适、充分、组织良好、写得好、可扩展、灵活、稳健、简单、直接、直观、显而易见、合理、有意义、重要、按需、优先、尽量、最少、很少、一些、许多、若干、各种。

**例外：**如果这些词后面有具体标准，则可以接受：

• “可读（函数不超过 50 行）” ✓
• “可维护” ✗

4.2 缺少阈值（📏）

标记隐含数量要求但没有给出数字的规则：

模式	问题
“小函数”	多小才算小？
“短方法”	多短才算短？
“限制参数”	限制为多少个？
“最少依赖”	怎样才算最少？
“少量嵌套层级”	多少层才算少？
“合理的超时时间”	怎样才算合理？

同时标记：最大/最小、太多/太少、保持在……以下/低于……、不超过——如果后面没有数字。

**修正方式：**添加具体数字（例如，“函数不超过 50 行”）

4.3 与 Linter 重叠（🔧）

标记通常可由 Linter 处理的规则（根据步骤 2）：

如果检测到 ESLint/Prettier：

• 分号用法
• 引号风格（单引号还是双引号）
• 缩进规则
• 尾随逗号
• 导入排序
• 未使用的变量
• 不使用 console.log

如果检测到 Flake8/Ruff：

• 行长度
• 导入排序
• 空白规则
• 命名约定（snake_case）

如果检测到任何 Linter：

• 一般格式规则
• 基本语法风格

4.4 多个关注点（🎯）

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

• 用“和”连接无关关注点的规则
• 超过 2 行的规则
• 包含多个“必须”语句的规则

示例：

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

4.5 无法验证的规则（❓）

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

• “考虑边界情况”
• “保持一致”
• “遵循团队约定”
• “运用常识”
• 未提供具体内容的外部文档引用

4.6 代码库抽查（🔬）

对于最多 10 条引用路径、glob 或命名模式的规则：

1. 验证每个引用的文件/目录是否存在（用 ls 检查）。不存在 → 标记为 过时。
2. 抽查 3 个符合规则的文件（按规则声明的范围使用 find/grep 查找），并检查 规则在每个文件中是否确实成立。
3. 0/3 成立 → 标记为 不属实（“规则与此代码库矛盾——删除规则或将其移至 Gaps”）。 1-2/3 成立 → 标记为 存在争议（“添加已知例外或放宽规则”）。 在 🔬 Spot-Check 部分按规则列出抽查的文件。

步骤 5：生成报告

按严重程度整理调查结果：

# Technical.md Validation Report

**File:** ./Technical.md
**Rules analyzed:** [N]
**Issues found:** [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 |

### 📏 Missing Thresholds

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

---

## 🟡 Warnings

Rules that may have issues.

### 🔧 Linter Overlap

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

### 🎯 Multiple Concerns

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

---

## 🔬 Spot-Check

[Per rule checked: verdict (stale/untrue/contested) with the 3 sampled files]

---

## ✅ Good Rules

[List of rules that passed validation]

如果没有问题，则输出一条简短的通过消息，包含文件路径和规则数量，而不是完整报告。

步骤 6：建议修复（如果使用 --fix 标志）

如果提供了 --fix 参数，则包含具体的改写建议：

## 💡 Suggested Rewrites

### Line 24: "Use appropriate error handling"
**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

步骤 7：总结

以可执行的总结结束：

---

## 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 🌫️

### Recommended Actions

1. Remove [Z] linter-overlap rules (your linter handles these)
2. Add numbers to [Y] threshold rules
3. Rewrite [W] vague rules with specific criteria

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

请记住

目标是帮助用户编写满足以下条件的 Technical.md 文件：

1. Candid 能够实际执行其中的要求
2. 不会重复现有工具的功能
3. 聚焦于重要内容（架构、安全、模式）
4. 具体到足以发挥作用

经过验证的 Technical.md 有助于改进代码审查。