前言
开源项目地址：github.com/SenbiaoXu/M…
敏捷软件开发宣言及其十二原则发布至今已经二十多年，随着CodeAgent的兴起，人与CodeAgent都作为软件开发的核心环节，曾经强调“人-人协作”的开发范式也悄然转向“人-机协作”。
我们需要新的原则，明确业务与代码的关系、人类与CodeAgent的职责分工、如何共同参与项目演进、如何相互高效协作与成长...于是我们提出了 人机协作开发宣言 及 人机协作十原则，希望与大家共同实践新时代开发范式。
人机协作开发宣言
我们一直在实践中探寻更好的软件开发方法，身体力行，同时也帮助他人。 随着人与智能体共同成为软件开发的核心参与者，我们建立了如下价值观：
业务价值 高于 编码实现
行为契约 高于 灵活指令
交付证据 高于 承诺汇报
适应演进 高于 定期更新
也就是说，尽管右项有其价值，我们更重视左项的价值。
人机协作十原则
我们遵循以下原则：
-
[业务至上] 我们最重要的目标是确保软件交付的业务价值，编码效率服务于业务价值判断。
-
[契约为纲] 契约先于实现，即使开发后期发现新场景，也先补充目标及验收标准，再进行编码实现。
-
[价值驱动分工] 人负责定义目标与标准，验收软件；智能体负责高效实现，提供证据。各司其职，互不越界。
-
[证据即交付] 证据是交付可信度的首要度量，没有证据的"已完成"等同于"未完成"。
-
[实事求是] 人通过契约如实表达意图，智能体如实实现并提供证据。人与智能体之间无需"隐瞒"与"谎言"。
-
[共享认知] 人与智能体共同维护软件的状态，演进历史不被隐藏，不被遗忘。
-
[人机友好] 人提供给智能体的信息精确有效；智能体提供给人的信息简约可读。
-
[激发能力] 人不断给智能体设计更好的运行环境和工具；智能体不断启发人的创意、细化人的想法。
-
[持续进化] 人不断反思优化人机协作流程；智能体不断从执行异常中反思，沉淀执行经验。
-
[共生增强] 人在协作过程中持续提升技术水平；智能体在协作过程中持续加深业务理解。
实践示例
本项目的skills文件夹下存放了几个技能，用于示例如何将《人机协作开发宣言》的价值观与十原则落地为可执行的工作流。
注: 您可以在其基础上添加细节，使其更契合您的项目。
| 技能 | 触发时机 | 核心职责 | 对应产出 |
|---|---|---|---|
| project-analyze | 接触新项目，或项目结构发生重大变化时 | 深度剖析工程，提取架构、技术栈、业务含义 | PROJECT_STATE/ 目录及文档集 |
| bdd-atdd | 用户要求实现功能、修复缺陷、重构代码时 | 先定义行为契约，再编码实现，最后自验证并交付证据 | PROJECT_STATE/BDD/ 和 PROJECT_STATE/ATDD/ 下的契约与验收文档 |
| doc-update | 完成代码改动之后 | 基于改动更新项目文档，记录演进状态与经验沉淀 | 更新 PROJECT_STATE/index.md、README.md、LEARNING/ 等 |
三者的协作关系：
project-analyze（认知奠基）
↓ 产出 PROJECT_STATE
bdd-atdd（验收标准驱动开发）
↓ 产出 BDD + ATDD 文档 + 代码
doc-update（演进同步）
↓ 更新 PROJECT_STATE / LEARNING
（回到 bdd-atdd 开始下一个迭代）
价值观映射
一、业务价值 高于 编码实现
在传统敏捷中，"工作的软件"是核心度量。但在人机协作场景下，智能体产出代码的速度远超人类审阅的速度，"能跑"不等于"有业务价值"。三个技能通过以下方式确保业务价值不被编码效率淹没：
- project-analyze 在 Phase 2 中执行"业务含义映射"——对每个模块必须回答"做什么"，结合命名、类型定义、API 路由推导业务职能，而非仅罗列技术组件。如果无法从代码推断业务含义，标注"待确认"而非猜测。这确保智能体对项目的理解始终锚定在业务层面。
- bdd-atdd 在阶段一要求先分析需求、澄清范围，再推导特性名称和编写行为规约。编码（阶段三）必须在行为规约经用户确认之后才能开始。这从流程上杜绝了"先写代码再想需求"的倾向。
- doc-update 在更新
README.md时强调只关注"对用户可见的功能"，内部代码重构不影响用户使用方式时不更新，避免信息噪音。
二、行为契约 高于 灵活指令
在传统敏捷中，"个体和互动"强调人与人之间的沟通。但在人机协作中，人与智能体的沟通存在天然的不对称——人的自然语言意图需要被精确转译为智能体可执行的结构化描述。自由形式的指令容易导致理解偏差，而行为契约（BDD 的 Given/When/Then 格式）提供了一种双方都能无歧义理解的共同语言。
- bdd-atdd 的核心就是"行为契约"的具体实现：
- 阶段一（BDD 规约）：将用户的自然语言需求转译为 Given/When/Then 格式的行为场景，覆盖正常路径、边界情况和错误条件。这一过程本身就是一个"澄清意图"的过程——编写 Given/When/Then 会迫使双方（人和智能体）把模糊的需求具体化。
- 阶段二（ATDD 初稿）：基于 BDD 场景进一步定义验收标准，明确"用什么命令验证、预期什么结果"。ATDD 初稿提交用户审阅，确保人与智能体对"怎样才算完成"达成一致。
- 阶段三（实现）：智能体严格按照已确认的行为契约编码。如果在实现中发现新场景，不允许直接编码，必须回到阶段一先将新场景补充到 BDD 文档中——契约先于实现。
- BDD 模板中有一条关键指引："从用户视角编写场景——描述行为，而非实现细节。"这确保契约描述的是"做什么"而非"怎么做"，将实现自由度留给智能体，将意图控制权留给人类。
三、交付证据 高于 承诺汇报
在传统敏捷中，"客户合作"强调与客户的持续协作而非合同条款的博弈。在人机协作中，智能体是一个高效但需要被验证的执行者。人类无法也不应逐行审阅智能体的所有产出，但也不能盲目信任。因此"证据"成为建立信任的桥梁——智能体不需要承诺"我做完了"，而是提供可审查的证据证明"我做完了"。
- bdd-atdd 的阶段四（自验证）和阶段五（ATDD 定稿）构成了完整的证据链：
- 自验证决策树：优先运行已有测试 → 编写针对性测试 → 代码路径追踪 → 标记为"无法验证"。这是一个逐层降级但始终诚实的策略。
- 证据形式多样：测试输出、日志片段、截图、数据文件均可作为证据，保存在
PROJECT_STATE/ATDD/<特性名称>/目录下。 - ATDD 定稿：将自验证的实际结果填入验收文档，包含每个测试用例的结果和证据。汇总表一目了然地展示场景覆盖情况。
- 关键规则：不得跳过任何场景，也不得在没有证据的情况下将其标记为通过。
- doc-update 维护的
PROJECT_STATE/index.md中的演进时间轴，本身也是项目级别的交付证据——记录了每一次改动的时间、类型和内容。
四、适应演进 高于 定期更新
在传统敏捷中，"响应变化"指团队灵活应对需求变更。在人机协作中，"演进"有更深的含义——智能体可能在每次会话中丢失上下文，项目状态可能在不同会话间断裂。因此需要一种机制，使项目的认知能够随代码同步演进，而非依赖定期的人工梳理。
- doc-update 的设计直接体现了这一价值观：
- 它在每次代码改动之后触发，而非按固定周期运行。
- 决策矩阵根据变更类型（新增功能、架构调整、缺陷修复等）精确判断需要更新哪些文档，避免过度更新和遗漏更新。
- 演进时间轴默认以
yyyy-mm-dd-hh-mm的精度记录，当条目超过 20 条时自动归纳为yyyy-mm格式，平衡了细节与可读性。
- project-analyze 在项目结构发生重大变化时可以重新运行，更新
PROJECT_STATE以反映最新状态。 - bdd-atdd 允许在实现阶段发现新场景时回到 BDD 阶段补充契约，而非强行将新需求塞入已有实现——这本身就是对变化的适应。
十原则映射
原则一：[业务至上]
我们最重要的目标是确保软件交付的业务价值，编码效率服务于业务价值判断。
落地方式：
- project-analyze 在分析项目时，不仅提取技术栈和架构，还强制执行"业务含义映射"——对每个模块回答"是什么、做什么、依赖谁、被谁依赖"。如果无法推断，标注"待确认"。
- bdd-atdd 在阶段一要求先分析需求、澄清范围。如果用户请求不够明确，智能体必须主动提问，理解输入、输出、边界情况和错误情况，而非直接动手编码。
- 这确保了智能体的编码效率始终服务于人对业务价值的判断，而非脱离业务上下文的盲目高效。
原则二：[契约为纲]
契约先于实现，即使开发后期发现新场景，也先补充目标及验收标准，再进行编码实现。
落地方式：
- bdd-atdd 的五阶段流程严格顺序执行，阶段一（BDD 规约）和阶段二（ATDD 初稿）必须在阶段三（编码）之前完成。
- 阶段三有一条硬性规则：如果在实现过程中发现新场景，必须回到阶段一，先将新场景添加到 BDD 文档中，并同步更新 ATDD 初稿，再继续实现。
- BDD 文档使用 Given/When/Then 格式，这是一种可被机器解析、可被人审查的正式契约。ATDD 初稿进一步将契约转化为可执行的验收标准。
原则三：[价值驱动分工]
人负责定义目标与标准，验收软件；智能体负责高效实现，提供证据。各司其职，互不越界。
落地方式：
- bdd-atdd 的工作流天然实现了这一分工：
- 人：审阅并确认 BDD 文档（阶段一），审阅并确认 ATDD 初稿（阶段二），最终验收软件。
- 智能体：编写 BDD 文档草案、编写 ATDD 初稿、编码实现（阶段三）、自验证（阶段四）、完善 ATDD 定稿（阶段五）。
- 每个阶段结束时都有明确的"提交用户审阅"检查点，确保人不会错过关键决策点，智能体也不会越权自行决定行为定义或验收标准。
- project-analyze 中，模块划分方案必须由用户确认——智能体提供分析结果和多种分类方案，人做最终决定。
原则四：[证据即交付]
证据是交付可信度的首要度量，没有证据的"已完成"等同于"未完成"。
落地方式：
- bdd-atdd 的自验证阶段（阶段四）对每个 BDD 场景逐个验证，记录通过/失败及证据。验证策略按优先级选择：运行已有测试 > 编写新测试 > 代码路径追踪 > 标记为"无法验证"。
- 验证指南中有一条不可逾越的底线：不得跳过任何场景，也不得在没有证据的情况下将其标记为通过。
- ATDD 定稿（阶段五）将验证结果结构化地填入文档，包含汇总表，使证据可追溯、可审查。
原则五：[实事求是]
人通过契约如实表达意图，智能体如实实现并提供证据。人与智能体之间无需"隐瞒"与"谎言"。
落地方式：
- bdd-atdd 的多个环节体现了实事求是：
- 自验证中，如果场景无法通过自动化测试验证，验证指南要求如实说明并描述检查了哪些内容，而非伪装成已通过。
- ATDD 定稿要求"诚实且完整"，如果场景确实无法验证应如实说明。
- 验证失败时，要求记录失败、调查原因、修复代码、重新验证，而非直接跳过。
- project-analyze 中，如果无法从代码推断出业务含义，要求标注"待确认"而非猜测。关键设计决策"禁止编造无法从代码验证的决策理由"。
- doc-update 中，
LEARNING/index.md用于记录执行异常、用户纠正和踩坑经验——这是对失败和问题的如实记录，而非只展示成功。
原则六：[共享认知]
人与智能体共同维护软件的状态，演进历史不被隐藏，不被遗忘。
落地方式：
- project-analyze 产出的
PROJECT_STATE/目录就是人机共享认知的载体。它包含：index.md：项目全貌总览architecture.md：架构与技术栈设计modules/*.md：各业务模块详情
- bdd-atdd 在
PROJECT_STATE/下创建BDD/和ATDD/子目录，将行为契约和验收证据也纳入共享认知体系。 - doc-update 通过演进时间轴持续更新
PROJECT_STATE/index.md，确保项目的状态变更被完整记录。时间轴在条目过多时自动归纳，平衡信息完整性与可读性。 - 这套机制的核心价值在于：即使智能体在新的会话中丢失了上下文，它也可以通过阅读
PROJECT_STATE/快速恢复对项目的理解。
原则七：[人机友好]
人提供给智能体的信息精确有效；智能体提供给人的信息简约可读。
落地方式：
- 人 → 智能体（精确有效）：
- BDD 的 Given/When/Then 格式强迫人将模糊的需求具体化为可验证的场景。模板指引要求"在 Then 子句中要具体明确——避免使用'它能正常工作'这类模糊断言"。
- ATDD 初稿要求明确"用什么命令、预期什么结果"，进一步将验收标准具体化。
- 智能体 → 人（简约可读）：
- BDD 文档使用统一的场景格式，一目了然。
- ATDD 定稿包含汇总表，以表格形式呈现场景覆盖和验证结果。
PROJECT_STATE/index.md的架构蓝图和业务模块描述均限制"不超过十行"，确保信息密度高、阅读负担低。LEARNING/index.md只放一句话摘要，详情拆分到独立文件，按需阅读。
原则八：[激发能力]
人不断给智能体设计更好的运行环境和工具；智能体不断启发人的创意、细化人的想法。
落地方式：
- 人 → 智能体：三个技能本身就是人为智能体设计的结构化运行环境。BDD 模板、ATDD 模板、验证指南为智能体提供了明确的行动框架，使其不需要猜测"下一步该做什么"。
PROJECT_STATE/为智能体提供了项目上下文，使其在任何会话中都能快速进入工作状态。 - 智能体 → 人：
- project-analyze 在分析过程中可能揭示人未注意到的架构问题或模块间依赖关系，启发人对项目的重新思考。
- bdd-atdd 在阶段一编写 BDD 场景时，智能体会主动考虑边界情况和错误条件，这些可能是人在提出需求时未想到的，从而帮助人细化和完善需求。
原则九：[持续进化]
人不断反思优化人机协作流程；智能体不断从执行异常中反思，沉淀执行经验。
落地方式：
- doc-update 维护的
LEARNING/目录是这一原则的直接实现：- 执行异常及解决方式：记录构建失败、依赖冲突、运行时错误等异常及其解决方案。这些经验在后续会话中可被智能体检索和参考，避免重复踩坑。
- 来自用户的纠正：记录用户对智能体工作方式的纠正和改进建议。这些反馈帮助智能体在后续工作中调整行为。
- 每条经验在
LEARNING/index.md中有一句话摘要，详情拆分到独立文件，形成可检索的经验库。
- project-analyze 可以在项目结构发生重大变化时重新运行，更新
PROJECT_STATE以反映最新状态，而非依赖一次性的初始分析。
原则十：[共生增强]
人在协作过程中持续提升技术水平；智能体在协作过程中持续加深业务理解。
落地方式：
- 人提升技术水平：通过审阅智能体产出的 BDD/ATDD 文档、阅读
PROJECT_STATE/architecture.md中的架构分析，人对项目的技术架构和设计决策有更深入的理解。LEARNING/中记录的技术约束和踩坑经验也是人技术成长的一部分。 - 智能体加深业务理解：
- project-analyze 的"业务含义映射"使智能体从源码中反推业务逻辑，而非仅理解技术层面。
- bdd-atdd 的 BDD 编写过程要求智能体从用户视角思考场景，这本身就是对业务理解的加深。
PROJECT_STATE/作为持久化的项目认知，使智能体在每次新会话中都能带着历史业务理解继续工作，而非从零开始。
协作流程全景
以下是一个典型的人机协作开发周期，展示三技能如何配合运作：
┌─────────────────────────────────────────────────────┐
│ 1. 首次接触项目 │
│ 触发 project-analyze │
│ 人确认模块划分方案 │
│ 产出 PROJECT_STATE/ │
└──────────────────────┬──────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 2. 用户提出功能需求 │
│ 触发 bdd-atdd │
│ ┌─ 阶段一：智能体编写 BDD，人审阅确认 │
│ ├─ 阶段二：智能体编写 ATDD 初稿，人审阅确认 │
│ ├─ 阶段三：智能体编码实现 │
│ ├─ 阶段四：智能体自验证，逐场景记录证据 │
│ └─ 阶段五：智能体完善 ATDD 定稿 │
└──────────────────────┬──────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 3. 代码改动完成 │
│ 触发 doc-update │
│ 根据 git diff 判断变更类型 │
│ 按决策矩阵更新 PROJECT_STATE / README / LEARNING │
└──────────────────────┬──────────────────────────────┘
↓
回到步骤 2，开始下一个需求
在这个循环中：
- 人的参与集中在决策点：确认模块划分、审阅 BDD、审阅 ATDD 初稿。其余时间由智能体自主执行。
- 智能体的执行始终受行为契约约束，并通过证据证明执行质量。
- PROJECT_STATE 作为共享认知的纽带，确保跨会话的上下文连续性。
