141 lines
5.6 KiB
Markdown
141 lines
5.6 KiB
Markdown
# 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/*：缺陷修复
|
||
- 中文提交信息，格式：{类型}({模块}): {描述}
|