refactor(docs): CLAUDE.md 精簡化 - 引用外部 MD
- 紅區治理:引用 RED_ZONES.md - 部署層級:引用 feedback_deployment_layer_decision.md - 積木化:引用 feedback_lewooogo_modular_enforcement.md - 新增:基礎設施參考 (SERVICE-ENDPOINTS.md + K3S-RUNBOOK.md) - 減少 35% 內容 (227 → 148 行) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
107
CLAUDE.md
107
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
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user