最佳实践（Best practices）

我该如何导入已有的需求文档？

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

  1. 使用 MCP 集成：如果你的需求管理工具提供支持 STDIO 的 MCP server，你可以直接连接并将需求导入到你的 spec 会话中。

  2. 手动导入：只需将已有的需求文档（例如 foo-prfaq.md）复制到你的代码库中新建的文件中，然后打开一个 spec 聊天会话并输入 #foo-prfaq.md Generate a spec from it。Kiro 会读取你的需求内容，并自动生成 requirement 和 design 的 spec 文件。

我该如何对我的 spec 进行迭代？

Kiro 的 specification（规范文档）是为持续迭代而设计的，允许你根据项目的进展不断更新和优化。这个迭代过程可以确保规范始终与不断变化的需求和技术设计保持一致，为开发提供可靠的基础。

  1. 更新 Requirements（需求）：你可以直接修改 requirements.md 文件，或者启动一个 spec 会话，指示 Kiro 添加新的需求或设计内容。

  2. 更新 Design（设计）：进入当前 spec 的 design.md 文件并点击 Refine（优化），Kiro 会根据修改后的需求更新设计文档和任务列表。

  3. 更新 Tasks（任务）：进入 tasks.md 文件并选择 Update tasks，Kiro 会根据新的需求生成新的任务列表。

我该如何与团队共享 spec？

spec 文件是为版本控制而设计的，非常适合在团队之间共享。你可以将 spec 文件直接存储在项目代码库中，与代码一起管理。这样做可以让所有项目资料集中管理，确保需求与实现之间始终保持关联。

我可以在多个团队之间共享 spec 吗？

可以。你可以通过使用 Git 子模块（submodule）或包引用的方式，在多个团队之间共享 spec。以下是一些管理跨团队共享 spec 的最佳实践：

  1. 创建中央 spec 仓库：建立一个专门用来存放共享 specification 的仓库，供多个项目引用。

  2. 使用 Git 子模块或包引用：根据你的开发环境，通过 Git 子模块、包引用或符号链接，将中央 spec 链接到各个项目中。

  3. 实施跨仓库的协作流程：建立一套流程，用于提交、审核和更新可能影响多个项目的共享 spec。

如果你对跨项目的 spec 管理有具体的需求，欢迎在我们的 GitHub issue tracker 提出，我们会优先考虑支持相关功能。

我可以从 vibe 会话中启动 spec 会话吗？

可以。在 vibe 会话中你只需输入 Generate spec，Kiro 就会询问你是否要启动一个新的 spec 会话。如果你选择“是”，Kiro 会根据当前 vibe 会话的上下文生成对应的 requirement。

我可以一次性执行 spec 中的所有任务吗？

可以。你只需让 Kiro agent 执行 Execute all tasks in the spec，它就会开始依次执行 tasks.md 文件中所有任务。但我们并不推荐这样做，更建议你逐个任务执行，以获得更好的结果和控制。

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

当你在已有的代码库中工作时，可能会发现 spec 中的一些任务其实已经完成了，可能是你或其他同事在其他会话中实现的。可以用以下两种方式处理这种情况：

方式一：点击 tasks.md 文件中的 Update tasks

  • 打开你的 tasks.md 文件
  • 点击 Update tasks
  • Kiro 会自动标记已完成的任务

方式二：让 Kiro 在 spec 聊天会话中自动扫描

  • 在 spec 会话中，向 Kiro 发送 “Check which tasks are already complete”
  • Kiro 会分析你的代码库并识别已实现的功能
  • Kiro 会自动标记已完成的任务

这样可以保持你的 task spec 的准确性。

我可以在一个 repo 中有多个 spec 吗？

当然可以。你可以在同一个 repo 中创建任意多个 spec。我们推荐你针对每个功能模块单独创建 spec，而不是整个代码库共用一个 spec。

比如在一个电商（e-commerce）应用中，你可以按以下方式组织你的 spec：

  1. .kiro/specs/
  2. ├── user-authentication/       # 登录、注册、密码重置
  3. ├── product-catalog/           # 商品列表、搜索、筛选
  4. ├── shopping-cart/             # 添加购物车、数量更新、结算
  5. ├── payment-processing/        # 支付接口集成、订单确认
  6. └── admin-dashboard/           # 商品管理、用户数据分析

这样的组织方式可以让你：

  • 独立开发各个功能模块，避免冲突
  • 维护结构清晰、内容专一的 spec 文档
  • 单独对某个功能模块进行迭代而不影响其他部分
  • 多个团队成员可以同时处理不同的 spec 文件