Claude Code｜CLAUDE.md 完整教學

CLAUDE.md 是讓 Claude Code 了解專案長期規矩的文件，適合保存啟動方式、測試要求與重要架構邊界。本篇會用 /init 建立起點，再把自動整理出的內容改成短而可驗證的規範，最後從新工作階段確認載入。讀完後，你能分清楚專案指引與真正控制權限的設定。

請先具備Markdown 基礎，並準備待辦練習專案。可以使用 CLI 或支援的桌面介面；下例的斜線指令輸入在 Claude Code 對話框，MD 範本則寫入專案檔案，兩者位置不同。

先決定哪些資訊值得長期保存

閱讀完整文字說明

CLAUDE.md 完整教學，以流程和文件圖形呈現教學重點。

CLAUDE.md 適合寫「這個專案如何正確工作」，例如測試命令、模組分工與不能破壞的資料行為。一次性任務的主標題文字、今天待修的錯誤清單，通常放在當次需求或任務紀錄即可。把所有聊天內容都複製進規則檔，只會增加讀取負擔與過期資訊。

官方建議規則保持精簡，因為載入的文字會使用上下文。與其追求固定字數，不如檢查每一段是否有實際用途：工具能否直接從程式看出來？團隊是否真的採用這項規則？過去是否因忽略它而出錯？保留最能影響工作品質的資訊。

使用 /init 建立起點

在專案根目錄啟動 Claude Code，先確認已有 README 與 package.json，再輸入 /init。它會依程式內容整理可用的指令與慣例；如果已存在 CLAUDE.md，應檢查提出的改善，而不是直接覆蓋既有規則。不同版本可能提供額外互動流程，依畫面閱讀提案。

/init

產生後立即打開文件，對照 package.json 核對每個命令。最常見的問題是把別的框架常用指令帶入本專案，例如本練習使用 npm start，而不是假設一定有 npm run dev。自動產生代表省下整理時間，並不免除人類核對責任。

寫一份可直接使用的短範本

以下範本適用於本系列的原生 JavaScript 待辦專案。若你的材料已換成其他框架，請先改成真正存在的路徑與命令。範本刻意不寫模型名稱、密碼或個人機器絕對路徑，讓其他讀者取得同一份專案也能理解。

# 待辦清單專案指引

## 技術與分工
- 使用 HTML、CSS 與原生 JavaScript，不新增框架或第三方套件。
- model.js 放純資料操作；app.js 負責 DOM 互動。
- 用項目 id 處理切換與刪除，不依畫面排序判斷項目。

## 常用命令
- npm start：啟動本機開發伺服器。
- npm test：執行 Node.js 測試。

## 變更與驗證
- 修改前先閱讀現有程式與測試，保留無關的既有變更。
- 行為變更要補上能重現需求或錯誤的測試。
- 介面修改後檢查新增、勾選、刪除，以及窄螢幕顯示。
- 回報實際做過的檢查，清楚列出未驗證的部分。

規則要描述可判斷的行為。「程式品質要好」很難驗收；「用 id 處理切換，不依顯示索引」就能透過程式與測試確認。也不要寫互相衝突的要求，例如同時規定所有變更都不能加測試，卻又要求每個行為變更一定補測試。

確認文件真的被載入

保存後啟動新的工作階段，使用 /context 查看 Memory files 等載入資訊，確認出現預期位置的 CLAUDE.md。也可以從 /memory 進入相關記憶與規則管理功能。只讓 Claude 回答「我知道規則」並不是最可靠的載入證據，先看檔案清單，再用小任務確認行為。

/context

請先指出目前載入的專案指引檔案。
根據這些指引，說明待辦清單的資料邏輯、DOM 互動與測試各放哪裡。
如果要加篩選功能，列出應保留的資料行為，先不要修改。

預期回覆能把規則對應到實際檔案與篩選需求。若檔案存在卻沒載入，先檢查名稱、啟動資料夾與設定來源；若載入了卻回答矛盾，查是否有上層或子目錄規則提供不同說法。這時請讀規則作用範圍，不要只在同一份文件重複加粗警告。

指引不能取代權限設定

CLAUDE.md 是進入上下文的自然語言指引，不是作業系統的存取控制。寫「不要讀金鑰」可以表達專案要求，但需要控制工具操作時，應另外設定權限、資料範圍與環境。兩者要一致，不能只靠一句話替代實際邊界。

需要重複執行的完整審查流程，可以整理成Skills；需要特定事件自動觸發的檢查，則參考Hooks 入門。把每項資訊放在合適的位置，會比把整份自動化腳本都塞進 CLAUDE.md 更容易維護。

維護方式與小練習

規則也應避免依賴只有你知道的縮寫。例如「照舊方式跑驗證」沒有告訴新讀者舊方式是什麼；改成實際命令與必要前提才可執行。若測試需要特殊環境，寫清楚無法執行時要回報缺少什麼，不要讓 Claude 用一句「測試通過」掩蓋環境尚未備妥。

當啟動指令、測試位置或架構改變時，一起更新規則並審查差異。發現 Claude 重複犯同一種錯誤，先判斷是資訊缺失、描述矛盾，還是工具能力問題；只有前兩者適合直接靠改寫規則改善。規則增加後也應定期刪除已無用途的段落。

小練習是依範本建立自己的 CLAUDE.md，核對每個路徑與指令，再從新 session 查看載入狀態。用一個「先分析篩選、不實作」的問題確認它能說出資料保留要求。完成判準是文件有效、來源可辨認、指令可執行，而且你知道哪些內容仍需透過設定與測試保證。

準備好練習完整流程時，接著閱讀專案規則工作坊，使用獨立材料進行故障重現與成果驗證。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code