# Skill 06: AWOOOI Monorepo Master
# 專案架構與版本守護者

> **管轄範圍**: `packages/*`, Git, Workspace, Dependencies
> **觸發條件**: 修改共用套件、Git 操作、依賴更新

---

## 文件資訊

| 欄位 | 值 |
|------|-----|
| **版本** | v1.6 |
| **建立日期** | 2026-03-20 (台北) |
| **建立者** | Claude Code |
| **最後修改** | 2026-04-24 22:30 (台北) |
| **修改者** | Codex |

### 變更紀錄

| 版本 | 日期 | 執行者 | 變更內容 |
|------|------|--------|----------|
| v1.0 | 2026-03-20 | Claude Code | 初始建立 |
| v1.1 | 2026-03-25 | Claude Code | 加入文件資訊區塊 |
| v1.2 | 2026-03-26 | Claude Code | 新增紅區治理 + Git Hooks 章節 |
| v1.3 | 2026-03-26 | Claude Code | 首席架構師審查流程 + 審查週期調整 (每週) |
| v1.4 | 2026-03-26 | Claude Code | 🔴 新增「封存而非刪除」策略 (統帥裁示) |
| v1.5 | 2026-03-26 | Claude Code | **dependency-cruiser 依賴治理整合 (Phase 14.2)** |
| v1.6 | 2026-04-24 | Codex | **新增 12-agent 協作治理：任務判型、主責/協作 agent、9 skills 對照** |

---

## Monorepo 結構

```
awoooi/
├── apps/
│   ├── api/          # FastAPI 後端
│   └── web/          # Next.js 前端
├── packages/
│   ├── lewooogo-core/ # 核心共用邏輯
│   ├── eslint-config/ # ESLint 共用配置
│   └── tsconfig/      # TypeScript 共用配置
├── k8s/
│   └── awoooi-prod/   # K8s Manifests
├── .agents/
│   └── skills/        # Claude Skills
└── docs/              # 文檔系統
```

---

## 核心約束 (Monorepo Iron Laws)

### 1. 絕對禁止 Import 舊專案

```typescript
// ❌ 絕對禁止
import { something } from '../../../wooo-aiops/...'
import { legacy } from '@wooo-aiops/...'

// ✅ 正確 (僅限 AWOOOI 內部)
import { something } from '@awoooi/lewooogo-core'
import { config } from '../core/config'
```

### 2. K8s Image Tag 禁止 latest

```yaml
# ❌ 絕對禁止
image: 192.168.0.110:5000/library/api:latest

# ✅ 正確 (精確版本)
image: 192.168.0.110:5000/library/api:a2f7d12-23406265221
# 格式: {git-sha}-{run-id}
```

### 3. 依賴版本鎖定

```json
// package.json - 禁止寬鬆版本
{
  "dependencies": {
    // ❌ 禁止
    "next": "^14.0.0",
    "react": "*",

    // ✅ 正確 (精確版本)
    "next": "14.2.29",
    "react": "18.3.1"
  }
}
```

---

## Git Commit 規範

### Commit Message 格式

```
<type>(<scope>): <description>

[optional body]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```

### Type 列表

| Type | 說明 | 範例 |
|------|------|------|
| feat | 新功能 | `feat(api): add incident aggregation` |
| fix | 修復 | `fix(web): resolve hydration mismatch` |
| refactor | 重構 | `refactor(core): extract redis client` |
| docs | 文檔 | `docs: update LOGBOOK.md` |
| chore | 雜項 | `chore: update dependencies` |
| test | 測試 | `test(api): add health endpoint tests` |

### Scope 列表

| Scope | 對應目錄 |
|-------|----------|
| api | apps/api |
| web | apps/web |
| core | packages/lewooogo-core |
| k8s | k8s/ |
| ci | .github/workflows |
| agents | .agents/ |

---

## LOGBOOK 更新規範

### 強制更新時機

| 事件 | 必須更新 |
|------|----------|
| Phase 完成 | ✅ |
| 重大修復 | ✅ |
| 架構變更 | ✅ |
| 部署成功 | ✅ |

---

## 12-Agent 協作治理 (2026-04-24 新增)

> 目的：讓專案任務分工有固定語法，不再只靠臨場口頭約定。

### 定位

- `12 agents` 是任務角色分工
- `.agents/skills/*.md` 是工程守則
- 實際工作流：**先判型與派工，再依對應 skills 執行**

### 最小必要組隊原則

1. 每個任務只能有 1 個主責 agent
2. 協作 agent 預設 1-3 位，避免過度編排
3. 涉及紅區、Telegram、learning loop、deploy 時，自動補 `critic`

### 常用派工規則

