你有沒有遇過這種情況：早上跟 AI 講了半小時的專案規則，中午開新對話，它全部忘光，還反問你「請問這個專案用什麼框架？」你只好再貼一次目錄結構、再解釋一次命名規範、再提醒一次「不要動 production 的設定檔」。一天下來，光是「重新自我介紹」就耗掉你半小時。

這篇文章要教你一個觀念上的轉彎：AI 代理不需要「記憶」，它需要「文件」。 這不是哲學討論，而是這週在 Hacker News 衝上 81 分、55 則留言的熱門話題核心。留言區有一位資深工程師說得最直白：「我們花了兩年想做記憶系統，最後發現工程師只要把規則寫進 repo 裡的 markdown 檔，問題就解決了八成。」

看完這篇，你會知道要寫哪些檔案、放在哪裡、內容怎麼寫，以及為什麼「寫給 AI 看的文件」跟你平常寫給同事看的文件，其實不太一樣。

為什麼「記憶」是錯的解法，「文件」才是對的？

先講一個很多人踩過的坑。市面上有一堆「AI 記憶」工具，幫你把對話存進向量資料庫，下次自動檢索。聽起來很聰明，但實務上常常出事：它檢索到三個月前你隨口說的一句「這個欄位先叫 temp」，然後在今天的重構裡堅持要把欄位改回 temp。你根本不知道它為什麼這樣做，因為那段記憶對你來說早就過期了。

文件不一樣。文件是你主動維護、看得見、改得動、進得了版控的東西。當 AI 讀的是 CLAUDE.md 而不是「記憶」，它每次看到的都是當前版本的事實。你要改規則，就改檔案、commit、push，下一個 session 立刻生效。這跟「訓練一個模型」或「餵它一堆歷史對話」是完全不同的可靠性等級。

而且文件有第二個好處：它同時對人類有用。 新同事進來，看同一份文件就能上手。你等於是用一份成本，同時服務了 AI 和人類隊友。

第一步：寫一份 CLAUDE.md，放在專案根目錄

Claude Code 會自動讀取專案根目錄的 CLAUDE.md。這是你的「開工簡報」，每次啟動都會載入。重點是：不要寫成百科全書，要寫成命令列。

一份實用的 CLAUDE.md 大概長這樣：

# 專案：MobDome 內容後台

## 技術棧
- Next.js 15 App Router、TypeScript strict、Tailwind v4
- 資料庫：Postgres + Drizzle ORM
- 部署：Vercel，preview 分支自動建置

## 絕對規則
- 不要修改 `src/config/production.ts`
- 所有 API route 必須回傳 `{ ok, data, error }` 格式
- 新增依賴前先問我，不要自己 npm install

## 常用指令
- 開發：`pnpm dev`
- 測試：`pnpm test --run`（不要用 watch 模式）
- 型別檢查：`pnpm typecheck`

## 風格
- 註解用繁體中文，變數名稱用英文
- 不要寫 `any`，不確定就用 `unknown` 再收窄

注意「絕對規則」那一段。這是最有價值的部分，因為它擋掉的是你最常需要口頭糾正 AI 的那幾件事。你可以這樣想：每次你在對話裡說「誒不要那樣」，那句話就該進 CLAUDE.md。

第二步：用 docs 資料夾分層，別把所有東西塞進一個檔

專案一大，CLAUDE.md 會膨脹到沒人想看，AI 也會開始忽略中間段落。比較好的做法是分層：根目錄的 CLAUDE.md 只放全域規則與索引，細節拆到 docs/ 底下。

例如：

  • docs/architecture.md — 系統架構、資料流、為什麼這樣設計
  • docs/api-conventions.md — API 命名、錯誤碼、版本策略
  • docs/runbook.md — 出事了怎麼查、log 在哪、誰負責
  • docs/decisions/ — 每個重大技術決策一頁，記錄「當時為什麼選 A 不選 B」

然後在 CLAUDE.md 裡寫一句：「需要架構背景時讀 docs/architecture.md；改 API 前先讀 docs/api-conventions.md。」這樣 AI 會在對的時機去讀對的檔案，而不是一次吞下三萬字。

這裡有個 HK/TW 團隊特別容易忽略的點：語言一致性。如果你的 docs/ 是中文、程式碼註解是英文、commit message 又是中英混雜，AI 會跟著混亂。建議至少統一「規則類文件用繁體中文、程式碼識別字用英文」，並在 CLAUDE.md 明講。

