wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
22b27d19df6003b9dc07c73ece65cd9c2dcbfe39
ewoooc/AGENTS.md
OoO 13f17d62e7 docs(frontend): 建立 V2 視覺基準
2026-04-30 23:37:52 +08:00

6.9 KiB
Raw Blame History

EwoooC (MOMO Pro System) — Codex 專案工作規則

版本: V13.4 目標: 把專案知識整理成 Codex 可低成本讀取、可持續維護、可安全落地的單一工作入口。

1. 入口原則

  • AGENTS.md 是本專案給 Codex 的唯一入口索引。
  • CONSTITUTION.md 是紅線與不可違反規則。
  • docs/adr/ 保存重大架構決策。
  • docs/memory/README.md 保存「要讀哪份記憶」的輕量索引。
  • CLAUDE.md 僅保留為舊文件相容入口，不再作為正式規範來源。

2. Token 節流原則

  • 先讀索引，再讀必要文件，禁止每次任務全文掃描所有 Markdown。
  • 預設只讀與當前任務直接相關的 1 到 3 份文件。
  • ADR 只讀 docs/adr/README.md 與命中的單篇 ADR，不整包展開。
  • Memory 只讀 docs/memory/README.md 與命中的單篇記憶，不整包展開。
  • 大型歷史文件、考古文、外部存檔只在任務明確需要時才開啟。
  • 若規則已存在於 CONSTITUTION.md，不要再到其他文件尋找重複版本。

3. Codex Session SOP

開始前

  1. 先讀 AGENTS.md。
  2. 再讀 CONSTITUTION.md 中與本次任務直接相關的章節。
  3. 讀 docs/adr/README.md，只打開命中的 ADR。
  4. 讀 docs/memory/README.md，只打開命中的 memory。

進行中

  • 先看程式碼與實際行為，再回頭補讀文件。
  • 若文件與程式碼衝突，以程式碼、部署實況、已接受 ADR 為準，並回補文件。
  • 修改時優先維持最小變更面，避免為了整理而擴大 diff。

結束前

  • 有新架構決策才新增 ADR。
  • 有長期有效且非架構層的專案知識才更新 memory。
  • 有 AI 自動化閉環、模型分工、告警/自癒行為變更才更新 docs/AI_INTELLIGENCE_MODULE_SOT.md。
  • 有全域紅線變更才更新 CONSTITUTION.md。
  • 有入口或索引變更才更新 AGENTS.md 或對應 README。

4. 文件分層

AGENTS.md

  • 只放 Codex 工作方式、入口索引、環境摘要、必讀路徑。
  • 保持短，不放長篇歷史、細節 SOP、逐步教學。

CONSTITUTION.md

  • 只放不可違反規則、跨任務穩定成立的硬性約束。
  • 避免放會頻繁變動的操作細節。

docs/adr/

  • 只放重大架構決策與後果。
  • 新 ADR 需包含 Context、Decision、Alternatives、Consequences。

docs/memory/

  • 只放高重用、非決策型、跨 session 容易遺忘但值得保存的資訊。
  • 每篇 memory 應短小、單主題、可被索引命中。

