CLAUDE.md 最佳實務：執行 10 家無人值守企業的文件（包括 Claude 忽略的指令）

每份清單 CLAUDE.md 最佳實踐 你會發現，今天這篇文章是由一位坐在代理商旁邊的人寫的。他/她打開一個會話，輸入提示，觀察輸出，修正錯誤，然後發布。他的 CLAUDE.md 檔案就像安全帶一樣，時時刻刻提醒著你。.

我的指令就像方向盤。我要展示的文件控制著一個容器，它會按照定時任務在凌晨 00:05 喚醒，將一篇完整的文章寫入並發佈到線上網站，更新四個記錄系統，然後再次進入休眠狀態——這一切都無人監管。沒有人會發現錯誤的指令。文件裡寫著什麼，它就執行什麼。.

這種差異決定了哪些建議是正確的。當你在場時，一條模糊的指示只會讓你犯錯一次。而當你不在場時，它卻會讓你默默地付出一週的錯誤代價。所以，這不是另一個模板。這是一個真實的文件，它記錄了實際成本的衡量標準，以及——沒人公開的部分—— 模型根本沒有按照說明書上的指示執行，日誌可以證明這一點。.

CLAUDE.md 檔案究竟是什麼——以及所有 CLAUDE.md 最佳實踐清單中都會犯的一個錯誤

CLAUDE.md 是一個 Markdown 文件，Claude Code 會在會話開始時自動讀取該文件，並在整個運行過程中將其保留在上下文中。這一點所有指南都認同。分歧從接下來的一句話開始。.

大多數指南都將其描述為 文件 ——需要找個地方解釋你的項目，以便模型能理解。這種框架有問題，每次編輯都會悄悄地讓你的文件變得更糟。.

CLAUDE.md 不是文件。它是 每次運行都會完整地重新讀取一套固定指令，每次都會以代幣的形式向您收費。. 文件只需編寫一次，供人閱讀相關部分即可。而 CLAUDE.md 檔案則由機器在每次呼叫時完整讀取，永無止境。這兩種模式截然相反。.

把它當作文檔來對待，你會不斷添加背景信息，因為添加上下文感覺很自由。把它當作一套固定的指令集來對待，就會得到三條規則：

• 每條線路都必須改變行為。. 如果刪除句子會產生相同的運行結果，那麼刪除該句子就是在浪費代幣，卻沒有任何實際意義。.
• 每條車道都能讀取每條線路。. 即使代理商正在撰寫部落格文章，我的影片渲染配置也會繼續載入。下文將詳細介紹其成本——這個數字著實讓我吃了一驚。.
• 無法驗證的指令只是願望。. 這是大多數 CLAUDE.md 最佳實踐清單從未提及的一點，因此我將在下面單獨列出——因為我可以準確地向您展示模型遵循了我的哪些規則，又沒有遵循哪些規則。.

如果您還在猶豫是否要讓代理完全無人值守運行，我寫了一篇關於這方面的文章。 實際上，是什麼在生產中運行我的10個品牌車隊？ — 本文假設您已經進行了該調用，現在需要該檔案正常運行。.

來自無人值守、有條不紊運營的企業的真正 CLAUDE.md

這是檔案的實際大小，按其目前在磁碟上的位置測量：

• 485 行，29,597 字節，約 7,400 個詞法單元
• 32個頂級部分
• 管理一個品牌容器；在同一台主機上運行著另外九個類似的容器

一個無人值守的檔案真正需要的並非編碼範本所建議的：身分和使命、品牌調性、發布目標、資料模式、媒體管道、API 呼叫模式、憑證位置以及十二條編號規則。這三點結構選擇值得借鏡。.

1. 憑證位於本機，但從不儲存。

文件裡從來不包含秘密──只有 尋找協議： 查看 env | grep KEY 首先， .env 文件不具權威性，主機透過 Docker 注入所有內容。五行程式碼可以防止代理程式找到過期檔案並錯誤地使用失效憑證。.

