read-before-edit（编辑前阅读）

Read Before Edit Skill

這是 maihouses 專案的核心規範：絕對禁止在沒有閱讀檔案的情況下進行修改。

🚨 核心原則

📖 READ → 🧠 UNDERSTAND → ✏️ EDIT

永遠不要跳過 READ 步驟！

🎯 執行時機

• 每次使用 Edit 工具前
• 每次使用 Write 工具前
• 用戶要求修改任何檔案時
• 用戶要求實作新功能時

📋 必讀檔案清單

修改檔案前，必須閱讀：

要修改的檔案本身
    │
    ├── 該檔案 import 的所有模組
    │
    ├── 相關的類型定義檔案 (types.ts, *.d.ts)
    │
    ├── 相關的 API/服務層檔案
    │
    ├── 相關的 hooks 和 context
    │
    ├── 相關的組件檔案
    │
    └── 相關的工具函數

🔍 實際範例

範例 1: 修改 React 組件

任務： 修改 src/pages/Login.tsx

必須閱讀的檔案：

# 1. 要修改的檔案本身
Read: file_path="src/pages/Login.tsx"

# 2. 搜尋相關類型定義
Glob: pattern="**/types/*auth*.ts"
Read: file_path="src/types/auth.ts"

# 3. 搜尋相關 API
Grep: pattern="login|auth" glob="**/api/**/*.ts" output_mode="files_with_matches"
Read: file_path="src/api/auth.ts"

# 4. 搜尋相關 hooks
Grep: pattern="useAuth" glob="**/hooks/**/*.ts" output_mode="files_with_matches"
Read: file_path="src/hooks/useAuth.ts"

# 5. 搜尋相關 context
Glob: pattern="**/context/*Auth*.tsx"
Read: file_path="src/context/AuthContext.tsx"

# 6. 檢查相關組件
Grep: pattern="LoginForm|Button" glob="**/components/**/*.tsx" output_mode="files_with_matches"
Read: file_path="src/components/LoginForm.tsx"

# 7. 檢查工具函數
Grep: pattern="validate" glob="**/utils/**/*.ts" output_mode="files_with_matches"
Read: file_path="src/utils/validation.ts"

範例 2: 修改 API 層

任務： 修改 src/api/users.ts

必須閱讀的檔案：

# 1. API 檔案本身
Read: file_path="src/api/users.ts"

# 2. 相關類型定義
Read: file_path="src/types/user.ts"
Read: file_path="src/types/api.ts"

# 3. API 基礎配置
Grep: pattern="axios|fetch|baseURL" glob="**/api/**/*.ts" output_mode="files_with_matches"
Read: file_path="src/api/client.ts"

# 4. 錯誤處理模組
Grep: pattern="handleError|ApiError" glob="**/api/**/*.ts" output_mode="files_with_matches"
Read: file_path="src/api/errorHandler.ts"

# 5. 認證相關（如果 API 需要認證）
Read: file_path="src/api/auth.ts"

範例 3: 新增功能

任務： 實作「忘記密碼」功能

必須閱讀的檔案：

# 1. 了解現有認證流程
Read: file_path="src/pages/Login.tsx"
Read: file_path="src/api/auth.ts"
Read: file_path="src/types/auth.ts"

# 2. 了解表單處理模式
Grep: pattern="handleSubmit|onSubmit" glob="**/pages/**/*.tsx" output_mode="content" -B=2 -C=5
Read: file_path="src/components/Form.tsx"

# 3. 了解驗證模式
Read: file_path="src/utils/validation.ts"

# 4. 了解錯誤處理模式
Grep: pattern="try.*catch" glob="**/pages/**/*.tsx" output_mode="content" -B=2 -C=5

# 5. 了解路由配置
Grep: pattern="route|path" glob="**/router/**/*.tsx" output_mode="files_with_matches"
Read: file_path="src/router/routes.tsx"

✅ 閱讀檢查清單

在開始修改前，確認已理解：

• 這個檔案的主要功能
• 所有 import 的模組來自哪裡、做什麼
• 使用的類型定義是什麼
• 現有的代碼風格和模式
• 錯誤處理方式
• 變數命名慣例
• 函數結構和組織方式
• 相依的其他模組如何運作

🚫 絕對禁止的行為

// ❌ 沒有先 Read 就直接 Edit
Edit: file_path="src/api/users.ts" ...

