簡介

使用Claude Code一段時間後，大家都會遇到一個瓶頸。

「剛剛還完全理解的東西，當我開啟新的會話後就全忘了」

需要重頭再解釋專案背景。必須再次傳達編碼規範。剛剛測試失敗的方法又被提了出來。對這樣的重複，你有沒有感到過熟悉？

MEMORY.md的機制最近也添加了，但後面會提到，它存在著許多問題。

我一開始也困擾於這種「失憶循環」。我會在CLAUDE.md上寫規則；在MEMORY.md上累積經驗。即便如此，當跨越會話時，背景依然中斷。

對我來說，白天在公司的PC上工作，晚上在家里的PC上繼續作業，但Claude Code的MEMORY.md並不在庫存中，因此無法繼承記憶。同樣的情況也發生在我想在Codex等多個LLM間切換作業時。

經過不斷試錯以解決這些問題，設定檔的分工結構、LLM中立設計、規格驅動開發，以及基於技能的開發環境自動化等一系列機制便應運而生。從解決失憶問題開始的努力，竟然不知不覺中改變了整個開發工作流程。

本文將分享這些設計思想和具體實作方法，並附上實際的技能檔案。

1. MEMORY.md的利弊

那麼，MEMORY.md到底是什麼？

Claude Code有兩種類型的設定檔。CLAUDE.md是「人類編寫的指示檔」，而MEMORY.md則是「AI自動書寫的記憶」。MEMORY.md用於在會話中自動記錄AI學到的教訓和模式，理論上看起來能夠隨著使用而變得更聰明。

然而，實際運用的結果卻揭示了四個問題。

問題① 200行的硬性限制

當MEMORY.md超過200行時，會被截斷。這一硬性限制是Claude Code方的約束，使用者無法進行更改（截至2026年3月）。

隨著AI持續寫下經驗，重要記憶可能被推到末尾而被抹去，形成矛盾情況。這就造成了「為了累積記憶而建立的機制，反而成為記憶流失的原因」這樣的諷刺局面。

問題② 與CLAUDE.md的重複

MEMORY.md中經常會有與CLAUDE.md相同的內容重複寫入。這樣的情況會導致：

• AI在「哪一個是正確的」方面產生 注意力分散
• 重複消耗200行的框架 行數浪費
• 單方面更新導致的矛盾 更新不一致

這四個問題同時出現。

問題③ 縮減後的劣化

當Claude Code的上下文超過95%時，系統會自動啟動壓縮（Auto-compact）。這是一種AI總結會話歷史並替換內容的處理方式，但如果重複進行壓縮，造成的結果是「摘要的摘要的摘要」，細節隨之喪失。

MEMORY.md也會陷入「自主生產垃圾」的狀態，導致AI的行為品質明顯劣化的案例已經被報導。

問題④ 不支援多PC和多LLM

目前Claude Code的MEMORY.md是與庫存分開管理的。因此，當工作PC更換時，無法繼承記憶或作業會話。類似地，切換至Codex或AntiGravity等工具時，每次都需要再次說明會話的情況。

本章小結: MEMORY.md很方便，但如果放任不管，會存在記憶質量劣化的兩難局面。需要一種「不讓AI過度自由書寫」的機制。

2. 三檔案體系的設計

失憶問題的根本原因

問題的本質在於「將多個角色混合在一個檔案中」。如果在CLAUDE.md中同時寫規則、經驗、延續，就會無法管理混合的信息。

因此，我們找到了解決方案：明確分離角色的三檔案體系。

為何選擇這三者

AGENTS.md（不變的規則） 由人類編寫並管理。儲存專案的編碼規範、使用語言、對AI的行為指示等，不隨會話變化。AI僅需閱讀，不進行書寫。

MEMORY.md（累積經驗） 則是AI自動記錄的學習檔案。針對200行限制，我們設置了以下規則：

• 不寫與AGENTS.md內容重複的資訊
• 更新前創建日期存檔（YYYY-MM-DD.md）
• 作為索引使用，并根據需要將詳細資訊分離至其他檔案

HANDOFF.md（會話間的延續） 是這個設計的關鍵。與MEMORY.md的決定性區別在於，能讓人類進行審核和策展。

AI自動生成的MEMORY.md往往內容過於泛用和冗長，而HANDOFF.md則能讓人類過濾出「真正必要的轉接信息」。AI在會話結束前生成，然後由人類審核，剔除不必要的信息。這個「人類策展的過程」是維持記憶質量的關鍵。

運作規則

HANDOFF.md保持固定名稱，始終保留最新版本，創建時會將前一版本檔案帶上時間戳進行存檔：

.agent/handoff/
├── HANDOFF.md            ← 總是最新（AI可讀）
├── 2026-03-02-1845.md    ← 存檔（供人類核對經過）
└── 2026-03-01-0930.md