2. 確切的 API 結構，而非 API 名稱

簡單地說「使用 Airtable API」會導致猜測。該文件包含實際的工作內容。 捲曲 而是使用實際的呼叫——真實的端點、真實的身份驗證標頭、真實的有效負載結構。代理收到精確的呼叫後不會隨意產生新的呼叫。.

這比聽起來更重要。我的 Airtable 基礎版塊中的一個表格使用 蛇殼 欄位名稱與其他所有表格一樣都採用標題大小寫 (Title Case)，而 Airtable 則採用大小寫混合 (Case-)。冷漠無情 當你閱讀但案例時-敏感的 當你編寫程式碼時，一個技能可能讀取完美，但每次寫入都會失敗，而且這種失敗會悄無聲息地發生，錯誤訊息看起來就像隊列為空。這種不對稱性隱藏了一個損壞的循環長達數月之久。任何模型智慧都無法恢復這樣的事實；它必須被記錄下來。.

3. 編號的、不可協商的規則區塊

十二條規則，編號，標題為： 不容商榷立即發布而非草稿，發佈時務必配上特色圖片，絕不捏造數據，只為今天寫作。.

該資料塊大小為 922 位元組——佔檔案大小的 3.2%，也是檔案中負載最高的部分。此外，它並未得到統一的遵守，而這正是 CLAUDE.md 最佳實踐建議的終點，也是真正有趣的部分開始的地方。.

克勞德無視的指令——以及證明這一點的日誌

每份 CLAUDE.md 最佳實踐指南都以命令式的語調寫成，彷彿沒有任何利害關係。所以我查看了自己的日誌目錄，並根據實際情況（而非瀏覽量）對我的文件進行了評估。以下是評估結果。.

規則1是不可能的，從它被寫下之日起就一直是如此。

規則1內容如下： “每次訓練開始前，請務必閱讀 MEMORY.md 檔案。” 這是「不可協商」標題下的第一條規則。.

MEMORY.md 目前大小為 1,971,423 位元組——約 493,000 個標記。. 它不適合上下文視窗。它從來都不適合。沒有任何代理程式按原樣執行過規則 1，也沒有任何代理程式報告過執行失敗，因為「讀取此文件」規則沒有附加成功條件。.

這是文件中最具啟發性的失敗案例，因為沒有出現任何問題，也沒有報錯。一條在文件較小時制定的規則，隨著文件的增長而被保留了下來，悄然變成了偽規則——儘管它仍然高居“不可協商”列表之首，看起來權威十足。.

規則 6 是可行的，但仍下降了 7.6% 的時間

規則 6： “「始終以…結束技能執行 技能結果：[成功|跳過|失敗] | [摘要].” 執行起來非常簡單——它只有一行文字。.

我用 grep 指令搜尋了艦隊產生的所有非空日誌：

• 1,584 條運行日誌
• 1,464 包含一個 技能結果 線 — 92.4%
• 120 不 — 7.6%

最嚴重的違規行為並非隨機發生：一項社交技能導致 19 次違規，而撰寫部落格的技能（即撰寫本文的技能）導致 10 次違規。一條規則可以清晰、簡短、編號、標記為不可協商，但仍然會在大約 13 次嘗試中被跳過一次。.

同一區塊中的兩條規則位於 100%

現在來看控制規則。規則 2 規定所有文章必須立即發布，不得儲存為草稿。規則 11 規定每篇文章必須包含特色圖片。我從網站上提取了最近的 50 篇文章：

• 已發布的50/50 — 零草稿，零排期間。 100%。.
• 50 張圖片中有 50 張是特色圖片。 — 缺零。 100%。.

四條規則。相同的文件、相同的標題、相同的編號清單、相同的強調性語言。符合 100%、100%、92.4% 和 0% 標準。. 強調並不能解釋任何差異。. 還有其他東西做到了。.

服從與默默放棄：區分它們的試金石

