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/ 中的符號連結正常
檢查軟路由共享機制運作
驗證雙邊技能一致性

自動檢查機制

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

🎯 樣板與格式

功能特色格式

### 🌍 功能類別

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

技術架構格式

### 核心技術

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

專案結構格式

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

自動檢查腳本

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

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

#!/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（不得延後）

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

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

內容檢查
- 所有版本號碼與實際一致
- 專案結構描述準確
- 功能描述完整且最新
- 範例程式碼可執行
格式檢查
- Markdown 語法正確
- 所有連結可正常點擊
- 程式碼區塊語法高亮正確
- 圖片顯示正常
實用性檢查
- 新手能按照說明成功安裝
- 功能使用說明清晰易懂
- 開發環境設置說明完整
- 問題排查指南有效
🔥 最重要：確認 README.md 已同步
- 確認本次修改的相關內容已更新
- 確認沒有遺漏任何變更說明
- 確認新使用者能理解最新狀態
最終驗證
- 在 GitHub 上顯示效果正常
- 所有連結都能正確跳轉
- 程式碼複製後可直接使用
- 表格和列表顯示正確

⚠️ 禁止行為

以下行為絕對禁止：

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

🎯 完成標準

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

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

readme-maintenance