| 任務類型 | 主責 agent | 協作 agent |
|----------|-----------|-----------|
| 查 bug / 查斷點 / 找根因 | `debugger` | `db-expert`, `tool-expert`, `critic` |
| migration / SQL / playbook / KM / learning | `db-expert` | `debugger`, `refactor-specialist` |
| 前端頁面 / UI / i18n / 戰情中心 | `frontend-designer` | `fullstack-engineer`, `critic` |
| 前後端一起改 / API 對 UI / 完整落地 | `fullstack-engineer` | `frontend-designer`, `debugger`, `db-expert` |
| 重構 / 抽層 / 技術債 | `refactor-specialist` | `migration-engineer`, `critic`, `db-expert` |
| Gitea / webhook / CI/CD / deploy | `migration-engineer` | `tool-expert`, `vuln-verifier`, `critic` |
| Telegram / approval / callback / 權限 / 安全 | `vuln-verifier` | `debugger`, `db-expert`, `critic` |
| 規劃 / 拆階段 / 驗收 | `planner` | `critic`, `onboarder` |
| 專案導覽 / 建立上下文 | `onboarder` | `planner`, `critic` |
| 官方規格 / SDK / 外部方案查證 | `web-researcher` | `planner`, `critic` |

### 與 9 Skills 的關係

| 12-agent | 最接近的 skills |
|----------|------------------|
| `frontend-designer` | `01-awoooi-frontend-aesthetics` |
| `fullstack-engineer` | `01 + 02 + 06` |
| `debugger` | `02 + 05` |
| `db-expert` | `02` |
| `refactor-specialist` | `09 + 02` |
| `migration-engineer` | `09 + 06 + 04` |
| `tool-expert` | `07` |
| `critic` | `05` |

完整規則見 `docs/12-agent-game-rules.md`

### 格式範例

```markdown
| 2026-03-23 00:30 | **🔧 Phase 8 NodePort 修復**: NetworkPolicy 新增 K3s Node IP 白名單，OTEL 端口修正 4317→24317 | CTO + Claude Code |
```

---

## 依賴管理

### pnpm Workspace 規範

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
```

### 安裝依賴

```bash
# 根目錄安裝 (開發依賴)
pnpm add -D -w <package>

# 特定 app 安裝
pnpm add <package> --filter @awoooi/web

# 共用套件安裝
pnpm add <package> --filter @awoooi/lewooogo-core
```

---

## 分支策略

| 分支 | 用途 | 保護 |
|------|------|------|
| main | 生產分支 | ✅ 禁止 force push |
| feature/* | 功能開發 | - |
| fix/* | 修復分支 | - |

### PR 規範

```markdown
## Summary
- 簡述變更內容

## Test plan
- [ ] 本地測試通過
- [ ] CI/CD 綠燈

🤖 Generated with Claude Code
```

---

## 🔴 封存而非刪除 (Archive, Not Delete)

> **統帥裁示 2026-03-26**: 專業團隊不輕易刪除代碼，改採「封存」策略

### 核心原則

| 原則 | 說明 |
|------|------|
| **不輕易刪除** | 代碼重構時，舊代碼先封存，不直接刪除 |
| **保留回滾能力** | 封存代碼可隨時恢復，降低風險 |
| **記錄封存操作** | 所有封存必須記錄到 ARCHIVE_LOG.md |
| **設定保留期限** | 封存後 90 天無問題才真正刪除 |

### 封存目錄結構

```
apps/api/src/services/
├── _archived/                      # 封存目錄 (底線開頭)
│   ├── ARCHIVE_LOG.md              # 封存紀錄 (必須)
│   ├── incident_memory_v1.py       # 封存副本
│   └── incident_engine_v1.py       # 封存副本
├── incident_memory.py              # 新版本 (active)
└── incident_engine.py              # 新版本 (active)
```

### ARCHIVE_LOG.md 格式

```markdown
# Archive Log

## incident_memory_v1.py

| 欄位 | 值 |
|------|-----|
| 封存日期 | 2026-XX-XX |
| 封存原因 | Phase 16 絞殺者模式，改用 lewooogo-brain |
| 原始位置 | apps/api/src/services/incident_memory.py |
| 替代方案 | lewooogo_brain.adapters.incident_memory |
| 回復指令 | `git checkout a202a26 -- apps/api/src/services/incident_memory.py` |
| 48hr 驗證通過 | 2026-XX-XX |
| 最終刪除日期 | 2026-XX-XX (封存後 90 天) |
```

### 封存流程

```
1. 新代碼穩定運行 48 小時 ✓
2. 建立 _archived/ 目錄 (如不存在)
3. 複製舊檔案到 _archived/ 並加上 _v1 後綴
4. 更新 ARCHIVE_LOG.md
5. 標記原檔案為 @deprecated (保留 90 天)
6. 90 天後無問題 → 真正刪除封存檔案
```

### 禁止事項

| 禁止 | 原因 |
|------|------|
| ❌ 直接 `rm` 舊代碼 | 無法追溯、無法快速回滾 |
| ❌ 跳過 48hr 驗證期 | 新代碼可能有隱藏 bug |
| ❌ 不記錄封存操作 | 團隊無法理解變更歷史 |
| ❌ 封存後立即刪除 | 未經充分驗證 |

---

## 🔴 紅區治理 (Codebase Zoning)

> **統帥 2026-03-26 批准**: 代碼防區化治理機制

### Git Pre-commit Hook

```bash
# 安裝 Hook
bash scripts/setup-hooks.sh

