diff --git a/CLAUDE.md b/CLAUDE.md index c9c51441..b6821cbc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,37 +49,11 @@ --- -## 🔴 紅區治理 (Codebase Zoning) +## 🔴 紅區治理 -**詳細文件:** [docs/RED_ZONES.md](docs/RED_ZONES.md) +→ **詳細文件:** [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 腳本 (每月第一週一) +**簡述**: Tier 3 核心檔案 (decision_manager, trust_engine, config 等) 修改需首席架構師授權 ## 專案架構 @@ -87,6 +61,11 @@ - `apps/web/` - Next.js 前端 - `k8s/` - Kubernetes 配置 +## 🏗️ 基礎設施參考 + +→ [SERVICE-ENDPOINTS.md](docs/reference/SERVICE-ENDPOINTS.md) - 五主機架構與服務端點 +→ [K3S-OPTIMIZATION-RUNBOOK.md](docs/runbooks/K3S-OPTIMIZATION-RUNBOOK.md) - K3s 維運手冊 + ## 🛑 修改前 修改以下檔案前,**必須先讀** [HARD_RULES.md](docs/HARD_RULES.md): @@ -125,77 +104,19 @@ --- -## 🔴 部署層級決策 (Deployment Layer) +## 🔴 部署層級決策 -**詳細文件:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_deployment_layer_decision.md` +→ **詳細文件:** [feedback_deployment_layer_decision.md](~/.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 被移除、修復時間長、無法回滾 +**簡述**: 部署新服務前必須評估 主機/容器/K3s 層級,禁止直接 `docker run` 或 `kubectl apply` --- -## 🔴🔴 leWOOOgo 積木化強制執行 +## 🔴🔴 leWOOOgo 積木化 -**詳細文件:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_lewooogo_modular_enforcement.md` +→ **詳細文件:** [feedback_lewooogo_modular_enforcement.md](~/.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 週開發浪費 +**簡述**: 修改 `apps/api/` 前必問 5 題,Router 層禁止直接存取 Redis/DB ---