---
name: readme-maintenance
description: 專案 README.md 維護與文檔同步指南。確保 README.md 與專案實際狀態保持同步，包括技術棧更新、功能變更、專案結構調整等。**🚨 關鍵要求：每次完成任何修改後，都必須檢查並更新 README.md！**
license: MIT
---

# README.md 維護技能

## 功能概述

這個技能確保專案的 README.md 文檔與實際專案狀態保持完全同步，包括：

- 技術棧版本更新
- 新功能文檔化
- 專案結構變更
- 安裝流程更新
- 使用方式說明調整

## 🔥 關鍵規則：每次修改後必須更新 README.md

### 📋 強制執行流程

**每次完成任何程式碼修改後，無論大小，都必須執行以下步驟：**

```
1️⃣  完成程式碼修改
    ↓
2️⃣  立即檢查 README.md 是否需要更新
    ↓
3️⃣  更新相應的 README.md 區段
    ↓
4️⃣  測試 README.md 內容的準確性
    ↓
5️⃣  提交包含 README.md 更新的 commit
```

### ⚠️ 不得跳過的檢查點

**以下情況完成後，絕對不能跳過 README.md 檢查：**

- 🔄 **技術棧更新**：版本號變更、新增依賴、移除套件
- 🆕 **功能增減**：新增功能、移除功能、功能變更
- 📁 **結構調整**：新增檔案/目錄、移除檔案/目錄、重新組織
- 🔧 **流程變更**：安裝步驟、開發流程、部署方式
- 📚 **文檔更新**：技能更新、配置變更、API 變更
- 🐛 **Bug 修復**：影響使用方式的錯誤修正
- 🚀 **版本發布**：任何準備發布的修改

### 🎯 為什麼這麼重要？

**❌ 不更新 README.md 的後果：**

- 使用者按照過時的文檔無法成功使用
- 技術棧版本不符導致安裝失敗
- 功能說明與實際不符造成困惑
- 專案可信度降低

**✅ 立即更新的好處：**

- 保持文檔與實際功能一致
- 避免使用者遇到過時資訊
- 維護專案專業形象
- 減少支援問題數量

## 何時使用我

在以下情況下使用此技能：

- 進行技術棧升級（如 Next.js、React、Jotai 版本更新）
- 新增或移除功能時
- 修改專案結構時
- 更新依賴套件版本
- 變更安裝或開發流程時
- **🔥 每次完成任何修改後（這是最重要的觸發條件）**
- 發布新版本前

## 🔍 立即檢查清單（每次修改後必須執行）

### ⚡ 每次修改完成後的強制檢查

**完成任何程式碼修改後，立即執行這個檢查清單：**

#### 🚨 第一步：README.md 影響評估

```
問問自己：
1. 我剛才的修改會影響 README.md 的哪些內容？
2. 是否涉及版本號、功能描述、專案結構？
3. 使用者會不會因為這個修改而困惑？
```

#### 📝 第二步：立即更新對應區段

根據修改類型，立即更新：

**技術棧修改**：

- [ ] 更新「核心技術」區段的版本號
- [ ] 更新「多國語系」區段的套件版本
- [ ] 檢查系統需求是否需要調整

**功能變更**：

- [ ] 在「功能特色」區段新增/修改/移除功能說明
- [ ] 更新「使用方式」區段的相關操作說明
- [ ] 調整「特色功能詳解」區段

**結構調整**：

- [ ] 更新「專案結構」區段的樹狀圖
- [ ] 修改相應的檔案說明
- [ ] 檢查路徑是否正確

**流程變更**：

- [ ] 更新「安裝與執行」區段
- [ ] 修改「開發指南」區段的相關說明
- [ ] 檢查範例指令是否正確

#### 🧪 第三步：驗證更新內容

```
1. 內容檢查：
   - [ ] 所有版本號碼與 package.json 一致
   - [ ] 功能描述與實際功能相符
   - [ ] 專案結構圖表正確

2. 格式檢查：
   - [ ] Markdown 語法正確
   - [ ] 程式碼區塊語法高亮正確
   - [ ] 連結都可以正常點擊

3. 實用性檢查：
   - [ ] 新手能按照說明成功安裝
   - [ ] 功能使用說明清晰易懂
   - [ ] 範例程式碼可以執行
```

#### ✅ 第四步：提交更新

```
1. 確認 README.md 已更新
2. 執行 git add README.md
3. 提交時明確說明文檔更新：
   git commit -m "docs: 更新 README.md 反映 [變更內容]

範例：
- "docs: 更新 README.md 技術棧版本到 Next.js 16.0.10"
- "docs: 新增 README.md 搜尋功能說明"
- "docs: 更新 README.md 專案結構反映新元件"
```

