用Kiro Specs做生产功能：需求→设计→任务→测试完整工作流

一个功能需求听起来可能非常清晰，但一旦 AI 编程 Agent 开始填补你没说出来的部分，问题就来了。

通过邮件添加密码重置功能。

但 Agent 应该怎么处理令牌的过期？令牌能否二次使用？API 是否应该暴露邮箱地址是否存在？一个账户允许发起多少次重置请求？

如果这些细节缺失，Agent 仍然要构建出什么东西。

于是各种假设就这样进入了代码。

Kiro Specs 提供了一种方式，让我们可以在实现开始之前把这些假设转移到可以阅读的文档中。

在这个演练中，我们将走完一个密码重置功能的完整流程：

需求分析

到结尾，你应该拥有一个可以复用的工作流，适用于身份验证、计费、权限、后台任务，或任何一个小误解就可能扩散到多个文件的场景。

一个 Kiro Feature Spec 可以生成三个文件：

.kiro/specs/password-reset/
├── requirements.md
├── design.md
└── tasks.md

它们各自回答不同的问题。

编码工作在这些层级有了有价值的内容之后才会开始。

而这正是我们要测试的部分。

1. 从一个真实的功能需求开始

在 Kiro CLI 中打开项目。

cd my-saas-app
kiro-cli

/spec new password-reset

选择 Feature Spec，并在这个示例中使用 Requirements-First 工作流。

现在描述这个功能。

先不要描述如何编码。

告诉 Kiro 你想要的行为：

为现有用户添加密码重置功能。

用户应该能够通过邮件请求密码重置，
并使用一次性重置令牌设置新密码。

需求：

- 重置令牌在 15 分钟后过期。
- 令牌不能重复使用。
- 重置请求端点不得暴露邮箱地址是否属于某个账户。
- 重复的重置请求必须被限流。
- 成功和被拒绝的重置尝试都必须可审计。
- 明文密码和重置令牌不得写入日志。

这比下面这个版本强大得多：

添加密码重置功能。

第二个提示词迫使 Agent 去猜测的内容要多得多。

2. 在 Agent 设计任何东西之前审查 requirements.md

Kiro 使用 EARS 风格的需求规范。

一个需求遵循类似这样的结构：

WHEN [condition]
THE SYSTEM SHALL [expected behaviour]

对于我们的功能，requirements.md 可能包含这样的内容：

# Password Reset Requirements

## Reset request

WHEN a user submits an email address to the password-reset endpoint
THE SYSTEM SHALL return the same public response whether or not an account exists

WHEN an existing account requests a password reset
THE SYSTEM SHALL create a one-time reset token

WHEN a reset token is created
THE SYSTEM SHALL make the token expire after 15 minutes

## Password update

WHEN a user submits a valid and unexpired reset token
THE SYSTEM SHALL allow the user to set a valid new password

WHEN a reset token has already been used
THE SYSTEM SHALL reject another password reset using that token

WHEN a reset token has expired
THE SYSTEM SHALL reject the password reset

## Abuse protection

WHEN password-reset requests exceed the configured rate limit
THE SYSTEM SHALL reject further requests for the rate-limit window

## Auditability

WHEN a password-reset attempt succeeds or fails
THE SYSTEM SHALL create an audit event without storing the plaintext password or reset token

这就是我停下来阅读的地方。

不是因为写需求让人兴奋。

而是因为这是发现 Agent 理解的内容与你不同最便宜的地方。

3. 寻找仍然缺失的内容

一份漂亮的需求文件仍然可能是不完整的。

对于密码重置，我会寻找这样的问题：

请求第二个令牌会使第一个失效吗？

密码规则是什么？

密码更改后现有会话应该保持活跃吗？

如果邮件提供商出错了怎么办？

限流应该按账户、邮箱、IP 地址，还是多个维度结合来实施？

审计事件中究竟要写入什么？