// ❌ 只讀要修改的檔案，不讀相關檔案
Read: file_path="src/pages/Login.tsx"
Edit: file_path="src/pages/Login.tsx" ...
// 跳過了 types, api, hooks, context!

// ❌ 隨便找一些檔案讀，假裝有在看
Read: file_path="src/index.tsx"  // 不相關
Read: file_path="README.md"      // 不相關
Edit: file_path="src/pages/Login.tsx" ...

// ❌ 讀了但沒理解就開始改
Read: file_path="src/api/auth.ts"
// 立即
Edit: file_path="src/api/auth.ts" ...
// 沒有理解現有架構！

✅ 正確的流程

// ✅ 步驟 1: 識別要修改的檔案
任務: 修改登入頁面加入「記住我」功能

// ✅ 步驟 2: 列出所有相關檔案
相關檔案:
- src/pages/Login.tsx (要修改的檔案)
- src/types/auth.ts (類型定義)
- src/api/auth.ts (API 呼叫)
- src/hooks/useAuth.ts (認證 hook)
- src/utils/storage.ts (localStorage 工具)

// ✅ 步驟 3: 完整閱讀所有檔案
Read: file_path="src/pages/Login.tsx"
Read: file_path="src/types/auth.ts"
Read: file_path="src/api/auth.ts"
Read: file_path="src/hooks/useAuth.ts"
Read: file_path="src/utils/storage.ts"

// ✅ 步驟 4: 理解現有架構
- Login.tsx 使用 useAuth hook
- 表單狀態用 useState 管理
- API 呼叫有完整錯誤處理
- 使用 LoginCredentials interface
- storage.ts 已有 localStorage 封裝

// ✅ 步驟 5: 規劃修改
1. 在 LoginCredentials 加入 rememberMe?: boolean
2. 在 Login.tsx 加入 checkbox
3. 在 useAuth 處理 rememberMe 邏輯
4. 使用 storage.ts 儲存登入狀態

// ✅ 步驟 6: 開始修改
Edit: file_path="src/types/auth.ts" ...
Edit: file_path="src/pages/Login.tsx" ...
Edit: file_path="src/hooks/useAuth.ts" ...

📊 閱讀覆蓋率檢查

修改前，確認閱讀覆蓋率：

### 閱讀覆蓋率報告

#### 已閱讀 ✅

- [x] src/pages/Login.tsx (要修改的檔案)
- [x] src/types/auth.ts (類型定義)
- [x] src/api/auth.ts (API 層)
- [x] src/hooks/useAuth.ts (hooks)
- [x] src/context/AuthContext.tsx (context)
- [x] src/utils/validation.ts (工具函數)

#### 覆蓋率: 100%

✅ 可以安全開始修改

🎯 為什麼必須這樣做？

避免的問題：

1. 破壞現有功能 - 不理解代碼就修改會破壞其他功能
2. 類型不匹配 - 不知道現有類型定義導致類型錯誤
3. 風格不一致 - 不了解代碼風格導致混亂
4. 重複造輪子 - 不知道已有工具函數而重複實作
5. 引入 bug - 不理解邏輯流程而引入錯誤

好處：

1. 理解上下文 - 知道代碼在做什麼、為什麼這樣做
2. 保持一致性 - 修改符合現有風格和模式
3. 避免重複 - 知道可以重用哪些代碼
4. 正確使用類型 - 使用正確的 interface/type
5. 高品質代碼 - 修改更準確、更安全

🚨 監督系統

專案已配置 hooks 監督系統（見 settings.json），會在 Edit/Write 前檢查是否已 Read。

如果違反規則，會看到：

🚫 [監督系統] Edit 被阻止！必須先 Read 該檔案

這不是建議，而是強制規則。

📝 完整案例研究

見專案根目錄的 CLAUDE.md 第 "📖 強制閱讀規範" 章節。

💡 快速提示

修改檔案前的自我檢查：

1. ❓ 我有讀過這個檔案嗎？
2. ❓ 我理解它的所有 import 嗎？
3. ❓ 我知道相關的類型定義嗎？
4. ❓ 我了解它如何與其他模組互動嗎？
5. ❓ 我清楚現有的代碼風格嗎？

如果有任何一個答案是「否」，就不要開始 Edit！

🎓 參考規範

• 完整規範: CLAUDE.md (專案根目錄)
• 監督系統: .claude/settings.json hooks 配置
• 稽核腳本: scripts/ai-supervisor.sh

記住：Read is not optional. Read is mandatory.