Kiro Spec 指南

什么是规格说明（Specs）？

规格说明（Specs）是结构化的工件，用于规范化应用程序复杂功能的开发过程。它们提供了一种系统化的方法，将高层次的想法转化为详细的实施计划，并具有清晰的跟踪和问责机制。

使用 Kiro 的规格说明，您可以：

• 分解需求为带有验收标准的用户故事
• 构建设计文档，包含序列图和架构计划
• 跟踪实施进度，通过离散的任务进行管理
• 有效协作，在产品和工程团队之间建立桥梁

快速开始

准备创建您的第一个规格说明了吗？以下是开始步骤：

1. 在 Kiro 面板中，点击 Specs 下的 + 按钮。或者，从聊天面板中选择 Spec。
2. 描述您的项目想法。
3. 按照三阶段工作流程进行：需求 → 设计 → 实施。

核心概念

规格说明在概念性产品需求和技术实施细节之间架起桥梁，确保一致性并减少开发迭代。Kiro 生成三个关键文件，构成每个规格说明的基础：

• requirements.md - 使用结构化的 EARS 记号法捕获用户故事和验收标准
• design.md - 记录技术架构、序列图和实施考虑因素
• tasks.md - 提供详细的实施计划，包含离散的、可跟踪的任务

graph TD
    A[产品想法] --> B[需求阶段]
    B --> C[设计阶段]
    C --> D[实施规划]
    D --> E[执行阶段]
    
    B --> F[requirements.md<br/>用户故事和验收标准]
    C --> G[design.md<br/>架构和序列图]
    D --> H[tasks.md<br/>离散实施任务]
    
    F --> I[EARS 记号法<br/>结构化需求]
    G --> J[技术架构<br/>组件交互]
    H --> K[可跟踪任务<br/>明确结果]
    
    style A fill:#e1f5fe
    style F fill:#f3e5f5
    style G fill:#e8f5e8
    style H fill:#fff3e0

工作流程

工作流程遵循逻辑递进，在各阶段之间设有决策点，确保每个步骤在进入下一步之前得到适当完成。

• 需求阶段（最左侧部分）：使用结构化的 EARS 记号法定义用户故事和验收标准
• 设计阶段（第二部分）：记录技术架构、序列图和实施考虑因素
• 实施规划（第三部分）：将工作分解为离散的、可跟踪的任务，具有清晰的描述和结果
• 执行阶段（最右侧部分）：跟踪任务完成进度，能够根据需要更新和完善规格说明

flowchart LR
    subgraph "需求阶段"
        A[定义用户故事] --> B[编写验收标准]
        B --> C[使用 EARS 记号法结构化]
    end
    
    subgraph "设计阶段"
        D[记录架构] --> E[创建序列图]
        E --> F[实施考虑因素]
    end
    
    subgraph "实施规划"
        G[分解任务] --> H[定义明确结果]
        H --> I[设置依赖关系]
    end
    
    subgraph "执行阶段"
        J[跟踪进度] --> K[更新状态]
        K --> L[根据需要完善]
    end
    
    C --> D
    F --> G
    I --> J
    
    style A fill:#ffebee
    style D fill:#e8f5e8
    style G fill:#fff3e0
    style J fill:#e3f2fd

需求文档

requirements.md 文件以用户故事的形式编写，使用 EARS 记号法的验收标准。这正是您希望产品经理给您提供需求的方式！

EARS（需求语法简易方法）记号法为编写清晰、可测试的需求提供了结构化格式。在规格说明的 requirements.md 文件中，每个需求都遵循以下模式：

例如：

这种结构化方法提供了几个好处：

• 清晰性：需求明确无歧义，易于理解
• 可测试性：每个需求都可以直接转化为测试用例
• 可追溯性：个别需求可以在实施过程中进行跟踪
• 完整性：格式鼓励思考所有条件和行为

Kiro 帮助您将模糊的功能请求转化为这些结构良好的需求，使开发过程更加高效，减少产品和工程团队之间的误解。

设计文档

design.md 文件是您记录技术架构、序列图和实施考虑因素的地方。这是捕获系统如何工作的全局视图的绝佳位置，包括组件及其交互。

Kiro 的规格说明为设计文档提供了结构化方法，使理解和协作复杂系统变得更容易。design.md 文件是捕获系统如何工作的全局视图的绝佳位置，包括组件及其交互。

sequenceDiagram
    participant 用户
    participant 前端
    participant API
    participant 数据库
    participant 外部服务
    
    用户->>前端: 发起操作
    前端->>API: 发送请求
    API->>数据库: 查询数据
    数据库-->>API: 返回数据
    API->>外部服务: 处理请求
    外部服务-->>API: 返回响应
    API-->>前端: 发送响应
    前端-->>用户: 显示结果
    
    Note over 用户,外部服务: 典型应用程序的示例序列流程