第三步：把「決策紀錄」當成 AI 的長期記憶

真正讓 AI 表現從「還行」跳到「可靠」的，是決策紀錄（decision log）。因為 AI 最常犯的錯不是寫不出程式，而是在不知情的狀況下推翻你三個月前的決定。

舉個真實場景：你當初刻意不用某個熱門套件，因為它的授權條款在商業使用上有疑慮。三個月後 AI 幫你重構，很開心地把它裝回來了。如果你有一份 docs/decisions/2026-07-no-xyz-license.md，寫著「因授權問題，本專案不使用 XYZ，替代方案為 ABC」，AI 讀到就會避開。

寫法很簡單，一頁一個決策，四段就好：背景、選項、決定、後果。不用寫得漂亮，重點是讓未來的 AI（和未來的你）知道「這不是隨便決定的」。

第四步：把重複指令變成「可執行文件」

文件不一定要是純說明。Claude Code 支援把常用流程寫成指令檔，放在 .claude/commands/ 底下，之後用 /指令名 就能呼叫。例如你每天都要做「檢查型別 → 跑測試 → 產生 changelog」，就寫一個 daily-check.md，內容是給 AI 的逐步指示。這等於是把「口頭交代」變成「版本控管的工作流程」。

同樣的概念也適用於其他工具。GitHub Copilot 有 .github/copilot-instructions.md，Cursor 有 .cursor/rules。檔案名稱不同，但精神一樣：把散在對話裡的規則，搬進 repo。

給 HK/TW 讀者的實務建議

如果你是一人團隊或小團隊，別想一次寫完。最務實的順序是：

第一天，只做一件事：開一個 CLAUDE.md，把你今天對 AI 講過的重複指令抄進去。大概十分鐘。第二天，每次你糾正 AI，就順手加一行。一週後你會有一份真正貼合你專案的文件，而不是網路上抄來的範本。

如果你在公司裡推動，記得把「更新 CLAUDE.md」寫進 PR 檢查清單。當它變成流程的一部分，就不會有人忘記。這比導入任何記憶工具都有效，而且成本幾乎是零。

最後提醒一句：文件會過期。每季花二十分鐘掃一遍，把已經不成立的規則刪掉。給 AI 一份說謊的文件，比不給它文件更危險。

延伸閱讀

常見問題

Q: 我沒用 Claude Code，這套方法對 ChatGPT 或 Gemini 有用嗎？

A: 有用，只是要手動貼。 你可以把 CLAUDE.md 的內容存成一段範本，每次開新對話時貼上。或者用 ChatGPT 的 Projects／Custom Instructions 功能，把規則常駐。核心觀念是一樣的：規則要寫成文件、放在你能維護的地方，而不是靠對話歷史。

Q: CLAUDE.md 寫太長會不會反而讓 AI 忽略？

A: 會。 實務上建議根目錄那份控制在 100～200 行以內，只放「每次都需要知道」的規則。細節用「需要時去讀 docs/xxx.md」的方式索引出去。這跟寫程式一樣，關注點分離。

Q: 這些文件會不會洩漏公司機密？

A: 會，所以要注意。 如果你用的是雲端 AI 服務，貼進去的內容會離開你的機器。建議在 CLAUDE.md 裡明確寫「不要讀取 .env、secrets/、客戶資料目錄」，並把敏感資訊放在那些地方而非文件裡。文件寫「金鑰放在 1Password 的 XX 項目」，而不是把金鑰本身寫進去。

Q: 團隊成員不想維護文件怎麼辦？

A: 讓它變成順手的事，而不是額外的事。 最有效的做法是把它綁進既有流程：開 PR 時如果改了架構卻沒更新 docs/architecture.md，就在 code review 提出來。另一個技巧是讓 AI 幫你寫初稿——你只要說「把我們剛剛討論的決策整理成一份 decision log」，它會幫你生好格式，你修兩句就行。

Q: 這跟 RAG、向量資料庫有什麼不同？

A: 差在「誰決定要看什麼」。 RAG 是系統自動檢索，你可能不知道它撈了什麼進來；文件是 AI 根據你寫的索引去讀，路徑清楚、可預測、可除錯。兩者不衝突，但對「專案規則」這種需要百分之百準確的內容，明確的文件比模糊的檢索可靠得多。