加载中

将意图捕获为 intent.md

第 2 课4 分钟

启动软件开发流程的 intent.md,可以通过不同的途径进入。一个人有了想法、提交了一个工单,或者通过警报发现了一个事件(参见第 6 阶段:维护)。

当一个人有了想法时,他们会与 Claude 进行头脑风暴,并生成一份 Markdown 原型规格说明(proto-spec)。在传统的软件开发生命周期(SDLC)中,同一个人随后必须说服产品团队的某位成员与他们一起或代表他们把这个想法写下来。

Claude 生成的原型规格说明是人类可读的、受版本控制的,并且可以立即被下一阶段使用。该原型规格说明被保存为 intent.md。

无论意图是源自事件触发还是源自某个人,所适用的步骤都是相同的:产品负责人会在提交之前审查并修正由智能体撰写的 intent.md。

发生了哪些变化

传统方式AI 原生方式
一个想法要经过待办事项条目、用户故事、故事点以及细化会议,然后才有人能够据此采取行动。每次交接时所有权都会转移,因此最终到达工程团队手中的内容,已经与发起者最初的意图相去甚远。发起者与 Claude 进行头脑风暴,并将结果以发起者自己的措辞写成 intent.md,即一份原型规格说明。该工件包含了想要什么、为什么想要,以及在哪些约束条件下。重复性流程通过技能(skills)进行编码。

入门指南

  • 前提条件:无。
  • 基础设施:为非工程师人员提供 Claude 访问权限(claude.ai 或 Cowork);一份商定好的 intent.md 模板;一个共享的、受版本控制的意图存放位置,供产品负责人关注。对于单一产品而言,最简单的存放位置是产品代码仓库中的一个 intent/ 文件夹。这种设置使该工件链与由其衍生出的代码保持相邻。只有当意图跨越多个代码仓库时,设立专门的意图仓库才值得付出额外开销;而在单体仓库(monorepo)中,它只是一个目录。第 3 阶段:构建中的"遗留系统"部分介绍了这个存放位置与已经保存记录的 Jira 或需求工具之间的关系。

搭建这一环境是平台团队或工程团队的一次性任务。需要一名技术团队成员来建立意图存放位置,并决定谁可以向其写入内容,因为许多贡献者将来自组织的各个部门。

一旦该代码仓库建立起来,没有 Git 使用经验的贡献者就不需要直接使用 Git。取而代之的是,一个连接到版本控制系统(例如 GitHub)的连接器,可以让 Claude 代表他们从 claude.ai 或 Cowork 提交 Markdown 文件。

如何执行

  1. 发起者用自己的话向 Claude 描述问题。发起者可以描述他们今天无法做到的事情、受该想法影响的人员、更好的状态是什么样子,或者哪些内容不在范围之内。不需要使用正式的语言。
  2. 进行头脑风暴,直到这个想法变得具体。Claude 会提出分析师会问的问题:范围、用户、约束条件,以及成功的标准是什么。
  3. 请 Claude 使用组织的模板将结果写成 intent.md,该模板可以被编码为一个技能集,由技术团队成员搭建并由负责人签字确认。这可以涵盖问题、提议的结果、受影响的用户和系统、约束条件以及待解决的问题。
  4. 发起者纠正 Claude 理解有误的任何内容。
  5. 将 intent.md 提交到共享存放位置。作者和时间戳会加入记录,产品负责人从此处接手该想法。

实际效果

intent.md:

markdown
# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.
## Problem
Customers phone the contact center to ask where their claim is.
Handlers spend roughly a third of call time on status-only queries.
## Proposed outcome
Customers see claim status, next step and expected date in the portal.
## Affected users and systems
Claims handlers, portal team, claims-core API.
## Constraints
No new PII in the portal session. Existing authentication only.
## Open questions
Do third-party loss adjusters need access too?

治理考量

证据就是已提交的 intent.md,其中列出了作者、时间戳以及完整的修订历史。它被记录在意图存放位置的 Git 历史中。产品负责人进行批准,而将意图送入第 2 阶段:设计的接受或拒绝决定,会被记录为合并操作或结束审查。

如何衡量

  • 领先指标:从首次对话到提交 intent.md 所经过的时间,该数据从意图存放位置的 Git 历史中读取,其中记录了作者和时间戳。预期这一时间会从历时数周的征询与细化周期,缩短为几个小时。
  • 滞后指标:存活率,即产品负责人接受进入第 2 阶段:设计而非关闭的 intent.md 文件所占的比例。接受或拒绝的决定会被记录为该工件的合并操作或已关闭的审查。此外,还要统计在同一变更的首次 spec.md 提交之后对 intent.md 所做的修改次数。