intent-driven-development

Intent-Driven Development

产出有用的验收标准，而不是把规格变成仪式。先检查可用上下文，暴露真实歧义，并选择适合工作本身及其风险的验证方法。

何时激活

• 用户要求在实现前澄清 feature、定义验收标准，或给变更降风险
• 请求触及 security、authentication、persistent data、migrations、external APIs 或 compliance
• 用户想为另一个智能体或团队准备 handoff artifact
• 请求足够含糊，期望结果尚不可观察或不可测试
• 用户用 /intent-driven-development 显式调用

不要在琐碎编辑、直接的单行修复、活跃调试会话、代码审查请求，或验收条件已清楚的实现请求上激活。

工作方式

1. 先检查上下文 — 读取 repository、docs、schemas 和测试基础设施的技术事实，然后再问任何问题；但把产品/业务约束视为只能由用户或产品 artifact 提供
2. 选择深度 — 按风险画像选择 Quick Capture（3-7 条标准，低/中风险）或 Full Acceptance Brief（安全、数据、迁移、跨系统变更）
3. 最少提问 — 只问那些无法推断且实质改变 scope 或行为的问题
4. 写可观察标准 — 每条 AC-NNN 描述起始条件、触发、期望结果、禁止的副作用、验证方法和优先级；不使用没有证据的 “correctly” 或 “securely” 等模糊词
5. 继续或交接 — 对没有阻塞风险的清晰请求，记录标准并继续；对有风险的变更，呈现 blockers 并等待确认
6. 处理修订 — 如果某条 AC 在实现中因架构约束失败，标记 [revised]，更新 scope 或验证方法，递增修订号，并只重新呈现变更的标准

示例

Quick Capture — “Add CSV export to the dashboard”

Goal: Authenticated users can download dashboard data as a CSV file.
In scope: Export of currently filtered rows; filename includes date.
Out of scope: Scheduled exports, email delivery, Excel format.
Assumptions: Max row count is under 10k; no PII in exported fields.

AC-001: Export generates file with correct headers
- Scenario: authenticated user, at least one data row visible
- Action: click "Export CSV"
- Expected: browser downloads file with columns [id, name, created_at]
- Must not: expose internal fields or rows belonging to other users
- Verification: automated integration test + manual schema spot-check
- Priority: Required

Full Acceptance Brief 触发 — “Migrate user auth to OAuth”

Auth 变更 + 外部依赖 + 已有 session 数据 → Full Brief，含 Risk Review 表、session invalidation 策略的 blocking decisions，以及显式 rollback AC。

现有 spec 审查 — 用户粘贴 PRD

技能审查它是否缺少 scope 边界、不可验证的要求（“the system shall be fast”）和静默假设，然后返回修正或补充的标准，无需重新开始 discovery。

运行规则

1. 在询问可在本地发现的技术事实前，先检查可用 repository、文档、issue、设计和测试上下文。
2. 不要从代码推断产品或业务约束。业务规则、compliance 与监管义务、合同 SLA、定价、data-retention policy、优先级和目标用户无法从 repository 读出。在用户提供它们或权威产品 artifact（PRD、合同、policy 文档）说明之前，把它们视为未知。把它们记录为待确认的假设，绝不是已发现事实。Repository 告诉你系统今天如何表现，而不是业务要求它做什么。
3. 只问那些答案必需且无法安全推断的问题。把短而相关的问题分组，节省多余轮次。
4. 默认不要阻塞实现。当用户要求实现一个足够清晰的变更时，简要记录关键假设和验收标准，然后继续或交给实现工作流。
5. 只有当未解决的决策可能造成重大安全暴露、数据丢失、不可逆迁移、合同/API 破坏、重大成本或破坏性外部操作时，才要求用户显式确认后再继续。
6. 不要把验收文档写进 repository、修改项目文件、创建 branch、commit 或调用其他技能，除非用户要求或活跃的 repository 工作流明确需要。
7. 把自动化测试视为证据，不是真理。可靠且成比例时优先自动化；在自动化无法确立结果时，允许人工 UX、可访问性、安全、法律或运维验证。
8. 绝不在验收标准、fixtures、示例或保存的 artifact 中包含真实 secrets、credentials、tokens、私钥、个人数据或敏感生产 payload。使用脱敏或合成值。
9. 未经明确授权和已识别的安全环境，不要运行破坏性测试、迁移、安全探测、负载测试、付费外部调用，或针对生产/线上数据的操作。
10. 当某条验收标准因实现中发现的架构、平台或外部约束无法满足时，不要静默丢弃或 workaround。更新受影响标准（标记 [revised]、说明约束、调整 scope 或验证方法），递增修订号，并只把变更后的标准重新呈现给用户后再继续。只有当修订改变 blocking decision 或实质降低安全或正确性保证时，才要求显式确认。

