From 8b0b2cb197f0c94d92bde1269a8624724882e10f Mon Sep 17 00:00:00 2001 From: ShaoHua <345265198@qqcom> Date: Tue, 16 Jun 2026 00:22:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9EAI=E6=B2=9F=E9=80=9A?= =?UTF-8?q?=E8=AE=B0=E5=BD=95=E8=A7=84=E8=8C=83=EF=BC=8C=E6=B8=85=E7=90=86?= =?UTF-8?q?=E6=97=A7=E8=A7=84=E5=88=99=E6=96=87=E4=BB=B6=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 08-AI沟通记录规范.md，约定沟通记录存储结构与生命周期 - 新增 docs/AI沟通记录/ 目录及首批沟通记录 - 删除已迁移的旧规则文件 commenting.md、documentation_sync.md - 更新索引与智能体记忆文件 --- .trae/rules/commenting.md | 33 ---------- .trae/rules/documentation_sync.md | 34 ---------- .trae/rules/全局/01-智能体记忆.md | 2 +- .trae/rules/全局/08-AI沟通记录规范.md | 77 ++++++++++++++++++++++ .trae/索引.md | 1 + docs/AI沟通记录/01-规则沟通记录体系建立.md | 55 ++++++++++++++++ docs/AI沟通记录/02-沟通记录目录结构修正.md | 39 +++++++++++ 7 files changed, 173 insertions(+), 68 deletions(-) delete mode 100644 .trae/rules/commenting.md delete mode 100644 .trae/rules/documentation_sync.md create mode 100644 .trae/rules/全局/08-AI沟通记录规范.md create mode 100644 docs/AI沟通记录/01-规则沟通记录体系建立.md create mode 100644 docs/AI沟通记录/02-沟通记录目录结构修正.md diff --git a/.trae/rules/commenting.md b/.trae/rules/commenting.md deleted file mode 100644 index 9c3139c..0000000 --- a/.trae/rules/commenting.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -alwaysApply: true -description: 强制项目注释规范（C# / TypeScript）：新增或修改代码必须补全必要注释，便于维护与跨平台开发。 ---- - -# 注释规范（必须遵守） - -## 通用 - -- 新增或修改的代码必须包含足够注释，使“不了解该模块的人”也能理解其职责、边界与关键决策。 -- 优先使用 **XML 文档注释**（`///`），而不是随意的行内注释。 -- 不允许无意义注释（例如“初始化变量”“进入方法”）。注释必须解释“为什么/约束/边界/副作用”。 -- 不允许出现“TODO/FIXME”但无上下文或无处理方案的注释。 - -## C#（.NET / MAUI） - -- 所有 `public` / `protected` 的 **类、接口、方法、属性** 必须提供 XML 文档注释，至少包含： - - `summary`：一句话说明用途 - - 对关键参数/返回值：`param` / `returns` - - 对异常或副作用：在 `summary` 中明确说明（例如会注册系统钩子/会启动后台服务） -- 对 **跨平台逻辑**： - - 禁止在同一文件内混写多个平台的大段 `#if` 实现；应优先使用 `partial`、接口与平台目录分离。 - - 平台分离后的公共入口处必须说明“平台差异在哪里、默认实现是什么、为什么这么做”。 -- 对 **异步/后台任务**： - - 必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入。 -- 对 **安全/隐私**： - - 禁止在日志或注释中输出密钥、Token、用户隐私信息。 - -## TypeScript / Vue（前端） - -- 对导出的函数/类型必须有注释，解释用途与输入输出。 -- 对“与后端/MAUI 交互”的协议字段（例如全局变量、事件名）必须注释说明来源与约束。 - diff --git a/.trae/rules/documentation_sync.md b/.trae/rules/documentation_sync.md deleted file mode 100644 index 9d7b666..0000000 --- a/.trae/rules/documentation_sync.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -alwaysApply: true -description: 强制文档同步规范：每次变更代码（如新增功能、修改接口、调整架构等）必须同步更新 README.md 和 docs 目录下的相关文档。 ---- - -# 文档同步规范（必须遵守） - -## 通用原则 - -- **代码即文档，文档随代码**：文档不是静态的，它必须真实反映当前代码的状态。 -- **及时性**：在提交代码变更的同时（或紧随其后），必须完成相关文档的更新。 -- **准确性**：确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。 -- **协作友好（局部修改）**：当并行处理多个任务/需求时，更新文档应尽量只修改与本任务直接相关的段落/小节，避免对不相关内容做无意义的重排、改写或格式化；如必须调整非关联内容，应拆分为独立的变更说明清楚原因与影响范围。 - -## 更新范围 - -- **README.md**： - - 如果变更涉及核心功能点（Features）、安装步骤（Installation）、快速开始（Quick Start）或 API 端点（API Endpoints），必须同步更新。 - - 变更涉及技术栈调整或项目结构变化时需更新。 -- **docs/ 目录文档**： - - **接口变更**：若修改了 API，需同步更新 [技术设计文档](docs/技术设计文档.md) 中的接口部分。 - - **功能新增/调整**：需在 [产品需求文档](docs/产品需求文档.md) 和 [技术栈与模块](docs/技术栈与模块.md) 中体现。 - - **架构/模式变更**：需更新 [技术设计文档](docs/技术设计文档.md)。 - - **代码规范**：若引入了新的编码模式或工具，需更新 [代码规范文档](docs/代码规范文档.md)。 - - **版本记录**：所有非琐碎的变更必须在 [版本记录.md](docs/版本记录.md) 中添加记录。 - -## 检查清单 - -1. [ ] 是否有新增的 API 端点？（更新 README 和技术设计文档） -2. [ ] 是否修改了现有的业务逻辑或数据结构？（更新技术设计文档） -3. [ ] 是否有新增的功能模块？（更新产品需求文档和技术栈说明） -4. [ ] 是否调整了开发环境或依赖？（更新 README） -5. [ ] 是否在 [版本记录.md](docs/版本记录.md) 中记录了本次变更？ -6. [ ] 文档变更是否保持“局部修改”，只影响与本任务相关的段落/小节？（避免无关重排/改写） diff --git a/.trae/rules/全局/01-智能体记忆.md b/.trae/rules/全局/01-智能体记忆.md index d2d2869..58f7708 100644 --- a/.trae/rules/全局/01-智能体记忆.md +++ b/.trae/rules/全局/01-智能体记忆.md @@ -34,7 +34,7 @@ | 子目录 | 当前最大序号 | 下一个可用 | |---|---|---| -| `rules/全局/` | 07 | 08 | +| `rules/全局/` | 08 | 09 | | `rules/项目/` | 04 | 05 | | `memory/` | 01 | 02 | | `coordination/` | 02 | 03 | diff --git a/.trae/rules/全局/08-AI沟通记录规范.md b/.trae/rules/全局/08-AI沟通记录规范.md new file mode 100644 index 0000000..0cab94a --- /dev/null +++ b/.trae/rules/全局/08-AI沟通记录规范.md @@ -0,0 +1,77 @@ +# AI沟通记录规范（必须遵守） + +> 适用范围：本规则属于 **全局规则**（跨项目通用），约束用户与智能体之间沟通记录的存储与管理。 + +## 一、存储结构 + +- AI沟通记录存放在 `docs/AI沟通记录/` 目录下 +- 每次对话生成一个独立的 Markdown 文件，命名格式：`NN-主题摘要.md`（`NN` 为两位序号） +- 序号从 `01` 开始，每次新建递增 +1，不得跳号或重复 +- 智能体在新建沟通记录时，默认使用当前最大序号 +1 + +## 二、目录结构 + +``` +docs/AI沟通记录/ +├── 01-首次项目分析.md +├── 02-架构讨论.md +└── NN-主题摘要.md +``` + +- 每个文件即一次对话的完整记录 +- 如有附件或补充材料，可在同目录下新建 `NN-主题摘要/` 子文件夹存放 + +## 三、记录内容规范 + +每个沟通记录文件必须包含以下结构： + +```markdown +# AI沟通记录：NN-主题摘要 + +- **日期**：YYYY-MM-DD +- **参与者**：用户、AI 助手 +- **会话序号**：NN + +## 讨论主题 +[简要描述本次对话的核心议题] + +## 关键决策 +[记录对话中达成的重要决策] + +## 待办事项 +[对话中确认的后续行动项] + +## 详细记录 +### NN-子主题1 +[内容] +### NN-子主题2 +[内容] +``` + +- **详细记录中的子主题必须带序号前缀**，格式为 `### NN-子主题名称`（`NN` 为两位序号，从 01 开始） +- 子主题序号用于精确引用，例如"沟通记录 03 的 02-xxx" + +## 四、序号管理与引用 + +- 智能体在对话中可通过序号引用历史沟通记录，例如"参见沟通记录 03" +- 用户也可通过序号要求智能体回顾某次对话内容 +- 序号一旦分配不可变更，即使删除了某个记录文件夹，也不得复用其序号 + +## 五、与记忆系统的边界 + +| 系统 | 用途 | 更新频率 | +|---|---|---| +| `docs/AI沟通记录/` | 对话过程与决策的完整记录 | 每次对话新建 | +| `.trae/memory/` | 长期沉淀的关键决策与经验 | 按需追加 | +| `.trae/rules/项目/04-即时状态记忆.md` | 当前快照（进度、临时决策） | 高频更新 | + +- 三者不要重复存放同一份信息 +- `docs/AI沟通记录/` 偏向**对话过程的完整存档** +- `.trae/memory/` 偏向**长期沉淀的提炼结论** + +## 六、检查清单 + +1. [ ] 新建沟通记录时，序号是否为当前最大值 +1？ +2. [ ] 文件名是否为 `NN-主题摘要.md` 格式？ +3. [ ] 记录内容是否包含日期、参与者、讨论主题等必要字段？ +4. [ ] 是否与 `.trae/memory/` 和即时状态记忆避免重复存储？ diff --git a/.trae/索引.md b/.trae/索引.md index fa0790e..8a2cf30 100644 --- a/.trae/索引.md +++ b/.trae/索引.md @@ -39,6 +39,7 @@ | [05-研发工单规则.md](./rules/全局/05-研发工单规则.md) | 研发工单术语与边界（编码工作项 vs Todo 待办项） | | [06-研发工单拆分规范.md](./rules/全局/06-研发工单拆分规范.md) | 工单拆分目录与文件结构 | | [07-并行窗口冲突规约.md](./rules/全局/07-并行窗口冲突规约.md) | 并行 solo 窗口下的 Touch List / Writer / 绿线策略 | +| [08-AI沟通记录规范.md](./rules/全局/08-AI沟通记录规范.md) | 用户与智能体沟通记录的存储目录、序号管理与内容规范 | --- diff --git a/docs/AI沟通记录/01-规则沟通记录体系建立.md b/docs/AI沟通记录/01-规则沟通记录体系建立.md new file mode 100644 index 0000000..fa820d1 --- /dev/null +++ b/docs/AI沟通记录/01-规则沟通记录体系建立.md @@ -0,0 +1,55 @@ +# AI沟通记录：01-规则沟通记录体系建立 + +- **日期**：2026-06-16 +- **参与者**：用户、AI 助手 +- **会话序号**：01 + +## 讨论主题 + +用户要求建立两套机制： +1. 在全局规则中新增"AI沟通记录规范" +2. 在 `docs/` 下建立AI沟通记录存储目录，每次对话新建文件，使用序号编号 + +## 关键决策 + +1. AI沟通记录规则文件编号为 `08-AI沟通记录规范.md`，存放在 `.trae/rules/全局/` 下 +2. AI沟通记录存放在 `docs/AI沟通记录/` 目录下 +3. 每次对话新建 `NN-主题摘要.md` 文件，序号从 01 开始递增 +4. 智能体默认使用当前最大序号 +1 作为新记录编号 +5. 序号一旦分配不可复用 +6. 详细记录中的子主题必须带序号前缀（如 `01-xxx`、`02-xxx`），便于精确引用 + +## 待办事项 + +- [x] 创建 `.trae/rules/全局/08-AI沟通记录规范.md` +- [x] 创建 `docs/AI沟通记录/01-规则沟通记录体系建立.md` +- [x] 更新 `.trae/索引.md` 同步新增内容 +- [x] 更新 `.trae/rules/全局/01-智能体记忆.md` 中的序号速查表 + +## 详细记录 + +### 01-用户初始请求 + +用户提出了两个明确要求： +1. 将AI沟通记录相关规则添加到全局规则目录 +2. 建立 `docs/` 下的AI沟通记录存储体系，每次对话新建文件，带序号编号，方便后续引用 + +### 02-过程中的纠正 + +AI 助手初始方向偏离，误以为需要读取源代码进行分析。用户明确纠正：此项工作与源代码无关，应直接操作规则文件等内容。 + +### 03-命名修正 + +用户指出"通信记录"名称不准确，应改为"AI沟通记录"。随即统一更新了规则文件名、目录名、索引引用及记录内容中的所有措辞。 + +### 04-目录结构修正 + +用户指出当前的子文件夹结构（`NN-主题摘要/记录.md`）不正确，应改为直接的单文件结构（`NN-主题摘要.md`）。 +同时文件夹名"规则与沟通记录体系建立"应去掉"与"字，改为"规则沟通记录体系建立"。 + +### 05-最终方案 + +- 全局规则文件：`.trae/rules/全局/08-AI沟通记录规范.md` +- AI沟通记录目录：`docs/AI沟通记录/` +- 记录格式：`NN-主题摘要.md`（直接在目录下创建 `.md` 文件，不使用子文件夹） +- 引用方式：通过序号引用，如"参见沟通记录 01" diff --git a/docs/AI沟通记录/02-沟通记录目录结构修正.md b/docs/AI沟通记录/02-沟通记录目录结构修正.md new file mode 100644 index 0000000..70d9316 --- /dev/null +++ b/docs/AI沟通记录/02-沟通记录目录结构修正.md @@ -0,0 +1,39 @@ +# AI沟通记录：02-沟通记录目录结构修正 + +- **日期**：2026-06-16 +- **参与者**：用户、AI 助手 +- **会话序号**：02 + +## 讨论主题 + +修正 AI 沟通记录的目录结构与文件命名：从"子文件夹 + 记录.md"改为直接单文件 `NN-主题摘要.md`，并修正文件夹名称中多余的"与"字。 + +## 关键决策 + +1. 存储结构从子文件夹（`NN-主题摘要/记录.md`）改为单文件（`NN-主题摘要.md`） +2. 文件名从"规则与沟通记录体系建立"去掉"与"字，改为"规则沟通记录体系建立" +3. 同步更新 `08-AI沟通记录规范.md` 中的存储结构、目录示意图和检查清单措辞 + +## 待办事项 + +- [x] 删除旧子文件夹 `docs/AI沟通记录/01-规则与沟通记录体系建立/` +- [x] 新建 `docs/AI沟通记录/01-规则沟通记录体系建立.md` +- [x] 更新 `08-AI沟通记录规范.md` 中的存储结构描述 +- [x] 确认 `.trae/索引.md` 无需修改 + +## 详细记录 + +### 01-用户指出目录结构问题 + +用户指出当前的 AI 沟通记录目录结构不正确：不应该用子文件夹（`NN-主题摘要/记录.md`），而应直接用单文件（`NN-主题摘要.md`）。同时文件夹名"规则与沟通记录体系建立"中的"与"字应去掉。 + +### 02-执行修正 + +- 创建新文件 `01-规则沟通记录体系建立.md`，内容基于原 `记录.md` 并更新了相关描述 +- 删除旧的子文件夹 `01-规则与沟通记录体系建立/` +- 更新 `08-AI沟通记录规范.md`：存储结构、目录示意图、检查清单措辞全部同步修改 +- 索引文件无需改动（只引用了规则文件本身） + +### 03-确认完成 + +用户确认规则已无问题，本次修正结束。