將這四條規則排列起來，其模式顯而易見——而正是這一發現徹底改變了我對 CLAUDE.md 最佳實踐的看法。.

規則	它的要求	遵守
2 — 直接發布，絕不草稿	API 呼叫中用於建立帖子的字段	100%
11 — 需要特色圖片	API 呼叫中用於建立帖子的字段	100%
6 — 列印結果行	作品完成後，另一項獨立的行為，無人閱讀。	92.4%
1 — 讀取一個 493k 個令牌的文件	無法在物理上完成的行為	0%

規則 2 和 11 不被遵守，因為它們很重要。. 之所以遵守這些規則，是因為它們是行為者無論如何都必須採取的行動的前提條件。. 建立 WordPress 文章時，必須提供文章狀態和特色媒體 ID。該指令位於關鍵路徑上，因此無法跳過。.

規則 6 已經失效。文章已經發布，內容也已上線，即使有人跳過摘要，也不會對後續內容產生任何影響——因此，摘要僅靠吸引眼球來維持，而眼球在長期閱讀過程中恰恰會逐漸耗盡。規則 1 也完全失效了。.

這樣就能進行真正具有預測性的測試，而且這是我所知的最有用的 CLAUDE.md 最佳實踐：

對於文件中的每一條指令，都要問自己：這是代理人必須執行的某項任務的前提條件，還是出於善意的單獨行為？如果是出於善意，則假設該指令有一定比例會被放棄執行－現在就決定這個比例是否可以接受。.

對您自己的文件執行此審核

這大約需要二十分鐘，對於一個已經生長了幾個月的 CLAUDE.md 來說，這是你能做的最有價值的事情。.

1. 每條指令都要編號。. 你無法衡量一個段落。如果一條規則不能單獨處理，那麼它就無法審計。.
2. 寫出每個可觀測變數。. 你會用 grep 指令、查詢或其他方式搜尋什麼？ 捲曲 如何證明它發生過？規則 11 就有一個： 特色媒體 貼文上的欄位。規則 1 沒有－－即缺少 曾是 該缺陷在任何測量之前即可顯現。.
3. 統計最後五十次得分。. 日誌、API、資料庫——證據存在於何處都行。重要的是數量，而不是記憶。.
4. 將規則分為三類。. 位於關鍵路徑上（可保留原文）。不在路徑上但可驗證（需要在其他地方強制執行－請參閱路由部分）。無法驗證（刪除或使其可驗證；沒有第三種選擇）。.
5. 刪除所有得分為零且無法修復的內容。. 一條既沒有規則被遵守也沒有規則進行檢查的規則，比沒有規則更糟糕，因為它會讓文件看起來受到約束，而實際上並非如此。.

我的規則 1 正在從「始終讀取 MEMORY.md」重寫為對特定最近切片進行有界讀取——這是一條實際可以完成的指令。我在[此處應插入原文連結]中討論了該問題的一般版本。 啟動時限制代理程式讀取內容的三種方法.

CLAUDE.md 不編寫程式碼的代理程式的最佳實踐

在谷歌搜尋「CLAUDE.md 最佳實踐」的第一頁結果都假設你在開發軟體。我的專案並不發布任何生產代碼。它負責撰寫文章、安排社交媒體貼文、發送新聞簡報、回覆郵件以及進行對外宣傳。有四件事會發生變化，而這四件事都比你通常看到的那些針對特定程式碼庫的建議重要得多。.

你沒有測試套件，所以你必須自行寫驗證程式。

程式碼編寫代理程式擁有一個免費且可靠的「預言機」：運行測試。內容代理則沒有類似的工具。 「文章是否發布成功？」沒有退出程式碼。.

因此，該文件必須明確指定驗證器。我的驗證器需要在發布後取得即時 URL，並確認新標題確實出現在傳回的 HTML 中。 帶有快取清除參數, 因為 CDN 會很樂意繼續提供舊頁面，讓你誤以為運行成功。這個教訓讓我們付出了慘痛的代價：一次 SEO 元資料寫入操作返回了 HTTP 200 狀態碼，確認了更改，但 30 秒後，線上頁面仍然顯示著舊標題。. API 確認資訊並不代表任何內容已經渲染完成。.

