docs: separate documentation and specs into initial commit

Establish baseline for project documentation including BMAD specs, PRD, and system architecture notes.
2026-02-11 11:49:49 +08:00
parent 8c87d71aa2
commit e9897388dc
34 changed files with 11920 additions and 8777 deletions
--- a/AGENCIES_REFACTOR_PROPOSAL.md
+++ b/AGENCIES_REFACTOR_PROPOSAL.md
@@ -0,0 +1,144 @@
+# AGENTS.md 重構提案
+
+## 當前狀況
+
+- **文件大小**: 8119 行，310KB（超過 256KB 上下文限制）
+- **結構**: 項目指南 + 自動生成的 BMAD 內容
+
+## 提議的文件結構
+
+```
+website-enchun-mgr/
+├── AGENTS.md                          # 精簡的根文件 (~30 行)
+├── CLAUDE.md                          # 項目指南（與 AGENTS.md 相同或符號連結）
+└── .bmad-core/                        # BMAD 工具目錄（已存在）
+    ├── agents/                        # BMAD agent 定義
+    ├── tasks/                         # BMAD task 定義
+    └── ...
+```
+
+---
+
+## 新的 AGENTS.md（根文件）
+
+```markdown
+# Repository Guidelines
+
+Astro frontend + Payload CMS backend monorepo for website migration.
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `pnpm install` | Sync dependencies |
+| `pnpm dev` | Start dev server (Astro at :4321) |
+| `pnpm test:unit` | Run Vitest tests |
+| `pnpm test:e2e` | Run Playwright tests |
+| `pnpm build` | Production build |
+
+## Module Locations
+
+| Type | Location |
+|------|----------|
+| Frontend components | `frontend/src/components` |
+| Frontend routes | `frontend/src/pages` |
+| Frontend shared | `frontend/src/services` or `frontend/src/lib` |
+| Backend collections | `backend/src/collections` |
+| Backend auth/integrations | `backend/src` |
+| Contract tests | `backend/tests` |
+| Specs | `specs/001-users-pukpuk-dev/` |
+
+## BMAD Agents & Tasks
+
+This project uses BMAD-METHOD for structured development. Agent and task definitions
+are managed in `.bmad-core/` and auto-generated into this file.
+
+**Useful commands:**
+- `npx bmad-method list:agents` - List available agents
+- `npx bmad-method install -f -i codex` - Regenerate Codex AGENTS.md
+- `npx bmad-method install -f -i opencode` - Regenerate OpenCode AGENTS.md
+
+For agent/task details, see:
+- `.bmad-core/agents/` - Agent definitions
+- `.bmad-core/tasks/` - Task definitions
+- `.bmad-core/user-guide.md` - Full BMAD documentation
+
+---
+
+<!-- BEGIN: BMAD-AGENTS -->
+<!-- Auto-generated by: npx bmad-method install -f -i codex -->
+<!-- END: BMAD-AGENTS -->
+```
+
+---
+
+## 標記刪除的內容
+
+以下內容應從 AGENTS.md 移除，因為它們是：
+1. **自動生成的** - BMAD 工具會重新生成
+2. **重複的** - OpenCode 和 Codex 部分幾乎相同
+3. **可通過工具訪問** - `.bmad-core/` 目錄已包含所有定義
+
+### 移除的區塊
+
+| 行範圍 | 內容 | 原因 |
+|--------|------|------|
+| 22-7624 | BMAD-METHOD Agents (Codex) | 自動生成，存在於 `.bmad-core/` |
+| 7627-8119 | BMAD-METHOD Agents (OpenCode) | 自動生成，存在於 `.bmad-core/` |
+
+---
+
+## 執行選項
+
+### 選項 A：最小化重構（推薦）
+
+保留自動生成區塊的標記，但讓 BMAD 工具管理內容：
+
+```bash
+# 1. 備份當前文件
+cp AGENTS.md AGENTS.md.backup
+
+# 2. 創建精簡的根文件（見上方模板）
+# 3. 讓 BMAD 重新生成內容
+npx bmad-method install -f -i codex
+npx bmad-method install -f -i opencode
+```
+
+### 選項 B：完全移除自動生成內容
+
+如果不需要 Codex/OpenCode 整合：
+
+```bash
+# 創建純粹的 AGENTS.md，不包含 BMAD 內容
+```
+
+### 選項 C：分離到不同文件
+
+將 BMAD 內容移至單獨文件：
+
+```
+AGENTS.md -> 項目指南
+.bmad/AGENTS-CODEX.md -> Codex 內容
+.bmad/AGENTS-OPENCODE.md -> OpenCode 內容
+```
+
+---
+
+## 建議
+
+**選項 A（最小化重構）是最佳選擇**，因為：
+
+1. BMAD 工具設計就是自動生成這些內容
+2. `.bmad-core/` 目錄已經包含所有 agent/task 定義
+3. 需要時可以通過命令重新生成
+4. 根文件保持簡潔，只包含項目特定的指南
+
+---
+
+## 下一步
+
+請確認要執行哪個選項：
+1. **選項 A** - 最小化重構（推薦）
+2. **選項 B** - 完全移除 BMAD 內容
+3. **選項 C** - 分離到不同文件
+4. **自定義** - 說明您的需求