docs: Phase 14 紅區治理 + Skills 01/03 更新

- CLAUDE.md: 紅區治理章節
- Skills 01/03: 版本更新
- ADR/Architecture: 標準化

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OG T
2026-03-26 09:55:47 +08:00
parent 9ea246c7c2
commit 604e38cf07
15 changed files with 391 additions and 25 deletions

114
CLAUDE.md
View File

@@ -47,6 +47,40 @@
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 後端
@@ -71,6 +105,7 @@
| 主題 | 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` |
@@ -78,11 +113,89 @@
| 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 必須評估 |
---
## 🔴 部署層級決策 (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 載入
@@ -94,6 +207,7 @@
| 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` 🆕 |
## Memory 系統