對AI的指示只需「讀取最新的HANDOFF.md並繼續」即可。存檔是為了讓人類之後能夠追溯「為何做出那樣的決策」。

3. 支援多PC與多LLM

為何選擇 .agent/ 資料夾

隨著設計的進一步推進，出現了以下疑問：

• 希望在公司PC與家裡PC之間繼續作業（多PC）
• 希望對除了Claude Code外的LLM工具使用相同的機制（多LLM）

若MEMORY.md和HANDOFF.md放在 .claude/ 資料夾中，則會成為Claude Code專屬的目錄。Codex CLI或Gemini CLI並不會去讀取 .claude/ 中的內容。

因此，我們將MEMORY和HANDOFF放在.agent/這個LLM中立的資料夾中。

每個LLM的設定檔（CLAUDE.md / AGENTS.md / GEMINI.md）中，都有寫下「會閱讀 .agent/memory/MEMORY.md 和 .agent/handoff/HANDOFF.md」這樣的共通指示。在各設定檔中僅記錄工具特有的差異，並將共通規則集中在AGENTS.md中。

支援多PC

對我而言，作業目錄是透過OneDrive進行同步的。.agent/資料夾也位於庫存中，因此會在OneDrive中自動同步。

• 作業檔案同步: OneDrive（即時）
• 版本管理: Git/GitHub（在合適的時機）

會話特有的本地信息（會話ID、逐字稿等）會保留在Claude Code的預設保存位置（~/.claude/）中，因此不會發生同步衝突。在切換PC時，我只需創建HANDOFF.md，便能在下一台PC上立即重新開始作業。

4. 規格驅動開發（SDD）

從管理記憶到管理作業

三檔案體系解決了失憶問題，但隨著使用的深入，出現了另一個挑戰。

「AI能理解指示，但輸出質量卻參差不齊」

原因顯而易見。在工作開始之前，人類的指示往往是模糊的。隨著AI理解力的提升，即便是模糊的指示也能運作。然而，這樣的結果會導致「以意圖不符的方式迅速產生成果」的全新問題。

因此我引入了規格驅動開發（Spec-Driven Development: SDD）。

四檔案體系

在.spec/資料夾中配置以下四個檔案：

重要重點：PLAN.md是「隨意的」

PLAN.md沒有設置任何標題模板。相反，裡面這樣寫著：

# PLAN - 想做的事情

<!-- 請自由地寫下你的想法，可以是項目符號或口語也可以 -->
<!-- Claude將閱讀這個內容並進行詢問，生成SPEC.md -->

如果有一個「嚴謹的模板」，會讓人有「必須寫好」的心理障礙。PLAN.md可以是口頭備註、零散的想法、項目符號的堆砌就足夠了。由此AI閱讀並進行詢問，藉由對話構建SPEC.md。這一流程顯著降低了「書寫規格」的門檻。

整合至AGENTS.md

SDD的規則將如下寫入AGENTS.md：

## 規格驅動開發（SDD）規則
- 開始編碼或業務作業前，務必確認並更新 `.spec/` 中的四個檔案
- 作業順序：PLAN（確認目的）→ SPEC（確認要求）→ TODO（確認任務）→ 實際作業
- **PLAN.md是人類的口頭備註・自由描述**，且可以是項目符號、口語或零碎內容
- 讀取PLAN.md之後，不要立即進入實作，而是詢問不明之處，並一起確認SPEC.md
- SPEC.md確定後，再執行TODO.md的任務分解，並獲得使用者批准後再開始實際作業

這樣一來，不論使用哪個LLM工具，「不會再有立刻開始編碼」的情況發生。

5. 全部自動化基於技能

每次手動構建是不現實的

迄今為止的設計相當有力，但每當啟動新專案時，手動執行以下工作是不現實的：

• 建立 .agent/ 資料夾及檔案
• 建立 .spec/ 下面的四個檔案
• 創建 AGENTS.md / CLAUDE.md / GEMINI.md
• 創建 .claude/commands/handoff.md
• 設定 .gitignore
• 初始化Git

因此，利用Claude Code的技能功能，我們使這些操作能夠一次性執行。

什麼是技能

Claude Code的技能（.claude/commands/ 或 .agent/skills/）是用來指示Claude Code執行特定任務的定義檔。描述步驟的Markdown格式，Claude Code將自動執行該步驟。

使用方法

1. 放置技能檔案（將以下全文保存為 .agent/skills/make_project/SKILL.md ）
2. 打開Claude Code的新專案資料夾
3. 指令為「初始化專案」

僅需這三步，三檔案體系 + SDD + Git初始化就全部完成。

SKILL.md 全文

以下是實際使用中的技能檔案全文，可以直接複製使用。

