File/Folder Structure for Projects Co-Developed with AI Agents

開始跟 AI agent 一起寫 code 之後，我發現最累人的不是寫不出功能，而是每次開新 session 都要重新交代：用咩 tech stack、測試點跑、邊啲檔案唔好亂改。重複幾次之後，我決定把這些資訊放進一個固定的地方，讓 AI 每次開工前先讀完。

這套資料夾結構的核心想法很直接：把「AI 該知道的」、「人要讀的」、「真正要 commit 的程式碼」和「用完即棄的暫存檔」分開。這樣 repo 不會被 AI 的草稿塞爆，人也不會在雜物堆裡翻來覆去找東西。

整體結構一覽

my-project/
├── .claude/                  # AI 上下文（會 commit）
│   ├── CLAUDE.md
│   ├── settings.json
│   └── skills/
│       └── verify.md
├── docs/                     # 人與 AI 的長期知識庫（會 commit）
│   ├── README.md
│   ├── ARCHITECTURE.md
│   ├── DECISIONS.md
│   ├── PROMPT_INVENTORY.md
│   └── guides/
│       ├── cross_check_guide.md
│       └── testing.md
├── src/ 或 app/              # 原始碼（會 commit）
│   └── ...
├── tests/                    # 測試（會 commit）
│   ├── unit/
│   ├── integration/
│   ├── fixtures/
│   └── reference/            # golden/reference 資料
├── scripts/                  # 工具腳本（會 commit）
│   ├── generate_reference.py
│   └── cross_check.py
├── scratch/                  # .gitignore，不會 commit
│   ├── reviews/
│   ├── suggestions/
│   ├── samples/
│   └── drafts/
├── .gitignore
├── pyproject.toml / package.json
└── README.md                 # 給人看的入口

.claude/：給 AI 的開工讀本

這個資料夾放的是每次開新對話時 AI 會先讀的內容。把規則寫清楚，等於省卻每次重複講解的時間。

檔案	用途
.claude/CLAUDE.md	專案規則：tech stack、命名慣例、如何跑測試、哪些檔案不要碰
.claude/settings.json	權限、允許執行的指令、MCP server 設定
.claude/skills/	自訂 skill，例如 verify、run、deploy 的執行步驟

我通常會把這些檔案直接 commit，因為它們是專案運作的一部分。CLAUDE.md 不用太長，但要夠具體，例如清楚寫明「測試用 pytest -q」、「不要直接改 database schema」。

docs/：人與 AI 都能讀的知識庫

docs/ 放的是會長期保存的參考文件，不是對話紀錄，而是整理過的專案記憶。

檔案	用途
docs/README.md	給人看的專案總覽與起步指南
docs/ARCHITECTURE.md	系統設計、資料流向、模組界線
docs/DECISIONS.md	「我們選了 X 因為 Y」——加上日期的決策日誌
docs/PROMPT_INVENTORY.md	哪些資料會送到 LLM 或外部 API
docs/guides/	流程指南：交叉檢查、測試、部署等

其中我覺得最被低估的是 DECISIONS.md。寫下選擇與原因並標上日期，三個月後回頭看會節省很多猜測的時間。PROMPT_INVENTORY.md 也愈來愈重要，因為它讓我清楚知道哪些資料會離開本機，對私隱和成本都更有掌握。

src/、tests/、scripts/：本來就該乾淨的主體

這三區沒有什麼特別，就是維持本來的紀律：原始碼、測試、輔助腳本分開。唯一想補充的是 tests/reference/，我會用來放 golden data，讓 AI 改動後有個客觀的對照基準。

scratch/：AI 的草稿紙，不要 commit

AI 很會生產一次性文件：review 快照、raw suggestion、sample output、未整理好的草稿。我把它們全部關進 scratch/，並在 .gitignore 裡排除。

子資料夾	內容
scratch/reviews/	一次性 review 快照，例如 project_review_20260709.md
scratch/suggestions/	未整理前的 raw suggestion_*.txt
scratch/samples/	生成的 sample output，例如 sample_ai_context.txt
scratch/drafts/	尚未整理好、未準備升級到 docs/ 的文件草稿

這個做法讓我保留 AI 的思考痕跡，同時不讓 repo 變成垃圾堆。有時想翻查 AI 上次的建議，直接在 scratch/suggestions/ 找就可以，不用在聊天視窗裡捲半天。

一個小提醒：從最小版本開始

你不用一開 project 就把所有資料夾都建好。我通常先放 .claude/CLAUDE.md、docs/ARCHITECTURE.md 和 scratch/，等 AI 開始產出雜物之後再逐步補齊。重點是早一點劃清界線：哪些東西要留給未來的自己，哪些東西只是今天用一次。

把 AI 當成長期協作者來準備工作空間，對話的質素會明顯提升。規則寫清楚，雜物關進籠裡，人和 AI 都能更專注在真正要解決的問題上。

今日可以做的第一步：在你的 project root 開一個 .claude/CLAUDE.md，用三、五句話寫下這個專案的 tech stack、測試指令、以及 AI 不應該亂碰的檔案。下次開新 session 時，你會感謝自己。