# /spec-kitty.specify - 创建功能规范 **版本**：0.11.0+ ## 📍 工作目录：保留在计划存储库中 **重要**：指定规划存储库中的工作。没有创建工作树。 # 从项目根目录运行： cd /path/to/project/root # 您的规划存储库 # 所有规划工件都在规划存储库中创建并提交： # - kitty-specs/###-feature/spec.md → 在规划存储库中创建 # - 提交到目标分支 (meta.json → target_branch) # - 没有创建工作树 **工作树稍后在`/spec-kitty.implement`期间创建**，而不是在规划期间。 ## 用户输入 $参数在继续之前，您**必须**考虑用户输入（如果不为空）。 ## 发现门（必填）在运行任何脚本或写入磁盘之前，您**必须**进行结构化发现访谈。 * **范围相称性（关键）**：首先，衡量请求的固有复杂性： * **琐碎/测试功能**（hello world、简单页面、概念验证）：最多询问 1-2 个问题，然后继续。示例：“一个简单的 hello world 页面”、“tic-tac-toe 游戏”、“基本联系表” * **简单功能**（小的 UI 添加、细微的增强）：询问 2-3 个涵盖目的和基本限制的问题 * **复杂功能**（新子系统、集成）：提出 3-5 个问题，涵盖目标、用户、约束、风险 * **平台/关键功能**（身份验证、支付、基础设施）：通过 5 个以上问题进行全面发现 * **用户发出减少质疑的信号**：如果用户说“只是测试”、“快速原型”、“跳到下一阶段”、“停止提问” - 将此视为减少发现并继续使用合理默认值的信号。 * **第一响应规则** : * 对于简单的功能（你好世界，简单的测试）：问一个澄清问题，然后如果答案确认它很简单，则直接进行规范生成 * 对于其他功能：提出一个集中的发现问题并以“WAITING_FOR_DISCOVERY_INPUT”结尾 * 如果用户没有提供初始描述（空命令），请保持**交互式访谈模式**：一次继续探究一个问题。 * **对话节奏**：在每个用户回复后，确定您是否有足够的上下文来支持此功能的复杂程度。对于琐碎的功能，1-2 个问题就足够了。仅在范围确实必要时才继续询问。发现要求（根据功能复杂性进行扩展）： 1. 在内部维护一个**发现问题**表，涵盖与功能复杂性相应的问题（1-2 个简单问题，最多 5 个以上复杂问题）。跟踪“#”、“问题”、“为什么重要”和“当前见解”列。 **不要**将此表呈现给用户。 2. 对于琐碎的功能，合理的默认值是可以接受的。仅在确实模棱两可时进行探究。 3. 当您对功能范围有足够的上下文时，将其解释为**意图摘要**并确认。对于琐碎的功能，这可能非常简短。 4. 如果用户明确要求跳过问题或说“只是测试”，请确认并以最少的发现继续进行。 ## 任务选择完成发现并确认意图摘要后，确定此功能的适当任务。 ### 可用任务 * **software-dev** ：用于构建软件功能、API、CLI 工具、应用程序 * 阶段：研究→设计→实施→测试→审查 * 最适合：代码更改、新功能、错误修复、重构 * **研究**：用于调查、文献综述、技术分析 * 阶段：问题→方法论→收集→分析→综合→发布 * 最适合：可行性研究、市场研究、技术评估 ### 任务推理 1. **分析功能描述**以确定主要目标： * 构建、编码、实施、创建软件 → **软件开发** * 研究、调查、分析、评估 → **研究** 2. **检查用户描述中是否有明确的任务请求**： * 如果用户提到“研究项目”、“调查”、“分析”→使用研究 * 如果用户提到“构建”、“实施”、“创建功能”→ 使用软件开发 3. **与用户确认**（除非明确）： > “根据你的描述，这听起来像是一个 **[软件开发/研究]** 项目。我将使用 **[任务名称]** 任务。这对你有用吗？” 4. **处理用户响应**： * 如果确认：继续执行选定的任务 * 如果用户想要不同的任务：使用他们的选择 5. **处理 --mission 标志** ：如果用户在命令中提供 `--mission `，则跳过推理并直接使用指定的任务。将最终的任务选择存储在笔记中，并将其包含在规范输出中。不要将“--mission”标志传递给功能创建。 ## 工作流程 (0.11.0+) **规划发生在规划存储库中 - 未创建工作树！** 1. 直接在规划仓库中创建 `kitty-specs/###-feature/spec.md` 2.自动提交到目标分支 3.指定期间没有创建工作树 **稍后创建的工作树** ：使用 `spec-kitty Implement WP##` 为每个工作包创建一个工作区。工作树稍后在实施过程中创建（例如“.worktrees/###-feature-WP##”）。 ## 地点 * 工作于：**规划存储库**（不是工作树） * 创建：`kitty-specs/###-feature/spec.md` * 提交到：目标分支 (`meta.json` → `target_branch`) ## 概要 ### 0\.生成友好的功能标题 * 将商定的意图总结为简短的描述性标题（目标是≤7 个单词；避免使用“功能”或“事物”等填充词）。 * 在意图摘要期间读回该标题，并在用户请求更改时对其进行修改。 * 使用已确认的标题为 create-feature 命令派生 kebab-case 功能 slug。用户在触发消息中的“/spec-kitty.specify”之后输入的文本**是**初始功能描述。逐字捕捉它，但仅将其视为发现的起点，而不是最终的真相。您的工作是询问请求、表面差距，并与用户共同创建完整的规范。鉴于该功能描述，请执行以下操作： * **生成模式（提供参数）** ：使用提供的文本作为起点，通过发现来验证它，并用明确的问题或明确记录的假设来填补空白（将“[需要澄清：...]”限制为最多三个用户推迟的关键决策）。 * **交互式访谈模式（无参数）** ：使用发现访谈来引出所有必要的上下文，综合工作功能描述，并在生成任何规范工件之前与用户确认。 1. **检查发现状态** : * 如果这是您的第一条消息或发现问题仍未得到解答，请停留在单问题循环中，捕获用户的响应，更新您的内部表，并以“WAITING_FOR_DISCOVERY_INPUT”结束。 **不要**把桌子摆在表面；将其保留在内部。 **不要**调用创建命令。 * 只有在每个发现问题都有明确答案并且用户已确认意图摘要后才继续。 * 空调用规则：保持面试模式，直到您可以重述商定的功能描述。当描述丢失或临时时，**不要**调用创建命令。 2. 发现完成并确认意图摘要、 **title** 和 **mission** 后，从存储库根目录运行功能创建命令： spec-kitty 代理功能 create-feature "" --json 其中 `` 是友好标题的短横线版本（例如，“Checkout Upsell Flow”→“checkout-upsell-flow”）。该命令返回 JSON： * `result`: “成功”或错误消息 * `feature`：功能编号和别名（例如“014-checkout-upsell-flow”） * `feature_dir`：主仓库内功能目录的绝对路径解析这些值以在后续步骤中使用。所有文件路径都是绝对路径。 **重要**：您只能运行此命令一次。 JSON 在终端输出中提供 - 请始终引用它来获取您要查找的实际路径。 3. **保留在主存储库中**：指定期间不会创建工作树。 4. 规范模板捆绑在该项目的“.kittify/missions/software-dev/templates/spec-template.md”中。该模板定义了软件开发功能所需的部分。 5. 在功能目录中创建meta.json： { "feature_number": "<数字>", "slug": "<全slug>", "friend_name": "<友好标题>", "mission": "<选定的任务>", "source_description": "$ARGUMENTS", "created_at": "", "target_branch": "<当前分支>", “vcs”：“git” } **关键**：始终明确设置这些字段： * `target_branch`：设置为当前分支（通过 `gitbranch --show-current` 检测到） * `vcs`：默认设置为“git”（启用 VCS 锁定并防止 jj 回退） 6. 按照以下流程生成规范内容： * 使用发现答案作为权威的事实来源（不要**依赖原始的“$ARGUMENTS”） * 对于空调用，将综合采访摘要视为规范特征描述 * 识别：参与者、行动、数据、约束、动机、成功指标 * 对于任何剩余的歧义： * 立即向用户询问一个有针对性的后续问题，并停止工作直到他们回答 * 仅当用户明确推迟决定时才使用“[需要澄清：...]” * 在假设部分记录任何临时假设 * 按影响优先澄清：范围 > 结果 > 风险/安全 > 用户体验 > 技术细节 * 填写用户场景和测试部分（如果无法确定明确的用户流程，则会出现错误） * 生成功能需求（每个需求必须是可测试的） * 定义成功标准（可衡量的、与技术无关的结果） * 识别关键实体（如果涉及数据） 7. 使用模板结构将规范写入“/spec.md”，用从功能描述中派生的具体细节替换占位符，同时保留部分顺序和标题。 8. **规格质量验证**：编写初始规格后，根据质量标准对其进行验证：一个。 **创建规格质量检查表** ：使用具有以下验证项的检查表模板结构在 `feature_dir/checklists/requirements.md` 生成检查表文件： # 规格质量检查表：[功能名称] **目的**：在进行规划之前验证规范的完整性和质量 **创建**：[日期] **功能**：[链接到spec.md] ## 内容质量 - [ ] 没有实现细节（语言、框架、API） - [ ] 关注用户价值和业务需求 - [ ] 为非技术利益相关者编写 - [ ] 已完成所有必填部分 ## 需求完整性 - [ ] 没有保留任何[需要澄清]标记 - [ ] 要求是可测试的且明确的 - [ ] 成功标准是可衡量的 - [ ] 成功标准与技术无关（无实施细节） - [ ] 定义所有接受场景 - [ ] 识别边缘情况 - [ ] 范围有明确界限 - [ ] 确定的依赖性和假设 ## 功能准备情况 - [ ] 所有功能需求都有明确的验收标准 - [ ] 用户场景覆盖主流流程 - [ ] 功能满足成功标准中定义的可衡量结果 - [ ] 规范中没有泄漏实现细节 ## 注释 - 标记为不完整的项目需要在`/spec-kitty.clarify`或`/spec-kitty.plan`之前更新规范 b. **运行验证检查**：针对每个清单项目检查规范： * 对于每个项目，确定它是通过还是失败 * 记录发现的具体问题（引用相关规范部分） c. **处理验证结果**： * **如果所有项目均通过** ：将清单标记为已完成并继续执行步骤 6 * **如果项目失败（不包括[需要澄清]）**： 1. 列出失败的项目和具体问题 2. 更新规范以解决每个问题 3. 重新运行验证，直到所有项目都通过（最多 3 次迭代） 4. 如果 3 次迭代后仍然失败，请在清单注释中记录剩余问题并警告用户 * **如果[需要澄清]标记仍然存在**： 1. 从规范中提取所有 [NEEDS CLARIFICATION: ...] 标记 2. 与用户重新确认每个未完成的决策是否确实需要悬而未决。不要假设忽略关键差距。 3. 对于用户明确推迟的每项澄清，使用纯文本（无表格）呈现选项：问题[N]：[主题] 上下文：[引用相关规范部分] 需要：[NEEDS CLARIFICATION 标记中的具体问题] 选项： (A) [第一个答案 — 影响] · (B) [第二个答案 — 影响] · (C) [第三个答案 — 影响] · (D) 自定义（描述您自己的答案）用信件或自定义答案回复。 4. 按顺序对问题编号（Q1、Q2、Q3 - 最多 3 个） 5. 在等待答复之前将所有问题集中提出 6. 等待用户回答所有问题的选择（例如“Q1：A，Q2：自定义 - [详细信息]，Q3：B”） 7. 通过用用户选择或提供的答案替换每个 [NEEDS CLARIFICATION] 标记来更新规范 8. 解决所有问题后重新运行验证 d. **更新检查表** ：每次验证迭代后，用当前的通过/失败状态更新检查表文件 9. 报告完成情况，包括功能目录、规范文件路径、清单结果以及下一阶段的准备情况（“/spec-kitty.clarify”或“/spec-kitty.plan”）。 **注意：** 该脚本创建并签出新分支，并在写入之前初始化规范文件。 ## 一般准则 ## 快速指南 * 关注**用户需要什么**以及**为什么**。 * 避免如何实现（没有技术堆栈、API、代码结构）。 * 为业务利益相关者而非开发人员编写。 * 不要创建任何嵌入在规范中的清单。这将是一个单独的命令。 ### 部分要求 * **必填部分**：必须为每个功能完成 * **可选部分**：仅在与功能相关时包含 * 当某个部分不适用时，将其完全删除（不要保留为“N/A”） ### 对于人工智能一代从用户提示创建此规范时： 1. **做出明智的猜测**：使用背景、行业标准和常见模式来填补空白 2. **记录假设**：在假设部分记录合理的默认值 3. **限制澄清**：最多 3 个 [需要澄清] 标记 - 仅用于以下关键决策： * 显着影响功能范围或用户体验 * 有多种合理的解释，具有不同的含义 * 缺乏任何合理的默认 4. **优先澄清**：范围>安全/隐私>用户体验>技术细节 5. **像测试人员一样思考**：每个模糊的需求都应该不符合“可测试且明确”清单项 6. **需要澄清的常见领域**（仅当不存在合理默认值时）： * 功能范围和边界（包括/排除特定用例） * 用户类型和权限（如果可能存在多种相互冲突的解释） * 安全/合规性要求（当具有法律/财务意义时） **合理默认值的示例**（不要询问这些）： * 数据保留：该领域的行业标准实践 * 性能目标：标准 Web/移动应用程序期望（除非另有说明） * 错误处理：用户友好的消息以及适当的后备措施 * 身份验证方法：基于标准会话或适用于 Web 应用程序的 OAuth2 * 集成模式：除非另有说明，否则采用 RESTful API ### 成功标准指南成功的标准必须是： 1. **可衡量**：包括具体指标（时间、百分比、计数、比率） 2. **与技术无关**：没有提及框架、语言、数据库或工具 3. **以用户为中心**：从用户/业务角度描述结果，而不是系统内部 4. **可验证**：可以在不知道实现细节的情况下进行测试/验证 **好例子**： *“用户可以在3分钟内完成结账” *“系统支持10000个并发用户” *“95% 的搜索在 1 秒内返回结果” *“任务完成率提高40%” **不好的例子**（以实现为重点）： *“API响应时间低于200毫秒”（技术性太强，使用“用户立即看到结果”） *“数据库可以处理 1000 TPS”（实现细节，使用面向用户的指标） *“React 组件高效渲染”（特定于框架） * “Redis缓存命中率80%以上”（技术特定）

规格 Kitty 指定

包含技能