<details>
<summary>make_project 技能（點擊展開）</summary>

---
name: make_project_skill
description: 執行新專案的初步建設技能。用於設置新專案、創建初始檔案和初始化Git。請根據請求如「初始化專案」、「設置新專案」、「建立專案初步架構」來進行使用。
---

# 新專案的技能設置步驟

## 事前確認
在開始作業前，請確認以下資訊：
- GitHub倉庫 URL：[USER_INPUT]
- 預設分支名稱：main（若有變更，請向用戶確認）

※ 請事先在GitHub上創建倉庫（不添加README等）
---
## 1. 創建資料夾

在專案根目錄運行：

```bash
mkdir -p .agent/skills
mkdir -p .agent/memory
mkdir -p .agent/handoff
mkdir -p .agent/workflows
mkdir -p .claude/commands
mkdir -p .spec

2. 創建初始檔案

README.md

cat << 'EOF' > README.md
# 自動化生成的新專案
EOF

.agent/memory/MEMORY.md

cat << 'EOF' > .agent/memory/MEMORY.md
# MEMORY

## 專案概述

## 學習所得的知識・教訓
EOF

.agent/handoff/HANDOFF.md

cat << 'EOF' > .agent/handoff/HANDOFF.md
# HANDOFF

初次設置完成。請開始您的工作。
EOF

CLAUDE.md（專案根目錄）

cat << 'EOF' > CLAUDE.md
- 在會議開始時，务必读取共同规则 AGENTS.md 
- 讀完後需首先報告
- 以下僅記載Claude Code特有的差異
EOF

GEMINI.md（專案根目錄）

cat << 'EOF' > GEMINI.md
- 在會議開始時，务必读取共同规则 AGENTS.md 
- 讀完後需首先報告
- 以下內容僅記載Gemini的特有差異
EOF

AGENTS.md（專案根目錄）

cat << 'EOF' > AGENTS.md
# 專案指導方針

## 1. 專案概述
- 本專案的計劃和回答全部以中文撰寫。

# 記憶與交接指示

## 三檔案的角色與哲學
- 本檔案（AGENTS.md）是「嚴格的規則」，由人撰寫
- MEMORY.md是「累積的經驗」，由AI創建和使用
- HANDOFF.md是「會話之間的延續」，由AI創建和使用，但經人類審核後需進行必要的信息策展

## 會話開始時（必須）
在會話開始時，需在對用戶的最初反應之前，閱讀以下兩個檔案並報告已讀：
- `.agent/memory/MEMORY.md` （學習到的知識・教訓）
- `.agent/handoff/HANDOFF.md` （上次工作的交接）

## 記憶管理
- 記錄新知識・教訓時需更新 `.agent/memory/MEMORY.md`
- 在更新現有的MEMORY.md之前，將當前檔案存檔至`.agent/memory/YYYY-MM-DD.md`後新建檔案
- 不要使用本地的自動記憶功能（~/.claude/ 資料夾下）
- MEMORY.md需保持在200行以內
- 內容不應重複於本檔案中

## 交接管理
- 交接需透過 `/handoff` 指令來創建（對Claude Code而言）
- 保存至 `.agent/handoff/HANDOFF.md` （固定名稱）
- 創建時需將現有檔案重新命名為 `.agent/handoff/YYYY-MM-DD-HHMM.md` 後再新建HANDOFF.md
- 時刻以本地時間和24小時計算
EOF

3. 需求驅動開發檔案創建（.spec/）

為了在開始編碼或業務作業之前必須整理需求，創建四份檔案。

.spec/PLAN.md

cat << 'EOF' > .spec/PLAN.md
# PLAN - 想做的事情

<!-- 在這裡自由地寫下你的想法，可以是項目符號或口語 -->
<!-- Claude 將閱讀這內容並進行詢問後生成SPEC.md -->
EOF

.spec/SPEC.md

cat << 'EOF' > .spec/SPEC.md
# SPEC - 技術規範・要求定義

## 功能需求
- [ ] 功能1：描述
- [ ] 功能2：描述

## 非功能需求
- 性能：
- 安全性：
- 限制條件：

## 技術架構
- 語言・框架：
- 環境・基礎設施：
- 外部服務・API：

## 數據結構・介面
- 主要數據定義
EOF

.spec/TODO.md

cat << 'EOF' > .spec/TODO.md
# TODO - 任務清單

## 優先度：高
- [ ] T001：任務名稱（詳細說明）

## 優先度：中
- [ ] T002：任務名稱（詳細說明）

## 優先度：低
- [ ] T003：任務名稱（詳細說明）

## 已完成
- [x] 初始設置
EOF

.spec/KNOWLEDGE.md

cat << 'EOF' > .spec/KNOWLEDGE.md
# KNOWLEDGE - 領域知識・調查結果

## 業務・領域知識
- 與此作業或專案相關的背景知識

## 調查・研究結果
- 參考的信息・來源

## 技術見解
- 所採用技術的特性・注意事項

## 決策事項及理由
- 為何選擇這個方針（與其他選擇的比較）
EOF

向AGENTS.md增加需求驅動規則

最後將以下內容添加至AGENTS.md末尾：

cat << 'EOF' >> AGENTS.md

## 規格驅動開發（SDD）規則
- 開始編碼或業務作業前，必須驗證和更新 `.spec/` 中的四檔案
- 作業順序為：PLAN（確認目的）→ SPEC（確認需求）→ TODO（確認任務）→ 執行作業
- 完成作業後，將TODO.md中相應的任務打勾，並在KNOWLEDGE.md中記錄學習成果
- 當需求不明確時，提交請求前不得開始作業，待用戶確認後再更新SPEC.md
EOF

5. 創建handoff指令

將以下內容分別保存為 .claude/commands/handoff.md 和 .agent/workflows/handoff.md：

HANDOFF_CONTENT='請根據以下步驟創建交接：

1. 假如 `.agent/handoff/HANDOFF.md` 存在：
   - 獲取該檔案的更新時間（本地時間）
   - Rename `.agent/handoff/YYYY-MM-DD-HHMM.md`

2. 根據以下模板創建新的 `.agent/handoff/HANDOFF.md`，完成後請報告「已創建HANDOFF.md」。各項目需填寫在目前的聊天記錄或作業內容中AI自我總結後的具體內容，而不是僅僅保存空的模板。

---
# HANDOFF - {日期時間}

## 使用工具
如Claude Code / Codex CLI / Gemini CLI等，請在此填寫相應工具名稱

## 當前任務及進展
- [ ] 任務名：當前狀況

## 嘗試內容・結果
- ✅ 成功的做法
- ❌ 失敗的做法（原因）

## 下一個會話中的首要工作
1. 初始行動
2. 下一個行動

## 注意事項・瓶頸
- 需要注意的事項
---'

printf '%s\n' "$HANDOFF_CONTENT" > .claude/commands/handoff.md
printf '%s\n' "$HANDOFF_CONTENT" > .agent/workflows/handoff.md

6. Git初始化

建立 .gitignore 檔案

cat << 'EOF' > .gitignore
# 日誌
logs
*.log

node_modules
dist
dist-ssr
*.local

# 編輯器資料夾及檔案
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
.env
EOF

Git初始化與push

使用事前確認所獲取的GitHub倉庫URL執行：

git init
git add .
git commit -m "first commit"
git remote add origin [USER_INPUT]
git push -u origin main

完成報告

所有步驟結束後，請報告：

• 創建的檔案・資料夾列表
• 推送至GitHub的結果
• 下一步的指引（「請在AGENTS.md中記錄專案概述」等）
  </details>

6. 實際的開發如何變化

導入前（Before）

導入後（After）

透過技能的力量，使開發環境完整搭建，僅需在PLAN.md中用口語寫下想做的事即可指示。實際上這篇文章也是在本記事中包含的技能下完成的，Claude Code根據在PLAN.md所寫的「針對本次的問題解決方案撰寫Qiita文章」而生成的內容。

最大的變化在於從「我應該告訴AI什麼」轉變為「我能和AI一起創造什麼」。

解決了失憶的問題後，從會話開始時便能直接進入「主題」。重新構建背景所需的時間減至零，能夠完全專注於實際的作業時間。

此外，通過引入需求驅動開發，消除了「AI依據模糊指示進行自我解讀並衝進去」的問題。只需在PLAN.md中撰寫隨意的備註，AI即可在詢問中確認並完善需求。這個「與AI協作以打磨需求」的體驗，是在單人開發中仍然能維持設計品質的強大結構。

7. 總結

本文介紹的機制可以整理為：

解決的問題與解決方案：

1. 會話記憶失效 → 三檔案體系（AGENTS.md / MEMORY.md / HANDOFF.md）
2. 支援多PC與多LLM → 透過 .agent/ 資料夾實現LLM中立設計
3. 輸出質量參差 → 規格驅動開發（PLAN → SPEC → TODO）
4. 每次手動設置 → 透過技能一鍵自動化

試圖解決記憶失效的問題，卻也整理了檔案設計、LLM中立設計、需求管理與自動化，進而改進了整個開發工作流程。

技能檔案的全文已在本文中展示，您可以複製並立即使用。僅需一句「初始化專案」，便可以啟動文中介紹的所有機制。

期待您在自己的專案中也試試看。

原文出處：https://qiita.com/ProgrammingForEver/items/ee68fc621f7d1c53ffe1