本文汇总 Kiro Specs 的使用最佳实践，涵盖 Feature Specs 的工作流选择（需求优先 vs 设计优先）、如何导入已有设计文档或需求、如何持续迭代 Spec 内容，以及 Bugfix Specs 的 Bug 描述技巧和回归预防方法。还包括团队间共享 Specs 的策略，以及从自由对话生成 Spec 的技巧。

Feature Specs

如何选择工作流？

Feature Specs 支持两种工作流：需求优先（Requirements-First）和设计优先（Design-First）。

选择需求优先的场景：

• 你清楚系统需要实现的行为
• 架构灵活，可以根据需求来设计
• 构建由客户反馈驱动的产品功能
• 无技术约束的绿地项目

选择设计优先的场景：

• 你已有现成的技术设计或架构方案
• 系统需满足严格的非功能性需求（延迟、吞吐量、合规性）
• 原型验证特定技术栈
• 在确定功能范围之前先探索技术可行性

了解更多工作流详情 →

开始后可以切换工作流吗？

不可以，工作流在创建 Spec 时确定。如需切换，请创建一个新的 Feature Spec 并选择所需工作流，必要时可从旧 Spec 中复制相关内容。

同一个项目可以同时使用两种工作流吗？

可以，你可以创建多个 Specs。例如：

1. 用设计优先验证技术可行性
2. 用需求优先开展完整功能开发

如何导入已有设计或架构？

如果你已有架构图或设计文档：

方式一：使用设计优先工作流

1. 创建新的 Feature Spec，选择设计优先
2. 上传架构图（PNG、JPG）或粘贴设计内容
3. Kiro 会将设计正式化为 design.md
4. 从架构中推导需求

方式二：使用图片

从 draw.io、Lucidchart 等工具导出图表，或拍摄白板照片，包含在初始提示词中。

方式三：使用 MCP 集成

如果你的设计工具有 MCP server，可以直接连接并导入设计。

如何导入已有需求文档？

如果需求或设计已存在于其他系统（如 JIRA、Confluence 或 Word 文档）：

方式一：MCP 集成

如果需求管理工具有 MCP server，可直接连接导入，Kiro 同时支持本地和远程 MCP server。

方式二：手动导入

将已有需求（如 foo-prfaq.md）复制到仓库中的新文件，打开 Spec 聊天会话并说 #foo-prfaq.md 从中生成 Spec，Kiro 会读取需求并生成 requirements 和 design 文档。

如何持续迭代 Feature Specs？

Kiro 的 Feature Specs 支持随项目演进持续优化。

需求优先 Spec 的迭代：

1. 更新需求：直接修改 requirements.md，或在 Spec 会话中指示 Kiro 添加新需求或设计元素
2. 更新设计：打开 design.md，选择 Refine，会同时更新设计文档和关联任务列表
3. 更新任务：打开 tasks.md，选择 Update tasks，为新需求生成对应任务

设计优先 Spec 的迭代：

1. 更新设计：直接修改 design.md，或在 Spec 会话中要求 Kiro 更新
2. 更新需求：架构变更后，让 Kiro 验证并重新生成需求，确保需求与架构保持一致
3. 更新任务：打开 tasks.md，选择 Update tasks 反映变更

Bugfix Specs

如何写出好的 Bug 描述？

清晰的 Bug 描述有助于 Kiro 进行准确的根本原因分析，应包含：

1. 复现步骤：描述触发 Bug 的确切条件
2. 当前行为：系统现在的（错误）表现
3. 预期行为：系统应该有的正确表现
4. 约束条件：不应被修改的代码或行为

示例提示词：

当用户在姓名字段中提交含特殊字符的表单时（如 O'Brien），
API 返回 500 错误。系统应接受该输入并正确保存。
邮箱和密码字段的验证逻辑不应受到影响。

如何通过 Bugfix Specs 预防回归？

Bugfix Specs 明确记录"不变行为"和修复方案，在分析阶段，记录必须继续正常工作的内容：

WHEN [条件] THEN 系统 SHALL CONTINUE TO [现有行为]

Kiro 生成属性测试（property-based tests），同时验证修复效果和已有行为的保留，确保修复不会破坏其他功能。

什么时候用 Bugfix Spec，什么时候直接修？

使用 Bugfix Spec 的场景：

• Bug 位于关键代码路径
• 之前的修复尝试导致了回归
• 根本原因不明显
• 需要合规或团队知识留存的文档

直接在聊天中修复的场景：

简单问题，如拼写错误、简单逻辑错误或已完全理解的单行修改。

可以把 Bugfix Spec 转换为 Feature Spec 吗？

不能直接转换。如果根本原因分析发现修复需要引入重大新功能，请为新工作单独创建 Feature Spec，并让 Bugfix Spec 聚焦在原始缺陷上。

通用问题

如何与团队共享 Specs？

Specs 天然支持版本控制，直接将其与代码一起存储在项目仓库中。这样所有项目产物都在一处，需求与实现之间的关联也得到保留。

可以跨多个团队共享 Specs 吗？

可以，通过 Git submodule 或包引用实现跨团队共享：

1. 建立中央 Specs 仓库：创建一个专门存放共享规格说明的仓库，供多个项目引用
2. 使用 Git submodule 或包引用：通过 Git submodule、包引用或符号链接将中央 Specs 关联到各个项目
3. 制定跨仓库工作流：建立提案、审查和更新共享 Specs 的流程

如有跨项目 Spec 管理的特定需求，欢迎在 GitHub issue tracker 上提交，以便优先开发支持该工作流的功能。

可以从自由对话中生成 Spec 吗？

可以。在自由对话中说 生成 Spec，Kiro 会询问是否要开启 Spec 会话，确认后会基于对话上下文生成需求。

可以一次执行所有任务吗？

可以，点击 tasks.md 中的 Run all tasks 按钮即可。注意：只有标记为 required 且尚未完成的任务会被执行。

如何在聊天中引用 Spec？

使用 #spec 上下文提供器：在聊天中输入 #spec 并回车，选择要引用的 Spec。Kiro 会自动将该 Spec 的所有文件（requirements.md、design.md、tasks.md）纳入对话上下文。

示例用法：

#spec:user-authentication 实现任务 2.3
#spec:user-authentication 更新设计文件，加入密码重置流程
#spec:user-authentication 当前实现是否满足任务 7.1 的验收标准？
#spec:user-authentication 为什么选择 JWT 而非 session 认证？

常见问题

Q：Feature Spec 中生成的设计不满足需求怎么办？

检查需求的清晰度和完整性，补充更具体的验收标准，然后从更新后的需求重新生成设计，反复迭代直到设计与需求对齐。

Q：一个仓库中建议创建多少个 Specs？

没有数量限制，建议为不同功能分别创建 Spec。例如一个电商应用可以按功能拆分为 user-authentication、product-catalog、shopping-cart、payment-processing、admin-dashboard 等多个 Specs，便于并行开发和独立追踪。

Q：Bugfix Spec 的"不变行为"文档有什么实际作用？

Kiro 会根据这些约束生成属性测试（PBT），不只验证 Bug 是否被修复，还会验证所有标注为"不变"的行为是否继续正常工作。这是防止修复引入回归的核心机制。