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 中

• ✅ 確認使用者不會困惑

相關技能

• code-standards: 確保程式碼品質

• git-workflow: 版本控制最佳實踐

• i18n-workflow: 多語言文檔維護

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