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 |
|
||||
| `memory/` | 01 | 02 |
|
||||
| `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/` 和即时状态记忆避免重复存储？
|
||||
Reference in New Issue
Block a user