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。 ```markdown # 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 或工具已安装。