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