过期令牌返回什么响应？

两次重置确认能否产生竞态？

这些在我们阅读 Markdown 时都是小问题。

但当它们出现在多个服务、数据库模型、测试和 API 处理器已经存在之后，就变得昂贵多了。

4. 让 Kiro 分析需求

Kiro CLI 支持 requirements-analysis 命令：

/spec analyze_requirements password-reset

分析会在需求集中查找诸如：

冲突的约束

逻辑不一致

例如，假设一个需求说：

A reset token is valid for 15 minutes.

但没有任何内容说明创建另一个令牌是否会使第一个失效。

这是一个隐藏在看似完整的需求内部的真实产品行为。

这种分析可以在设计开始之前浮出类似的问题。

对于一个非常小的功能，这额外的步骤可能是不必要的。

但对于身份验证、支付、权限、客户积分或有多个失败状态的工作流，这几分钟是值得花的。

5. 审查技术设计

一旦行为清晰了，就进入设计阶段。

对于这个功能，一份有用的 design.md 应该解决这样的问题：

Endpoints

POST /auth/password-reset/request
POST /auth/password-reset/confirm

还应该描述重置令牌的行为：

Reset token

- generated using a cryptographically secure random value
- plaintext token sent to the user
- only a hash stored in the database
- expires after 15 minutes
- single use

以及周围的组件：

PasswordResetService
EmailService
RateLimiter
AuditService
UserRepository
ResetTokenRepository

具体架构取决于你的应用。

审查设计时有用的关键是：

Kiro 是否复用了这个仓库中已存在的模式？

如果你的应用已经有了邮件服务、审计系统、限流器或令牌工具，设计不应该悄悄地为这个功能再创建一套重复的东西。

6. 让实现任务足够小以便审查

Kiro 然后生成 tasks.md。

对于这个功能，一个有用的任务列表可能长这样：

# Implementation Tasks

- [ ] 1. Add password-reset token persistence
  - store a token hash
  - store expiration time
  - store consumed state

- [ ] 2. Add password-reset request service
  - generate a secure token
  - apply rate limiting
  - send reset email
  - return the same public response for existing and unknown emails

- [ ] 3. Add password-reset confirmation service
  - verify token hash
  - verify expiration
  - verify token has not already been consumed
  - validate new password
  - update password
  - consume token

- [ ] 4. Add audit events
  - reset requested
  - reset completed
  - reset rejected

- [ ] 5. Add API endpoints

- [ ] 6. Add tests
  - successful reset
  - expired token
  - reused token
  - unknown email
  - repeated requests
  - invalid password

对比这个版本：

Implement password reset.

第一个版本给了我们检查点。

第二个版本给 Agent 的是一个巨大的区域，让它在其中自行做假设。

一旦需求、设计和任务列表看起来没问题了：

/spec run password-reset

Kiro 验证 tasks.md 存在，然后按顺序处理任务。

如果实现开始朝错误方向移动，你可以中断执行。

这也给了代码审查一个更清晰的参考。

这个实现看起来合理吗？

这个实现是否满足重置令牌只能使用一次的需求？

这是一个更容易测试的问题。

8. 保留你正常的测试

Agent 的工作流应该放在你现有的工程检查旁边。

它不应该取代它们。

对于一个 Node.js 项目，这可能仍然意味着：

npm test
npm run lint
npm run typecheck

然后添加映射回 Spec 中行为的测试。

使用 Vitest 或 Jest，结构可能长这样：

describe("password reset", () => {
  it("rejects an expired reset token", async () => {
    const token = await createResetToken({
      expiresAt: new Date(Date.now() - 1000),
    });

    const result = await resetPassword({
      token,
      password: "A-Valid-New-Password-123",
    });

    expect(result.ok).toBe(false);
    expect(result.code).toBe("RESET_TOKEN_EXPIRED");
  });

  it("allows a valid token only once", async () => {
    const token = await createValidResetToken();

    const first = await resetPassword({
      token,
      password: "A-Valid-New-Password-123",
    });

    const second = await resetPassword({
      token,
      password: "Another-Valid-Password-123",
    });

    expect(first.ok).toBe(true);
    expect(second.ok).toBe(false);
  });
});

