spec-inspect

spec-inspect — 规格质量检查器

自动验证 spec-generator 的输出（requirement.md、design.md、tasks.md），并报告质量问题。

语言规则

1. 自动检测输入语言 → 使用相同语言输出
2. 日语输入 → 输出日语报告
3. 英语输入 → 输出英语报告
4. 显式指定的语言优先（例如，“in English”、“日本語で”）

运行时机

• spec-generator 完成后（自动建议）
• 使用 spec-to-issue 注册 Issues 前
• 更新规格文档后

执行流程

步骤 1：定位项目路径

根据用户输入或当前上下文，确定 .specs/{project-name}/ 路径。

验证：

• .specs/{project-name}/requirement.md 存在
• .specs/{project-name}/design.md 存在
• .specs/{project-name}/tasks.md 存在

如果缺少任何文件，显示错误消息并退出。

步骤 2：读取规格

读取全部三个规格文件：

requirement_content = Read(".specs/{project-name}/requirement.md")
design_content = Read(".specs/{project-name}/design.md")
tasks_content = Read(".specs/{project-name}/tasks.md")

# Optional: acceptance test plan (only present for full-workflow / pipeline specs).
# Absence is expected for legacy three-document specs — do NOT treat as an error.
test_content = Read(".specs/{project-name}/test.md") or None

# Optional: load coding rules if available
coding_rules = Read("docs/coding-rules.md") or None
# Also check CLAUDE.md / AGENTS.md for alternative path

检测规格所用语言，通过名称从当前可用的技能中解析 spec-writing，并读取其完整的 SKILL.md 以及匹配的 references/abstract-verbs.md 或 references/abstract-verbs.ja.md，将其作为主要词汇来源。读取匹配的 abstract-process-check.md 和 projection-consistency-check.md 参考文档（日语使用 *.ja.md），并在步骤 3 中运行这两项检查。如果无法读取该技能、词汇表、必需列或 ID，请按照 abstract-process 参考文档中的词汇错误处理流程操作，不要推断模式列表；其他所有检查仍须继续。

步骤 3：运行质量检查

按顺序执行以下检查。将检测到的问题添加到问题列表中。

检查 1：需求 ID 一致性 [CRITICAL]

目的：验证 requirement.md 中定义的需求 ID 是否在 design.md、tasks.md 以及存在时的 test.md 中被正确引用。

流程：

1. 从 requirement.md 中提取需求 ID（正则表达式：\[(REQ|NFR|CON|ASM|T)-\d{3,}\]）
2. 从 design.md、tasks.md 以及存在时的 test.md 中提取被引用的需求 ID

检测模式：

• [CRITICAL] design.md、tasks.md 或 test.md 中引用的 ID 未在 requirement.md 中定义

  ID: CRITICAL-{seq}
  Title: "Requirement ID {req_id} does not exist"
  File: design.md, tasks.md, or test.md
  Line: {line_number}
  Description: "{req_id} is referenced in {file} but not defined in requirement.md"
  Suggestion: "Add {req_id} to requirement.md or fix the reference"
  

• [INFO] requirement.md 中定义的 ID 从未被引用

  ID: INFO-{seq}
  Title: "Requirement ID {req_id} is unreferenced"
  File: requirement.md
  Line: {line_number}
  Description: "{req_id} is not linked to any design or task"
  Suggestion: "Is this requirement still needed? Consider removing if unnecessary"
  

• [WARNING] 需求覆盖不足（计算 design.md 对所有 ID（包括 [NFR-XXX]）的引用率；低于 100% 时发出警告）

  ID: WARNING-{seq}
  Title: "Requirement coverage: {covered}/{total} ({percentage}%)"
  Description: "The following requirements are not mentioned in design.md: {uncovered_list}"
  Suggestion: "Add coverage for each requirement in design.md"
  

检查 2：必需结构与需求边界 [WARNING]

目的：确认每份规格都包含预期章节、非空的范围边界，以及可测试的需求。

流程：

