三份文檔與方法論沉澱
做了 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 第九章「版本記錄與文檔維護」、第十二章「產品方法論沉澱」。