选择深度

使用最小有用输出。

Quick Capture

用于清晰但非平凡的变更，风险低或中。产出：

• Goal
• In scope / out of scope
• Assumptions
• 3-7 条带验证方法的验收标准
• Blocking questions（如有）

除非存在运行规则中的 blocking 风险，或用户特别要求先出规格，否则不要为批准而延迟实现。

Full Acceptance Brief

用于含糊、跨系统、安全敏感、改数据、迁移、compliance 或高成本变更，或用户要求 handoff artifact。产出下方完整模板，并在有风险的实现前对未解决的 blocking decisions 请求确认。

现有规格审查

当用户已提供 PRD、issue、plan 或验收标准时：

1. 审查它，而不是重启 discovery。
2. 识别缺少的 scope 边界、不安全假设、矛盾和不可验证要求。
3. 返回修正或补充标准。

工作流

1. 确立 Goal 和风险

提取或询问：

• 用户或系统的可观察结果。
• 受影响的 actors。
• 主要失败后果。
• 实际适用的风险维度：security/privacy、persistent data、compatibility/API、migration、external dependencies、cost、concurrency、performance、usability/accessibility。

避免问关于无关风险的通用问题。

2. 发现上下文

当本地或关联 artifact 可用时，只检查所需部分：

• 现有行为和直接相关文件或接口。
• repository 约定、产品文档、API contracts、数据 schemas 或迁移历史。
• 现有验证基础设施和现实命令。
• 外部依赖以及它们是否可隔离测试。

把已发现事实与用户提供的假设分开记录。如果上下文无法检查，说明什么是未知的并提聚焦问题。

Repository 揭示技术事实——系统今天如何表现、它的约定和 contracts。它不揭示产品或业务约束：业务规则、compliance 与监管义务、合同 SLA、定价、data-retention policy、优先级和目标用户。绝不从代码或命名重建它们。只从用户或权威产品 artifact 捕获它们，并在那之前列为待确认假设。

3. 定义 scope

说明：

• Goal：一句话描述预期结果。
• In scope：此变更必须交付的行为。
• Out of scope：明确排除的诱人相邻工作。
• Assumptions：尚未证实的声明。
• Blocking decisions：实质影响安全或行为的未解决选择。

4. 写验收标准

使用 AC-001、AC-002 等。每条标准必须描述可观察行为和恰当验证方法；标准和测试不必一一对应。

对每条适用标准包含：

• Scenario 或起始条件。
• Action 或触发。
• Expected 可观察行为。
• Prohibited 副作用（有意义时）。
• Verification method：automated test、integration check、manual UX review、accessibility check、security review、operational check 或 stakeholder acceptance。
• Environment/safety 约束（当验证可能影响数据、服务、成本或 secrets 时）。
• Priority：required、important 或 optional。

不要使用 “correctly”、“securely”、“fast”、“intuitive” 或 “robust” 等词，除非定义了可观察证据或记录为人工审查判断。

5. 只覆盖相关边界

考虑这些类别，但只纳入适用的：

类别	何时纳入	典型证据
Happy path	新增或变更的用户可见行为	成功 workflow 或状态转移
Validation	变更接受输入	拒绝畸形或边界值且不发生 mutation
Authorization/privacy	数据或操作有访问边界	拒绝访问且不泄漏敏感信息
Persistence/migration	存储数据或 schemas 变更	向后读取、迁移、rollback 或备份行为
Compatibility	公共 API、文件、事件或客户端可能破坏	现有 contract 或 fixture 仍有效
Failure recovery	存在网络、服务或异步失败	无部分状态，或有清晰 retry/degraded 行为
Idempotency/concurrency	重复或同时写入可能发生	无重复副作用或无效终态
Performance	某个用户或服务阈值重要	定义测量条件和阈值
UX/accessibility	有人与结果交互	键盘、反馈、错误恢复、视觉/人工审查

6. 呈现并继续

• 对澄清/规格请求，呈现 brief 并只对列出的 blockers 请求决策。
• 对无 blocker 的实现请求，呈现紧凑标准摘要作为工作一部分并继续实现。
• 对交接给另一个智能体或团队，包含足够上下文和验证细节，使他们无需发明需求即可行动。
• 只在请求时把 brief 保存到文件。当存在 repository 批准的路径时使用它；否则在写入前询问或说明所选目标。