# Hook 位置
scripts/hooks/pre-commit  # 原始檔 (tracked)
.git/hooks/pre-commit     # 已安裝 (not tracked)
```

### Tier 3 紅區 (核心大腦)

| 檔案 | 功能 | 破壞後果 |
|------|------|----------|
| `services/decision_manager.py` | 決策狀態機 | AI 無法做決策 |
| `services/trust_engine.py` | 信任評分 | Multi-Sig 失效 |
| `services/consensus_engine.py` | 共識引擎 | 審批繞過 |
| `services/incident_engine.py` | 事件處理 | 告警無法處理 |
| `services/multi_sig_redis.py` | 分散式鎖 | 併發競爭 |
| `services/security_interceptor.py` | 安全攔截 | 權限繞過 |
| `core/config.py` | 環境配置 | 連線全斷 |
| `core/telemetry.py` | OTEL 監控 | 可觀測失明 |

### Tier 2 橙區 (基礎設施)

| 路徑 | 功能 |
|------|------|
| `k8s/awoooi-prod/*.yaml` | K8s 正式環境 |
| `apps/api/src/db/models.py` | 資料庫 Schema |
| `.github/workflows/*.yml` | CI/CD Pipeline |
| `core/redis_client.py` | Redis 連線池 |
| `services/telegram_gateway.py` | Telegram 閘道 |

### 🏛️ 首席架構師審查流程

當 Claude Code 看到紅區警告時：

```
1. 立即停止 commit
2. 呼叫首席架構師介入
3. 首席架構師進行架構與代碼 Review:
   - 變更必要性
   - 影響範圍評估
   - 替代方案評估
   - 回滾計畫
4. 首席架構師簽核後，方可繼續 commit
```

### 定期審查

| 項目 | 週期 | 下次審查 |
|------|------|----------|
| **紅區清單** | **每週一** | 2026-03-31 |
| **Hook 腳本** | **每月第一個週一** | 2026-04-06 |

---

---

## 🔗 dependency-cruiser 依賴治理 (Phase 14.2)

> **ADR-014**: 前端依賴分層治理
> **配置檔**: `.dependency-cruiser.cjs`

### Layer Model

```
Layer 0: app/           (Pages - 可引用所有)
    ↓
Layer 1: components/    (Features - 禁止互相引用)
    │   ├── agent/
    │   ├── approval/
    │   ├── incident/
    │   └── dashboard/
    ↓
Layer 2: shared/layout  (禁止下行引用 Layer 1)
    ↓
Layer 3: ui/lib/stores/hooks  (純工具層 - 禁止引用 components)
```

### 檢查指令

```bash
# 掃描前端依賴違規
pnpm dep-check

# 輸出格式: severity | rule | from → to
```

### 規則清單

| 規則 | 嚴重度 | 說明 |
|------|--------|------|
| `feature-isolation-*` | error | Feature 禁止互相引用 |
| `shared-no-feature-import` | error | Shared 禁止引用 Feature |
| `ui-no-feature-import` | error | UI 禁止引用 Feature/Shared |
| `components-no-app-import` | error | Components 禁止引用 app |
| `no-circular` | error | 禁止循環依賴 |
| `hooks-no-component-import` | warn | Hooks 禁止引用 Components |
| `stores-no-component-import` | warn | Stores 禁止引用 Components |

### 違規範例

```typescript
// ❌ 違反 feature-isolation-agent
// apps/web/src/components/agent/AgentChat.tsx
import { ApprovalCard } from '../approval/ApprovalCard'  // error!

// ✅ 正確: 使用 shared 層
import { Card } from '../ui/card'
```

### CI 整合

```yaml
# .github/workflows/ci.yaml
- name: Check dependencies
  run: pnpm dep-check
```

---

## 參考文檔

- `turbo.json`: Turborepo 配置
- `pnpm-workspace.yaml`: Workspace 定義
- `DEPENDENCIES.md`: 依賴清單
- `docs/LOGBOOK.md`: 進度追蹤
- `docs/RED_ZONES.md`: 紅區治理手冊
- `scripts/hooks/pre-commit`: 紅區 Hook 腳本
- `.dependency-cruiser.cjs`: **Phase 14.2 依賴治理規則**
- `docs/adr/ADR-014-dependency-governance.md`: **ADR-014 決策記錄**
