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

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

项目级工作入口 = 根 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/*：缺陷修复
• 中文提交信息，格式：{类型}({模块}): {描述}