# 文件修改管理規範 v1.0 | 項目 | 內容 | |------|------| | 建立者 | Warren | | 建立時間 | 2026-03-22 | | 文件版本 | V1.0 | --- ## 1. 概述本文檔定義 Momentry 專案的文件修改流程，確保不同工具/模型對文件的一致性理解，防止誤修改並保留完整的修改紀錄。 ### 1.1 適用範圍 - 所有 `.md` 文件（技術文檔、安裝指南、API 文件等） - 所有 `.rs` 文件（Rust 源代碼） - 所有 `.sh` 文件（Shell 腳本） - 所有 `.yaml` / `.yml` 文件（配置文件） - 所有 `.json` 文件（配置及數據文件） ### 1.2 核心原則 1. **先讀後改**：修改前必須完整閱讀相關文件 2. **預檢清單**：修改前執行預檢查步驟 3. **變更對照**：修改後必須比對差異 4. **驗證確認**：變更後執行驗證測試 5. **完整紀錄**：所有修改必須記錄於版本歷史 --- ## 2. 修改前預檢清單 ### 2.1 文件閱讀要求修改文件前，必須完成以下閱讀： | 步驟 | 項目 | 說明 | |------|------|------| | 1 | 閱讀完整文件 | 不可僅閱讀部分章節 | | 2 | 理解文件用途 | 確認文件的目標讀者 | | 3 | 確認現有術語 | 使用一致的術語和命名 | | 4 | 查閱相關文件 | 確認相關聯的文件 | ### 2.2 預檢問題清單在修改前回答以下問題： ``` □ 1. 此修改是否影響其他文件？ □ 2. 此修改是否與現有規範衝突？ □ 3. 此修改是否需要更新版本歷史？ □ 4. 此修改是否需要新增測試？ □ 5. 此修改是否需要通知相關人員？ □ 6. 此修改是否有破壞性變更（Breaking Change）？ ``` ### 2.3 預檢命令修改前執行以下命令確認現有狀態： ```bash # 1. 確認 git 狀態 git status # 2. 檢查相關文件的最新版本 git log -3 --oneline # 3. 查看現有版本歷史 cat docs/.md | grep -A 20 "版本歷史" ``` --- ## 3. 文件修改流程 ### 3.1 標準修改流程 ``` ┌─────────────────────────────────────────────────────────────┐ │ Step 1: 閱讀 │ │ ├─ 完整閱讀目標文件 │ │ └─ 閱讀相關聯文件 │ ├─────────────────────────────────────────────────────────────┤ │ Step 2: 預檢 │ │ ├─ 回答預檢問題清單 │ │ └─ 執行預檢命令 │ ├─────────────────────────────────────────────────────────────┤ │ Step 3: 規劃 │ │ ├─ 說明修改內容 │ │ └─ 列出變更差異 │ ├─────────────────────────────────────────────────────────────┤ │ Step 4: 修改 │ │ ├─ 執行修改 │ │ └─ 更新版本歷史 │ ├─────────────────────────────────────────────────────────────┤ │ Step 5: 驗證 │ │ ├─ 執行 lint/format 檢查 │ │ └─ 執行相關測試 │ ├─────────────────────────────────────────────────────────────┤ │ Step 6: 提交 │ │ └─ 撰寫清晰的 commit message │ └─────────────────────────────────────────────────────────────┘ ``` ### 3.2 預修改彙報格式在執行修改前，必須先彙報以下內容： ```markdown ## 檔案 `` ## 修改原因 <說明修改的目的> ## 變更內容 ```diff - <刪除的內容> + <新增的內容> ``` ## 版本歷史更新 | 版本 | 日期 | 內容 | 操作人 | 工具/模型 | |------|------|------|--------|-----------| | Vx.x | YYYY-MM-DD | <修改說明> | <操作者> | <使用的工具> | ``` ### 3.3 版本歷史格式每個文件頂部必須包含版本歷史表： ```markdown ## 版本歷史 | 版本 | 日期 | 目的 | 操作人 | 工具/模型 | |------|------|------|--------|-----------| | V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 | | V1.1 | 2026-03-22 | 更新內容 | Warren | OpenCode / big-pickle | ``` --- ## 4. 變更對照 ### 4.1 diff 對照修改後必須提供 diff 對照： ```bash git diff ``` ### 4.2 變更類型分類 | 類型 | 標記 | 說明 | |------|------|------| | 新增 | `+` | 新增內容 | | 刪除 | `-` | 刪除內容 | | 修改 | `~` | 修改內容 | | 移動 | `↕` | 移動位置 | | 格式 | `@` | 格式變更 | ### 4.3 變更確認清單 ``` □ 1. diff 輸出已確認 □ 2. 變更符合預期 □ 3. 無意外變更 □ 4. 版本歷史已更新 □ 5. 其他關聯文件已檢查 ``` --- ## 5. 驗證流程 ### 5.1 自動化驗證修改後執行以下自動化檢查： ```bash # Rust 文件 cargo fmt -- --check cargo clippy --lib cargo test --lib # Python 文件 ruff check ruff format --check # Markdown 文件 markdownlint # Shell 文件 shellcheck -S error ``` ### 5.2 手動驗證清單 ``` □ 1. 文件語法正確 □ 2. 連結有效 □ 3. 格式一致 □ 4. 術語一致 □ 5. 版本歷史完整 □ 6. 變更記錄清晰 ``` --- ## 6. 提交規範 ### 6.1 Commit Message 格式 ``` :