agent-template

Agentic Engineering 專案 scaffold。把整個資料夾複製到新專案根目錄當起手包，照下方步驟把 placeholder 換成你的東西就能用。

設計概念來自 Vibe Coding 升級教學：2026 Agentic Engineering 六階段實戰 SOP，擴充成三 track 開發流程（新功能 / 修改需求 / 除錯）+ 員工 pipeline + dev-logs 沉澱機制。

對 tech stack 中立 — 範本內所有 stack 相關欄位都是 <placeholder>，不預設你用哪個 framework / 語言。

初次使用

1. 複製整個資料夾到新專案根目錄
2. 全文搜尋取代 <Project Name>，換成你的專案名稱
3. 填 AGENTS.md：Project Overview、Tech Stack、Build & Test 指令、明確排除的事
4. 填 agents/planning/ROADMAP.md：你的 Phase / Week 規劃
5. 看 agents/conventions/ 裡每份規範開頭的說明，留你要的、刪你不要的

第一次跟 AI 對話直接說「依 AGENTS.md 跟 agents/conventions/dev-workflow.md 開始」即可。

目錄結構

agent-template/
├── CLAUDE.md                                # 1 行 @AGENTS.md（Claude Code 入口）
├── AGENTS.md                                # 跨工具規範本體
├── agents/                                  # 知識庫主目錄
│   ├── README.md                            # 索引 + 員工清單 + 鐵則速查
│   ├── conventions/                         # 規範本體（按主題拆檔）
│   │   ├── architecture.md
│   │   ├── dev-workflow.md                  # ⭐ 三 track Agentic Engineering SOP
│   │   ├── jsdoc-format.md
│   │   ├── commit-message-format.md
│   │   └── ui-design.md
│   ├── templates/                           # Task brief 範本
│   │   ├── task.md                          # Track A 新功能
│   │   ├── change-request.md                # Track B 修改需求
│   │   ├── bug-report.md                    # Track C 除錯
│   │   └── dev-log.md                       # 每日日誌
│   ├── planning/                            # 動態文件
│   │   ├── ROADMAP.md
│   │   └── tasks.md
│   └── dev-logs/                            # 每日日誌（YYYY-MM-DD.md）
│       └── README.md
└── .claude/                                 # Claude Code 專屬
    ├── agents/
    │   ├── code-reviewer.md                 # Step 4 — fresh-context review
    │   └── spec-tester.md                   # Step 5 — acceptance → 整合測試
    └── skills/
        ├── needs-analysis/SKILL.md          # Step 2 — 三 track 入口
        └── dev-cycle/SKILL.md               # Step 3 — 開發紀律

員工 + 三 track 對應 dev-workflow

Step	員工	類型	Track A 新功能	Track B 修改	Track C 除錯
2	needs-analysis	Skill	需求分析	變更分析 + Backward compat	Bug triage + Root cause
3	dev-cycle	Skill	開發紀律	+ Regression	+ 修 root cause
4	code-reviewer	Sub-agent	常規 review	+ Backward compat 檢查	+ Root cause 檢查
5	spec-tester	Sub-agent	Acceptance 整合測試	既有 + 新 acceptance	Regression test

詳見 agents/conventions/dev-workflow.md。

為什麼是這個結構

設計選擇	原因
agents/ 不叫 docs/	命名跟 AGENTS.md 對齊，明確是「給 AI 員工讀的知識庫」
Convention 拆檔	單一職責、好維護，AGENTS.md 只放摘要 + link 過去
三份 brief 範本	新功能 / 修改 / 除錯本來就是不同類型，欄位需求不同
4 員工 pipeline 化	對應 dev-workflow Step 2-5，不是「各種專家拼盤」
Skill vs Sub-agent	要對話用 Skill（主 context）、要抗 bias 用 Sub-agent（fresh context）
dev-logs 每日一檔	沉澱「詢問與裁決 Q&A」，未來 session 可回推當時的決策脈絡

不該放在這的東西

• ~/.claude/rules/ 全域規則（跨專案通用的）— 放在 home dir、不在專案內
• ~/.claude/CLAUDE.md 全域個人偏好 — 同上
• Auto memory（~/.claude/projects/<project>/memory/）— Claude 自己累積的、不是手寫的