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：リンター設定を検出する

既存のリンター設定を確認します。

# 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

検出したリンターをステップ 4 で使用できるように保存します。

ステップ 3：Technical.md を解析する

Technical.md ファイルを読み込み、ルールを抽出します。

ルールの検出：

• - または * で始まる行（リスト項目）
• 数字で始まる行（番号付きリスト）
• ## 見出しの次に続く行

スキップする項目：

• コードブロック（``` の間）
• 空行
• コメント（HTML または Markdown）
• 見出し行自体

各ルールについて、以下を保存します。

• 行番号
• 該当するセクションの見出し
• ルールの全文

ステップ 4：各ルールを検証する

次の問題カテゴリに照らして各ルールを確認します。

4.1 曖昧な表現（🌫️）

具体的な基準を伴わずに曖昧な用語を含むルールにフラグを立てます。

曖昧な用語	曖昧である理由
"clean"	主観的で、定義がありません
"good"	主観的です
"proper" / "appropriate"	基準が定義されていません
"well-designed" / "well-structured"	判断基準がありません
"readable" / "maintainable"	指標がありません
"best practices"	循環参照です
"when necessary" / "when appropriate"	条件が定義されていません
"avoid"（単独）	代替案の指針がありません
"consider"	要件ではありません

次の語句も対象とします：suitable、adequate、well-organized、well-written、scalable、flexible、robust、simple、straightforward、intuitive、obvious、sensible、meaningful、significant、as needed、prefer、try to、minimal、few、some、many、several、various。

**例外：**具体的な基準が後に続く場合、これらの用語は問題ありません。

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

4.2 しきい値の不足（📏）

数値を示さずに数量を示唆するルールにフラグを立てます。

パターン	問題
"small functions"	どの程度小さいのですか？
"short methods"	どの程度短いのですか？
"limit parameters"	いくつまでですか？
"minimal dependencies"	どの程度が最小限ですか？
"few levels of nesting"	いくつまでですか？
"reasonable timeout"	どの程度が妥当ですか？

次の表現も対象とします：maximum/minimum、too many/too few、keep under/below、no more than — 数値が後に続かない場合。

**修正方法：**具体的な数値を追加します（例："functions under 50 lines"）。

4.3 リンターとの重複（🔧）

ステップ 2 に基づき、通常リンターが処理するルールにフラグを立てます。

ESLint/Prettier が検出された場合：

• セミコロンの使用
• クォートのスタイル（シングルまたはダブル）
• インデントのルール
• 末尾のカンマ
• インポートの順序
• 未使用の変数
• console.log を使わないこと

Flake8/Ruff が検出された場合：

• 行の長さ
• インポートの並べ替え
• 空白のルール
• 命名規則（snake_case）

リンターが検出された場合：

• 一般的な書式設定ルール
• 基本的な構文スタイル

4.4 複数の懸念事項（🎯）

一度に多くのことを求めるルールにフラグを立てます。

• 関連のない懸念事項を「and」でつなげているルール
• 2 行を超えるルール
• 「must」を複数含むルール

例：

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

4.5 検証できないルール（❓）

コードを読んでも確認できないルールにフラグを立てます。

• "Think about edge cases"
• "Be consistent"
• "Follow team conventions"
• "Use common sense"
• 具体的な内容を伴わない外部ドキュメントへの参照

4.6 コードベースの抜き取り確認（🔬）

パス、glob、または命名パターンを示しているルールを最大 10 件確認します。

1. 指定されたすべてのファイル／ディレクトリが存在することを確認します（ls で確認）。存在しない場合は stale としてフラグを立てます。
2. ルールが適用されるファイルを 3 件抽出し（ルールに記載された範囲に基づいて find/grep で検索）、それぞれでルールが実際に守られているかを確認します。
3. 0/3 件で守られている場合は untrue としてフラグを立てます（「ルールがこのコードベースと矛盾しています — 削除するか、Gaps に移してください」）。 1〜2/3 件で守られている場合は contested としてフラグを立てます（「既知の例外を追加するか、ルールを緩和してください」）。 各ルールについて、抽出したファイルを列挙した 🔬 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]

問題が 0 件の場合は、レポート全文の代わりに、ファイルパスとルール数を含む短い合格メッセージを出力します。

ステップ 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 は、コードレビューの質を高めます。