📄 指令與技能文件優化準則 (Refactoring Guide)

當單一指令檔超過 300-500 行時，會導致 AI 注意力稀釋（Lost in the Middle）及 RAG 檢索純度下降。請依照以下規範執行拆分與重構。

1. 長度與權重配置 (The 60-200-500 Rule)

• 黃金範圍：單一檔案維持在 50 ~ 200 行 效果最佳。
• 關鍵頭部：檔案的前 8 ~ 10 行 權重最高，應放置核心原則或最重要的規則。
• 拆分紅線：超過 300 行 應考慮拆分，超過 500 行 必須拆分。

2. 結構化拆分策略

不要僅按章節切割，應按 「觸發場景」 與 「單一職責」 拆分：

• 按技術棧 (Tech Stack)：如 php.md, laravel.md, vue.md。
• 按橫切關注點 (Cross-cutting Concerns)：如 testing.md, security.md, error-handling.md。
• 使用階層式結構：在特定目錄放置區域性的 AGENTS.md，讓 Agent 根據當前工作目錄自動載入最相關的局部指令。

3. 建立入口索引檔 (Entry Point Index)

於 .github/copilot-instructions.md 建立一個 少於 60 行 的導航檔：

• 快速導覽：列出各子檔路徑及其適用場景。
• 高優先規則：僅保留 3-5 條絕對必須遵守的全域準則。
• 避免冗餘：索引檔不應重複子檔內的細節，僅作為路由。

4. 執行流程 (Action Plan)

1. 分析密度：識別檔案中是否包含 3 種以上不同性質的內容（如：風格、架構、部署）。
2. 物理切割：將「可獨立使用」的主題提取至 .ai/skills/ 或 .github/instructions/ 子目錄。
3. 引用連結：在入口檔使用明確的 Markdown 連結指向子檔案。
4. 驗證：確保每個子檔主題單一、結構清晰（使用 H1, H2, H3 標題）。