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

> **本项目以 AI 驱动开发。** 无论你是 AI agent 还是工程师,**每个任务都从这里开始**。
> 本文件是**项目唯一事实源**:既答"这是什么项目"(定位/目录),也答"怎么在这里干活"(先读什么、守什么规则、怎么把经验沉淀回去)。
> 能力细节在 [`.agents/`](.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/` 三个实现仓代码**就在本工作树里、被本仓版本控制**;CI 在 `muse-cloud/.github/workflows/`。
- 因此:**agent 可以也应当修改这些实现代码**(遵循各自规范 + [`.agents/rules/`](.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)
    └── memorys/             # 已归档清理(见 README);进度改用 mvp/进度总账.md
```

---

## 4. 任务前必读

| 序 | 文档 | 作用 |
|---|---|---|
| 1 | [`.agents/rules/verification-and-anti-false-green.md`](.agents/rules/verification-and-anti-false-green.md) | **脊柱规则**:完成=机械验证、机械门禁优先、反假绿 |
| 2 | `docs/agent-specs/2026-06-13-项目目标与模块现状基线.md` | 项目目标 + 模块**真实**现状(避免重复探索) |
| 3 | `docs/agent-specs/2026-06-13-目标达成对抗复盘.md` | 失控根因(假绿)与重定路径 |
| 4 | [`.agents/README.md`](.agents/README.md) | 能力中枢导航 |
| 5 | design-docs(`00-文档大纲.md` 入口 + `架构-01/02`、`后端-01`) | 设计事实 |

---

## 5. 工作协议(硬约束)

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

---

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

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

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

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

---

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

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

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