Kerwin AI Information

標籤: VS Code 開發代理

  • 用 Claude.md 做一個不會爛掉的長跑代理

    用 Claude.md 做一個不會爛掉的長跑代理

    📌 本文重點

    • 用 CLAUDE.md 嚴格約束代理行為，避免長跑爛掉
    • 核心原則是「行動＋證據」，禁止空談與無限迴圈
    • 透過上下文壓力自查與簡潔憲法，讓代理長時間穩定運作

    用一份不到 100 行的 CLAUDE.md，就能讓你的 Claude 代理連跑幾小時都不會開始胡言亂語、卡住不動或重複修同一個 bug。

    參考原作者在 Reddit 的分享：
    – 長跑 Claude Code 代理的設定檔開源文：https://www.reddit.com/r/ClaudeAI/comments/1tjy3sk/i_opensourced_the_operating_file_that_keeps_my/
    – 100 條個人 AI 代理實戰心得：https://www.reddit.com/r/ClaudeAI/comments/1thi6nh/100_tips_tricks_for_building_your_own_personal_ai/

    核心功能：這份 CLAUDE.md 到底做了什麼？

    1. 只允許「行動與證據」，禁止長篇空談

    長跑代理會爛掉，通常是這三個症狀：

    1. 開始寫「我將會…」「接下來我要…」但不真的執行工具
    2. 一直說「應該已修好」但沒有測試結果
    3. 花很多篇幅重複解釋計畫，實際變更很少

    CLAUDE.md 的核心規則，就是把這些行為全部關掉：

    • 輸出只允許三種型態：
    • 已完成的動作（例如：檔案修改、指令執行、API 呼叫）
    • 具體問題 / 需要決策的提問
    • 極短的進度摘要
    • 聲稱「完成」前要附證據：如測試輸出、報表截圖路徑、命令列結果

    💡 關鍵： 將輸出限制為「行動＋證據」，能大幅減少長篇空談與無效迴圈，讓長跑代理真正持續推進任務

    你可以做的事：
    – 在你的專案根目錄放一份 CLAUDE.md，明確寫出：
    – 「不要描述你要做什麼，只要直接做並回報結果」
    – 「任何『應該已修好』前，必須貼出測試輸出」

    2. 內建「上下文壓力」自我檢查

    長跑幾小時後，對話上下文會變超長，Claude 開始：

    • 忘記早期需求
    • 無法把握目前專案狀態
    • 回答變模糊或重覆

    原作者在 CLAUDE.md 裡加了一條關鍵原則：

    代理要定期自查上下文壓力：發現自己搞不清狀態，就主動整理摘要、刪除多餘上下文、或要求人類幫它重設現狀。

    具體做法通常包含：

    • 每完成一個階段任務，就輸出一個「短摘要 + 關鍵檔案清單」
    • 長度過大時，優先保留：
    • 最新的決策
    • 目前版本的檔案 / 結構
    • 尚未完成的待辦

    你可以做的事：
    – 在 CLAUDE.md 寫明：
    – 「當你感覺自己不確定目前狀態時，先輸出一份 10 行內的現況摘要，再繼續工作。」
    – 「如需要，可要求人類提供『目前唯一真實狀態』說明，並用這份說明覆蓋舊假設。」

    3. 任務憲法：不靠「一長串 Prompt」，靠幾條簡潔原則

    多數人用代理會寫一大段 prompt，結果 Claude 讀不完、也記不住。CLAUDE.md 的思路是：

    • 用 10–20 條簡短規則，定義這個代理的「憲法」
    • 每條都要能對應到實際行為約束，例如：
    • 「若有工具可以做某事，優先用工具，不要手寫模擬輸出」
    • 「對同一錯誤連續嘗試 3 次仍失敗，就停下來請人類決策，不要無限迴圈」

    💡 關鍵： 把 10–20 條行為規則寫成固定「憲法」，比灌輸一大段單次 prompt 更能在長跑中維持穩定行為

    參考 Reddit 另一篇實戰文：https://www.reddit.com/r/ClaudeAI/comments/1thi6nh/100_tips_tricks_for_building_your_own_personal_ai/

    你可以做的事：
    – 先列出你的代理最常「爛掉」的 3 個行為，逐條寫進 CLAUDE.md，用「禁止 / 應改為」的格式：
    – 「禁止：連續兩次貼出幾乎相同的錯誤訊息。應改為：第二次失敗時，整理你已試過的方法，請人類選下一步。」

    適合誰用：3 個實戰場景

    1. 單機腳本型代理：排程任務、批次資料處理

    你有這些需求時，很適合：

    • 每晚跑一次報表轉檔腳本
    • 每週整理一批 CSV / Excel 檔，把欄位標準化
    • 定期爬某個網站的資料、存到本地或資料庫

    做法：

    1. 用 Claude Code 或本地腳本，讓代理可以：
    2. 讀寫特定資料夾
    3. 執行 shell 指令（或以 PowerShell / bash 包一層）
    4. 把 CLAUDE.md 放在專案根目錄，寫清楚：
    5. 允許改動哪些檔案
    6. 批次任務完成的判定方式（例如輸出檔案數量、檔名規則）
    7. 用排程工具觸發：
    8. macOS / Linux：cron 或 systemd timer
    9. Windows：排程工作排程器 + 命令列啟動代理腳本

    2. 長連線開發代理：Claude Code / VS Code / Cursor 類工作流

    如果你常用 Claude 來寫程式、改大型專案，長時間開著一個 session，很容易出現：

    • 忘記三小時前的設計決定
    • 重複修同一支檔案
    • 一直在講解架構，但實際 commit 很少

    這時 CLAUDE.md 非常好用：

    實際操作：

    1. 在 VS Code 專案根目錄新增 CLAUDE.md，內容包含：
    2. 專案簡述
    3. 允許的工具（例如：跑測試、執行 npm test、pytest 等）
    4. 「行動 > 敘述」與「證據 > 猜測」等規則
    5. 在 Claude Code / Cursor 內重新開啟專案，確保代理會讀到這個檔案
    6. 開發時明確下指令：
    7. 「請遵守 CLAUDE.md，連續工作直到完成以下任務…」
    8. 「每完成一個子任務，產出最多 5 行的進度摘要」

    進階：也可以搭配多代理流程，參考：https://www.reddit.com/r/ClaudeAI/comments/1thi16y/how_i_built_a_9agent_team_where_my_agents/

    3. 自建小型自動化服務：抓報表、清理資料

    你想做一些「半自動」小工具，例如：

    • 每週自動登入內部系統下載報表
    • 讀取資料夾裡的新檔案，做資料清洗 / 格式標準化
    • 根據最新資料，產出簡短摘要寄 Email

    可用的整合方式：

    • MCP / shell 指令：
    • 透過 Model Context Protocol 暴露一組工具給 Claude，例如：
      • list_files, read_file, run_command

    • 規則寫進 CLAUDE.md：

      • 「處理檔案時，一律用工具列出檔名，不要從記憶猜」

    • Power Automate：

    • 由 Power Automate 排程觸發 HTTP / CLI，呼叫你的 Claude 代理後端
    • 回傳的結果可再串 Outlook 寄信、寫入 Excel、更新 SharePoint

    你可以做的事：
    – 先選一個最小自動化任務，例如「每週整理銷售報表」，只把這一個流程寫入 CLAUDE.md，確保跑穩，再慢慢加其他任務。

    10 分鐘上手：從 fork 到跑起你自己的代理

    以下是一條「10 分鐘內能動起來」的最短路徑，你可以依你使用的工具微調。

    Step 1：fork 開源專案

    1. 前往 Reddit 原文查看作者提供的 repo（通常會在貼文內）：https://www.reddit.com/r/ClaudeAI/comments/1tjy3sk/i_opensourced_the_operating_file_that_keeps_my/
    2. 在 GitHub 上 fork 到自己的帳號
    3. 本地 git clone 下來

    Step 2：複製 CLAUDE.md 到你的專案

    1. 打開作者的 CLAUDE.md，通讀一遍規則
    2. 複製到你自己的專案根目錄
    3. 只做三種修改：
    4. 把專案描述改成你的任務（例如：財報整理、數據清洗、網站爬蟲）
    5. 調整允許使用的工具（例如是否允許 rm / 刪檔）
    6. 加上 2–3 條你最在意的「不准爛掉」條款

    💡 關鍵： 只動專案描述、工具白名單與 2–3 條關鍵禁令，能在 10 分鐘內把通用 CLAUDE.md 變成專屬代理憲法

    Step 3：綁定你常用的工作環境

    依你用的平台選一條：

    • Claude Code / VS Code / Cursor：
    • 在這個專案資料夾內開啟編輯器
    • 確認工具（跑測試、shell、檔案操作）已啟用

    • 對 Claude 說：「請讀 CLAUDE.md 並照裡面的規則長時間工作」

    • MCP + shell 指令：

    • 建立一個 MCP server，提供 run_shell, read_file, write_file 等工具
    • 在 CLAUDE.md 明確寫出「所有系統操作一律經由 MCP 工具」

    • 用你偏好的前端（例如自寫 CLI、簡單 Web）呼叫 Claude

    • Power Automate / 其他自動化：

    • 建一個小型後端服務（可用 Python FastAPI / Node.js）包住 Claude API
    • 後端每次呼叫 Claude 時，都把專案檔案＋CLAUDE.md 帶入 context
    • 用 Power Automate 定期觸發這個 API

    Step 4：跑一個「能觀察的」任務，調整規則

    1. 選一個 30–60 分鐘的任務給代理連續跑（例如重構某一個資料夾的程式碼）
    2. 觀察：
    3. 什麼時候開始廢話變多？
    4. 哪種情況會卡在同一個錯誤？
    5. 直接把這些「失敗模式」寫回 CLAUDE.md 變成新條款

    重複兩三輪，你會得到一份專屬於你工作流、而且真的能「長跑不爛」的代理憲法。

    小結：先管好行為，再管工具

    長跑 AI 代理很容易越跑越爛，通常問題不在模型，而在缺乏清楚的行為規則。透過一份設計良好的 CLAUDE.md：

    • 把輸出限制在「行動＋證據」
    • 讓代理主動監控上下文壓力
    • 用幾條簡單原則當作「憲法」

    你可以在單機腳本、開發環境、多工具自動化裡，得到一個穩定得多的 Claude 代理。

    建議從今天開始：先為你最常用的一個專案寫一份 CLAUDE.md，跑一個完整任務，看看它能連續跑多久還保持專注。那會是你感受到「長跑代理真的可用」的第一步。

    🚀 你現在可以做的事

    • 在一個常用專案根目錄新建 CLAUDE.md，寫入「行動＋證據」與上下文自查規則後實際跑一次長任務
    • 從 Reddit 原文 fork 作者 repo，閱讀並複製其中 CLAUDE.md，依你的工作流做 2–3 處客製調整
    • 列出你代理常見的 3 個「爛掉模式」，逐條轉寫成禁止條款加進 CLAUDE.md，並在下一次工作中觀察效果