### 📦 技術棧同步

每次更新依賴套件後，檢查並更新以下區段：

#### 核心技術

- [ ] Next.js 版本：檢查 `package.json` 中的 `next` 版本
- [ ] React 版本：檢查 `react` 和 `react-dom` 版本
- [ ] Jotai 版本：檢查 `jotai` 相關套件版本
- [ ] Tailwind CSS 版本：檢查 `tailwindcss` 版本
- [ ] TypeScript 版本：檢查 `typescript` 版本

#### 多國語系

- [ ] i18next 版本：檢查 `react-i18next` 版本
- [ ] 語言偵測器版本：檢查 `i18next-browser-languagedetector`
- [ ] 支援語言列表：確認與 `src/i18n/locales/` 目錄一致

### 📁 專案結構同步

當新增、移除或重新組織檔案時：

#### 新增檔案/目錄時

- [ ] 在專案結構區段新增對應說明
- [ ] 更新相應的功能描述
- [ ] 確認檔案路徑正確

#### 移除檔案/目錄時

- [ ] 從專案結構區段移除相應說明
- [ ] 檢查是否影響功能描述
- [ ] 更新相關使用方式說明

#### 重新組織時

- [ ] 更新所有相關的路徑
- [ ] 調整說明文字以反映新的結構
- [ ] 確認範例程式碼中的路徑正確

### 🚀 功能變更同步

#### 新增功能時

- [ ] 在「功能特色」區段添加功能說明
- [ ] 更新「使用方式」區段的相關說明
- [ ] 考慮是否需要新增範例程式碼
- [ ] 更新「特色功能詳解」區段

#### 修改功能時

- [ ] 更新現有的功能描述
- [ ] 檢查使用方式說明是否需要調整
- [ ] 更新相關的範例程式碼
- [ ] 確認技術細節說明正確

#### 移除功能時

- [ ] 從功能特色區段移除相關說明
- [ ] 更新使用方式，移除相關操作說明
- [ ] 檢查是否影響其他功能的描述
- [ ] 清理相關的範例程式碼

### 📊 版本資訊更新

#### 檢查點

- [ ] 確認所有版本號碼與實際安裝的版本一致
- [ ] 檢查是否有過時的版本資訊
- [ ] 確認系統需求是否仍然準確
- [ ] 驗證安裝步驟是否正確

### 🔧 開發指南更新

#### OpenCode Skills 整合

- [ ] 檢查技能列表是否與 `.opencode/skills/` 目錄一致
- [ ] 更新技能描述和使用方式
- [ ] 確認配置結構說明正確
- [ ] 更新防錯機制說明

#### GitHub Copilot Agent Skills 整合

- [ ] 確認 `.github/skills/` 中的符號連結正常
- [ ] 檢查軟路由共享機制運作
- [ ] 驗證雙邊技能一致性

#### 自動檢查機制

- [ ] 確認自動檢查腳本說明正確
- [ ] 檢查防錯措施描述是否完整
- [ ] 驗證規範說明與實際配置一致

### 🎯 樣板與格式

#### 功能特色格式

```markdown
### 🌍 功能類別

- **子功能 1**: 簡短描述
- **子功能 2**: 簡短描述
- **子功能 3**: 簡短描述
```

#### 技術架構格式

```markdown
### 核心技術

- **Framework**: Next.js [版本] (App Router)
- **UI Library**: React [版本]
- **狀態管理**: Jotai [版本] + 本地持久化
- **樣式框架**: Tailwind CSS [版本]
- **開發語言**: TypeScript [版本]
- **套件管理**: pnpm
```

#### 專案結構格式

```markdown
src/
├── app/ # Next.js App Router
│ ├── admin/ # 說明
│ │ └── page.tsx # 檔案說明
├── components/ # React 組件庫
│ └── ComponentName.tsx # 組件說明
...
```

## 自動檢查腳本

建立以下腳本來自動檢查一致性：

### 檢查腳本 (`scripts/check-readme.sh`)

```bash
#!/bin/bash

echo "🔍 檢查 README.md 與專案同步狀態..."

# 檢查技術棧版本
echo "📦 檢查技術棧版本..."
NEXT_VERSION=$(cat package.json | grep -o '"next": "[^"]*"' | cut -d'"' -f4)
echo "實際 Next.js 版本: $NEXT_VERSION"

# 檢查專案結構
echo "📁 檢查專案結構..."
if [ -d "src/app" ]; then
    echo "✅ src/app 目錄存在"
else
    echo "❌ src/app 目錄不存在"
fi

# 檢查技能目錄
echo "🛠️ 檢查 Skills 整合..."
if [ -d ".opencode/skills" ]; then
    echo "✅ .opencode/skills 目錄存在"
else
    echo "❌ .opencode/skills 目錄不存在"
fi

if [ -d ".github/skills" ]; then
    echo "✅ .github/skills 目錄存在"
else
    echo "❌ .github/skills 目錄不存在"
fi
```