冪等性不再是優勢

重新運行測試套件是免費的。重新運行發布程式會導致文章發布兩次。無人值守的內容代理最終會重試——在逾時、崩潰或調度程序出現故障之後——因此，該文件必須說明「已完成」的狀態以及如何在執行操作之前檢查它。.

這就是第 10 條規則存在的意義： 只寫今天的內容，不要提前大量生產。. 它還需要進行時區感知檢查。我的 WordPress 運行在 UTC 時間，而容器的調度時間是印尼中部時間，因此晚間發布的內容會延遲到 UTC 時間。 以前的 UTC 日期——而簡單的“今天有帖子嗎？”查詢返回零，這看起來像是完全失敗，但實際上一切正常。.

語音需要單獨的文件，而不是段落。

四個形容詞無法重現語音。我的檔案包含一條壓縮語音，然後 積分 針對特定文件——品牌聲音、品牌規則，以及在撰寫任何回覆之前都要閱讀的獨立郵件角色。指標操作成本很低；文件只會載入到需要它的頻道中。.

“「完成」是外部可見的，因此它的定義也必須是外部的。

對於程式碼來說，「完成」指的是合併提交。而在這裡，“完成”指的是一個有效的 URL，並且四個記錄系統彼此一致——必須明確說明，因為如果代理將“完成”定義為“我寫完了”，那麼你的跟踪數據就會在幾週內悄無聲息地不同步。同樣的道理也適用於此。 用人工智慧取代虛擬助理時，真正能轉移的是什麼？.

《背景法案》：各部分實際成本是多少？

這是我意想不到的衡量標準，也是我能給你的關於冷酷無情的最強論點。.

我將 CLAUDE.md 檔案分成 32 個部分，並分別調整了每個部分的大小。最大的單一部分— 整份文件的 12.5% — 是一個包含設定精靈產生檔案時留下的佔位符定義的表格。它解釋了每個模板變數的含義。 曾是 在填寫之前，每次跑步、每條跑道都會讀取它，永遠如此，但它不會改變任何事情。.

加入兩份剩餘的兄弟姊妹食物 文件第 18.3% 部分是搭建鷹架。. 相較之下，「不可協商規則」模組（即支配所有行為的部分）是 3.2%. 巫師殘餘勢力與規則勢力的比例接近六比一。.

然後我為這次部落格寫作過程中實際參考的每個部分都做了標記。視訊渲染管線（9.1%）沒有被參考。社群媒體發布架構、社群媒體挖掘配置、電子郵件回覆指南、搜尋控制台工具、B2B 概況、競爭對手清單也沒有被參考。.

本次運行中，檔案中有 47.8%（約 3,460 個令牌）是無用資料。. 沒錯。只是跟正在執行任務的車道無關，而且那條車道已經全額付費了。.

還有兩個漏洞值得您在自己的文件中檢查：

