CLAUDE.md

本專案的完整技術架構、目錄結構、開發流程、內容撰寫規範與 AI 代理人守則， 維護於 .agents/AGENTS.md。

開始任何修改前，請先完整閱讀 .agents/AGENTS.md，尤其是：

• 第 3 節：開發維護指令（本地預覽、建置、電子書同步/編譯）
• 第 4 節：內容撰寫與結構規範（部落格文章、電子書章節、美食地圖、影片短連結、 財經文章數學公式／Mermaid／內嵌圖表／私有計算器）
• 第 9 節：AI 代理人特別守則（含多項已踩過坑、務必遵守的具體規則）

以下是最容易踩到的地雷，先記住：

• 本機預覽用 npm run preview（不需要 Ruby/Jekyll），一次性建置用 powershell -ExecutionPolicy Bypass -Command "npm run build"。
• 純更新電子書一律加 --ebook-only：node tools/import-content.mjs --ebook-only， 否則會連帶重寫全部 _posts/finance/*.md。
• Markdown 清單一律用 *（不用 -）且絕不縮排——縮排 4 格以上會被 kramdown 誤判成程式碼區塊，清單符號會原樣印出。
• 數學公式一律用 $$...$$（kramdown 原生語法），絕不用單一 $；且只在 解釋模型本身時使用，其餘敘述段落改寫白話文字。
• 手寫文章／公告的檔名必須包含 welcome、released 或 notice，否則會被 tools/import-content.mjs 當作過期匯入檔自動清除。
• 提交前務必本地驗證：node --check ebook/reader.js + 本地建置成功。

完整細節、原因與例外情況都在 .agents/AGENTS.md 裡，這裡只是入口索引， 不要只看這份摘要就動手，仍要讀完整份文件。