三份文档与方法论沉淀
做了 30 个功能，三个月后想查「这个功能什么时候加的、当初为什么这样设计、中间改过几次方案」，翻遍 git log 也找不到。解法是让 AI 按严格模板维护三份文档，再加一份自动沉淀的方法论手册。本页两个演示都可以动手操作。
核心分工：FEATURES 回答「这个功能怎么来的」，CHANGELOG 回答「这次改了什么」，RELEASE_NOTES 回答「用户得到了什么」，METHODOLOGY 回答「我们是怎么想的」。四个问题各有归处，决策才能跨越对话存活。
功能的完整生命周期
功能点的唯一事实来源。状态流转 🟡 规划中 → 🔵 开发中 → 🟢 已完成 / ⚪ 已取消，每个功能带「历史沿革」，记录初始需求、方案变更及原因、最终实现。取消的功能也不删，标 ⚪ 并注明原因。
每次改动的技术细节
按时间倒序，每条用表格记录问题/需求、根因/方案、改动范围、影响面、状态，类型标签 BUG / FEAT / REFACTOR / PERF / DOCS。写之前必须读系统时间，禁止凭记忆填时间戳，禁止积压补写。
用户能感知的变化
面向真实用户，语言风格与 CHANGELOG 完全不同。每条描述必须能回答「这对我有什么用」。红线：禁写调试功能、技术细节和用户无感知的改动。
产品决策与品味
AI 主动识别对话中的产品思路、决策逻辑和取舍偏好，提炼后直接写入，新对话自动继承。四段结构：产品原则、设计决策记录、用户体验偏好、反模式。
项目里每天都会产生各种信息，分诊能力决定文档体系能不能跑起来。下面逐条给出 8 条真实信息，判断每条该写进哪份文档。
FEATURES 里每个功能都带一条「历史沿革」。它靠状态流转自动生长：每次状态变更、方案调整都追加一条带日期的记录。点击按钮，亲手把一个功能从规划推到上线。
记录里的日期读的是你设备的系统时间。规则原文要求：时间必须读取系统当前时间，不能凭记忆填写；方案没变过也要写一条「初始需求」。
每条改动用固定字段的表格记录，AI 按格填写就行，不需要每次想该写什么。
## YYYY-MM-DD HH:MM
### [类型] 标题 类型：BUG / FEAT / REFACTOR / PERF / DOCS
| 字段 | 内容 |
|-----------|--------------------------------------------|
| 问题/需求 | 触发这次改动的原因（用户反馈 / Bug 表现 / 新需求）|
| 根因/方案 | Bug 填根因分析，功能填技术方案概述 |
| 改动范围 | 涉及的文件或模块列表 |
| 影响面 | 这次改动可能影响哪些已有功能 |
| 状态 | ✅ 已完成 / ⏳ 进行中 / ⚠️ 需观察 |- Debug / 调试相关功能
- 技术实现细节：模块名、文件路径、重构
- 用户无感知的改动
- 开发者术语和技术原理解释
- 用户能感知到的变化，每条能回答「这对我有什么用」
- 新功能：一句话说明用户能做什么新事情
- 修复：之前什么问题，现在解决了
- 每条不超过 3 句话，版本号遵循 SemVer
四段结构
- 产品原则：反复出现的核心信念和产品理念
- 设计决策记录：[日期] 决策内容，附理由与上下文
- 用户体验偏好：对 UI/UX 的品味、倾向、审美标准
- 反模式：明确拒绝过的方案，附拒绝理由
写入原则
- 提炼本质，同类合并，新条目标注日期，避免照搬对话原文
- 不记技术实现细节（那是 CHANGELOG 的事），不记一次性临时决定
- 触发时机：用户解释了「为什么这样做」、否决了方案并给出理由、表达了明确的 UI/UX 偏好、复盘时总结了经验
- AI 识别到就直接写入，写完简要告知，无需每次征求许可
为什么放在仓库里：设计决策写在 Notion 或飞书里也没用，AI 读不到外部文档。放在项目仓库内的 Markdown 文件是唯一能让 AI 自动获取上下文的方式。
提交物：docs/ 目录 + 3 条方法论。① 在一个进行中的项目里建 docs/ 目录，让 AI 按模板初始化三份文档，把现有功能补进 FEATURES.md；② 把文档维护规则加入 Rule 文件，做一次小改动，验证 AI 是否自动更新 CHANGELOG；③ 回顾最近的产品讨论，手动往 METHODOLOGY.md 写 3 条你确认过的设计决策。
素材来源：开源仓库 itshen/xs_vibe_rules 中 rule-opensource.mdc 第九章「版本记录与文档维护」、第十二章「产品方法论沉淀」。