1. 对 requirement.md 运行所选的 references/requirement-boundary-check.md / .ja.md。
2. 对 design.md，要求包含 Architecture Overview、Technology Stack、Data Model、适用时的 API Design，以及 Security Design。对 tasks.md，要求包含 Task List 和 Priority。

输出：每缺少一个必需章节、所选范围外章节为空，或 REQ / NFR 块不含非空验收标准列表，就输出一个 WARNING-{seq}。

检查 3：矛盾检测 [WARNING]

目的：检测规格文档之间相互矛盾的陈述。

检测示例：

• 技术栈不匹配（例如，需求中写 PostgreSQL，设计中写 MySQL）
• 数值不匹配（例如，需求中写“100 users”，设计中写“1000 users”）
• API 端点不匹配
• 在 design.md 中设计、但 tasks.md 实施计划中缺失的组件

流程：

1. 从 requirement.md 中提取技术专有名词（数据库名称、库名称等）
2. 检查 design.md 是否以其他名称指代相同概念
3. 检测数值数据不一致

检测模式：

• [WARNING] 存在相互矛盾的陈述

  ID: WARNING-{seq}
  Title: "Contradiction: {concept}"
  File: requirement.md, design.md
  Line: {line_number}
  Description: "requirement.md states {value1}, but design.md states {value2}"
  Suggestion: "Unify to one value"
  

检查 4：模糊表达检测 [INFO]

目的：检测缺乏实现所需明确性的模糊表达。

检测关键词（英文）：

• "appropriately", "as much as possible", "reasonable", "adequate"
• "fast", "large amount", "many"（没有数值标准）
• "to be determined", "under consideration", "planned"（尚未最终确定）

检测关键词（日文）：

• 「適切に」「できる限り」「なるべく」「ある程度」
• 「高速に」「大量の」「多くの」（没有数值标准）
• 「検討する」「考慮する」「予定」（尚未确定）

流程：

1. 在全部三个规范中搜索模糊关键词
2. 列出所有出现位置

检测模式：

• [INFO] 模糊表达

  ID: INFO-{seq}
  Title: "Ambiguous expression: '{keyword}'"
  File: {filename}
  Line: {line_number}
  Description: "The expression '{context}' may be interpreted differently by implementors"
  Suggestion: "Specify concrete numbers or criteria"
  

检查 5：术语一致性 [WARNING]

目的：确保所有规范中的术语使用一致。

检测模式：

• 同一概念使用不同术语表达（例如："user" 与 "member"、"delete" 与 "remove"）
• 缩写不一致（例如：混用 "DB" 和 "database"）
• 术语偏离词汇表中的定义（如果存在词汇表章节）

流程：

1. 提取全部三个规范中的关键名词／概念
2. 检测同义词／近义词对
3. 与词汇表章节交叉核对（如果存在）

输出：WARNING-{seq} "术语不一致：'{term1}' 与 '{term2}'" + 建议统一用法

检查 6：设计到任务的覆盖情况 [WARNING]

目的：确认 design.md 中的组件在 tasks.md 中有对应的实现任务。

检测模式：

• 已设计的组件／模块没有对应任务
• 数据库架构设计没有对应的迁移任务
• API 设计没有对应的实现任务

流程：

1. 从 design.md 中提取主要组件／模块名称
2. 检查 tasks.md 中是否为每个组件列出了对应任务
3. 列出未覆盖的设计元素

输出：WARNING-{seq} "设计元素 '{component}' 没有对应任务"

检查 7：依赖关系验证 [WARNING]

目的：确认任务依赖关系在逻辑上正确。

检测模式：

• 循环依赖（任务 A 依赖 B，B 依赖 A）
• 未定义的前置任务（依赖不存在的任务）
• 明显颠倒的依赖顺序（例如：测试任务在实现任务之前）

流程：

1. 从 tasks.md 中提取任务间的依赖关系
2. 构建依赖图并检测循环
3. 标记逻辑上不一致的顺序

输出：WARNING-{seq} "循环依赖：{taskA} ⇄ {taskB}" 或 "不合逻辑的依赖顺序"

