---
alwaysApply: false
description: 
---
# 并行 solo 窗口冲突规约（必须遵守）

> 适用范围：本规则属于 **全局规则**（跨项目通用）。

> ⚠️ 术语澄清：本规范中的「研发工单（Dev Work Item）」专指智能体 / 开发者执行的**编码工作项**，与 Hua.Todo 项目业务领域中的「Todo 待办项」是两个完全不同的概念。
> 详见 [05-研发工单规则.md](./05-研发工单规则.md)。
> 凡涉及编码侧拆分时，**必须使用「研发工单」或「工单」**，禁止使用「任务」二字以避免与 Todo 待办项混淆。

## 适用范围

- 当同一个版本/需求被拆分为多个并行研发工单，并由多个 solo 窗口同时推进时适用。
- 目标是同时降低两类风险：
  - **文件冲突**：多人同时改同一文件/相邻行导致冲突。
  - **编译区间冲突**：A 窗口引入的未完成变更破坏编译，阻塞 B 窗口集成与验证。

## 核心原则

- **先声明后修改**：任何代码改动前，先在研发工单文档中声明"触碰文件清单（Touch List）"与"共享文件策略"。
- **文件所有权唯一**：同一时段内，一个文件只能被一个窗口作为"写入者（Writer）"修改。
- **共享文件单点修改**：涉及高耦合/共享入口的改动，集中到一个"集成窗口（Integrator）"完成，其他窗口只做准备工作（新文件/独立模块/文档/测试）。
- **绿线优先（可编译）**：任何可落盘、可合入的变更必须保持可编译；临时状态必须通过"隔离手段"而不是破坏编译来实现。

## Touch List（触碰文件清单）

- 每个并行研发工单 md 必须在开头包含一个明确的 Touch List，至少包含：
  - 新增/修改/删除的文件路径（精确到文件，必须写"准确目录"）
  - 预期修改类型（新增/小改/重构/接口变更/配置变更）
  - 是否为共享文件（是/否）
- Touch List 必须保持可检索与可更新：变更范围扩大时，必须先更新 Touch List 再改代码。

### 目录书写要求（必须遵守）

- Touch List 内每一条必须使用以下两种格式之一：
  - **仓库相对路径（推荐）**：`src\<module>\<file>`
  - **绝对路径（可选）**：`<repo-root>\src\<module>\<file>`（`<repo-root>` 为本机仓库根目录）
- Touch List 禁止包含构建产物与临时目录中的文件（这些文件不应被手工修改，且极易产生冲突），包括但不限于：
  - `**\bin\**`、`**\obj\**`
  - `**\node_modules\**`
  - `**\.vite\**`、`**\dist\**`

### Touch List 模板（复制即可用）

- Touch List:
  - `src\<module>\<file>`（共享：否｜Writer：本窗口）
  - `src\<module>\<file>`（共享：是｜Writer：<窗口名>）
  - `docs\<file>`（共享：是/否｜Writer：<窗口名>）
  - `.trae\<file>`（共享：是｜Writer：<窗口名>）

## 文件所有权与共享文件策略

- **默认规则**：Touch List 中标记为"共享文件"的条目，必须指定唯一 Writer。
- **Writer 约束**：
  - 非 Writer 窗口不得编辑该共享文件（包括格式化、重排 import、无关重构）。
  - 需要对共享文件提出修改时，非 Writer 只能提供"差异建议"（文字说明/伪代码/小片段）交给 Writer 落盘。
- **共享文件判定（满足其一即为共享）**：
  - 项目入口/启动逻辑、依赖注入注册、全局路由/导航、公共配置、公共协议与 DTO、公共组件/样式、跨模块公共工具
  - 解决方案/项目文件（如 `.sln`、`.csproj`）、锁文件、全局配置文件（如 `appsettings*`、构建脚本）

## 协调目录（必须遵守）

- 为了让"文件冲突"和"编译中途状态"可操作、可对齐，仓库内必须固定保留一个专用协调目录：
  - `.trae\coordination\`
- 该目录只用于协作对齐，不承载业务实现代码；多人可在不同文件中写入，避免互相踩踏。
- 并行推进时必须使用该目录中的文件记录"谁在改什么"和"中途状态怎么保证不破坏编译"：
  - `.trae\coordination\01-ownership.md`：文件/目录所有权（Writer）登记表
  - `.trae\coordination\02-shared-files.md`：本阶段共享文件清单（只有 Integrator 维护）
  - `.trae\coordination\handoff\`：非 Writer 提交的差异建议/交接说明（Integrator 落盘）
  - `.trae\coordination\wip\`：编译中途状态说明（为什么需要隔离、如何保证绿线、何时收敛）

## 目录分区与低冲突写法

- 优先通过"新增文件"完成并行开发，减少在同一文件内的交错修改。
- 需要扩展既有逻辑时，优先选择低冲突策略：
  - C#：新增类/partial 文件、扩展方法、接口实现分文件、平台目录分离
  - TypeScript/Vue：新增模块/组件文件，避免在同一大文件内做多处改动
- 禁止在非必要情况下对共享文件做纯格式化、纯重排或无收益重构（这些改动高度易冲突且难以 review）。

## 编译绿线（避免编译区间冲突）

- **不得提交/合入破坏编译的变更**：包括缺失类型、未实现接口、引用不存在、配置缺项导致启动失败等。
- **允许的临时隔离手段（按优先级）**：
  1. 新功能先放在新文件/新类中，不在入口路径上启用
  2. 通过显式开关控制启用（配置/运行时开关），默认关闭
  3. 通过依赖注入分支注册或特性开关隔离，默认不触发
- 当必须进行接口演进时，采用"双写/兼容期"策略：
  - 先新增（保持旧接口可用）→ 再迁移调用方 → 最后清理旧接口

## 合入顺序与集成职责

- 每个并行阶段必须明确一个集成窗口（Integrator），负责：
  - 处理共享文件的实际落盘与冲突消解
  - 保持主干/集成分支持续可编译、可运行
- 其他窗口提交的成果应尽量以"新增文件 + 最小修改点"的方式交付，降低集成成本。

## 任务验收后 coordination 清理

研发工单验收完成、并行阶段结束后，**Integrator 必须**对 `.trae/coordination/` 做收尾清理：

- **清空记录行**：将 `01-ownership.md` 与 `02-shared-files.md` 中的运行时记录行删除，仅保留文件顶部说明、表头与示例占位行（让下一轮并行可以直接复用）
- **归档 handoff/wip**：删除已落盘消化掉的 `handoff/` 与 `wip/` 内容；如有需要长期沉淀的关键决策，迁移到 [.trae/memory/](../../memory) 对应文件中
- **不删除文件本身**：`00-README.md`、`01-ownership.md`、`02-shared-files.md` 三个常驻文件保留，仅清空内容
- **冲突收尾确认**：清理前确保所有共享文件已合入主干、Touch List 已不再被任何窗口引用
- **同步项目状态**：在 [.trae/rules/项目/04-即时状态记忆.md](../项目/04-即时状态记忆.md) 的"工单状态快照"中将相关工单标记为已验证

## 最小检查清单

1. [ ] 每个研发工单 md 是否已写 Touch List（精确到文件）？
2. [ ] Touch List 中的共享文件是否指定了唯一 Writer？
3. [ ] 是否避免了对共享文件的无意义格式化/重排？
4. [ ] 当前改动是否保持可编译（绿线）？
5. [ ] 若涉及接口演进，是否采用兼容期策略而非一次性破坏式变更？