输出模板

对 Full Acceptance Brief 使用此模板。Quick Capture 时省略无关 sections。

# Acceptance Brief: <Change Name>

**Status:** Draft | Approved | Implemented | Verified
**Revision:** <number>
**Prepared for:** <user/team/agent, when known>
**Approval required before risky work:** Yes | No - <reason>

## Revision Log

| Rev | Date | Changed criteria | Reason |
| --- | --- | --- | --- |
| 1 | <date> | — | Initial draft |

## Goal

<One observable outcome sentence.>

## Scope

**In scope**
- <behavior included>

**Out of scope**
- <adjacent work excluded>

## Context

**Discovered facts** (technical, verified from repository or artifact)
- <how the system behaves today, conventions, contracts>

**Product/business constraints** (supplied by user or product artifact, never inferred from code)
- <business rule, compliance/SLA obligation, retention policy, priority, target user — or "none supplied yet">

**Assumptions**
- <unverified claim to confirm or validate>

**Dependencies and constraints**
- <external service, local convention, compatibility obligation, environment limit>

## Risk Review

| Risk area | Applies? | Required handling |
| --- | --- | --- |
| Security/privacy | Yes/No | <redaction, authorization, review, etc.> |
| Persistent data/migration | Yes/No | <compatibility, backup, rollback, etc.> |
| External effects/cost | Yes/No | <sandbox/test environment/authorization> |
| Compatibility/API | Yes/No | <contract to preserve or version> |
| UX/accessibility | Yes/No | <manual or automated evidence> |

## Acceptance Criteria

### AC-001: <observable behavior>
- **Scenario:** <starting condition>
- **Action:** <single trigger>
- **Expected:** <observable result>
- **Must not:** <prohibited side effect, if applicable>
- **Verification:** <method and intended evidence>
- **Environment/safety:** <constraints, if applicable>
- **Priority:** Required | Important | Optional

## Blocking Decisions

- [ ] <only decisions that prevent safe or correct progress>

## Verification Plan

| Criterion | Verification evidence | Status |
| --- | --- | --- |
| AC-001 | <test/check/review command or evidence type> | Pending |

通过/失败示例

用这些判断技能是否真的产出了可验证 brief，而不是 planning prose。

失败的验收标准

AC-001: The export works correctly and is secure.

失败——“works correctly” 和 “secure” 不可观察，没有 scenario、trigger、expected result 或 verification method，也没有说明什么绝不能发生。读者无法判断实现是否满足了它。

通过的验收标准

AC-001: Export generates file with correct headers
- Scenario: authenticated user, at least one data row visible
- Action: click "Export CSV"
- Expected: browser downloads file with columns [id, name, created_at]
- Must not: expose internal fields or rows belonging to other users
- Verification: automated integration test + manual schema spot-check
- Priority: Required

通过——一个具体可观察结果、一个禁止副作用，以及一个命名验证方法。两个人会就是否满足达成一致。

失败的 context 条目

Discovered facts: Users on the free tier are limited to 100 exports per month.

失败——按 tier 限制是业务规则。它不能作为从代码推断的 discovered facts 出现；它属于 Product/business constraints，由用户提供，或列为待确认假设。

通过/失败 rubric

只有当每个答案是 “yes” 时 brief 才通过。任何 “no” 意味着返回前修订。

• 每条必需标准是否有 scenario、可观察 expected result 和命名 verification method？
• 所有模糊词（“correctly”、“secure”、“fast”、“robust”）是否被替换为可观察证据，或标记为人工判断？
• 产品/业务约束是否列为已提供/假设，没有从代码静默推断？
• scope 是否显式，out-of-scope 项是否命名？
• blocking decisions 是否限于真正影响安全或正确性的选择，而非偏好？

质量检查

返回 brief 前检查：

• Goal 描述结果而非实现选择。
• scope 边界和假设显式。
• 每条必需标准可观察，或清晰标记为人工判断。
• 只在相关处考虑 security、privacy、data、compatibility、external-effect 和 UX 风险，不静默忽略。
• 验证方法为有风险操作识别安全环境。
• 无 secret 或生产敏感信息被复制进输出。
• 无 repository 变更或实现阻塞在没有理由或请求的情况下被强加。

交接

当另一个 planning 或实现工作流可用时，把验收 brief 或标准 ID 传给它。当没有专用工作流时，直接把 brief 作为实现参考提供。不要假设任何命名 skill 或工具已安装。