一套檔案規範,令任何 AI agent(Claude Code、Codex、openclaw 等)打開 project 就即刻知道做緊咩、做到邊、下一步做咩。
# 1. Clone 框架
npx degit <your-repo>/agent-framework my-new-project
cd my-new-project
git init && git add -A && git commit -m "init: scaffold from agent framework"
# 2. 填寫 PROJECT.md
# 將 [placeholder] 換成真實內容:項目描述、目標
# 3. 填寫 .agent/config.md
# 揀你用咩工具、MCP、自動化 level
# 4. 開始工作
# 打開 Claude Code / Codex,agent 會自動行 orientation
Agent 會自動:
- 讀 PROJECT.md 了解目標
- 用 brainstorming → 產出設計 spec
- 用 writing-plans → 產出實施 plan
- 將 plan 拆成 task files
- 開始執行第一個 task
你只需要填好 PROJECT.md,其餘 agent 識做。
| 我想... | 點做 |
|---|---|
| 話 agent 知啲嘢 | 寫入 .agent/NOTES.md |
| 改方向 / 改決定 | 更新 decision file,標舊嘅為 superseded |
| 兩個 agent 並行 | 分好 module,填 task 嘅 assigned_to |
| Agent 自動跑 | 同 agent 講「啟動 autopilot」 |
| 睇進度 | bash scripts/status.sh 或 bash scripts/status.sh <module> |
| Review 研究結果 | 睇 .agent/research/INDEX.md |
| 睇架構決定 | 睇 .agent/decisions/ |
| 了解上次做咗咩 | 睇 .agent/handoffs/ 最新嗰份 |
開始:
1. 讀 PROJECT.md → 知道做咩
2. 讀 NOTES.md → 有冇人類通知
3. Scan task files → 知道做到邊
4. 讀最新 handoff → 上次做咗咩
做嘢:
5. 用 task 選擇邏輯揀 task(跳過 blocked → 做 assigned → priority 高先)
6. 做嘢
收工:
7. 更新 task status
8. 寫 handoff
9. 更新 PROJECT.md 現況
10. Commit
project-root/
├── AGENTS.md # Agent 行為指引(所有工具都讀)
├── CLAUDE.md # Claude Code 專用(@import AGENTS.md)
├── PROJECT.md # 項目身份證
├── .gitignore
│
├── .agent/
│ ├── config.md # 工具 / MCP / 自動化配置
│ ├── NOTES.md # 人類 → Agent 嘅臨時通知
│ ├── log.jsonl # 活動日誌(自動生成,gitignored)
│ │
│ ├── specs/ # 設計文檔
│ ├── plans/ # 實施計劃
│ ├── tasks/ # 任務(唯一 source of truth)
│ │ ├── <module>/ # 大 project 按 module 分
│ │ └── _archive/ # 完成 >90 日(gitignored)
│ ├── research/ # 研究結果
│ │ └── INDEX.md # 研究索引
│ ├── decisions/ # 架構決定
│ └── handoffs/ # Session 交接記錄
│
└── scripts/
└── status.sh # 即時狀態報告
- File-First — 全部 plain files,git 做 version control
- Single Source of Truth — Task frontmatter 係唯一嘅狀態來源,冇第二份
- Mandatory Orientation — Agent 每次開工必須先讀 context
- Immutable Tasks — Task 描述唔可以改,只改狀態
- Tool-Agnostic — Claude Code、Codex、openclaw 全部用同一套檔案
- Context Assembly — Agent 之間靠寫/讀檔案溝通,唔傳 message
---
id: task-001
title: 簡短描述
status: pending # pending / in_progress / done / blocked / removed
priority: high # high / medium / low
module: module-name
blocked_by: []
assigned_to:
source: # 對應 plan 步驟(可選)
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
## 描述
## 驗收標準
## 相關資料
## 進度記錄
---
id: res-001
title: 研究主題
date: YYYY-MM-DD
status: done
confidence: high # high / medium / low / needs-revalidation
related_tasks: []
---
## 背景
## 調研咗咩
## 結論(放最前面,agent 大部分時間只讀呢度)
## 點解
## 未解決嘅問題
## 資料來源
---
id: dec-001
title: 決定標題
date: YYYY-MM-DD
status: accepted # accepted / superseded
related_tasks: []
---
## 決定
## 點解
## 考慮過嘅替代方案
## 後果
---
date: YYYY-MM-DDTHH:MM:SSZ
agent: agent-name
session_branch: branch-name
tasks_touched: []
---
## 做咗咩
## 未做完嘅嘢
## 下一步建議
## 注意事項
- Research 60 日過期 — git commit 超過 60 日嘅 research 要重新驗證先用
- Stale task 檢測 —
in_progress但長時間冇活動嘅 task 會被改回pending - Decision cascade — Decision 改為
superseded時,相關 task 會被標blocked - 並行隔離 — 多 agent 並行用 git worktree,每人一個 module,唔好撞
- Spec →
.agent/specs/YYYY-MM-DD-<topic>-design.md - Plan →
.agent/plans/YYYY-MM-DD-<feature>.md - 其餘 skill(TDD、debugging、review)照常用
- 所有 skill 照常用
- 運行時數據留喺
~/.gstack/(唔影響 repo)