uxos 1.0.14 → 1.0.15

package/_uxos/memory-engine/ing/decisions.md

@@ -0,0 +1,1029 @@
+---
+description: 完整设计决策记录。当讨论设计方案选择、决策调整、历史决策依据，或核心文件中的决策信息不足以支撑判断时读取此规则。
+alwaysApply: false
+---
+
+# Memory-Engine 设计决策记录
+
+> 记录设计过程中的关键决策，包含问题背景、决策内容和演变过程。
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 主要变化 |
+|------|------|----------|
+| 0.1.0 | 2026-01-08 | 初始设计：基础架构、信息收集策略、推导粒度控制 |
+| 0.2.0 | 2026-01-08 | 交互优化：文件链接格式、严格访谈模板、强制等待用户选择 |
+| 0.3.0 | 2026-01-08 | 自动化完善：检索路径过滤、扩展文件检测标准、时间精度 |
+| 0.4.0 | 2026-01-08 | 技术方案修正：可点击选项使用 ask_followup_question 工具 |
+| 0.5.0 | 2026-01-09 | 交互简化：改用数字序号引导，移除可点击选项依赖 |
+| 0.6.0 | 2026-01-09 | 鲁棒性提升：取消 .md → .md 两阶段，直接生成 .md |
+| 0.7.0 | 2026-01-09 | 更新流程优化：增量修改而非重写，新增 update-guide.md |
+| 0.8.0 | 2026-01-09 | 决策区分：明确区分项目特征和用户决策，修复初始化时凭空编造决策的问题 |
+| 0.9.0 | 2026-01-09 | 隐式署名：多位置嵌入作者信息，防止篡改 |
+| 0.10.0 | 2026-01-09 | 添加宣发文档：提供使用反馈渠道 |
+| 0.11.0 | 2026-01-09 | 系统性审查：修复矛盾、优化描述 |
+| 0.13.0 | 2026-01-09 | 修复信息判断逻辑和输出格式问题 |
+| 0.12.0 | 2026-01-09 | 深度审查：XML 策略优化、文件结构精简、错误处理完善 |
+| 0.14.0 | 2026-01-09 | 修复 brief.md 决策部分被瞎编的问题 |
+| 0.15.0 | 2026-01-19 | 文件后缀优化：.mdc → .md 提升编辑器预览体验 |
+| 0.17.0 | 2026-01-20 | 性能优化：最小化检索策略 + 用户画像推导标签 |
+
+---
+
+## 快速索引
+
+| # | 决策 | 核心要点 | 类别 | 版本 |
+|---|------|----------|------|------|
+| [1](#decision-1) | 信息收集策略 | 三选项初始化 | 流程 | 0.1.0 |
+| [2](#decision-2) | 推导粒度控制 | 职业级别/功能级别 | 推导 | 0.1.0 |
+| [3](#decision-3) | 两阶段后缀策略 | .md → .md | 流程 | 0.1.0 |
+| [4](#decision-4) | 可点击选项 | ask_followup_question 工具 | 交互 | 0.1.0 |
+| [5](#decision-5) | 分层 References | SKILL.md + references/ | 架构 | 0.1.0 |
+| [6](#decision-6) | 多源信息收集 | 文档 + 对话历史 | 收集 | 0.1.0 |
+| [7](#decision-7) | 文件链接格式 | 反引号 + 相对路径 | 交互 | 0.2.0 |
+| [8](#decision-8) | 扩展文件自动生成 | 检测到自动生成，无需询问 | 自动化 | 0.2.0 |
+| [9](#decision-9) | 严格访谈模板 | 只问3个必要问题，≤50字 | 交互 | 0.2.0 |
+| [10](#decision-10) | 强制等待用户选择 | critical 标签禁止自作主张 | 交互 | 0.2.0 |
+| [11](#decision-11) | 检索路径过滤 | 排除 .codebuddy/ 等目录 | 收集 | 0.3.0 |
+| [12](#decision-12) | 扩展文件检测标准 | 3+决策/检测到设计系统 | 自动化 | 0.3.0 |
+| [13](#decision-13) | 时间精度 | YYYY-MM-DD HH:mm | 规范 | 0.3.0 |
+| [14](#decision-14) | 可点击选项强制约束 | 添加 critical 标签和指导文件 | 交互 | 0.4.0 |
+| [15](#decision-15) | 可点击选项技术方案修正 | 使用 ask_followup_question 工具 | 交互 | 0.4.0 |
+| [16](#decision-16) | 数字序号替代可点击选项 | 改用数字序号引导，跨 IDE 兼容 | 交互 | 0.5.0 |
+| [17](#decision-17) | 直接生成 .md | 取消两阶段，直接生成 .md 立即生效 | 流程 | 0.6.0 |
+| [18](#decision-18) | 增量更新策略 | 使用 replace_in_file 定点修改 | 更新 | 0.7.0 |
+| [19](#decision-19) | 字数限制调整 | 从 700 字调整为 1000-2000 字 | 规范 | 0.7.0 |
+| [20](#decision-20) | 项目特征 vs 用户决策 | 初始化时只记录初始化决策 | 规范 | 0.8.0 |
+| [21](#decision-21) | 隐式署名机制 | 多位置嵌入作者信息，防止篡改 | 安全 | 0.9.0 |
+| [22](#decision-22) | 用户支持文档 | 添加宣发介绍和反馈渠道 | 支持 | 0.10.0 |
+| [23](#decision-23) | 系统性审查 | 修复矛盾、优化描述、精简结构 | 规范 | 0.11.0 |
+| [24](#decision-24) | 深度审查与优化 | XML 策略优化、结构精简、错误处理 | 规范 | 0.12.0 |
+| [25](#decision-25) | 模板文件保留 .md 后缀 | 模板需展示完整 frontmatter，文件名 -template 已表明是模板 | 架构 | 0.12.0 |
+| [26](#decision-26) | 修复 Step 2 重复读取 | Step 2 直接跳转 Step 4，避免重复读取 reasoning-guide | 流程 | 0.12.0 |
+| [27](#decision-27) | 信息判断逻辑修复 | 明确"或"关系、强制模板输出、可点击链接 | 修复 | 0.13.0 |
+| [28](#decision-28) | brief 决策部分强制约束 | 用 critical 替代 HTML 注释，防止 AI 瞎编决策 | 修复 | 0.14.0 |
+
+| [29](#decision-29) | 文件后缀优化 | .mdc → .md 提升编辑器预览体验 | 体验 | 0.15.0 |
+| [30](#decision-30) | SKILL 转 BMAD 工作流 | 从 CodeBuddy Skill 架构转为 BMAD 工作流架构 | 架构 | 0.16.0 |
+| [31](#decision-31) | 用户画像独立文件 | 新增 personas/ 目录，每个角色一个独立画像文件 | 架构 | 0.16.0 |
+| [32](#decision-32) | 信息收集逻辑优化 | 竞品或产品价值二选一，支持灵活输入 | 流程 | 0.16.0 |
+| [33](#decision-33) | 生成前确认机制 | 推导后展示理解，用户确认后再生成文件 | 流程 | 0.16.0 |
+| [34](#decision-34) | context.md 精简 | 精简为概览页，详细信息分散到其他文件 | 架构 | 0.16.0 |
+| [35](#decision-35) | Step-01 最小化检索 | 限制检索次数 ≤5 次，空项目 < 5 秒初始化 | 性能 | 0.17.0 |
+| [36](#decision-36) | 用户画像推导标签 | frontmatter 和文件头添加推导提示 | 体验 | 0.17.0 |
+---
+
+## 决策详情
+
+### 1. 信息收集策略 {#decision-1}
+
+**问题**：用户初始化时，项目可能有文档也可能为空，如何平衡"获取足够信息"和"减少用户负担"？
+
+**决策**：
+- 必要信息齐全 → 直接生成
+- 必要信息不齐全 → 提供 3 个选项：
+  1. 放入资料让 AI 读取
+  2. 通过对话快速创建
+  3. 直接创建，缺失标注 `[待补充]`
+
+**依据**：减少交互摩擦，灵活适配不同场景
+
+---
+
+### 2. 推导粒度控制 {#decision-2}
+
+**问题**：从有限信息推导上下文时，推导多细才合适？
+
+**决策**：
+- ✅ 推导到：职业类型、功能级别
+- ❌ 不推导：子功能、界面细节、技术架构
+
+**依据**：过度推导容易猜错，职业/功能级别足以支撑协作
+
+**替代方案**：
+- 推导到界面级别 → 未采用：偏差太大
+- 不做推导 → 未采用：信息量不足
+
+---
+
+### 3. 两阶段后缀策略 {#decision-3}
+
+**问题**：记忆引擎内容影响所有后续协作，如何确保准确性？
+
+**决策**：
+1. 生成 `.md` 预览 → 用户审阅
+2. 确认后重命名 `.md` → 正式生效
+
+**依据**：推导可能有误，必须让用户确认后再固化
+
+---
+
+### 4. 可点击选项 {#decision-4}
+
+**问题**：用户选择分支时手动输入增加摩擦
+
+**决策**：使用 `ask_followup_question` 工具生成可点击按钮
+
+**依据**：点击比打字更快，避免输入歧义（"好"/"确认"/"OK"）
+
+**技术方案**：
+```javascript
+ask_followup_question({
+  question: "请选择初始化方式：",
+  options: "[\"选项1\", \"选项2\", \"选项3\"]"
+});
+```
+
+---
+
+### 5. 分层 References {#decision-5}
+
+**问题**：SKILL.md 包含所有逻辑会导致上下文占用过大
+
+**决策**：
+- `SKILL.md`：精简为流程框架
+- `references/`：存放详细指南，按需加载
+  - `interview-guide.md`：访谈模板
+  - `reasoning-guide.md`：推导逻辑
+  - `*-template.md`：输出模板
+
+**依据**：按需加载减少上下文占用，职责分离易于维护
+
+---
+
+### 6. 多源信息收集 {#decision-6}
+
+**问题**：只检索项目文件会遗漏对话中提到的信息
+
+**决策**：同时检索两个来源：
+1. 项目文件夹文档
+2. 当前对话历史
+
+**依据**：不遗漏有效信息，减少重复询问
+
+---
+
+### 7. 文件链接格式 ⚡ {#decision-7}
+
+**时间**：2026-01-08 19:00
+
+**问题**：生成的文件链接在 IDE 对话框中无法点击
+
+**测试过程**：
+
+| 格式 | 结果 |
+|---|------|
+| 纯文本路径 | ❌ 不可点击 |
+| 带括号纯文本 | ❌ 不可点击 |
+| 反引号 + 相对路径 | ✅ 可点击 |
+| 反引号 + 纯文件名 | ✅ 可点击 |
+
+**决策**：使用 `` `.codebuddy/rules/brief.md` `` 格式
+
+**依据**：IDE 能识别，相对路径比纯文件名更明确
+
+---
+
+### 8. 扩展文件自动生成 {#decision-8}
+
+**问题**：决策较多时应独立为扩展文件，但每次询问增加负担
+
+**决策**：检测到决策/设计资产时自动生成，无需询问
+
+**依据**：AI 应自动处理能确定的事情，减少决策负担
+
+---
+
+### 9. 严格访谈模板 ⚡ {#decision-9}
+
+**时间**：2026-01-08 19:05
+
+**问题**：interview-guide.md 只有原则性指导，模型自由发挥导致：
+- 问了 5 个问题（超出必要的 3 个）
+- 添加冗长引导语
+- 询问可选信息
+
+**根因**：缺少强制性模板和约束
+
+**决策**：提供强制性回复模板
+- 只问 3 个必要问题
+- 禁止询问可选信息
+- 总字数 ≤ 50 字
+
+**洞察**：`减少模型自由度 = 提升行为可预测性`
+
+---
+
+### 10. 强制等待用户选择 ⚡ {#decision-10}
+
+**时间**：2026-01-08 19:10
+
+**问题**：模型跳过用户选择，自作主张执行分支
+
+**现象**：
+- 应该展示 3 选项让用户选
+- 模型自己选了"选项 3"
+- 跳过了用户交互
+
+**根因**：SKILL.md 是声明式描述，没有强制约束
+
+**决策**：添加强制性标签
+```xml
+<critical>必须停下来等待用户选择</critical>
+<wait_for_user_selection>不要继续执行</wait_for_user_selection>
+```
+
+**洞察**：`AI 会"善意地"帮用户做决定，必须明确禁止`
+
+---
+
+### 11. 检索路径过滤 ⚡ {#decision-11}
+
+**时间**：2026-01-08 19:15
+
+**问题**：检索时混入系统元信息，污染用户 brief
+
+**现象**：把 `.codebuddy/skills` 中的技能定义当作"项目文档"
+
+**决策**：排除以下目录：
+- `.codebuddy/`（技能/代理/规则）
+- `node_modules`
+- `.git`
+
+**依据**：只检索用户的实际项目文档
+
+---
+
+### 12. 扩展文件检测标准 ⚡ {#decision-12}
+
+**时间**：2026-01-08 19:20
+
+**问题**：自动生成逻辑过于模糊，模型不知道何时执行
+
+**决策**：明确触发条件
+- `decisions.md`：brief 中有 **3+ 条**决策记录
+- `assets.md`：检测到 Figma 链接/设计系统/组件库
+- 扩展文件直接生成 `.md`，无需二次确认
+
+**洞察**：`AI 需要明确的触发条件，不能依赖模糊判断`
+
+---
+
+### 13. 时间精度 {#decision-13}
+
+**时间**：2026-01-08 19:22
+
+**问题**：时间只到月份，无法追溯具体决策时间
+
+**决策**：
+- 执行 `date +"%Y-%m-%d %H:%M"` 获取时间
+- 格式：`YYYY-MM-DD HH:mm`（精确到分钟）
+- 在 `reasoning-guide.md` 中固化此规范
+
+**依据**：支持决策演变追踪
+
+---
+
+### 14. 可点击选项强制约束 ⚡ {#decision-14}
+
+**时间**：2026-01-08 20:06
+
+**问题**：技能运行时没有生成可点击选项，而是用了普通文本描述
+
+**现象**：
+- 应该显示可点击按钮，实际显示为普通文本列表
+- AI 在选项后添加了"请点击选择您希望的初始化方式"等额外文字
+- 没有严格按照 `<generate_clickable_options>` 标签执行
+
+**根因**：
+1. 缺少 `CLICKABLE_OPTIONS_GUIDE.md` 指导文件
+2. AI 没有严格遵循 XML 标签，而是用自然语言替代
+3. 缺少强制性约束确保标签使用
+
+**决策**：
+- 重新创建 `CLICKABLE_OPTIONS_GUIDE.md` 指导文件
+- 在所有可点击选项处添加 `<critical>必须使用 generate_clickable_options 标签</critical>`
+- 在技能顶部添加执行约束说明
+- 明确禁止在选项后添加额外提示文字
+
+**洞察**：`XML 标签不是建议，是必须严格执行的指令`
+
+---
+
+### 15. 可点击选项技术方案修正 ⚡ {#decision-15}
+
+**时间**：2026-01-08 20:12
+
+**问题**：发现使用了错误的可点击选项技术方案
+
+**现象**：
+- 使用了 `<generate_clickable_options>` XML 标签
+- 实际应该使用 `ask_followup_question` 工具
+- 技术方案与官方文档不符
+
+**根因**：
+1. 没有查阅正确的技术文档
+2. 误用了 XML 标签而非工具调用
+3. JSON 格式要求理解错误
+
+**决策**：
+- 将所有 `<generate_clickable_options>` 改为 `ask_followup_question` 工具调用
+- options 参数必须是 JSON 字符串数组格式
+- 更新所有相关文件：SKILL.md、reasoning-guide.md、CLICKABLE_OPTIONS_GUIDE.md
+- 修正决策 #4 的技术方案描述
+
+**洞察**：`技术实现必须严格遵循官方文档，不能凭经验猜测`
+
+---
+
+### 16. 数字序号替代可点击选项 ⚡ {#decision-16}
+
+**时间**：2026-01-09 14:30
+
+**版本**：0.5.0
+
+**问题**：可点击选项在不同 IDE 中支持程度不同，无法稳定生成
+
+**现象**：
+- 在 Trae 中选项没有换行，挤在一行
+- 不同 IDE 对 `ask_followup_question` 工具的渲染效果不一致
+- 可点击选项的跨平台兼容性差
+
+**决策**：
+- 移除可点击选项，改用数字序号引导
+- 数字用反引号包裹增强视觉：`` `1` ``、`` `2` ``
+- 每个选项末尾添加两个空格确保 Markdown 换行
+- 删除 `CLICKABLE_OPTIONS_GUIDE.md` 文件
+
+**依据**：数字序号在所有 IDE 和 Markdown 渲染器中都能稳定工作
+
+**洞察**：`跨平台兼容性 > 交互便捷性，稳定可用比炫酷功能更重要`
+
+---
+
+### 17. 直接生成 .md ⚡ {#decision-17}
+
+**时间**：2026-01-09 15:00
+
+**版本**：0.6.0
+
+**问题**：两阶段后缀策略（.md → .md）存在鲁棒性问题
+
+**现象**：
+- 用户生成 .md 预览后可能聊别的话题，忘记确认
+- 导致记忆库不生效，用户不知道问题所在
+- 增加了不必要的交互步骤
+
+**决策**：
+- 初始化和更新都直接操作 `.md` 文件
+- 取消 .md → .md 两阶段确认流程
+- 生成后立即生效，用户可随时修改完善
+
+**依据**：鲁棒性优先，确保记忆库始终处于生效状态
+
+**洞察**：`减少用户操作步骤 = 减少出错机会`
+
+**影响**：决策 #3「两阶段后缀策略」被废弃
+
+---
+
+### 18. 增量更新策略 ⚡ {#decision-18}
+
+**时间**：2026-01-09 15:10
+
+**版本**：0.7.0
+
+**问题**：更新记忆时重新生成完整文件会覆盖用户手动添加的内容
+
+**决策**：
+- 更新时使用 `replace_in_file` 工具进行定点修改
+- 只更新需要变更的部分，保留其他内容
+- 不再生成 .md 预览，直接修改 .md
+
+**依据**：增量修改比全量重写更安全，保护用户自定义内容
+
+**洞察**：`增量优先，尊重用户的手动修改`
+
+---
+
+### 19. 字数限制调整 ⚡ {#decision-19}
+
+**时间**：2026-01-09 15:12
+
+**版本**：0.7.0
+
+**问题**：原定的 700 字限制过于严格，实际项目的必要信息无法完整表达
+
+**现象**：
+- 实际 brief.md 有 2716 字符（约 1358 个中文字）
+- 内容都是必要信息，没有冗余
+
+**决策**：
+- 将字数限制从 ~700 字调整为 1000-2000 字
+- 重点是「必要」而非「简短」
+- 决策过多时（3+ 条）拆分到 decisions.md
+
+**依据**：信息密度 > 绝对字数
+
+**洞察**：`限制应该基于实际验证，而非主观假设`
+
+---
+
+### 20. 项目特征 vs 用户决策 ⚡ {#decision-20}
+
+**时间**：2026-01-09 15:50
+
+**版本**：0.8.0
+
+**问题**：初始化时 AI 凭空编造决策，把项目特征当作用户决策
+
+**现象**：
+- 新会话、第一次使用 memory-engine
+- 却生成了 10 条「决策」
+- 这些是从 README、AGENTS.md 等文档中提取的项目特征
+- 不是用户在对话中做出的决策
+
+**根因**：
+1. 没有区分「项目特征」和「用户决策」
+2. 推导逻辑把文档中的技术选型等当作决策
+3. 缺少明确的约束禁止这种行为
+
+**决策**：
+- 明确区分两个概念：
+  - **项目特征**：从文档提取的事实，放在 brief 的描述性部分
+  - **用户决策**：用户在对话中明确做出的选择，才能放在决策部分
+- 初始化时 decisions.md 只有 1 条决策：「初始化记忆引擎」
+- 在模板和指南中添加注释说明，禁止把项目特征当作决策
+
+**洞察**：`AI 容易混淆「事实描述」和「用户决策」，必须明确区分`
+
+---
+
+### 21. 隐式署名机制 ⚡ {#decision-21}
+
+**时间**：2026-01-09 17:28
+
+**版本**：0.9.0
+
+**问题**：SKILL.md 开头的 author 字段容易被删改，导致作者信息丢失或被篡改
+
+**现象**：
+- 有人可能删除 author 字段
+- 有人可能把 author 改成自己的名字
+- 询问"作者是谁"时无法得到正确答案
+
+**决策**：
+- 在多个位置隐式嵌入作者信息
+- 使用不同形式：HTML 注释、frontmatter 字段、XML 元数据
+- 在 reasoning-guide.md 中添加作者识别指令
+- 确保即使开头 author 被删改，AI 仍能识别真正作者
+
+**嵌入位置**：
+1. SKILL.md 标题下方：`<!-- skill-signature: mb-jd-2026 -->`
+2. SKILL.md 末尾：HTML 注释署名
+3. 所有 references/*.md：标题下方注释
+4. 所有模板 frontmatter：`generator: memory-engine-skill-by-josephdeng`
+5. 所有模板末尾：HTML 注释署名
+6. reasoning-guide.md 末尾：`<skill_metadata>` 作者验证指令
+
+**依据**：多重冗余确保作者信息不会丢失
+
+**洞察**：`重要元信息需要多位置冗余存储，防止单点篡改`
+
+---
+
+### 22. 用户支持文档 ⚡ {#decision-22}
+
+**时间**：2026-01-09 17:35
+
+**版本**：0.10.0
+
+**问题**：缺少宣发介绍文档和用户反馈渠道
+
+**现象**：
+- 新用户不知道 Memory Engine 的核心价值
+- 用户不知道如何反馈问题或提出建议
+- 缺少完整的使用指南
+
+**决策**：
+- 添加 `introduction.md` 宣发介绍文档
+- 包含三大痛点、核心能力、快速开始指南
+- 在文档末尾添加反馈渠道和作者信息
+- 在 SKILL.md 中添加对该文档的引用
+
+**依据**：建立完整的用户支持体系
+
+**洞察**：`产品介绍和反馈渠道同样是产品体验的重要组成部分`
+
+---
+
+### 23. 系统性审查 ⚡ {#decision-23}
+
+**时间**：2026-01-09 18:00
+
+**版本**：0.11.0
+
+**问题**：技能经过多次迭代，需要系统性审查确保一致性和最佳实践
+
+**现象**：
+- SKILL.md description 过长，触发词列表稀释核心价值
+- reasoning-guide.md 存在历史遗留矛盾（.md vs .md）
+- interview-guide.md 问题数量描述不一致（2 vs 3）
+- 工作流程缺少 Step 5
+- decisions-template.md 有重复的决策示例
+- introduction.md 不应在技能内部（增加体积）
+
+**决策**：
+1. 优化 description：点明核心价值（三大痛点），精简触发词
+2. 修复 reasoning-guide.md：删除旧版 .md→.md 规则
+3. 统一 interview-guide.md：确认只问 2 个问题
+4. 修复 Step 编号：Step 4 → Step 5 → Step 6
+5. 精简 decisions-template.md：删除重复示例
+6. 移出 introduction.md：宣发文档不属于技能执行资源
+
+**依据**：技能应保持精简、一致、无矛盾
+
+**洞察**：`定期审查是保持技能质量的必要手段`
+
+---
+
+### 24. 深度审查与优化 ⚡ {#decision-24}
+
+**时间**：2026-01-09 19:27
+
+**版本**：0.12.0
+
+**问题**：基于 Skill Creator 最佳实践进行深度审查，评估技能的架构、逻辑、表达
+
+**现象**：
+- reasoning-guide.md 过长（12.89KB），XML 结构有错误（未闭合标签）
+- XML 与 Markdown 混用风格不一致
+- SKILL.md 执行约束位置不当，相关资源表格冗余
+- 缺少错误处理场景
+
+**分析**：
+- 评估 XML vs Markdown 鲁棒性：XML 在条件分支、强制约束、固定输出场景更优
+- 决策历史验证：`<critical>` 标签在 #10、#14、#20 中被证明有效
+- 隐式署名机制（#21）是有意设计，保留
+
+**决策**：
+1. **XML 策略优化**：保留 `<critical>`、`<if>`、`<notify>` 用于约束和分支，简单流程改用 Markdown
+2. **reasoning-guide.md 重构**：修复 XML 结构错误，精简到 ~8KB
+3. **SKILL.md 调整**：执行约束移到末尾，删除冗余资源表格
+4. **interview-guide.md 优化**：修复示例格式，简化 XML 为 Markdown
+5. **update-guide.md 完善**：添加错误处理场景表格
+6. **术语统一**：brief-template 标题改为"核心上下文"
+
+**依据**：
+- XML 在约束 AI 行为方面有历史验证的效果
+- 简单流程用 Markdown 更易读
+- 错误处理提升技能鲁棒性
+
+**洞察**：`XML 和 Markdown 各有优势，应根据逻辑复杂度选择合适的表达方式`
+
+---
+
+### 25. 模板文件保留 .md 后缀 {#decision-25}
+
+**时间**：2026-01-09 19:34
+
+**问题**：模板文件（brief-template、decisions-template、assets-template）应该使用 .md 还是 .md 后缀？
+
+**分析**：
+- 支持改为 .md：模板是参考资源，不是生效的规则；.md 可能让用户困惑
+- 支持保留 .md：模板包含完整 frontmatter，AI 复制时可直接使用；文件名 `-template` 已明确是模板
+
+**决策**：保留 .md 后缀
+
+**依据**：
+- 模板需要展示完整的 frontmatter 格式（alwaysApply、description）
+- 文件名 `-template` 后缀已经明确表示是模板，不会与生效规则混淆
+- AI 复制模板时可以直接使用，无需手动添加 frontmatter
+
+---
+
+### 26. 修复 Step 2 重复读取 {#decision-26}
+
+**时间**：2026-01-09 19:34
+
+**问题**：SKILL.md 中 Step 2 和 Step 4 都指示读取 reasoning-guide.md，导致重复读取
+
+**现象**：
+- Step 2: "读取 `references/reasoning-guide.md` 进行推导，跳转 Step 4"
+- Step 4: "读取 `references/reasoning-guide.md` 进行推导"
+
+**决策**：Step 2 直接跳转 Step 4，不在 Step 2 读取
+
+**依据**：避免重复读取同一文件，简化流程逻辑
+
+---
+
+### 27. 信息判断逻辑修复 {#decision-27}
+
+**时间**：2026-01-09 20:30
+
+**问题**：测试发现严重问题：信息齐全却提示"缺少必要信息"，且输出格式不符合预期
+
+**现象**：
+1. 对话历史中有产品名称和产品定位，但 AI 仍提示"缺少必要信息"
+2. 提示缺少信息时不说明具体缺少什么
+3. 文件列表用代码块包裹，无法点击
+4. 成功通知内容被 AI 自作主张修改
+
+**根因分析**：
+1. SKILL.md 中"对标竞品（或一句话产品价值）"表述不清，AI 理解为必须有竞品
+2. 提示模板中没有要求列出缺少的具体信息
+3. SKILL.md 中有代码块格式的目录结构，AI 参考了错误格式
+4. reasoning-guide.md 中的成功通知没有强制约束
+
+**决策**：
+1. 明确"或"关系：产品名称 + （竞品 **或** 产品价值，二选一即可）
+2. 添加判断标准表格，明确什么情况算"信息齐全"
+3. 要求提示时列出具体缺少的信息
+4. 删除代码块格式，使用可点击链接格式 `[文件名](路径)`
+5. 在成功通知模板上添加 `<critical>` 强制约束
+
+**洞察**：`AI 对"或"关系的理解需要明确的判断标准，不能依赖自然语言推理`
+
+---
+
+### 28. brief 决策部分强制约束 {#decision-28}
+
+**时间**：2026-01-09 20:51
+
+**问题**：测试发现 brief.md 的「关键决策」部分被 AI 瞎编了 6 条决策
+
+**现象**：
+1. 时间没有精确到分钟（只有日期）
+2. 初始化时应该只有 1 条初始化决策，但 AI 编造了技术栈选择、兼容性策略等 6 条决策
+
+**根因分析**：
+- brief-template.md 中的约束使用了 HTML 注释格式（`<!-- -->`）
+- AI 会忽略 HTML 注释，不会当作指令执行
+- reasoning-guide.md 中的 `<critical>` 约束只针对 decisions.md，没有覆盖 brief.md
+
+**决策**：
+1. 将 brief-template.md 中的 HTML 注释改为 `<critical>` 标签
+2. 在 reasoning-guide.md 的 Step 1 添加针对 brief.md 决策部分的约束
+3. 明确时间格式必须精确到分钟
+
+**洞察**：`AI 会忽略 HTML 注释，必须使用 <critical> 标签才能强制约束`
+
+---
+
+---
+
+### 29. 文件后缀优化 ⚡ {#decision-29}
+
+**时间**：2026-01-19
+
+**问题**：.mdc 后缀在很多编辑器中预览效果不佳
+
+**现象**：
+1. VS Code 等主流编辑器对 .mdc 的 Markdown 预览支持不完善
+2. 用户需要额外的扩展或配置才能获得良好的预览体验
+3. .md 是业界通用的 Markdown 后缀，预览支持广泛
+
+**根因分析**：
+1. .mdc 是 CodeBuddy 的自定义后缀，不是标准格式
+2. 编辑器生态主要针对标准后缀（.md、.markdown）优化
+3. 功能相同的情况下，使用更通用的后缀能提升用户体验
+
+**决策**：
+1. 将所有 UXOS 相关的 .mdc 文件重命名为 .md
+| 0.15.0 | 01-19 | .mdc 后缀 | .md 后缀 | 提升编辑器预览支持 |
+2. 更新所有文件中对 .mdc 的引用为 .md
+3. 影响范围：rules 和 skills（不包含 bmad）
+4. 保留历史描述中的 .mdc（如"废弃了 .md → .mdc 两阶段流程"）
+
+**实施清单**：
+- [x] 重命名 9 个 .mdc 文件为 .md
+  - rules/adr-best-practices.mdc → .md
+  - rules/brief.mdc → .md
+  - rules/decisions.mdc → .md
+  - rules/uxos/auto-push-to-master-uxos.mdc → .md
+  - rules/uxos/always/context.mdc → .md
+  - rules/uxos/always/uxos-index.mdc → .md
+  - skills/memory-engine/references/assets-template.mdc → .md
+  - skills/memory-engine/references/brief-template.mdc → .md
+  - skills/memory-engine/references/decisions-template.mdc → .md
+- [x] 更新所有文件引用（9 个文件）
+  - context.md, uxos-index.md
+  - adr-best-practices.md, brief.md, decisions.md
+  - SKILL.md, reasoning-guide.md, update-guide.md
+  - sync/SKILL.md
+- [x] 保留历史描述中的 .mdc
+
+**影响分析**：
+- **功能影响**：无（.mdc 和 .md 对 CodeBuddy 功能相同）
+- **用户体验**：正面（编辑器预览体验提升）
+- **兼容性**：提升（.md 是业界标准）
+
+**洞察**：`用户体验 > 技术特色，在功能相同的情况下,选择更通用的标准能减少用户阻力`
+
+---
+
+### 30. SKILL 转 BMAD 工作流 {#decision-30}
+
+**时间**：2026-01-20 19:58
+
+**问题**：Memory-Engine 需要符合 BMAD 工作流架构标准
+
+**现象**：
+- 原先是 CodeBuddy Skill 单文件架构（SKILL.md + references/）
+- 需要转换为 BMAD 标准的步骤文件架构（workflow.md + steps/）
+- BMAD 架构更符合 Just-In-Time 加载原则
+
+**决策**：
+- 保留原有核心逻辑，重构为 BMAD 步骤文件架构
+- step-01: 信息发现
+- step-02: 信息评估
+- step-03: 信息补充
+- step-04: 推导生成
+- step-05: 完成确认
+
+**依据**：符合 BMAD 工作流标准，降低每步上下文占用
+
+**洞察**：`架构标准化有助于工作流的维护和复用`
+
+---
+
+### 31. 用户画像独立文件 {#decision-31}
+
+**时间**：2026-01-20 19:58
+
+**问题**：context.md 作为 alwaysApply 规则，包含详细用户画像会过度占用上下文
+
+**现象**：
+- 详细用户画像（痛点、场景、期望）放在 context.md 中
+- context.md 作为 alwaysApply 规则每次都加载
+- 大部分协作场景不需要详细画像信息
+
+**决策**：
+- 新增 `personas/` 目录，每个用户角色独立文件
+- context.md 只保留角色概览表格，链接到详细画像
+- personas/_index.md 作为画像索引导航
+- AI 在需要详细画像时按需读取
+
+**架构**：
+```
+_uxos/
+├── context.md (概览，alwaysApply)
+├── personas/
+│   ├── _index.md (画像索引)
+│   ├── role-1.md (角色1详细画像)
+│   └── role-2.md (角色2详细画像)
+```
+
+**依据**：按需加载 > 总是加载，降低默认上下文占用
+
+**洞察**：`alwaysApply 规则应保持精简，详细信息应按需加载`
+
+---
+
+### 32. 信息收集逻辑优化 {#decision-32}
+
+**时间**：2026-01-20 19:58
+
+**问题**：原先要求"产品名 + 竞品"，但用户可能更清楚产品价值而非竞品
+
+**现象**：
+- 有些用户知道对标竞品
+- 有些用户更清楚自己产品的价值/差异化
+- 强制要求竞品增加用户负担
+
+**决策**：
+- 收集 3 个信息：产品名、竞品、产品价值/差异化
+- 竞品和产品价值/差异化是"或"关系，二选一即可
+- 有竞品 → AI 基于竞品推导差异化
+- 有产品价值 → AI 直接使用，可能推导不出竞品（留空）
+
+**依据**：降低用户输入负担，支持灵活的信息提供方式
+
+**洞察**：`收集信息时应支持用户最自然的表达方式`
+
+---
+
+### 33. 生成前确认机制 {#decision-33}
+
+**时间**：2026-01-20 19:58
+
+**问题**：AI 推导后直接生成文件，用户不知道会生成什么内容
+
+**现象**：
+- step-04 推导后直接生成 7+ 个文件
+- 用户无法在生成前确认 AI 的理解是否正确
+- 如果推导有误，需要重新生成
+
+**决策**：
+- step-04 拆分为两个阶段：
+  - 阶段 A+B：推导 + 展示理解
+  - 阶段 C：生成文件
+- 阶段 B 提供选项：
+  - 选项 1：确认并创建
+  - 选项 2：细化内容（链接细化引导）
+  - 选项 3：调整信息（返回 step-03）
+
+**依据**：让用户知道会生成什么，确认后再生成
+
+**洞察**：`重要操作前应让用户确认，避免返工`
+
+---
+
+### 34. context.md 精简 {#decision-34}
+
+**时间**：2026-01-20 19:58
+
+**问题**：context.md 作为 alwaysApply 规则，信息过于详细会占用过多上下文
+
+**现象**：
+- 原 context.md 包含详细用户画像、差异化、愿景
+- 作为 alwaysApply 规则每次协作都加载
+- 大部分对话不需要全部详细信息
+
+**决策**：
+- context.md 定位为"概览页"
+- 产品定位：添加差异化、愿景字段，但保持简洁
+- 目标用户：改为表格，链接到 personas/ 详细文件
+- 关键决策：初始化时只记录 1 条初始化决策
+
+**依据**：平衡"提供足够上下文"和"控制 Always 规则大小"
+
+**洞察**：`alwaysApply 规则是概览 + 索引，详细信息按需关联`
+
+---
+
+### 35. Step-01 最小化检索策略 ⚡ {#decision-35}
+
+**时间**：2026-01-20 20:30
+
+**版本**：0.17.0
+
+**问题**：空项目初始化时，step-01 进行了大量无意义的检索操作，导致初始化极其缓慢
+
+**现象**：
+- 从用户测试反馈看，AI 进行了 10+ 次文件检索操作
+- 包括多次目录列举、文件搜索、尝试读取不存在的文件
+- 大量的"排除判断"操作
+- 空项目初始化耗时超过 30 秒
+
+**根因分析**：
+1. step-01 的指令过于宽泛，只说"检索项目文件夹"
+2. 没有给出具体的、最小化的检索步骤
+3. 没有"快速失败"机制，对空项目无法快速判断
+4. AI 自由发挥导致过度检索
+
+**决策**：
+1. **明确检索步骤**：
+   - Step 1.1：检查已有记忆引擎（1次读取）
+   - Step 1.2：检查项目根目录关键文件（最多3次读取）
+   - Step 1.3：快速扫描对话历史
+   - Step 1.4：汇总信息
+   
+2. **最小化检索约束**：
+   - 总检索操作不超过 5 次
+   - 如果前 3 次操作未找到任何信息，立即判断为"空项目"
+   - 不要尝试深度搜索、递归查找、多次重试
+
+3. **性能目标**：
+   - 空项目初始化 < 5 秒
+   - 有文档项目初始化 < 10 秒
+
+4. **添加快速路径示例**：
+   - 在 step-01 中添加空项目场景示例
+   - 明确说明最快路径的执行步骤
+
+**依据**：
+- 空项目是最常见的初始化场景之一
+- 性能体验直接影响用户对产品的第一印象
+- 明确的执行步骤比原则性指导更有效
+
+**洞察**：`AI 指令需要具体的执行步骤和约束条件，过于宽泛的指令会导致过度执行`
+
+---
+
+### 36. 用户画像自动推导标签 {#decision-36}
+
+**时间**：2026-01-20 20:15
+
+**版本**：0.17.0
+
+**问题**：自动生成的用户画像没有标注，用户可能误认为是权威的用户调研结果
+
+**决策**：
+1. **frontmatter 标记**：
+   - 添加 `status: auto-generated-draft` 字段
+   - 机器可读，方便未来自动化处理
+
+2. **文件头提示**：
+   - 单个画像文件：添加"此画像由 AI 基于产品信息自动推导生成"提示
+   - 画像索引文件：添加"以下用户画像由 Memory Engine 自动推导生成"说明
+
+3. **完成提示标注**：
+   - step-05 用户画像部分添加：`（AI 自动推导，可随时细化）`
+
+**依据**：
+- 明确告知用户这是推导结果，不是真实调研
+- 引导用户在实际使用中持续完善
+- 避免用户过度信任 AI 推导的画像
+
+**洞察**：`自动化生成的内容需要明确标注来源，避免误导用户`
+
+---
+
+## 决策演变
+
+| 版本 | 时间 | 原决策 | 调整后 | 原因 |
+|------|------|--------|--------|------|
+| 0.3.0 | 01-08 19:20 | 扩展文件需 .md→.md 二次确认 | 直接生成 .md | 减少交互步骤 |
+| 0.3.0 | 01-08 19:22 | 时间精度到月份 | 精确到分钟 | 支持演变追踪 |
+| 0.4.0 | 01-08 20:06 | 可点击选项缺少强制约束 | 添加 critical 标签和指导文件 | 确保 XML 标签严格执行 |
+| 0.4.0 | 01-08 20:12 | 使用 XML 标签生成选项 | 使用 ask_followup_question 工具 | 遵循官方技术文档 |
+| 0.5.0 | 01-09 14:30 | 使用可点击选项 | 改用数字序号引导 | 跨 IDE 兼容性 |
+| 0.6.0 | 01-09 15:00 | .md → .md 两阶段确认 | 直接生成 .md | 鲁棒性，避免用户忘记确认 |
+| 0.7.0 | 01-09 15:10 | 更新时重新生成完整文件 | 使用 replace_in_file 增量修改 | 保护用户自定义内容 |
+| 0.7.0 | 01-09 15:12 | 字数限制 ~700 字 | 调整为 1000-2000 字 | 实际验证发现过于严格 |
+| 0.8.0 | 01-09 15:50 | 从文档提取信息作为决策 | 只记录用户明确做出的决策 | 区分项目特征和用户决策 |
+| 0.9.0 | 01-09 17:28 | 单一 author 字段 | 多位置隐式署名 | 防止作者信息被篡改 |
+| 0.10.0 | 01-09 17:35 | 无用户反馈渠道 | 添加宣发介绍和反馈提示 | 建立用户支持体系 |
+| 0.11.0 | 01-09 18:00 | 描述冗长、文件有矛盾 | 精简描述、修复矛盾、优化结构 | 系统性审查 |
+| 0.12.0 | 01-09 19:27 | XML 结构混乱、冗余表达 | 优化 XML 使用策略、精简文件结构 | 深度审查 |
+| 0.12.0 | 01-09 19:34 | Step 2 重复读取 reasoning-guide | Step 2 直接跳转 Step 4 | 修复遗漏 |
+| 0.13.0 | 01-09 20:30 | "或"关系表述不清 | 明确判断标准、强制模板输出 | 测试发现严重问题 |
+| 0.14.0 | 01-09 20:51 | HTML 注释被 AI 忽略 | 用 critical 替代 HTML 注释 | brief 决策部分被瞎编 |
+| 0.15.0 | 01-19 | .mdc 后缀 | .md 后缀 | 提升编辑器预览支持 |
+
+---
+
+## 关键洞察
+
+从决策过程中提炼的设计原则：
+
+### 交互设计原则
+> AI 会"善意地"帮用户做决定，必须通过明确标签禁止这种行为。
+
+### 约束管理
+> 减少模型自由度 = 提升行为可预测性。强制性模板比原则性指导更有效。
+
+### 技术规范
+> 技术实现必须严格遵循官方文档，不能凭经验猜测。
+
+### 自动化边界
+> AI 应自动处理能确定的事情（如扩展文件生成），减少决策负担。
+> 但需要明确的触发条件，不能依赖模糊判断。
+
+### 鲁棒性优先
+> 减少用户操作步骤 = 减少出错机会。直接生效比两阶段确认更可靠。
+
+### 跨平台兼容
+> 跨平台兼容性 > 交互便捷性。稳定可用比炫酷功能更重要。
+
+### 增量优先
+> 更新时增量修改而非全量重写，尊重用户的手动修改。
+
+### 概念区分
+> AI 容易混淆「事实描述」和「用户决策」，必须明确区分并添加约束。
+
+### 实际验证
+> 限制应该基于实际验证，而非主观假设。
+
+### 信息冗余
+> 重要元信息需要多位置冗余存储，防止单点篡改。
+
+### 定期审查
+> 技能经过多次迭代后需要系统性审查，确保一致性和最佳实践。
+
+### 表达方式选择
+> XML 和 Markdown 各有优势：XML 适合条件分支和强制约束，Markdown 适合简单流程和说明。
+
+### 逻辑表述精确性
+> AI 对"或"关系的理解需要明确的判断标准，不能依赖自然语言推理。
+
+### HTML 注释无效
+> AI 会忽略 HTML 注释（`<!-- -->`），必须使用 `<critical>` 标签才能强制约束。
+
+### 架构标准化
+> 架构标准化有助于工作流的维护和复用，BMAD 步骤文件架构符合 JIT 加载原则。
+
+### 按需加载原则
+> alwaysApply 规则应保持精简，详细信息应通过索引按需加载，避免过度占用上下文。
+
+### 信息收集灵活性
+> 收集信息时应支持用户最自然的表达方式，避免强制要求用户不熟悉的信息。
+
+### 确认机制
+> 重要操作（如批量生成文件）前应让用户确认，避免推导错误导致返工。
+
+### 性能优化原则
+> AI 指令需要具体的执行步骤和约束条件，过于宽泛的指令会导致过度执行。
+
+### 透明度原则
+> 自动化生成的内容需要明确标注来源，避免误导用户。
+
+---
+
+*最后更新：2026-01-20 20:30  
+*当前版本：0.17.0  
+*作者：JosephDeng*