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

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

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

1. 內容檢查

   • 所有版本號碼與實際一致
   • 專案結構描述準確
   • 功能描述完整且最新
   • 範例程式碼可執行

2. 格式檢查

   • Markdown 語法正確
   • 所有連結可正常點擊
   • 程式碼區塊語法高亮正確
   • 圖片顯示正常

3. 實用性檢查

   • 新手能按照說明成功安裝
   • 功能使用說明清晰易懂
   • 開發環境設置說明完整
   • 問題排查指南有效

4. 🔥 最重要：確認 README.md 已同步

   • 確認本次修改的相關內容已更新
   • 確認沒有遺漏任何變更說明
   • 確認新使用者能理解最新狀態

5. 最終驗證

   • 在 GitHub 上顯示效果正常
   • 所有連結都能正確跳轉
   • 程式碼複製後可直接使用
   • 表格和列表顯示正確

⚠️ 禁止行為

以下行為絕對禁止：

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

🎯 完成標準

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

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

相關技能

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

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