## 常見問題

### Q: 如何處理版本號衝突？

A: 以 `package.json` 中的實際版本為準，優先更新 README.md 中的版本資訊。

### Q: 專案結構變更很大時如何處理？

A: 分階段更新，先更新主要目錄結構，再逐步完善各個子目錄的說明。

### Q: 新功能很多時如何組織？

A: 按功能類別分組，使用統一的格式和一致的描述風格。

### Q: 如何確保 README.md 始終是最新的？

A: 在每次重大變更後都觸發此技能，建立定期檢查的習慣。

### Q: 軟路由共享如何運作？

A: `.github/skills/` 中的符號連結指向 `.opencode/skills/`，確保兩邊共享同一份檔案，修改一次即可同步到兩個系統。

## 最佳實踐

### ✅ 做什麼

- **即時更新**：變更後立即更新 README
- **一致格式**：使用統一的 markdown 格式
- **清晰描述**：用簡潔明確的語言
- **範例程式碼**：提供實用的程式碼範例
- **版本同步**：確保所有版本資訊正確
- **軟路由共享**：透過符號連結避免重複維護

### ❌ 避免什麼

- **過時資訊**：不要留下過時的版本或功能說明
- **冗長描述**：避免過於冗長的功能描述
- **不一致格式**：不要混用不同的格式風格
- **缺少範例**：不要只有描述沒有實際範例
- **錯誤路徑**：確保所有路徑和檔名正確
- **重複維護**：避免建立多個相同內容的檔案

## 🚨 最終驗證：完成任何修改後的強制流程

### ⚡ 必須遵守的最終檢查

**每次完成任何程式碼修改後，無論大小，都必須完成以下所有步驟：**

#### 🔥 第一步：立即 README.md 影響評估（不得跳過）

```
問問自己：
1. 我剛才的修改會如何影響 README.md？
2. 有沒有版本號、功能、結構的變更？
3. 使用者會不會因為沒更新文檔而困惑？
```

#### 📝 第二步：立即更新 README.md（不得延後）

```
根據修改類型，立即更新對應區段：
- 技術棧修改 → 更新版本號
- 功能變更 → 更新功能說明
- 結構調整 → 更新專案結構圖
- 流程變更 → 更新安裝說明
```

#### ✅ 第三步：完整驗證（必須完成）

1. **內容檢查**
   - [ ] 所有版本號碼與實際一致
   - [ ] 專案結構描述準確
   - [ ] 功能描述完整且最新
   - [ ] 範例程式碼可執行

2. **格式檢查**
   - [ ] Markdown 語法正確
   - [ ] 所有連結可正常點擊
   - [ ] 程式碼區塊語法高亮正確
   - [ ] 圖片顯示正常

3. **實用性檢查**
   - [ ] 新手能按照說明成功安裝
   - [ ] 功能使用說明清晰易懂
   - [ ] 開發環境設置說明完整
   - [ ] 問題排查指南有效

4. **🔥 最重要：確認 README.md 已同步**
   - [ ] **確認本次修改的相關內容已更新**
   - [ ] **確認沒有遺漏任何變更說明**
   - [ ] **確認新使用者能理解最新狀態**

5. **最終驗證**
   - [ ] 在 GitHub 上顯示效果正常
   - [ ] 所有連結都能正確跳轉
   - [ ] 程式碼複製後可直接使用
   - [ ] 表格和列表顯示正確

#### ⚠️ 禁止行為

**以下行為絕對禁止：**

- ❌ 修改程式碼後不檢查 README.md
- ❌ 說「等一下再更新文檔」
- ❌ 只提交程式碼，延後文檔更新
- ❌ 假設「小修改不需要更新文檔」

#### 🎯 完成標準

**只有滿足以下條件才算完成：**

- ✅ README.md 已更新
- ✅ 更新內容已驗證
- ✅ 包含在本次 commit 中
- ✅ 確認使用者不會困惑

## 相關技能

- **code-standards**: 確保程式碼品質
- **git-workflow**: 版本控制最佳實踐
- **i18n-workflow**: 多語言文檔維護

---

**這個技能確保您的專案文檔始終保持最新、準確和專業，同時透過軟路由實現 OpenCode 和 GitHub Copilot 的雙系統共享！**