这里的函数名是示例。你的仓库会有自己的服务和测试辅助工具。

重要的是测试现在有了一个共同认可的行为来验证。

9. Quick Spec 在功能已经清晰时很有用

完整的 Requirements-First 工作流并非对每个变更都必要。

Kiro 也提供 Quick Spec。

它在开始时提出澄清问题，然后一次性生成：

requirements.md
design.md
tasks.md

各阶段之间没有审批关卡。

这对于以下场景很合适：

为现有表格添加 CSV 导出

扩展一个已建立的 CRUD 流程

使用仓库中已有的模式添加另一个 API 端点

在熟悉的管理工作流中添加一个字段

对于身份验证、计费、权限或有多个失败状态的功能，我通常希望有更多空间来审查 Agent 认为这个功能意味着什么。

不同的任务应该配以不同量的结构。

10. Kiro 也支持 Design-First Specs

Requirements-First 不是唯一的 Feature Spec 工作流。

如果技术约束已经固定，Kiro 可以从设计开始。

当你已经知道以下内容时，这样做更有意义：

所需的数据库

云架构

延迟或吞吐量要求

合规约束

现有的低级设计

流程就变成了：

Design
↓
Requirements
↓
Tasks
↓
Implementation

所以 Specs 不必意味着"产品需求总是优先"。

起点可以与你实际面对的问题类型相匹配。

11. 一个值得了解的最新限制

Kiro 还记录了属性测试，用于检查实现是否与 Spec 中描述的行为匹配。

目前，Kiro 的文档将该功能标记为在 IDE 中可用，而非 CLI。

因此，如果你遵循这个精确的 CLI 演练，请继续保持你正常的自动化测试。

如果你使用 Kiro IDE，属性正确性检查是你可以探索的另一层。

经济效益体现之处

OpenAI 在 8 月 24 日发布了关于 Kiro 中 GPT-5.6 的更新。

在与 AWS 一起在 Terminal-Bench 2.1 上测试时，OpenAI 报告称 GPT-5.6 Terra 在 Kiro 中以大约低 82% 的成本完成了该基准测试中的成功任务。

我不会把 82% 变成对真实客户代码库的估算。

你的仓库、任务大小、测试质量、模型选择、上下文和需求都可能改变结果。

对于真实的开发工作，我更愿意追踪：

Agent 需要多少次纠正？

因为需求变更有多少文件被重写了？

第一次实现是否通过了预期的测试？

这个任务需要多少审查时间？

代码实际可合并之前需要多少 AI 使用量？

这些数字描述的是你的开发过程。

基准测试描述的是别人的测试环境。

值得保持的模式

Spec 最有益的部分不是它们创建了三个 Markdown 文件。

而是有机会在误解仍然容易更改的时候暴露它。

Feature request
      ↓
Requirements
      ↓
Design
      ↓
Tasks
      ↓
Implementation
      ↓
Verification

在 Ascent Innovate Software，这种结构在隐藏行为重要的功能周围最有意义：身份验证、使用规则、计费状态、权限、后台处理和类似的工作流。

对于微小的变更，保持流程轻量。

对于一个缺失一个条件就可能扩散到产品多处的功能，先让意图可见可以节省大量不必要的返工。

OpenAI: Advancing price-performance for developers with GPT-5.6 in Kiro

Kiro: Requirements-First workflow

Kiro: Analyze Requirements

Kiro: Correctness with Property-based Tests

技术声明、Kiro 命令、工作流细节、代码示例和最终文章在发布前已根据当前 OpenAI 和 Kiro 文档进行了审查。