---
document_type: "operation_doc"
service: "MOMENTRY_CORE"
title: "文件修改管理規範 v1.0"
date: "2026-03-22"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "文件修改管理規範"
ai_query_hints:
  - "查詢 文件修改管理規範 v1.0 的內容"
  - "文件修改管理規範 v1.0 的主要目的是什麼？"
  - "如何操作或實施 文件修改管理規範 v1.0？"
---

# 文件修改管理規範 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 <file_path>

# 3. 查看現有版本歷史
cat docs/<file>.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
## 檔案
`<file_path>`

## 修改原因
<說明修改的目的>

## 變更內容
```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 <file_path>
```

### 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 <files>
ruff format --check <files>

# Markdown 文件
markdownlint <files>

# Shell 文件
shellcheck -S error <files>
```

### 5.2 手動驗證清單

```
□ 1. 文件語法正確
□ 2. 連結有效
□ 3. 格式一致
□ 4. 術語一致
□ 5. 版本歷史完整
□ 6. 變更記錄清晰
```

---

## 6. 提交規範

### 6.1 Commit Message 格式

```
<type>: <subject>

<body>

<footer>
```

### 6.2 Type 類型

| Type | 說明 |
|------|------|
| `feat` | 新功能 |
| `fix` | 錯誤修復 |
| `refactor` | 重構 |
| `docs` | 文檔更新 |
| `style` | 格式變更 |
| `test` | 測試相關 |
| `chore` | 維護工作 |

### 6.3 Commit Message 範例

```bash
# 文檔更新
git commit -m "docs: update INSTALL_MONGODB.md with LaunchAgent instructions

- Add LaunchDaemon plist installation steps
- Update management commands section
- Add version history entry

Closes: #xxx"

# 配置文件更新
git commit -m "fix: remove duplicate mongodb entry in monitor_config.yaml

The backup section had two mongodb entries which caused confusion.
Removed the duplicate config entry at line 408-414."
```

---

## 7. AI 工具修改額外規範

### 7.1 修改前確認

AI 工具修改文件前，必須：

1. **完整閱讀**：閱讀完整文件（不可只讀取部分）
2. **理解語境**：理解文件的用途和目標讀者
3. **查閱相關**：查閱相關聯文件確保一致性
4. **提出計畫**：修改前先提出變更計畫供確認

### 7.2 修改後確認

AI 工具修改文件後，必須：

1. **展示差異**：顯示修改的 diff 內容
2. **說明變更**：解釋每項變更的目的
3. **執行驗證**：執行相關的 lint/test 命令
4. **更新歷史**：更新版本歷史表

### 7.3 禁止事項

AI 工具**禁止**以下行為：

```
□ 未閱讀完整文件即進行修改
□ 未經確認直接執行大規模修改
□ 未提供 diff 即提交變更
□ 未更新版本歷史
□ 未執行驗證即聲稱完成
□ 擅自刪除其他工具/模型添加的內容
□ 無視現有文件規範
```

---

## 8. 審查清單

### 8.1 提交前審查

```
□ 1. 修改內容已完整閱讀
□ 2. 預檢問題清單已回答
□ 3. diff 對照已確認
□ 4. 版本歷史已更新
□ 5. 自動化驗證已通過
□ 6. 手動驗證清單已完成
□ 7. Commit message 符合規範
□ 8. 無敏感資訊泄露
```

### 8.2 Code Review 關注點

- [ ] 修改是否影響現有功能？
- [ ] 修改是否與專案規範一致？
- [ ] 是否有遺漏的關聯修改？
- [ ] 測試是否足夠？
- [ ] 文檔是否同步更新？

---

## 9. 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode / big-pickle |