检查 8：不可行需求警告 [WARNING]

目的：检测技术上难以实现或相互矛盾的需求。

检测模式：

• 相互冲突的非功能性需求（例如："响应时间低于 1ms" + "加密所有数据"）
• 使用所选技术栈难以实现的功能
• 不切实际的资源需求（例如：无限存储空间、零停机时间）

输出：WARNING-{seq} "可能不可行：{requirement}" + 替代建议

检查 9：缺失需求检测 [WARNING]

目的：检测明显必要但未记录的需求。

检测模式：

• 存在身份验证 → 没有安全需求
• 使用数据库 → 没有备份／恢复需求
• 集成外部 API → 没有错误处理／重试需求
• 文件上传 → 没有大小／格式限制
• 存储用户数据 → 没有隐私／数据保护需求

流程：

1. 从 requirement.md／design.md 中提取功能特征
2. 根据检测模式进行匹配，并检查是否存在对应需求

输出：WARNING-{seq} "{feature} 的 {requirement_type} 可能缺失且未定义"

检查 10：命名约定一致性 [INFO]

目的：验证各项规范中的命名约定是否一致。

检测模式：

• kebab-case、camelCase、snake_case 混用
• 同一上下文中的命名变体（例如，user_id、userId 和 userID）
• 常量、表名、组件名的命名约定违规

流程：

1. 从 design.md / tasks.md 中提取代码相关名称（变量名、表名、API 名称等）
2. 汇总命名模式统计数据，并标记少数模式

输出：INFO-{seq} "命名约定不一致：{pattern1}（{count1} 处）与 {pattern2}（{count2} 处）"

检查 11：目录结构一致性 [INFO]

目的：验证目录结构和文件放置规则是否一致。

检测模式：

• 类似组件的放置位置不一致（例如，src/features/A/ 与 src/components/B/）
• 测试文件放置位置混用（tests/ 与 __tests__/）
• 配置文件分散放置

输出：INFO-{seq} "目录结构不一致：{pattern description}"

检查 12：重复实现检测 [INFO]

目的：检测对已在声明的库中提供的功能进行自定义实现的情况。

检测模式：

• 重新实现技术栈中库已提供的功能
  • 例如，已包含 date-fns 时仍自定义处理日期
  • 例如，已包含 Zod 时仍自定义实现验证
• 重新实现标准库功能

流程：

1. 从 design.md 的“技术栈”部分提取库列表
2. 将其与 tasks.md 中的实现任务进行比较，以检测功能重叠

输出：INFO-{seq} "可能存在重复实现：{task} 可由 {library_name} 处理"

检查 13：项目规则合规性 [WARNING]

目的：检查规范是否符合 CLAUDE.md / AGENTS.md 和 coding-rules.md 中定义的项目特定规则。

流程：

1. 读取项目根目录中的 CLAUDE.md、AGENTS.md 和 .claude/
2. 如果 docs/coding-rules.md 存在，则读取该文件（或读取 CLAUDE.md / AGENTS.md 中指定的路径）
3. 从 coding-rules.md 中提取 [MUST] 规则
4. 提取编码约定、禁止模式和必需模式
5. 与 design.md / tasks.md 交叉核对

检测示例：

• “必须启用 TypeScript 严格模式” → design.md 中未提及
• “必须使用 JWT 身份验证” → design.md 使用了不同的方案
• “禁止使用 console.log” → tasks.md 描述了 console.log 的使用

coding-rules.md 特定检查：

• 命名规则与 design.md 中的文件名 / 类名（例如，coding-rules：[MUST] kebab-case 与 design：UserProfile.service.ts）
• 测试覆盖率要求与 tasks.md 中的测试规划（例如，coding-rules：[MUST] 80%+ coverage，而 tasks.md 中没有测试任务）
• 必需库与 design.md 中的技术选型（例如，coding-rules：[MUST] Use Prisma，而 design 中使用直接 SQL）
• 禁止模式与 design.md / tasks.md 中的描述

输出：WARNING-{seq} "违反项目规则：{rule} 与 {violation_location} 冲突"