实施计划

tasks.md 文件是您提供详细实施计划的地方，包含离散的、可跟踪的任务和子任务。每个任务都有清晰的定义，包含明确的描述、预期结果以及任何必要的资源或依赖关系。Kiro 的规格说明为实施计划提供了结构化方法，使理解和协作复杂系统变得更容易。

Kiro 为 tasks.md 文件提供了任务执行界面，显示实时状态更新。任务会更新为进行中或已完成状态，让您能够高效跟踪实施进度并保持开发状态的最新视图。

最佳实践

如何导入现有需求？

如果您的需求或设计已经存在于其他系统中（如 JIRA、Confluence 或 Word 文档），您有两个选择：

1. 使用 MCP 集成：如果您的需求工具有支持 STDIO 的 MCP 服务器，您可以直接连接将需求导入到您的规格说明会话中。

2. 手动导入：只需将您现有的需求（例如 foo-prfaq.md）复制到仓库中的新文件，然后打开规格说明聊天会话并说 #foo-prfaq.md 从中生成规格说明。Kiro 将读取您的需求，并生成需求和设计规格说明。

如何迭代我的规格说明？

Kiro 的规格说明设计用于持续完善，允许您在项目发展过程中更新和增强它们。这种迭代方法确保规格说明与不断变化的需求和技术设计保持同步，为开发提供可靠的基础。

1. 更新需求：直接修改 requirements.md 文件或启动规格说明会话，指示 Kiro 添加新需求或设计元素。

2. 更新设计：导航到您规格说明的 design.md 文件并选择 完善。这个操作将更新设计文档和相关的任务列表，以反映您修改的需求。

3. 更新任务：导航到 tasks.md 文件并选择 更新任务。这将创建映射到新需求的新任务。

规格说明设计为版本控制，使它们在团队中易于共享。将规格说明直接存储在项目仓库中，与它们描述的代码一起。这样可以将所有项目工件保持在一起，并维护需求和实施之间的连接。

是的，您可以通过利用 Git 子模块或包引用在多个团队之间共享规格说明。以下是管理跨团队共享规格说明的一些最佳实践：

1. 创建中央规格说明仓库 - 建立一个专门的仓库用于多个项目可以引用的共享规格说明。

2. 使用 Git 子模块或包引用 - 根据您的开发环境，使用 Git 子模块、包引用或符号链接将您的中央规格说明链接到各个项目。

3. 实施跨仓库工作流程 - 为提议、审查和更新影响多个项目的共享规格说明制定流程。

如果您对跨项目规格说明管理有特定需求，请在我们的 GitHub 问题跟踪器 上分享您的需求，以便我们优先考虑支持您工作流程的功能。

我可以从 vibe 会话开始规格说明会话吗？

可以。您可以进行 vibe 对话，然后说 生成规格说明。Kiro 将询问您是否要开始规格说明会话。如果您同意，它将基于您 vibe 会话的上下文生成需求。

我可以一次性执行规格说明中的所有任务吗？

可以，您可以通过要求 Kiro 代理 执行规格说明中的所有任务 来执行 tasks.md 文件中的所有任务。Kiro 将开始执行您的所有任务。注意：我们不建议这样做，因为我们建议按任务执行以获得更好的结果。

如果某些任务已经实施了怎么办？

在现有代码库上工作时，您可能会发现规格说明中的某些任务已经完成，因为同事或您在另一个会话中已经完成了它。以下是处理这种情况的两种方法：

选项 1：在您的 tasks.md 中点击更新任务

• 打开您的 tasks.md 文件
• 点击 更新任务
• Kiro 将自动标记已完成的任务。

选项 2：让 Kiro 在规格说明聊天会话中为您扫描

• 在规格说明会话中，询问 Kiro："检查哪些任务已经完成"
• Kiro 将分析您的代码库并识别已实施的功能
• Kiro 将自动标记已完成的任务

这样可以保持您的任务规格说明准确。

我可以在单个仓库中有多少个规格说明？

您可以在单个仓库中拥有任意数量的规格说明。我们建议为项目的不同功能创建多个规格说明，而不是试图为整个代码库只有一个规格说明。

例如，在电子商务应用程序中，您可以这样组织规格说明：

这种方法允许您：

• 独立处理功能而不产生冲突
• 维护专注的、可管理的规格说明文档
• 迭代特定功能而不影响其他区域
• 与团队成员同时协作不同功能