oh-my-muse/CLAUDE.md

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

本仓职责

本仓是 Muse 四仓架构中的设计文档仓，承担产品、架构、流程、前端、后端、专题设计的单一事实源（SSOT）。

• 不承载运行时代码
• 不承载 CI/CD 配置或部署脚本
• 只定义目标设计和 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 中测试失败阻断合入

长任务持续性保障

• 大功能拆为可独立验证的子任务
• 每个子任务完成后更新 design-docs/memorys/ 留痕
• Agent 可从 memorys 和 git log 恢复上下文

关键文件索引

文件	用途
design-docs/00-文档大纲.md	文档集导航入口
design-docs/内容映射表.md	概念归属和 owner 清单
docs/dev-baseline/global/01-AI开发管理总则.md	AI 开发全局规则
docs/dev-baseline/global/02-跨仓库协作规范.md	四仓协作规则
docs/dev-baseline/muse-cloud/CLAUDE.md	后端开发规范
docs/dev-baseline/muse-studio/CLAUDE.md	用户端前端规范
docs/dev-baseline/muse-admin/CLAUDE.md	管理端前端规范

Git 工作流

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