ADDED Requirements

ADDED Requirements

Requirement: New Feature

The system SHALL do something new.

Scenario: Basic case

• WHEN user does X
• THEN system does Y

MODIFIED Requirements

Requirement: Existing Feature

Scenario: New scenario to add

• WHEN user does A
• THEN system does B

REMOVED Requirements

Requirement: Deprecated Feature

RENAMED Requirements

• FROM: ### Requirement: Old Name
• TO: ### Requirement: New Name

格式上有三个值得注意的约定：

1. 需求以 `### Requirement: <名称>` 标题锚定，需求描述使用 **SHALL** 规范措辞（RFC 2119 风格）；
2. scenario 以 `#### Scenario:` 标题组织，条件与断言采用 `WHEN / THEN`（可选 `AND` 续行）的 bullet 列表，使每一条场景都可以独立验证；
3. MODIFIED 分区里**只需要写出差异部分**——上例中 "Existing Feature" 下仅列了一个要新增的 scenario，而不必重复既有 scenario，这正是"智能合并"在格式层面的体现。

## 五、核心原则：意图而非整体替换

文档以 **Key Principle: Intelligent Merging** 一节强调了与程序化合并的本质区别：

> 与程序化合并不同，你可以应用**部分更新（partial updates）**：
> - 要新增一个 scenario，只需在 MODIFIED 下包含该 scenario——不必复制已有 scenario；
> - delta 表达的是*意图*（intent），而不是整体替换（wholesale replacement）；
> - 用你的判断力（use your judgment）合理地合并变更。

这条原则直接约束了 Agent 的编辑行为：合并时必须"读懂"delta 的意图，把增量叠加到主规格上，而不是把 delta 内容原样粘贴、覆盖既有内容。

## 六、在 Halo 仓库中的真实印证

以下两个归档变更展示了该同步机制在 Halo 中的实际产物形态。

**案例一：纯 ADDED 的新 capability。** [2026-06-03-support-theme-screenshot-preview 变更的 delta spec](https://gitcode.com/GitHub_Trending/ha/halo/blob/2ab802d044112086bbcd2694d08dbd87cf7fb763/openspec/changes/archive/2026-06-03-support-theme-screenshot-preview/specs/theme-screenshot-preview/spec.md?utm_source=gitcode_repo_files) 只含一个 `## ADDED Requirements` 分区，定义了主题根目录 `screenshot.png/jpg/jpeg/webp` 暴露为 `Theme.status.screenshot` 公共预览图、静态路由只服务受支持的截图文件名（含路径穿越拒绝场景）、Console 优先使用 `status.screenshot` 而非 `spec.logo` 等三条需求。按步骤 4d 的约定，同步后生成的 [主规格](https://gitcode.com/GitHub_Trending/ha/halo/blob/2ab802d044112086bbcd2694d08dbd87cf7fb763/openspec/specs/theme-screenshot-preview/spec.md?utm_source=gitcode_repo_files) 在 ADDED 内容之外补上了 `# ... Specification` 标题与 `## Purpose` 小节，并把需求收敛进 `## Requirements` 之下——这正是"创建新主规格时添加 Purpose 小节（可简短，标记 TBD）"规则的直接体现，两份文件的逐字对照可以作为该规则的实例证据。

**案例二：ADDED 与 MODIFIED 混合。** [2026-07-03-simplify-console-menu-tree-management 变更的 menu-hierarchy delta spec](https://gitcode.com/GitHub_Trending/ha/halo/blob/2ab802d044112086bbcd2694d08dbd87cf7fb763/openspec/changes/archive/2026-07-03-simplify-console-menu-tree-management/specs/menu-hierarchy/spec.md?utm_source=gitcode_repo_files) 同时包含两个分区：`## ADDED Requirements` 新增"Console 菜单树 API 提供规范化层级""菜单删除级联删除所属菜单项"两条需求（每条含 10 个 WHEN/THEN 场景，覆盖无效父引用、环检测、兄弟优先级重算等边界）；`## MODIFIED Requirements` 则只重写了"Console 菜单管理写入新层级字段"这一条既有需求的场景集（拖拽保存只发送单条 position update、失败后重载规范化树、删除菜单不批量 patch `Menu.spec.menuItems` 等）。该 delta 对应的 [主规格](https://gitcode.com/GitHub_Trending/ha/halo/blob/2ab802d044112086bbcd2694d08dbd87cf7fb763/openspec/specs/menu-hierarchy/spec.md?utm_source=gitcode_repo_files) 即为合并基线，可以看到合并后需求同时保留了基线场景与新 delta 中的增量场景——印证了"保留 delta 未提及的内容"这一护栏。

## 七、成功输出模板与护栏约束

**成功输出**要求 Agent 在完成后给出如下格式的摘要（原文模板保留）：

Specs Synced:

Updated main specs:

:

• Added requirement: "New Feature"
• Modified requirement: "Existing Feature" (added 1 scenario)

:

• Created new spec file
• Added requirement: "Another Feature"

Main specs are now updated. The change remains active - archive when implementation is complete.