oh-my-muse/AGENTS.md

AGENTS.md —— oh-my-muse(Muse)· Agent 工作入口

本项目以 AI 驱动开发。 无论你是 AI agent 还是工程师,每个任务都从这里开始。 本文件是项目唯一事实源:既答"这是什么项目"(定位/目录),也答"怎么在这里干活"(先读什么、守什么规则、怎么把经验沉淀回去)。 能力细节在 .agents/;CLAUDE.md 是 design-docs(设计 SSOT)的写作规范,从属本文件。

---

1. 项目定位

Muse = AI 驱动的长篇创作工具(Shadow→Canonical 主权:AI 产出经"先审后入"才进入正式正文)。四仓协作,采用 monorepo 承载。

仓	技术栈	职责
muse-cloud	Java 21 + Spring Boot 3 + PostgreSQL + Yudao 框架	后端(9 业务域 muse-module-*)
muse-admin	Vue 3 + Vben Admin + TS	管理端前端
muse-studio	React + Vite + TS	用户端前端
design-docs / docs	Markdown + SQL	设计 SSOT / agent 规格与基建

业务域:account(member) / ai / content / knowledge / market / meta / events + 平台底座。

---

2. ⚠️ 仓库物理事实(2026-06-14 订正,对抗复盘 A1/R6)

本仓是 monorepo,物理承载实现代码,不是"纯设计文档仓"。

• git ls-files muse-cloud = 4468 文件、无 .gitmodules → muse-cloud/、muse-admin/、muse-studio/ 三个实现仓代码就在本工作树里、被本仓版本控制;既有 Maven CI 在 muse-cloud/.github/workflows/,OpenAPI diff 因自建 Gitea Actions 扫描规则已接到仓库根 .github/workflows/。
• 因此:agent 可以也应当修改这些实现代码(遵循各自规范 + .agents/rules/)。此前"本仓不承载代码/CI"的描述与磁盘矛盾,会让 agent 误判改动边界、绕路产生文档 churn,已订正。
• design-docs/、docs/ 是设计/规格 SSOT;实现代码须反向对齐其正式文档。

---

3. 目录导航

oh-my-muse/
├── AGENTS.md                # 本文件:项目入口(唯一事实源)
├── CLAUDE.md                # design-docs 写作规范(从属本文件)
├── .agents/                 # Agent 能力中枢(knowledge/rules/skills/workflows;见 .agents/README.md)
├── muse-cloud/ muse-admin/ muse-studio/   # 三实现仓代码(可改)
├── design-docs/             # 产品/架构/前后端/流程/专题 设计 SSOT + 内容映射表/大纲
└── docs/
    ├── agent-specs/         # 现状基线 + 对抗复盘 + P0 冻结令 + 六砖交付(过程 churn 已清理)
    ├── mvp/进度总账.md       # 进度单一事实源(+ 历史交付时间线)
    ├── api-contracts/       # 各域 OpenAPI = API 契约 SSOT(原地;见 .agents/rules/contract-first.md)
    ├── dev-baseline/        # 早期规范历史归档(已收敛进 .agents/rules;见 README)
    └── memorys/             # 已归档清理(见 README);进度改用 mvp/进度总账.md

---

4. 任务前必读

序	文档	作用
0	docs/项目功能与进度总览.md	人读全局:功能清单 + 进度表 + 待办表(一眼看全局;详细流水仍在 mvp/进度总账.md)
1	.agents/rules/verification-and-anti-false-green.md	脊柱规则:完成=机械验证、机械门禁优先、反假绿
2	docs/agent-specs/2026-06-13-项目目标与模块现状基线.md	项目目标 + 模块现状(2026-06-13 历史快照;当前现状以序0总览 / 主台账 / 覆盖 JSON 为准)
3	docs/agent-specs/2026-06-13-目标达成对抗复盘.md	失控根因(假绿)与重定路径
4	.agents/README.md	能力中枢导航
5	design-docs(00-文档大纲.md 入口 + 架构-01/02、后端-01)	设计事实

---

5. 工作协议(硬约束)

1. 读后动手:复杂任务先读 .agents/ 与相关 docs/,对齐事实再开工。
2. 机械门禁优先 / 完成=验证:遵守 verification-and-anti-false-green——无自动化绿证据不得声称完成;新规则必配机械门禁,不靠自觉。
3. 复杂/高危先评审:跨模块 / 改用户可见行为 / 触外部服务·支付·数据 → 评审版 → 两轮评审 → 执行版,再写代码。
4. 契约先行:改接口/数据结构先改契约(API=docs/api-contracts/*、DB=新增 sql/muse/V*.sql,均为原地 SSOT)再实现;遵守 contract-first,已有 Flyway 卫生 + OpenAPI 结构机械门禁(openapi-diff 已接 root workflow,远端首跑待确认)。
5. 最小改动 + 中文注释:只动相关代码,复用既有模式,不顺手重构;代码全简体中文注释,关键路径可追溯日志。
6. 无孤儿/拼接设计:任何新结构/接口/模型须带入口、使用路径、失败路径、验收标准。
7. 证据规则:区分已验证事实/推断/假设;无证据不声称"完成/修复/通过"。

---

6. 知识沉淀机制(也是硬约束 —— 复利的来源)

.agents/ 的价值在于复利:让"越往后开发越快越准"。因此:

• 每次有价值的交付后,把可复用产出回写对应层:新事实→knowledge/;新硬约束(必配门禁)→rules/;新操作手册→skills/;流程改进→workflows/。
• 先查重再新增;过时即修正/删除;结构性变更同步 .agents/README.md 索引与本文导航。
• 进度只进 总账 + per-module .agent,不再新增“状态推进”过程文档(过程文档 churn 是失控来源之一)。

无沉淀的任务是"一次性消耗";有沉淀,下一个同类任务在已有成果上更快更准地推进。

---

7. 当前基建建设状态(随建随更)

• ✅ 机械门禁地基:CI 真跑测试(JDK21、触发分支已修为 main——此前误配 master 致 CI 从不运行)、门禁去硬编码(含分域计数派生化)、P0 冻结令。
• ✅ 入口与中枢骨架:本文件 + .agents/README.md + 脊柱规则。
• ✅ BC 边界 ArchUnit 门(bc-boundaries):通用覆盖全业务 BC 间方向;AI/knowledge 直连 content、market 直写 member 三处违例均已整改消除,豁免清单 KNOWN_VIOLATION_EXEMPTIONS 清空 → 全绿(0 Architecture Violation;遗留:market-server pom 仍依赖 member-server,仅消除了 .dal 代码 import,见该规则 §三)。
• ✅ 契约先行门(contract-first):Flyway 迁移卫生 + OpenAPI 存在性/结构(注:挡不住语义破坏;openapi-diff root workflow 已接线,需远端首次 PR 运行验证)。
• ✅ loop 机械牙(AgentsInfraIntegrityTest):每业务 BC 有 .agent、README 索引每篇 .agents 文档、总账在——把写回/索引同步从自觉变机械。
• ✅ knowledge 蒸馏 / skills / workflow(AI 开发协议)/ 进度总账 + 7 BC .agent。
• ⏳ 后续:openapi-diff 远端 CI 首跑验证、Meta/schema 投影真实化、前端深页继续关 MSW 活体验收。dev-baseline 收敛进 rules、completed=测试证据兜底(testFiles)、跨域 .application 边界、market-server→member-server pom 坐标收口、ai/平台预存红测试整改均已完成。

进度只进 docs/mvp/进度总账.md + 各模块 .agent,不新增状态过程文档。