Skills

  • 本專案不再維護 .claude/skills 或本地技能腳本作為正式規範。
  • 若使用者要求「更新 Skills」，預設轉譯為更新 docs/guides/*.md 的可重複流程與 AGENTS.md 索引，不新增私有 skill 真相來源。
  • 若未來需要可重複流程，優先寫成：
    1. docs/guides/*.md 的操作手冊
    2. 可執行腳本
    3. 對應 ADR 或 memory 的短索引

4.1 Agent 角色原則

  • 本專案保留歷史上的 12 角色分工思維，但改用 Codex 官方建議的「按需分工」模式。
  • 角色矩陣不作為 session 開場必讀，詳細說明放在 docs/guides/codex_agent_roles.md。
  • 預設由單一 Codex 直接完成任務；只有高風險、大規模、或明確可並行時才分角色思考。
  • 最小心法：先 planner，出問題先 debugger，做完一定經過 critic。

4.2 一頁式 Dispatch 表

如果任務是… 先用哪個角色思維 第二角色 收尾
一般功能開發 planner fullstack-engineer critic
線上 bug / 排程異常 / Telegram 故障 debugger fullstack-engineer critic
大型重構 / 拆大檔 / Blueprint 清理 planner refactor-specialist critic
DB schema / ORM / 漏表 / migration db-expert migration-engineer critic
安全修補 / 權限邊界 / secret 防護 vuln-verifier fullstack-engineer critic
外部 API / SDK / 平台規格更新 web-researcher tool-expert fullstack-engineer
接手舊模組 / 新 session 重新進場 onboarder explorer planner
工具、CI、hook、部署流程選型 tool-expert planner critic

最小決策規則：

  • 不確定先 planner
  • 有錯先 debugger
  • 動 DB 先 db-expert
  • 動安全先 vuln-verifier
  • 要上線前一定有 critic

5. 環境摘要

主機 IP 角色
110 192.168.0.110 Gateway、Nginx、Gitea、n8n、Superset
188 192.168.0.188 App、DB、Ollama、生產容器

6. 核心服務

容器 角色 入口
momo-pro-system Flask/Gunicorn 主應用 app.py
momo-scheduler 排程任務 run_scheduler.py
momo-telegram-bot Telegram Bot run_telegram_bot.py
momo-db PostgreSQL + pgvector momo-postgres service

7. 生產安全紅線

  • 禁止使用 docker compose ... --remove-orphans。
  • 禁止影響 momo-db 的資料與容器生命週期。
  • 跨專案資源邊界以 ADR-011 為準。
  • 部署、容器、SSH 類操作先看 docs/adr/ADR-011-cross-project-resource-isolation.md。
  • gunicorn.conf.py 必須透過 docker-compose.yml bind mount 進 momo-app；除救急外，不以 docker cp 當常態部署方式。
  • CD rebuild 應先完成 image build，再短暫 recreate 三應用容器；禁止把 no-cache build 時間變成長時間 502。

8. 常用入口

  • 部署 SOP: docs/guides/deployment_sop.md
  • DevOps 手冊: docs/guides/devops_handbook.md
  • 模組化治理: docs/guides/modularization_governance.md
  • 前端更版路線圖: docs/guides/frontend_upgrade_roadmap.md
  • AI 自動化 Session SOP: docs/guides/ai_automation_session_sop.md
  • AI 競價情報 SOT: docs/AI_INTELLIGENCE_MODULE_SOT.md
  • Agent 角色矩陣: docs/guides/codex_agent_roles.md
  • ADR 索引: docs/adr/README.md
  • Memory 索引: docs/memory/README.md
  • 歷史紀錄: docs/memory/history_logs.md
  • 程式碼模組化盤點: docs/memory/code_modularization_inventory_20260430.md
  • AI 自動化閉環記憶: docs/memory/ai_automation_closure_20260429.md
  • 憑證手冊: docs/memory/credentials_passbook.md

9. 常用指令

source venv/bin/activate && python app.py
git push origin main
ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"docker ps --format '{{.Names}} | {{.Status}}' | grep momo-; docker exec momo-scheduler env | grep -iE 'TELEGRAM|NVIDIA'; docker logs momo-scheduler --since 1h | grep -E 'Telegram|Error' | tail -10\""
ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"cd /home/ollama/momo-pro && docker compose up -d --no-deps --force-recreate <service>\""

10. 正式規範結論

  • Codex 在本專案的正式治理入口是：AGENTS.md、CONSTITUTION.md、docs/adr/README.md、docs/memory/README.md；AI 架構事實以 docs/AI_INTELLIGENCE_MODULE_SOT.md 為 SOT。
  • 其他文件預設都視為按需查閱資料，不是 session 開場必讀。
Reference in New Issue View Git Blame Copy Permalink