• 未設計的模板語法。. 我的還剩12個 {{#if}} 從未被處理的表達式。由於它們從未被渲染，模型讀取到 兩個都 分支指令之間存在矛盾－其中一個分支指示產品行動呼籲（CTA），而另一個分支則指示未配置任何產品，應跳過CTA。這兩條指令完全相反，但都存在於上下文中，且沒有任何方法可以解決它們。.
• 未填入的佔位符。. 七 待辦事項 標記仍然存在。其中之一是品牌圖像風格指南，因此每個生成圖像的通道都會讀取該字串的字面含義。 TODO_JON(IMAGE_STYLE) 然後它又從其他地方的設計文件中重新獲取了該樣式。指令存在、已被閱讀、已付費，但卻無法執行。.

實際要切掉什麼

CLAUDE.md 的最佳實踐在這裡不再是個人喜好，而是變成了計算。刪除精靈遺留的所有內容。刪除僅一個頻道使用的部分，並將其移至該頻道的技能檔案中。刪除所有未渲染的條件語句－選擇為真的分支並刪除其餘部分。解析或刪除所有佔位符。然後對剩餘部分執行刪除測試： 如果我刪除這個記錄，運行結果會不一樣嗎？ 否則，就放棄。.

CLAUDE.md vs 技能 vs 鉤子：哪個指令應該放在哪裡

「技能與內容臃腫之間的矛盾」是這個主題中真正難以權衡的難題，而提出這個問題的指南往往無法給出解決方案。既然我已經付了錢，我可以給你一個具體的、而非空泛的理論規則。.

最終決定勝負的數字是：我的技能文件總數為 39 個。 468,064 位元組－約 117,000 個令牌，是 CLAUDE.md 檔案大小的 15.8 倍。. 目前正在執行的單一技能大小為 47,730 字節，是整個 CLAUDE.md 檔案大小的 1.6 倍。如果流程檔案直接放在 CLAUDE.md 檔案中，那麼每次執行每個通道都會載入整個流程檔案。這種架構並非出於風格偏好，而是為了降低整個流程的成本。.

CLAUDE.md — 適用於每條跑道、每次跑步的真理

身分、語音、目標系統、憑證儲存位置、編號規則。測試： 如果是另一條車道，從事完全不同的工作，是否也需要這個？ 如果只有一條車道需要，那就不應該放在這裡。.

技能－單車道按需裝載流程

逐步流程、該任務的確切有效載荷、其特定故障模式。技能文件可能非常龐大，因為只有需要它的通道才會付費——而且每個通道的修正都應該在這裡進行，固定在技能中，而不是附加到全域文件中。同樣的邏輯也適用於 次級代理人何時提供協助，何時會增加額外開銷 和 哪些插件會獲取它們所消耗的上下文信息.

鉤子－任何必然發生的事件

這是我自己測量得出的結論，也是本文中最具實用價值的結論。.

規則 6 以書面指令的形式運行，運行時間為 92.4%。. 這本來就不應該以書面記錄下來。. 鉤子執行的正是確定性的、機械的、運行結束時的操作，而該操作具有明確的格式——鉤子不會在長時間運行結束時分心。你文件中所有「始終記錄日誌」、「始終通知」和「始終清理」的規則也是如此。.

所以路由規則是：

如果某件事必須每次都發生，毫無例外，那麼它應該放在鉤子函數裡。如果它只是針對某個特定通道的流程，那麼它應該放在技能函數裡。 CLAUDE.md 只處理那些全域真理且真正需要判斷的事情。.

對照之前的審計報告來看，這兩部分內容完全吻合。標記為「不在關鍵路徑上但可驗證」的部分並不是需要更明確地編寫的規則列表，而是你尚未實現的鉤子列表。措詞上的改變永遠無法彌合這個差距——我7.6%的未完成率就是最好的證明，而且這個數據已經在日誌裡存在好幾個月了。.

如果你有一個半成品 CLAUDE.md，而且你不想自己進行這項審核，這正是我為別人做的事情——你可以… 預約工作坊 我們將查看您提供的實際文件和日誌，而不是使用範本。.

關於 CLAUDE.md 的常見問題

CLAUDE.md 檔案應該要多長？

程式碼長度要短到每一行都會影響其行為。我的程式碼有 485 行，大約 7400 個字元，我計算出其中有 47.8% 是單次運行的冗餘部分——所以「像我的程式碼一樣長」並不能說明什麼。程式碼長度完全是錯誤的衡量標準。正確的衡量標準是刪除測試：刪除一段程式碼，如果執行結果沒有變化，那麼就應該保留刪除狀態。.

CLAUDE.md 該住哪裡？

在專案根目錄下，Claude Code 會自動讀取它。個人文件位於 ~/.claude/CLAUDE.md 適用於所有專案—對於您自己的工作偏好很有用，但對於任何特定於專案的工作都很有風險，因為您忘記的全域指令會跟隨您到不相關的工作。.

我應該讓 Claude 自己編寫 CLAUDE.md 檔案嗎？

如果只是結構初稿，是的—— /init 我會掃描項目並產生一些還算過得去的東西。但我最大的一個部分是每次運行都會讀取的“嚮導殘留”，所以請把生成的輸出當作一個起點，然後進行精簡。生成很便宜；編輯才是真正的工作，也是人們常常忽略的部分。.

為什麼 Claude 會忽略我的 CLAUDE.md 檔案？

通常情況下，它不會忽略文件——而是會丟棄特定的指令，而且丟棄的指令也總是可以預測的。根據我的測量，作為代理必須執行的操作的前提條件的規則運行時間為 100%，而要求在運行結束時執行單獨操作的規則運行時間為 92.4%，要求執行物理上不可能的操作的規則運行時間為 0%。在修改任何指令之前，請先檢查該指令是否位於關鍵路徑上。如果不在，修改措詞也無濟於事。.

CLAUDE.md 和 AGENTS.md 有什麼不同？

目的相同——啟動時讀取的常規指令—— 代理商.md 正在成為廠商中立的會議 CLAUDE.md 這是 Claude Code 原生讀取的內容。檔案名稱本身並不重要：本文中關於可驗證性、關鍵路徑合規性和上下文成本的每項 CLAUDE.md 最佳實踐都同樣適用於這兩種情況。.

如果我不寫程式碼，還需要 CLAUDE.md 檔案嗎？

你更需要它。編碼代理有測試套件來捕獲錯誤；內容或維運代理則沒有類似的機制，因此「完成」的定義和驗證方法必須明確寫下來，否則就形同虛設。我的團隊所做的一切都不是代碼，而這個文件就等於缺少的預言機。.

我應該多久更新一次？

事件發生時進行編輯，並依計畫進行審核。每次生產意外都應該在文件中記錄一行或建立一個鉤子。此外，每隔一兩個月重新測量一次，因為這裡的失效模式並非糟糕的編輯——而是看似權威但逐漸失效的良好規則，就像我的第一條規則一樣。保持運行時本身的更新也很重要；我寫過 如何在不中斷運作中的艦隊的情況下更新 Claude Code.

總結：CLAUDE.md 最佳實務在生產環境中依然適用

坦白說：我的文件沒問題，只是在 0% 和 92.4% 這兩個位置還有一條規則，我數了一下才知道這兩個數字。這不是疏忽——書面指示會悄無聲息地失效，一個滿是自信命令的文件，無論是否有效，看起來都一樣。.

需要攜帶的三樣東西：

修改之前先測量。. 直覺告訴我們應該透過更強有力的措辭來修復有問題的文件。但數據顯示措辭並非關鍵因素。首先要統計數據。.

把指令放在能夠執行的地方。. CLAUDE.md 中的關鍵路徑事實、技能中的車道程序、鉤子中每次都必須發生的任何內容。一條依賴模型在長時間運行結束時記憶的規則，其運行速度約為 92%——對於某些事情來說還可以，但對於你認為不可協商的事情來說就不行了。.

刪除超出你感覺舒適的範圍。. 我的文件裡將近一半都與執行它的那次運行無關，其中最大的一部分是設定之後就沒人看過的腳手架程式碼。增加上下文看似免費，但不然——每次運行、每條通道，你都要為此付出代價，而且這種代價會一直存在。.

這些 CLAUDE.md 最佳實踐的真正考驗不在於文件是否易於閱讀，而在於你是否能夠產生每條規則旁邊的編號。如果不能，那麼你擁有的就不是一個受控代理，而是一個充滿希望的代理。如果你想了解圍繞此類文件的其他堆疊結構，, 完整的操作指南在這裡。, ， 和 運行所有程式的伺服器在這裡。.