# CLAUDE.md — oh-my-muse (muse-design-docs)

## 项目全貌

Muse 是一个 AI 驱动的长篇创作工具，采用四仓架构：

| 仓库 | 技术栈 | 职责 |
|------|--------|------|
| muse-cloud | Java 21 + Spring Boot 3 + PostgreSQL + Yudao Cloud | 后端主仓 |
| muse-admin | Vue 3 + Vben Admin + TypeScript | 管理端前端 |
| muse-studio | React + Vite + TypeScript | 用户端前端 |
| **muse-design-docs（本仓）** | Markdown + SQL | 设计文档 SSOT |

## 本仓职责与项目入口（2026-06-14 订正）

> **项目级工作入口 = 根 [`AGENTS.md`](AGENTS.md)**。本文件聚焦 **design-docs（设计文档 SSOT）的写作规范**；项目定位/目录/工作协议以 AGENTS.md 为准。
> ⚠️ **订正（对抗复盘 A1/R6）**：本仓**不是**“纯设计文档仓”。它是 monorepo，同一 git 工作树内**物理承载** `muse-cloud/`、`muse-admin/`、`muse-studio/` 实现代码（`git ls-files muse-cloud` 4468 文件、无 submodule）+ CI（`muse-cloud/.github/workflows/`）。此前“本仓不承载代码/CI”与磁盘事实矛盾，会让 agent 误判可改动边界、绕路产生文档 churn，故订正。

- `design-docs/` 与 `docs/`：产品、架构、流程、前端、后端、专题设计的**单一事实源（SSOT）**；实现代码须反向对齐这些正式文档。
- `muse-cloud/`、`muse-admin/`、`muse-studio/`：**实现仓代码，可被 agent 修改**（遵循各自规范 + `.agents/rules/`）。
- 设计文档的 owner 归属与写作规范见下文各节。

## 开发模式

AI agent 驱动开发：
- Agent 负责：编码、测试编写、重构、文档更新
- 人类负责：架构决策、需求确认、PR review、发布决策
- 协作模式：人类提出任务 → agent 规划 → 人类确认 → agent 执行 → 人类 review

## 核心架构决策（已确认）

| 决策 | 结论 |
|------|------|
| Governance | 按消费者归属拆散，MetaSchema 独立模块 |
| AI 授权隔离 | 包级隔离 + ArchUnit |
| Source 传播 | 事件驱动 + 各模块自治 |
| Candidate Envelope | 去掉，简化为来源版本实时对比 |
| needs_recheck | 去掉，直接决策 active/disabled |
| 图查询 | 依赖 RAGFlow GraphRAG |
| 数据库 | PostgreSQL |
| API 版本 | X-API-Version Header |
| 实时通信 | SSE（AI stream 独立 + 事件统一） |
| 正文保护 | 自动保存 + IndexedDB 安全网 |
| Block 粒度 | 场景/小节级 |
| 知识确认 | 默认自动 + 冲突时人工 |
| Entitlement | 可变表 + 审计日志 |
| Archive | 先同表，后续按量分离 |

## 文档编写规范

### 文件命名

格式：`{角色前缀}-{编号}-{主题}.md`

角色前缀：产品 / 架构 / 后端 / 前端 / 流程 / 专题 / 临时

规则：
- 扁平结构，不建子目录（prototypes / memorys 除外）
- 编号连续，子编号用大写字母后缀（02A、02B）

### 版本管理

每个文档头部必须包含版本号、更新日期、目标读者、边界说明。每次实质性修改递增版本号。

### 交叉引用

只允许"链接 + 一句话摘要"，禁止大段复制粘贴。

### 术语统一

所有术语以 `架构-02-核心数据结构与双轨模型.md` 为权威定义。

### 单一归属

每个概念只有一个 owner 文档。归属清单见 `design-docs/内容映射表.md` 和 `design-docs/00-文档大纲.md`。

## Agent 行为约束

### 修改文档前
1. 读取 `design-docs/内容映射表.md` 确认概念 owner
2. 非 owner 文档只能添加引用链接，不能重复定义
3. 检查 `design-docs/00-文档大纲.md` 了解文档间关系

### 禁止行为
- 不在非 owner 文档中重复定义概念
- 不大段复制其他文档内容
- 不创建与现有文档职责重叠的新文档
- 不用临时文档内容反向覆盖正式分册
- 不在文档中硬编码实现细节（代码路径、类名属于实现仓）

### 修改后验证
1. 交叉引用完整性：被引用的文档和章节是否存在
2. 术语一致性：与 `架构-02` 是否一致
3. 版本号和更新日期是否已递增

### 新增 ADR 规范

新增架构决策记录必须包含：背景、选项（表格）、结论、后果。

### 新增文档规范

新增前确认：无现有文档覆盖该主题、owner 边界不冲突、在大纲和映射表中注册。

## 代码质量基线（适用于所有实现仓）

- 所有代码必须有合理的中文注释
- 关键业务逻辑（状态转换、事务边界、安全校验）必须有大量中文注释
- 注释说明 WHY 而非 WHAT
- 各仓遵循各自的 CLAUDE.md 规范

## 测试自动化

- 目标：自动化率 > 90%，人工只复核非标准场景
- 每次业务代码变更必须评估测试用例的增删改
- CI 中测试失败阻断合入

## 长任务持续性保障

- 大功能拆为可独立验证的子任务
- 每个子任务完成后按 AGENTS.md 写回总账、模块 `.agent` 或 `.agents/` 对应层;不要新增过程状态文档
- Agent 可从总账、模块 `.agent`、`.agents/knowledge` 和 git log 恢复上下文

## 关键文件索引

| 文件 | 用途 |
|------|------|
| `design-docs/00-文档大纲.md` | 文档集导航入口 |
| `design-docs/内容映射表.md` | 概念归属和 owner 清单 |
| `AGENTS.md` | 项目唯一工作入口 |
| `.agents/README.md` | Agent 能力中枢索引 |
| `.agents/rules/engineering-conventions.md` | 工程约定 / 跨仓协作 / CI 发布规则 |
| `.agents/rules/security-and-reliability.md` | 安全 / 可靠性 / 可观测规则 |
| `docs/dev-baseline/README.md` | 早期 dev-baseline 历史归档说明 |

## Git 工作流

- main：稳定基线
- feature/*：功能开发
- fix/*：缺陷修复
- 中文提交信息，格式：{类型}({模块}): {描述}