awoooi/CLAUDE.md

AWOOOI Project Configuration

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

---

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

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

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

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

---

🔴 絕對禁止 (Hard Rules)

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

→ 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

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：

• .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 層禁止清單

# ❌ 禁止
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 → 標記下一步