# AWOOOI Project Configuration

> Claude Code 自動載入，定義核心原則

---

## 🚨🚨🚨 強制提醒 (每小時自我檢查)

**你有確實執行以下動作嗎？沒有就立刻執行！**

```
□ 讀過 MEMORY.md 索引？
□ 讀過 docs/LOGBOOK.md 最新進度？
□ 讀過 docs/HARD_RULES.md 絕對禁止規則？
□ 涉及特定主題時，讀過對應 feedback_*.md？
□ 修改檔案前，讀過該檔案的所有註解？ 🔴 NEW
```

**違反後果**: 重複犯錯、統帥需要反覆提醒、信任度下降

---

## 🔴 絕對禁止 (Hard Rules)

**做任何修改前，先讀對應的鐵律文件：**

→ [HARD_RULES.md](docs/HARD_RULES.md)

---

## ⚠️ Session 啟動第一步

**在做任何事之前，先讀：**
1. `MEMORY.md` - 記憶索引
2. `docs/LOGBOOK.md` - 最新進度
3. `docs/HARD_RULES.md` - 絕對禁止規則
4. 涉及主題的 `feedback_*.md`

**不要讓統帥說「你讀過 Memory 了嗎？」**

---

## 四大核心原則

1. **變更前 → 先讀註解** (理解設計意圖再動手) 🔴 NEW
2. **不可逆操作 → 人工確認** (刪除、logOut、DROP、force push)
3. **有疑問 → 先問統帥** (不確定就停下來)
4. **任務完成 → 更新 Memory** (不等被問)

---

## 🔴 紅區治理 (Codebase Zoning)

**詳細文件:** [docs/RED_ZONES.md](docs/RED_ZONES.md)

### 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 監控 | 可觀測失明 |

### 🏛️ 看到紅區警告時必須

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

**審查週期**: 紅區清單 (每週一) / Hook 腳本 (每月第一週一)

## 專案架構

- `apps/api/` - FastAPI 後端
- `apps/web/` - Next.js 前端
- `k8s/` - Kubernetes 配置

## 🛑 修改前

修改以下檔案前，**必須先讀** [HARD_RULES.md](docs/HARD_RULES.md)：

- `.github/workflows/*` → GitHub Billing 章節
- `*telegram*` → Telegram Token 章節
- `apps/web/**` → i18n 章節
- Incident/Approval 流程 → 確認 Telegram + DB 鏈路
- **Alertmanager/NetworkPolicy** → ADR-025 告警鏈路 E2E 驗證 🔴🔴

---

## 任務前必讀

涉及以下主題時，**先讀取對應 Memory**：

| 主題 | Memory 路徑 |
|------|-------------|
| **變更前必讀** | `feedback_read_comments_first.md` 🔴 先讀註解 |
| **變更註解** | `feedback_change_annotation_standard.md` 🔴🔴 人事物+版本+時區 |
| **重大變更** | `feedback_product_survival_principles.md` |
| Telegram | `feedback_telegram_token_disaster.md` |
| OpenClaw | `feedback_architecture_openclaw_core.md` |
| 命名規範 | `feedback_openclaw_naming.md` |
| i18n | `feedback_i18n_zero_hardcode.md` |
| 防禦性工程 | `feedback_defensive_engineering.md` |
| 模組化 | `feedback_modular_architecture.md` |
| **🔴🔴 積木化強制** | `feedback_lewooogo_modular_enforcement.md` 🔴🔴 修改前 5 問 |
| API 整合 | `feedback_api_response_verification.md` |
| 構建部署 | `feedback_build_from_git_only.md` |
| **測試** | `feedback_no_mock_testing.md` 🔴🔴 禁止 Mock |
| **API 路徑** | `feedback_api_path_naming.md` 🔴 修改需同步前端 |
| **部署驗證** | `feedback_deployment_verification.md` 🔴🔴 必須驗證 Pod 版本 |
| **部署層級** | `feedback_deployment_layer_decision.md` 🔴🔴🔴 主機/容器/K3s 必須評估 |
| **告警鏈路** | `feedback_alertchain_e2e_validation.md` 🔴🔴🔴 Alertmanager→API→Telegram |

---

## 🔴 部署層級決策 (Deployment Layer)

**詳細文件:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_deployment_layer_decision.md`

### 部署新服務前必須

```
1. ❌ 禁止: 直接 docker run / kubectl apply
2. ✅ 必須: 先提出「服務部署評估報告」
3. ✅ 必須: 等待統帥確認部署層級
4. ✅ 必須: 確認備份/回滾機制
```

### 三層部署選項

| 層級 | 適用場景 | 範例 |
|------|---------|------|
| **主機層** | 核心基礎設施、需持久化 | Harbor, Runner, PostgreSQL |
| **容器層** | 獨立工具、非核心路徑 | Sentry, Langfuse, OpenClaw |
| **K3s 層** | 生產應用、需水平擴展 | AWOOOI API/Web/Worker |

### 評估必答問題

1. 服務類型是什麼？(無狀態/有狀態)
2. 需要持久化嗎？
3. 可以接受中斷嗎？
4. 有備份機制嗎？
5. 配置如何版本化？
6. 如何回滾？

**違規後果**: 容器不見、Pod 被移除、修復時間長、無法回滾

---

## 🔴🔴 leWOOOgo 積木化強制執行

**詳細文件:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_lewooogo_modular_enforcement.md`

### 修改 apps/api/ 前必問 5 題

```
1. 這個邏輯是否已存在於 packages/？ → 用 packages，禁止重寫
2. Router 是否只做 HTTP 轉發？ → 禁止直接存取 Redis/DB
3. Service 是否依賴 Interface？ → 必須用 Protocol/ABC
4. 是否可被其他模組重用？ → 可重用邏輯放 packages/
5. 是否遵循依賴注入？ → 禁止 global singleton
```

### 正確架構層次

```
api/v1/*.py (Router) → services/*.py (Service) → packages/lewooogo-*/ (積木)
```

### Router 層禁止清單

```python
# ❌ 禁止
from src.core.redis_client import get_redis
from src.db.base import get_session
LUA_SCRIPT = """..."""

# ✅ 正確
from src.services.xxx_service import XxxService
```

### Git Hook 強制阻擋

Pre-commit Hook 會自動檢查並阻擋 Router 層違規

**違規後果**: Commit 被阻擋、技術債累積、3 週開發浪費

---

## Skills 載入

| 任務類型 | Skill 路徑 |
|---------|-----------|
| 前端 | `.agents/skills/01-awoooi-frontend-aesthetics.md` |
| 後端 | `.agents/skills/02-lewooogo-backend-core.md` |
| AI/決策 | `.agents/skills/03-openclaw-cognitive-expert.md` |
| DevOps | `.agents/skills/04-awoooi-devops-commander.md` |
| 測試 | `.agents/skills/05-awoooi-sre-qa.md` |
| Git | `.agents/skills/06-awoooi-monorepo-master.md` |
| Tool 整合 | `.agents/skills/07-tool-integration-expert.md` |
| 模型路由 | `.agents/skills/08-model-router-expert.md` |
| **絞殺者重構** | `.agents/skills/09-strangler-pattern-expert.md` 🆕 |

## Memory 系統

- 長期記憶：`~/.claude/projects/-Users-ogt-awoooi/memory/`
- 索引：`MEMORY.md`
- 進度：`docs/LOGBOOK.md`

## Session 協議

**啟動時**：讀 MEMORY.md → LOGBOOK.md → 確認當前任務

**結束前**：更新相關 Memory → 更新 LOGBOOK → 標記下一步