From 44633baae50a9b5289fd304c2b49eccecc62fa6c Mon Sep 17 00:00:00 2001 From: mzaxd Date: Sun, 18 Jan 2026 12:33:43 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E7=A7=BB=E9=99=A4=20SpecKit=20?= =?UTF-8?q?=E7=9B=B8=E5=85=B3=E6=96=87=E4=BB=B6=E5=92=8C=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除所有 SpecKit 命令文件（.claude/commands/speckit.*） - 删除 .specify 配置目录（templates, scripts, memory） - 删除 specs 文档目录 - 更新 CLAUDE.md：移除 SpecKit Skills 说明 --- .claude/commands/speckit.analyze.md | 184 ------ .claude/commands/speckit.checklist.md | 287 ---------- .claude/commands/speckit.clarify.md | 179 ------ .claude/commands/speckit.constitution.md | 81 --- .claude/commands/speckit.fixbug.md | 74 --- .claude/commands/speckit.implement.md | 131 ----- .claude/commands/speckit.plan.md | 89 --- .claude/commands/speckit.specify.md | 237 -------- .claude/commands/speckit.tasks.md | 120 ---- .claude/commands/speckit.taskstoissues.md | 28 - .specify/memory/constitution.md | 200 ------- .../powershell/check-prerequisites.ps1 | 148 ----- .specify/scripts/powershell/common.ps1 | 137 ----- .../scripts/powershell/create-new-feature.ps1 | 327 ----------- .specify/scripts/powershell/setup-plan.ps1 | 61 -- .../powershell/update-agent-context.ps1 | 442 --------------- .specify/templates/agent-file-template.md | 23 - .specify/templates/checklist-template.md | 40 -- .specify/templates/plan-template.md | 101 ---- .specify/templates/spec-template.md | 115 ---- .specify/templates/tasks-template.md | 249 --------- CLAUDE.md | 136 ++++- .../checklists/requirements.md | 36 -- .../contracts/webhook.yaml | 456 --------------- specs/001-ai-project-navigator/data-model.md | 524 ------------------ specs/001-ai-project-navigator/plan.md | 157 ------ specs/001-ai-project-navigator/quickstart.md | 519 ----------------- specs/001-ai-project-navigator/research.md | 509 ----------------- specs/001-ai-project-navigator/spec.md | 180 ------ specs/001-ai-project-navigator/tasks.md | 266 --------- 30 files changed, 133 insertions(+), 5903 deletions(-) delete mode 100644 .claude/commands/speckit.analyze.md delete mode 100644 .claude/commands/speckit.checklist.md delete mode 100644 .claude/commands/speckit.clarify.md delete mode 100644 .claude/commands/speckit.constitution.md delete mode 100644 .claude/commands/speckit.fixbug.md delete mode 100644 .claude/commands/speckit.implement.md delete mode 100644 .claude/commands/speckit.plan.md delete mode 100644 .claude/commands/speckit.specify.md delete mode 100644 .claude/commands/speckit.tasks.md delete mode 100644 .claude/commands/speckit.taskstoissues.md delete mode 100644 .specify/memory/constitution.md delete mode 100644 .specify/scripts/powershell/check-prerequisites.ps1 delete mode 100644 .specify/scripts/powershell/common.ps1 delete mode 100644 .specify/scripts/powershell/create-new-feature.ps1 delete mode 100644 .specify/scripts/powershell/setup-plan.ps1 delete mode 100644 .specify/scripts/powershell/update-agent-context.ps1 delete mode 100644 .specify/templates/agent-file-template.md delete mode 100644 .specify/templates/checklist-template.md delete mode 100644 .specify/templates/plan-template.md delete mode 100644 .specify/templates/spec-template.md delete mode 100644 .specify/templates/tasks-template.md delete mode 100644 specs/001-ai-project-navigator/checklists/requirements.md delete mode 100644 specs/001-ai-project-navigator/contracts/webhook.yaml delete mode 100644 specs/001-ai-project-navigator/data-model.md delete mode 100644 specs/001-ai-project-navigator/plan.md delete mode 100644 specs/001-ai-project-navigator/quickstart.md delete mode 100644 specs/001-ai-project-navigator/research.md delete mode 100644 specs/001-ai-project-navigator/spec.md delete mode 100644 specs/001-ai-project-navigator/tasks.md diff --git a/.claude/commands/speckit.analyze.md b/.claude/commands/speckit.analyze.md deleted file mode 100644 index e318482..0000000 --- a/.claude/commands/speckit.analyze.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -description: 在任务生成后, 对 spec.md、plan.md 和 tasks.md 执行非破坏性的跨制品一致性和质量分析. ---- - -## 用户输入 - -```text -$ARGUMENTS -``` - -在继续之前, 你**必须**考虑用户输入(如果不为空). - -## 目标 - -在实施之前, 识别三个核心制品(`spec.md`、`plan.md`、`tasks.md`)之间的不一致、重复、模糊和规范不足的项目. 此命令**必须**在 `/speckit.tasks` 成功生成完整的 `tasks.md` 后运行. - -## 操作约束 - -**严格只读**: **不要**修改任何文件. 输出结构化分析报告. 提供可选的修复计划(用户必须明确批准后才能手动调用任何后续编辑命令). - -**章程权威**: 项目章程(`.specify/memory/constitution.md`)在此分析范围内是**不可协商的**. 章程冲突自动为严重问题, 需要调整规范、计划或任务——而不是稀释、重新解释或默默忽略原则. 如果原则本身需要更改, 那必须在 `/speckit.analyze` 之外的单独、明确的章程更新中进行. - -## 执行步骤 - -### 1. 初始化分析上下文 - -从仓库根目录运行一次 `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` 并解析 JSON 以获取 FEATURE_DIR 和 AVAILABLE_DOCS. 推导绝对路径: - -- SPEC = FEATURE_DIR/spec.md -- PLAN = FEATURE_DIR/plan.md -- TASKS = FEATURE_DIR/tasks.md - -如果任何必需文件缺失, 则以错误消息中止(指示用户运行缺失的先决条件命令). -对于参数中的单引号, 如 "I'm Groot", 使用转义语法: 例如 'I'\''m Groot'(或尽可能使用双引号: "I'm Groot"). - -### 2. 加载制品(渐进式展示) - -仅从每个制品加载最小必需的上下文: - -**从 spec.md: ** - -- 概述/上下文 -- 功能需求 -- 非功能需求 -- 用户故事 -- 边缘情况(如果存在) - -**从 plan.md: ** - -- 架构/技术栈选择 -- 数据模型引用 -- 阶段 -- 技术约束 - -**从 tasks.md: ** - -- 任务 ID -- 描述 -- 阶段分组 -- 并行标记 [P] -- 引用的文件路径 - -**从章程: ** - -- 加载 `.specify/memory/constitution.md` 进行原则验证 - -### 3. 构建语义模型 - -创建内部表示(输出中不包含原始制品): - -- **需求清单**: 每个功能和非功能需求, 带有稳定键(基于祈使短语推导 slug; 例如, "User can upload file" → `user-can-upload-file`) -- **用户故事/操作清单**: 带有验收标准的离散用户操作 -- **任务覆盖映射**: 将每个任务映射到一个或多个需求或故事(通过关键词/显式引用模式推断, 如 ID 或关键短语) -- **章程规则集**: 提取原则名称和 MUST/SHOULD 规范性声明 - -### 4. 检测过程(高效令牌分析) - -专注于高信号发现. 限制总共 50 个发现; 在溢出摘要中聚合其余部分. - -#### A. 重复检测 - -- 识别近似重复的需求 -- 标记较低质量的表述以进行合并 - -#### B. 模糊性检测 - -- 标记缺乏可测量标准的模糊形容词(快速、可扩展、安全、直观、稳健) -- 标记未解决的占位符(TODO、TKTK、???、`` 等) - -#### C. 规范不足 - -- 有动词但缺少对象或可测量结果的需求 -- 缺少验收标准对齐的用户故事 -- 引用规范/计划中未定义的文件或组件的任务 - -#### D. 章程对齐 - -- 与 MUST 原则冲突的任何需求或计划元素 -- 章程中缺失的强制部分或质量门控 - -#### E. 覆盖缺口 - -- 没有关联任务的需求 -- 没有映射需求/故事的任务 -- 未在任务中反映的非功能需求(例如, 性能、安全性) - -#### F. 不一致性 - -- 术语漂移(相同概念在不同文件中命名不同) -- 计划中引用但在规范中缺失的数据实体(反之亦然) -- 任务排序矛盾(例如, 集成任务在基础设置任务之前而没有依赖说明) -- 冲突需求(例如, 一个要求 Next.js 而另一个指定 Vue) - -### 5. 严重性分配 - -使用此启发式方法对发现进行优先级排序: - -- **严重**: 违反章程 MUST、缺失核心规范制品, 或零覆盖的需求阻止基线功能 -- **高**: 重复或冲突需求、模糊的安全/性能属性、不可测试的验收标准 -- **中**: 术语漂移、缺失非功能任务覆盖、规范不足的边缘情况 -- **低**: 风格/措辞改进、不影响执行顺序的轻微冗余 - -### 6. 生成紧凑分析报告 - -输出 Markdown 报告(不写入文件), 结构如下: - -## 规范分析报告 - -| ID | 类别 | 严重性 | 位置 | 摘要 | 建议 | -|----|------|--------|------|------|------| -| A1 | 重复 | 高 | spec.md:L120-134 | 两个相似需求... | 合并表述; 保留更清晰的版本 | - -(每个发现添加一行; 生成以类别首字母为前缀的稳定 ID. ) - -**覆盖摘要表: ** - -| 需求键 | 有任务？ | 任务 ID | 备注 | -|--------|----------|---------|------| - -**章程对齐问题: **(如果有) - -**未映射任务: **(如果有) - -**指标: ** - -- 总需求数 -- 总任务数 -- 覆盖率%(有 >=1 个任务的需求) -- 模糊性计数 -- 重复计数 -- 严重问题计数 - -### 7. 提供下一步操作 - -在报告末尾, 输出简洁的下一步操作块: - -- 如果存在严重问题: 建议在 `/speckit.implement` 之前解决 -- 如果只有低/中问题: 用户可以继续, 但提供改进建议 -- 提供明确的命令建议: 例如, "运行 /speckit.specify 进行细化"、"运行 /speckit.plan 调整架构"、"手动编辑 tasks.md 为 'performance-metrics' 添加覆盖" - -### 8. 提供修复 - -询问用户: "你希望我为前 N 个问题建议具体的修复编辑吗？"(不要自动应用它们. ) - -## 操作原则 - -### 上下文效率 - -- **最小高信噪比令牌**: 专注于可操作的发现, 而不是详尽的文档 -- **渐进式展示**: 增量加载制品; 不要将所有内容倾倒到分析中 -- **高效令牌输出**: 限制发现表为 50 行; 总结溢出部分 -- **确定性结果**: 无更改重新运行应产生一致的 ID 和计数 - -### 分析指南 - -- **绝不修改文件**(这是只读分析) -- **绝不虚构缺失部分**(如果缺失, 准确报告) -- **优先处理章程违规**(这些总是严重的) -- **使用示例而非详尽规则**(引用具体实例, 而不是通用模式) -- **优雅报告零问题**(发出带有覆盖统计的成功报告) - -## 上下文 - -$ARGUMENTS diff --git a/.claude/commands/speckit.checklist.md b/.claude/commands/speckit.checklist.md deleted file mode 100644 index ce7866b..0000000 --- a/.claude/commands/speckit.checklist.md +++ /dev/null @@ -1,287 +0,0 @@ ---- -description: 基于用户需求为当前功能生成自定义检查清单. ---- - -## 清单目的: "需求编写的单元测试" - -**核心概念**: 清单是**需求编写的单元测试** - 它们验证特定领域中需求的质量、清晰度和完整性. - -**不用于验证/测试**: -- ❌ 不是"验证按钮点击正确" -- ❌ 不是"测试错误处理有效" -- ❌ 不是"确认 API 返回 200" -- ❌ 不是检查代码/实现是否符合规范 - -**用于需求质量验证**: -- ✅ "是否为所有卡片类型定义了视觉层次需求？"(完整性) -- ✅ "'突出显示'是否通过具体尺寸/位置进行了量化？"(清晰度) -- ✅ "所有交互元素的悬停状态需求是否一致？"(一致性) -- ✅ "是否为键盘导航定义了可访问性需求？"(覆盖度) -- ✅ "规范是否定义了 logo 图像加载失败时的处理？"(边缘情况) - -**比喻**: 如果你的规范是用英文编写的代码, 那么清单就是它的单元测试套件. 你测试的是需求是否编写良好、完整、明确并准备好实施 - 而不是实现是否有效. - -## 用户输入 - -```text -$ARGUMENTS -``` - -在继续之前, 你**必须**考虑用户输入(如果不为空). - -## 执行步骤 - -1. **设置**: 从仓库根目录运行 `.specify/scripts/powershell/check-prerequisites.ps1 -Json` 并解析JSON以获取FEATURE_DIR和AVAILABLE_DOCS列表. - - 所有文件路径必须是绝对路径. - - 对于参数中的单引号如"I'm Groot", 使用转义语法: 例如 'I'\''m Groot'(或者尽可能使用双引号: "I'm Groot"). - -2. **澄清意图(动态)**: 推导最多三个初始上下文澄清问题(无预编目录). 它们必须: - - 从用户的表述 + 从规范/计划/任务中提取的信号生成 - - 只询问实质上改变清单内容的信息 - - 如果在`$ARGUMENTS`中已经明确, 则单独跳过 - - 优先考虑精确性而非广度 - - Generation algorithm: - 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). - 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. - 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. - 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. - 5. Formulate questions chosen from these archetypes: - - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") - - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") - - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") - - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") - - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") - - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") - - Question formatting rules: - - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters - - Limit to A–E options maximum; omit table if a free-form answer is clearer - - Never ask the user to restate what they already said - - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." - - Defaults when interaction impossible: - - Depth: Standard - - Audience: Reviewer (PR) if code-related; Author otherwise - - Focus: Top 2 relevance clusters - - Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. - -3. **理解用户请求**: 结合 `$ARGUMENTS` + 澄清答案: - - 推导清单主题(例如: security, review, deploy, ux) - - 整合用户明确提到的必需项目 - - 将焦点选择映射到类别框架 - - 从规范/计划/任务中推断任何缺失的上下文(不要虚构) - -4. **加载功能上下文**: 从 FEATURE_DIR 读取: - - spec.md: 功能需求和范围 - - plan.md(如果存在): 技术细节、依赖关系 - - tasks.md(如果存在): 实施任务 - - **上下文加载策略**: - - 仅加载与活动焦点区域相关的必要部分(避免全文转储) - - 优先将长部分总结为简洁的场景/需求要点 - - 使用渐进式披露: 仅在检测到差距时添加后续检索 - - 如果源文档很大, 生成临时摘要项目而不是嵌入原始文本 - -5. **生成清单** - 创建"需求的单元测试": - - Create `FEATURE_DIR/checklists/` directory if it doesn't exist - - Generate unique checklist filename: - - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) - - Format: `[domain].md` - - If file exists, append to existing file - - Number items sequentially starting from CHK001 - - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists) - - **核心原则 - 测试需求, 而非实现**: - 每个清单项目必须评估需求本身, 检查: - - **完整性**: 所有必要的需求是否存在？ - - **清晰度**: 需求是否明确无歧义且具体？ - - **一致性**: 需求之间是否相互一致？ - - **可测量性**: 需求是否可以客观验证？ - - **覆盖度**: 是否涵盖了所有场景/边缘情况？ - - **类别结构** - 按需求质量维度分组项目: - - **需求完整性**(所有必要的需求是否已记录？) - - **需求清晰度**(需求是否具体且无歧义？) - - **需求一致性**(需求是否一致且无冲突？) - - **验收标准质量**(成功标准是否可测量？) - - **场景覆盖度**(是否涵盖了所有流程/情况？) - - **边缘情况覆盖度**(是否定义了边界条件？) - - **非功能性需求**(性能、安全性、可访问性等 - 是否已指定？) - - **依赖关系和假设**(是否已记录和验证？) - - **歧义和冲突**(什么 NEEDS CLARIFICATION？) - - **如何编写清单项目 - "需求编写的单元测试"**: - - ❌ **WRONG** (Testing implementation): - - "Verify landing page displays 3 episode cards" - - "Test hover states work on desktop" - - "Confirm logo click navigates home" - - ✅ **CORRECT** (Testing requirements quality): - - "Are the exact number and layout of featured episodes specified?" [Completeness] - - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] - - "Are hover state requirements consistent across all interactive elements?" [Consistency] - - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] - - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] - - "Are loading states defined for asynchronous episode data?" [Completeness] - - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] - - **项目结构**: - Each item should follow this pattern: - - Question format asking about requirement quality - - Focus on what's WRITTEN (or not written) in the spec/plan - - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] - - Reference spec section `[Spec §X.Y]` when checking existing requirements - - Use `[Gap]` marker when checking for missing requirements - - **按质量维度分类的示例**: - - 完整性: - - "Are error handling requirements defined for all API failure modes? [Gap]" - - "Are accessibility requirements specified for all interactive elements? [Completeness]" - - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" - - 清晰度: - - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" - - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" - - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" - - 一致性: - - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" - - "Are card component requirements consistent between landing and detail pages? [Consistency]" - - 覆盖度: - - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" - - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" - - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" - - 可测量性: - - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" - - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" - - **场景分类与覆盖度**(需求质量焦点): - - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios - - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" - - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" - - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" - - **可追溯性要求**: - - MINIMUM: ≥80% of items MUST include at least one traceability reference - - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` - - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" - - **发现和解决问题**(需求质量问题): - Ask questions about the requirements themselves: - - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" - - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" - - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" - - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" - - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" - - **内容整合**: - - Soft cap: If raw candidate items > 40, prioritize by risk/impact - - Merge near-duplicates checking the same requirement aspect - - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" - - **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: - - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior - - ❌ References to code execution, user actions, system behavior - - ❌ "Displays correctly", "works properly", "functions as expected" - - ❌ "Click", "navigate", "render", "load", "execute" - - ❌ Test cases, test plans, QA procedures - - ❌ Implementation details (frameworks, APIs, algorithms) - - **✅ REQUIRED PATTERNS** - These test requirements quality: - - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" - - ✅ "Is [vague term] quantified/clarified with specific criteria?" - - ✅ "Are requirements consistent between [section A] and [section B]?" - - ✅ "Can [requirement] be objectively measured/verified?" - - ✅ "Are [edge cases/scenarios] addressed in requirements?" - - ✅ "Does the spec define [missing aspect]?" - -6. **结构参考**: 按照 `.specify/templates/checklist-template.md` 中的规范模板生成清单, 包括标题、元部分、类别标题和 ID 格式. 如果模板不可用, 使用: H1 标题、purpose/created 元行、包含 `- [ ] CHK### ` 行的 `##` 类别部分, ID 从 CHK001 开始全局递增. - -7. **报告**: 输出创建清单的完整路径、项目数量, 并提醒用户每次运行都会创建新文件. 总结: - - 选择的焦点区域 - - 深度级别 - - 执行者/时间 - - 任何整合的用户明确指定的必需项目 - -**重要说明**: 每次 `/speckit.checklist` 命令调用都会创建一个使用简短描述性名称的清单文件, 除非文件已存在. 这允许: - -- 创建多种不同类型的清单(例如: `ux.md`, `test.md`, `security.md`) -- 使用简单、易记的文件名来表明清单用途 -- 在 `checklists/` 文件夹中轻松识别和导航 - -为避免混乱, 请使用描述性类型, 并在完成后清理过时的清单. - -## 示例清单类型和示例项目 - -**UX 需求质量**: `ux.md` - -示例项目(测试需求, 而非实现): -- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" -- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" -- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" -- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" -- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" -- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" - -**API 需求质量**: `api.md` - -示例项目: -- "Are error response formats specified for all failure scenarios? [Completeness]" -- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" -- "Are authentication requirements consistent across all endpoints? [Consistency]" -- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" -- "Is versioning strategy documented in requirements? [Gap]" - -**性能需求质量**: `performance.md` - -示例项目: -- "Are performance requirements quantified with specific metrics? [Clarity]" -- "Are performance targets defined for all critical user journeys? [Coverage]" -- "Are performance requirements under different load conditions specified? [Completeness]" -- "Can performance requirements be objectively measured? [Measurability]" -- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" - -**安全需求质量**: `security.md` - -示例项目: -- "Are authentication requirements specified for all protected resources? [Coverage]" -- "Are data protection requirements defined for sensitive information? [Completeness]" -- "Is the threat model documented and requirements aligned to it? [Traceability]" -- "Are security requirements consistent with compliance obligations? [Consistency]" -- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" - -## 反例: 什么不要做 - -**❌ 错误 - 这些测试实现, 而非需求: ** - -```markdown -- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001] -- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003] -- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010] -- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005] -``` - -**✅ 正确 - 这些测试需求质量: ** - -```markdown -- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] -- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] -- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] -- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] -- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] -- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] -``` - -**关键区别: ** -- 错误: 测试系统是否正常工作 -- 正确: 测试需求是否编写正确 -- 错误: 验证行为 -- 正确: 验证需求质量 -- 错误: "它是否做 X？" -- 正确: "X 是否明确指定？" diff --git a/.claude/commands/speckit.clarify.md b/.claude/commands/speckit.clarify.md deleted file mode 100644 index e5e80cc..0000000 --- a/.claude/commands/speckit.clarify.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -description: 通过提出最多 5 个高度针对性的澄清问题, 识别当前功能规范中未充分说明的领域, 并将答案编码回规范中. -handoffs: - - label: 构建技术计划 - agent: speckit.plan - prompt: 为规范创建计划。我正在构建... ---- - -## 用户输入 - -```text -$ARGUMENTS -``` - -在继续之前, 你**必须**考虑用户输入(如果不为空). - -## 概述 - -目标: 检测并减少活跃功能规范中的模糊性或缺失的决策点, 并将澄清内容直接记录在规范文件中. - -注意: 此澄清工作流应在调用 `/speckit.plan` 之前运行(并完成). 如果用户明确表示他们跳过澄清(例如, 探索性原型), 你可以继续, 但必须警告下游返工风险增加. - -执行步骤: - -1. 从仓库根目录运行 `.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` **一次**(组合 `--json --paths-only` 模式 / `-Json -PathsOnly`). 解析最小 JSON 负载字段: - - `FEATURE_DIR` - - `FEATURE_SPEC` - - (可选捕获 `IMPL_PLAN`、`TASKS` 用于未来的链式流程. ) - - 如果 JSON 解析失败, 中止并指示用户重新运行 `/speckit.specify` 或验证功能分支环境. - - 对于参数中包含单引号的情况(如 "I'm Groot"), 使用转义语法: 例如 'I'\''m Groot'(或优先使用双引号: "I'm Groot"). - -2. 加载当前规范文件. 使用此分类法执行结构化模糊性和覆盖范围扫描. 对于每个类别, 标记状态: 清晰 / 部分 / 缺失. 生成用于优先级排序的内部覆盖范围图(除非不会提问, 否则不输出原始图). - - 功能范围与行为: - - 核心用户目标和成功标准 - - 明确的超出范围声明 - - 用户角色 / 角色区分 - - 领域与数据模型: - - 实体、属性、关系 - - 身份和唯一性规则 - - 生命周期 / 状态转换 - - 数据量 / 规模假设 - - 交互与 UX 流程: - - 关键用户旅程 / 序列 - - 错误 / 空白 / 加载状态 - - 可访问性或本地化说明 - - 非功能性质量属性: - - 性能(延迟、吞吐量目标) - - 可扩展性(水平 / 垂直、限制) - - 可靠性和可用性(正常运行时间、恢复期望) - - 可观察性(日志、指标、追踪信号) - - 安全性和隐私(身份验证 / 授权、数据保护、威胁假设) - - 合规性 / 监管约束(如有) - - 集成与外部依赖: - - 外部服务 / API 和故障模式 - - 数据导入 / 导出格式 - - 协议 / 版本控制假设 - - 边缘情况与故障处理: - - 负面场景 - - 速率限制 / 节流 - - 冲突解决(例如, 并发编辑) - - 约束与权衡: - - 技术约束(语言、存储、托管) - - 明确的权衡或被拒绝的替代方案 - - 术语与一致性: - - 规范术语表术语 - - 避免的同义词 / 已弃用术语 - - 完成信号: - - 验收标准可测试性 - - 可衡量的完成定义风格指标 - - 其他 / 占位符: - - TODO 标记 / 未解决的决策 - - 缺少量化的模糊形容词("robust"、"intuitive") - - 对于每个处于部分或缺失状态的类别, 添加候选问题机会, 除非: - - 澄清不会实质性地改变实施或验证策略 - - 信息更适合推迟到规划阶段(内部记录) - -3. (内部)生成候选澄清问题的优先级队列(最多5个). 不要一次性输出所有问题. 应用这些约束: - - 整个会话最多10个问题. - - 每个问题必须可以用以下任一方式回答: - * 简短的多项选择(2-5个不同的、互斥的选项), 或 - * 单词 / 短语答案(明确约束: "Answer in <=5 words"). - - 仅包含答案实质上影响架构、数据建模、任务分解、测试设计、UX 行为、运营准备或合规性验证的问题. - - 确保类别覆盖平衡: 尝试首先覆盖最高影响的未解决类别; 避免在单个高影响领域(例如, 安全态势)未解决时询问两个低影响问题. - - 排除已回答的问题、琐碎的风格偏好或规划级别的执行细节(除非阻碍正确性). - - 偏好减少下游返工风险或防止不一致验收测试的澄清. - - 如果超过5个类别仍未解决, 通过(影响 * 不确定性)启发式选择前5个. - -4. 顺序提问流程(交互式): - - 一次只提出**确切一个**问题. - - 对于多项选择题: - * **分析所有选项**并基于以下确定**最合适的选项**: - - 项目类型的最佳实践 - - 类似实现中的常见模式 - - 风险降低(安全性、性能、可维护性) - - 与规范中可见的任何明确项目目标或约束的一致性 - * 在顶部突出显示你的**推荐选项**并附上清晰推理(1-2句话解释为什么这是最佳选择). - * 格式为: `**Recommended:** Option [X] - ` - * 然后将所有选项渲染为 Markdown 表格: - - | Option | Description | - |--------|-------------| - | A |