Skip to content

About

通用 AI Agent 協調框架 — 令任何 agent 打開 project 就知道做緊咩

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Agent 協調框架

一套檔案規範,令任何 AI agent(Claude Code、Codex、openclaw 等)打開 project 就即刻知道做緊咩、做到邊、下一步做咩。


點樣用

開新 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

冷啟動(全新 project,未有任何 task)

Agent 會自動:

  1. 讀 PROJECT.md 了解目標
  2. 用 brainstorming → 產出設計 spec
  3. 用 writing-plans → 產出實施 plan
  4. 將 plan 拆成 task files
  5. 開始執行第一個 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/ 最新嗰份

Agent 每次 Session 會做咩

開始:
  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                # 即時狀態報告

核心原則

  1. File-First — 全部 plain files,git 做 version control
  2. Single Source of Truth — Task frontmatter 係唯一嘅狀態來源,冇第二份
  3. Mandatory Orientation — Agent 每次開工必須先讀 context
  4. Immutable Tasks — Task 描述唔可以改,只改狀態
  5. Tool-Agnostic — Claude Code、Codex、openclaw 全部用同一套檔案
  6. Context Assembly — Agent 之間靠寫/讀檔案溝通,唔傳 message

檔案格式速查

Task(.agent/tasks/task-001.md)

---
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
---
## 描述
## 驗收標準
## 相關資料
## 進度記錄

Research(.agent/research/res-001.md)

---
id: res-001
title: 研究主題
date: YYYY-MM-DD
status: done
confidence: high      # high / medium / low / needs-revalidation
related_tasks: []
---
## 背景
## 調研咗咩
## 結論(放最前面,agent 大部分時間只讀呢度)
## 點解
## 未解決嘅問題
## 資料來源

Decision(.agent/decisions/dec-001.md)

---
id: dec-001
title: 決定標題
date: YYYY-MM-DD
status: accepted      # accepted / superseded
related_tasks: []
---
## 決定
## 點解
## 考慮過嘅替代方案
## 後果

Handoff(.agent/handoffs/YYYY-MM-DD-HHMMSS-slug.md)

---
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,唔好撞

Skill 整合

Superpowers

  • Spec → .agent/specs/YYYY-MM-DD-<topic>-design.md
  • Plan → .agent/plans/YYYY-MM-DD-<feature>.md
  • 其餘 skill(TDD、debugging、review)照常用

gstack

  • 所有 skill 照常用
  • 運行時數據留喺 ~/.gstack/(唔影響 repo)

About

通用 AI Agent 協調框架 — 令任何 agent 打開 project 就知道做緊咩

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages