14c81f728f
新增: - ADR-025: 告警鏈路 E2E 驗證架構 (2026-03-26 事故教訓) 更新: - ADR-011: 新增 DNS 規則最佳實踐 (附錄 B) - Skill 04: 新增 NetworkPolicy DNS 規則 + CoreDNS 設定 - Skill 05: 新增告警鏈路 Smoke Test 要求 - CLAUDE.md: 新增告警鏈路驗證到任務前必讀 事故根因: 1. URL 路徑錯誤 (webhook vs webhooks) 2. NetworkPolicy DNS 規則標籤不匹配 3. CoreDNS 上游 DNS 依賴 systemd-resolved Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
227 lines
7.0 KiB
Markdown
227 lines
7.0 KiB
Markdown
# 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 → 標記下一步
|