检查 14：API / UI 命名约定一致性 [WARNING]

开始检查 14 前，请完整阅读 references/extended-quality-checks.md （如需日语版本，请阅读 .ja.md）。按顺序执行其中的检查 14 至 19， 并严格遵循每项检查的严重级别和输出约定，不得修改。

步骤 4：生成摘要

按严重级别汇总检测到的问题：

• 严重：{count}
• 警告：{count}
• 信息：{count}

步骤 5：生成报告

将 Markdown 报告写入 .specs/{project-name}/inspection-report.md。

模板：# spec-inspect Report — {project_name} → 检查摘要（日期、目标、数量）→ 严重级别部分（CRITICAL / WARNING / INFO）。每个问题包含：### [{issue.id}] {issue.title} + 文件:行号、详情、建议。问题数为 0 的部分显示 "None"。

使用 Write 工具将报告保存到 .specs/{project-name}/inspection-report.md。

步骤 6：控制台输出

显示用户友好的摘要：

spec-inspect complete

Results:
  CRITICAL: {count}
  WARNING:  {count}
  INFO:     {count}

{if critical_count > 0}
Critical issues found. Fix before implementation.

{if critical_count == 0}
No critical issues found.

Report: .specs/{project-name}/inspection-report.md

步骤 7：建议下一步操作（工作流集成）

根据结果，使用 AskUserQuestion 建议下一步操作（标题：“Next action” / “下一步操作”，multiSelect: false）：

结果	问题	选项
存在严重问题	“发现 {count} 个严重问题。需要采取措施。” / “发现 {count} 个严重问题。需要采取措施。”	“修复并重新运行” / “修复并重新运行”，“跳转至 Issue 登记” / “跳转至 Issue 登记”，“取消” / “取消”
仅有警告/信息	“发现 {count} 个警告。要继续登记 Issue 吗？” / “发现 {count} 个警告。要继续登记 Issue 吗？”	“登记 Issue” / “登记 Issue”，“修复并重新运行” / “修复并重新运行”，“取消” / “取消”
没有问题	“质量检查通过。要登记 Issue 吗？” / “质量检查通过。要登记 Issue 吗？”	“登记 Issue” / “登记 Issue”，“取消” / “取消”

处理用户选择：

• “登记 Issue” / “跳转至 Issue 登记” → 调用 spec-to-issue 技能
• “修复并重新运行” → 退出（由用户修复并手动重新运行）
• “取消” → 退出

步骤 8：为 spec-to-issue 保存交接数据

将检查结果保存为临时文件，供下一个技能使用：

{
  "project_path": ".specs/{project-name}",
  "project_name": "{project-name}",
  "critical_count": 0,
  "warning_count": 0,
  "info_count": 0,
  "report_path": ".specs/{project-name}/inspection-report.md",
  "timestamp": "{ISO 8601}"
}

使用 Write 工具保存：

Write(".specs/{project-name}/.inspection_result.json", json_content)

错误处理

• 文件未找到 / 读取错误：“错误：未找到所需文件”或“错误：读取文件失败” + 文件名和详细信息，并提供路径验证指导
• ID 提取错误：继续处理并显示“警告：提取需求 ID 时发生部分错误”

实现说明

• 效率：尽量减少对大文件的 Read 操作；使用搜索工具；每项检查后显示进度。
• 准确性 / 用户体验：对章节名称进行部分匹配；检测矛盾时考虑上下文；灵活匹配日文和英文内容；错误提示附带具体修复建议和表情符号标记。

约束

• 仅支持日文和英文 Markdown 规格（自然语言分析存在固有的准确性限制）；依赖 spec-generator 的输出格式

成功标准

• 100% 检测需求 ID 引用错误、缺少必需章节，以及未覆盖的 REQ/NFR（存在 test.md 时）；缺少 test.md 时报告为 INFO，且不因此导致旧版规格失败
• 矛盾检测准确性：尽力而为（取决于大模型的推理能力）
• 处理时间：合并后的规格文件少于 3000 行时，低于 30 秒