分享一個我在建立軟體專案時常用的目錄與文件結構範本，最近將它整理成一個 Agent Skill，名稱為 project-scaffold。
這個 Skill 主要用於建立軟體專案的基礎骨架。
使用者可以先預覽預設的專案結構樹，再透過自然語言調整需要新增、移除或更名的目錄與文件，確認後就能自動生成專案骨架。
GitHub：project-scaffold-skill
整個 Skill 採用 Agent Skills 開放規格，不綁定單一 AI 工具，可供 Codex、GitHub Copilot、Claude Code，以及其他相容的 Agent 使用。
AI Agent 協作專案需要哪些基礎結構？
在 AI Agent 協作開發中，我認為專案的基礎骨架至少需要涵蓋兩個部分：
- 專案規範（Project Rules）：讓 Agent 理解專案的開發原則、技術規範與目錄組織方式。
- 專案文件（Project Documents）：讓 Agent 能找到需求、架構、研究、工作記錄及交接資訊。
這兩個部分，也是 project-scaffold 預設專案結構的主要設計方向。
一、專案規範（Project Rules）
目前多數 AI Coding Agent 已支援透過 Markdown 文件定義專案規範。
例如 Codex、GitHub Copilot 可以使用 AGENTS.md 作為規範入口；Claude Code 則主要使用 CLAUDE.md。
兩者都是 Markdown 格式，規範內容基本可以共用。
主規範應維持簡潔
我的習慣是將主規範控制在約 100 行以內，並參考 Andrej Karpathy 所倡議的簡潔、務實原則，避免將過多細節全部塞進同一份文件。
其他細部規範則依不同性質拆分，預設放在 .agent-rules/ 目錄下。
例如：
tech-stack.md：定義專案採用的技術堆疊、框架及相關開發規範。project-structure.md：定義專案目錄結構，以及各目錄的用途。
其他如工作追蹤、測試與驗證等規範，也可以視專案需要再增加。
依需求載入細部規範
主規範只保留共通原則與細部規範文件的索引。
當 Agent 執行特定任務時，再依據任務性質讀取對應文件，而不是每次都將所有規範載入 Context Window。
這樣可以讓主要規範保持精簡，也比較容易維護不同類型的開發規則。
二、專案文件（Project Documents）
另一個重要部分，是專案開發過程中的各類文件。
我的習慣是將這些文件統一整理在 docs/ 目錄下，再依照用途分類。
主要文件分類
docs/
├── requirements/
├── architecture/
├── research/
└── tracking/各目錄的用途：
requirements/：需求規格與功能需求。architecture/：系統架構、設計決策與 ADR（Architecture Decision Record）。research/：技術研究與調研資料。tracking/：專案工作追蹤與開發記錄。
開發記錄與工作交接
其中 tracking/ 還可以進一步細分：
tracking/
├── devlog/
├── handoff/
└── backlog/devlog/：記錄開發過程、程式變更及驗證結果。handoff/：整理工作交接資訊，讓不同 Agent 或新的 Session 可以接續先前的工作。backlog/：管理待辦事項與後續工作規劃，可依需求選用。
這幾個目錄在 AI Agent 協作開發時尤其實用。
例如，一個 Agent 完成部分功能後，可以將目前進度、修改內容及尚未處理的問題記錄在交接文件中，讓後續的 Agent 或新的 Session 有明確的接續依據。
當然，這些目錄並不是強制規定，而是提供一個可以調整的起點。
不同專案可以依實際規模與需求增減，不需要一開始就建立過於複雜的結構。
三、為什麼要先整理專案規範與文件？
良好的專案組織，不只是為了讓目錄看起來整齊，更重要的是改善 AI Agent 的協作方式。
透過明確的規範與文件分類，可以讓 Agent 更容易找到需要的上下文，減少不必要的 Token 消耗，也降低開發過程中偏離需求或設計方向的機會。
尤其在以下情境中，這些文件更能發揮作用：
- 跨 Session 開發：新的對話或工作階段，可以透過既有文件了解目前進度。
- 不同 Agent 協作：讓不同 Coding Agent 依據共同規範與交接資訊接續工作。
- 長期專案維護：保留開發記錄與設計決策，避免重要資訊只存在於過去的對話紀錄中。
我認為關鍵在於：
把專案的規範、需求、架構、研究、驗證與工作狀態，放在一個 Agent 找得到、讀得懂，也能持續追蹤與維護的位置。
這也是我將這套專案骨架整理成 project-scaffold Skill 的主要目的。
project-scaffold：從專案範本到可調整的 Skill
與直接複製一份固定的專案模板相比，我希望透過 Agent Skill 的方式，讓使用者能先檢視整體結構，再使用自然語言調整目錄與文件。
不論是新增、移除或重新命名，都可以在確認後再建立實際的專案骨架。
讓專案規範與文件結構成為開發流程的一部分，而不是每次開始新專案時，都要重新整理一次。
專案原始碼與使用說明：
GitHub：kenming/project-scaffold-skill
如果使用上遇到問題，或有改進建議，也歡迎透過 GitHub Issue 交流。