四份文档各管一个维度：功能生命周期、改动细节、用户视角与产品品味

开场：翻遍 git log 也找不到答案

做了 30 个功能，三个月后想查「这个功能什么时候加的、当初为什么这样设计、中间改过几次方案」，翻遍 git log 也找不到。解法是让 AI 按严格模板维护四份文档。

一句话速览：FEATURES / CHANGELOG / RELEASE_NOTES 各管一个维度，METHODOLOGY 沉淀产品品味。

一、核心分工

FEATURES 回答「这个功能怎么来的」，CHANGELOG 回答「这次改了什么」，RELEASE_NOTES 回答「用户得到了什么」，METHODOLOGY 回答「我们是怎么想的」。四个问题各有归处，决策才能跨越对话存活。

二、四份文档各管一个维度

docs/FEATURES.md —— 功能的完整生命周期

功能点的唯一事实来源。状态流转 🟡 规划中 → 🔵 开发中 → 🟢 已完成 / ⚪ 已取消，每个功能带「历史沿革」，记录初始需求、方案变更及原因、最终实现。取消的功能也不删，标 ⚪ 并注明原因。

历史沿革靠状态流转自动生长：每次状态变更、方案调整都追加一条带日期的记录。日期必须读取系统当前时间，不能凭记忆填写；方案没变过也要写一条「初始需求」。

docs/CHANGELOG.md —— 每次改动的技术细节

按时间倒序，每条用表格记录问题/需求、根因/方案、改动范围、影响面、状态，类型标签 BUG / FEAT / REFACTOR / PERF / DOCS。写之前必须读系统时间，禁止凭记忆填时间戳，禁止积压补写。

docs/RELEASE_NOTES.md —— 用户能感知的变化

面向真实用户，语言风格与 CHANGELOG 完全不同。每条描述必须能回答「这对我有什么用」。

红线：禁止出现 Debug/调试功能、技术实现细节（模块名、文件路径、重构）、用户无感知的改动、开发者术语。只写用户能感知的变化：新功能一句话说明用户能做什么新事情；修复说明之前什么问题、现在解决了。每条不超过 3 句话，版本号遵循 SemVer。

docs/METHODOLOGY.md —— 产品决策与品味

AI 主动识别对话中的产品思路、决策逻辑和取舍偏好，提炼后直接写入，新对话自动继承。四段结构：

产品原则： 反复出现的核心信念和产品理念
设计决策记录： [日期] 决策内容，附理由与上下文
用户体验偏好： 对 UI/UX 的品味、倾向、审美标准
反模式： 明确拒绝过的方案，附拒绝理由

写入原则：提炼本质，同类合并，新条目标注日期，避免照搬对话原文；不记技术实现细节（那是 CHANGELOG 的事），不记一次性临时决定。触发时机：用户解释了「为什么这样做」、否决了方案并给出理由、表达了明确的 UI/UX 偏好、复盘时总结了经验。AI 识别到就直接写入，写完简要告知，无需每次征求许可。

三、CHANGELOG 表格模板

## YYYY-MM-DD HH:MM

### [类型] 标题        类型：BUG / FEAT / REFACTOR / PERF / DOCS

| 字段       | 内容                                     |
|-----------|------------------------------------------|
| 问题/需求  | 触发这次改动的原因（用户反馈 / Bug 表现 / 新需求）|
| 根因/方案  | Bug 填根因分析，功能填技术方案概述        |
| 改动范围   | 涉及的文件或模块列表                       |
| 影响面     | 这次改动可能影响哪些已有功能                |
| 状态       | ✅ 已完成 / ⏳ 进行中 / ⚠️ 需观察           |

四、为什么放在仓库里

设计决策写在 Notion 或飞书里也没用，**AI 读不到外部文档。**放在项目仓库内的 Markdown 文件是唯一能让 AI 自动获取上下文的方式。

课堂练习 · 30 分钟

① 在一个进行中的项目里建 docs/ 目录，让 AI 按模板初始化三份文档，把现有功能补进 FEATURES.md；② 把文档维护规则加入 Rule 文件，做一次小改动，验证 AI 是否自动更新 CHANGELOG；③ 回顾最近的产品讨论，手动往 METHODOLOGY.md 写 3 条你确认过的设计决策。