docs: 新增AI沟通记录规范，清理旧规则文件引用
- 新增 08-AI沟通记录规范.md，约定沟通记录存储结构与生命周期 - 新增 docs/AI沟通记录/ 目录及首批沟通记录 - 删除已迁移的旧规则文件 commenting.md、documentation_sync.md - 更新索引与智能体记忆文件
This commit is contained in:
ShaoHua
@@ -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 交互”的协议字段（例如全局变量、事件名）必须注释说明来源与约束。
|
|
||||||
|
|
||||||
@@ -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. [ ] 文档变更是否保持“局部修改”，只影响与本任务相关的段落/小节？（避免无关重排/改写）
|
|
||||||
@@ -34,7 +34,7 @@
|
|||||||
|
|
||||||
| 子目录 | 当前最大序号 | 下一个可用 |
|
| 子目录 | 当前最大序号 | 下一个可用 |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `rules/全局/` | 07 | 08 |
|
| `rules/全局/` | 08 | 09 |
|
||||||
| `rules/项目/` | 04 | 05 |
|
| `rules/项目/` | 04 | 05 |
|
||||||
| `memory/` | 01 | 02 |
|
| `memory/` | 01 | 02 |
|
||||||
| `coordination/` | 02 | 03 |
|
| `coordination/` | 02 | 03 |
|
||||||
|
|||||||
@@ -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/` 和即时状态记忆避免重复存储？
|
||||||
@@ -39,6 +39,7 @@
|
|||||||
| [05-研发工单规则.md](./rules/全局/05-研发工单规则.md) | 研发工单术语与边界（编码工作项 vs Todo 待办项） |
|
| [05-研发工单规则.md](./rules/全局/05-研发工单规则.md) | 研发工单术语与边界（编码工作项 vs Todo 待办项） |
|
||||||
| [06-研发工单拆分规范.md](./rules/全局/06-研发工单拆分规范.md) | 工单拆分目录与文件结构 |
|
| [06-研发工单拆分规范.md](./rules/全局/06-研发工单拆分规范.md) | 工单拆分目录与文件结构 |
|
||||||
| [07-并行窗口冲突规约.md](./rules/全局/07-并行窗口冲突规约.md) | 并行 solo 窗口下的 Touch List / Writer / 绿线策略 |
|
| [07-并行窗口冲突规约.md](./rules/全局/07-并行窗口冲突规约.md) | 并行 solo 窗口下的 Touch List / Writer / 绿线策略 |
|
||||||
|
| [08-AI沟通记录规范.md](./rules/全局/08-AI沟通记录规范.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"
|
||||||
@@ -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-确认完成
|
||||||
|
|
||||||
|
用户确认规则已无问题，本次修正结束。
|
||||||
Reference in New Issue
Block a user