# AI 开发管理总则

- 版本：v1
- 更新日期：2026-05-24
- 适用范围：muse-cloud / muse-admin / muse-studio / muse-design-docs 四仓全局
- 目标读者：AI agent、人类开发者、架构师、项目管理者

## 规范优先级

当多份文档存在冲突时，按以下优先级执行：
1. 各仓库 CLAUDE.md（最具体的约束）
2. 全局总则和跨仓协作规范（通用规则）
3. dev-guide 开发指南（参考性指导）

如果发现冲突，应修正低优先级文档使其与高优先级对齐，而非忽略。

## 1. 开发模式定义

### 1.1 职责分工

| 角色 | 职责 | 不负责 |
|---|---|---|
| AI agent | 编码实现、测试编写、重构执行、文档更新、CI 修复、代码评审辅助、调试定位 | 架构决策、需求确认、发布决策、安全审计最终判定 |
| 人类开发者 | 架构决策、需求确认、PR review、发布决策、安全审计、异常升级处理 | 重复性编码、格式化、简单 bug 修复 |

### 1.2 协作流程

```
人类提出任务 → agent 分析并规划方案 → 人类确认方案 → agent 执行实现 → agent 自验证 → 人类 review → 合入
```

对于低风险、局部、验证明确的任务（typo 修复、简单 bug fix、测试补充），agent 可直接执行后提交 review，无需预先确认方案。

### 1.3 决策升级规则

以下情况 agent 必须停下来等待人类确认：
- 涉及架构变更（新增模块、修改模块边界、新增外部依赖）
- 涉及数据模型变更（新增表、修改字段语义、删除字段）
- 涉及 API 契约变更（新增接口、修改入参出参语义、废弃接口）
- 涉及安全相关变更（认证、授权、加密、数据脱敏）
- 涉及跨仓协调（一个变更需要多个仓库同步修改）
- 方案有多个可行路径且各有明显取舍时

## 2. 代码质量基线

### 2.1 中文注释规范

所有代码必须有合理的中文注释，遵循以下分级：

| 级别 | 适用场景 | 注释要求 |
|---|---|---|
| 必须详细注释 | 状态转换、事务边界、安全校验、数据流转换、AI 编排逻辑、双轨写入规则 | 说明 WHY（为什么这样做）、边界条件、失败处理策略 |
| 必须注释 | 公开接口、领域服务方法、配置项、枚举值 | 说明用途、参数含义、返回值语义 |
| 建议注释 | 工具方法、数据转换、非显而易见的条件判断 | 说明意图或 workaround 原因 |
| 禁止注释 | 代码自解释的简单操作 | 如 `// 获取用户` 对应 `getUser()` 是无意义注释 |

### 2.2 注释原则

- 注释说明 WHY 而非 WHAT（代码本身说明 what）
- 复杂算法必须注释时间/空间复杂度和核心思路
- 非显而易见的设计决策必须注释决策原因
- Workaround 必须注释：问题描述、临时方案、TODO 标记预期修复时间
- 禁止注释掉的代码长期留存（用 git 管理历史）

### 2.3 代码可读性

- 方法长度：单个方法不超过 80 行（不含注释），超过必须拆分
- 嵌套深度：不超过 3 层，超过用 early return 或提取方法
- 命名：变量和方法名必须自解释，禁止单字母变量（循环变量除外）
- 魔法值：禁止硬编码数字和字符串，必须提取为常量并注释含义

## 3. 代码风格一致性

### 3.1 各仓独立规范

每个仓库遵循各自 CLAUDE.md 中定义的语言和框架规范：
- muse-cloud：Java / Spring Boot / MyBatis-Plus 规范
- muse-admin：Vue 3 / TypeScript / Vben Admin 规范
- muse-studio：React / TypeScript / Vite SPA 规范
- muse-design-docs：Markdown 文档规范

### 3.2 跨仓一致性约定

以下约定跨四仓统一执行：

| 约定项 | 统一标准 | 说明 |
|---|---|---|
| 错误码格式 | `{系统}-{模块}-{分类}-{序号}` | 系统：1=muse；模块：001=content, 002=ai, 003=knowledge, 004=market, 005=account, 006=meta；分类：000=通用, 001=参数校验, 002=业务规则, 003=权限, 004=外部依赖；序号：000-999。示例：1-001-002-001 表示 content 模块的业务规则错误第 1 号 |
| API 路径命名 | 小写 kebab-case | `/app-api/work/text-block` |
| 日期时间格式 | ISO 8601（`2026-05-24T10:30:00+08:00`） | 前后端传输统一 |
| 分页参数 | `pageNo`（从 1 开始）/ `pageSize`（默认 20，最大 100） | 请求参数 |
| 分页响应 | `{ list, total }` | 响应体 |
| 布尔参数命名 | `is` / `has` / `can` / `enable` 前缀 | 语义明确 |
| 枚举传输 | 整数值传输，前端维护显示映射 | 不传字符串枚举 |
| 空值语义 | `null` 表示未设置，空字符串/空数组表示显式清空 | 前后端统一理解 |
| 时区 | 服务端存储 UTC，展示层转本地时区 | 数据库存 UTC |
| ID 类型 | Long（雪花算法），JSON 传输为 string 避免精度丢失 | 前端用 string 接收 |

## 4. 测试自动化策略

### 4.1 测试金字塔

```
        /  E2E 测试  \          ← 关键用户旅程，数量少
       / 集成测试      \        ← Application 层，验证模块协作
      / 契约测试        \       ← API 入参出参校验
     / 单元测试          \      ← Domain 层，覆盖业务规则
    /____________________\
```

### 4.2 各层测试要求

| 测试层 | 覆盖目标 | 运行时机 | 失败影响 |
|---|---|---|---|
| 单元测试 | Domain 实体、值对象、领域服务的业务规则 | 每次提交 | 阻断合入 |
| 集成测试 | Application Service 的编排逻辑、事务边界 | 每次提交 | 阻断合入 |
| 契约测试 | API 入参校验、出参结构、错误码 | 每次提交 | 阻断合入 |
| 组件测试（前端） | 组件渲染、交互、状态管理 | 每次提交 | 阻断合入 |
| E2E 测试 | 关键用户旅程端到端验证 | 合入主分支前 | 阻断发布 |
| AI 质量评测 | 生成文本的 canon_compliance、character_voice | 模型/Prompt 变更时 | 阻断相关发布 |

### 4.3 测试编写规则

- 每次业务代码变更必须评估测试用例的增删改
- 新增功能必须同步提交对应测试
- Bug 修复必须先写失败测试，再修复使其通过
- 测试命名：`should_{预期行为}_when_{前置条件}`
- 测试数据：使用 Builder 或 Factory 模式构造，不依赖外部数据源
- Mock 边界：只 mock 外部依赖（数据库、第三方 API、消息队列），不 mock 被测模块内部

### 4.4 覆盖率目标

- Domain 层：行覆盖率 > 90%
- Application 层：行覆盖率 > 80%
- Controller 层：契约测试覆盖所有公开接口
- 前端组件：关键交互路径覆盖率 > 80%
- 整体自动化率目标：> 90%，人工只复核非标准场景

## 5. 长任务持续性保障

### 5.1 任务拆分原则

大功能必须拆为可独立验证的子任务，每个子任务满足：
- 有明确的完成条件（可验证）
- 可独立提交和 review
- 不依赖未完成的其他子任务才能运行
- 单个子任务工作量不超过一个 agent 会话能完成的范围

### 5.2 上下文传递机制

```
任务开始 → 读取 docs/memorys/ 和 git log 恢复上下文
    ↓
执行子任务 → 完成后更新 docs/memorys/YYYY-MM-DD-任务描述.md
    ↓
下一个子任务 → 从 memorys 和 git log 恢复上下文继续
```

### 5.3 留痕规范

每个有复杂度的任务完成后，在 `docs/memorys/` 留痕：
- 文件名：`YYYY-MM-DD-任务描述.md`（任务描述 10-20 字）
- 内容：目标、关键决策、变更范围、验证结果、遗留问题
- 目的：下次类似任务或断点恢复时可快速获取上下文

### 5.4 断点恢复

agent 恢复中断任务时：
1. 读取最近相关的 `docs/memorys/` 文件
2. 查看 `git log` 了解最近提交
3. 检查当前分支状态和未完成的变更
4. 确认当前进度后继续执行，不重复已完成的工作

## 6. 稳定性保障

### 6.1 CI 门禁

每个 PR 必须通过以下检查才能合入：
- 编译成功（零错误）
- Lint 通过（零错误，warning 不阻断但需逐步清理）
- 单元测试全部通过
- 集成测试全部通过
- 类型检查通过（前端 TypeScript strict mode）

### 6.2 数据库变更规则

- 所有 Schema 变更必须通过 migration 脚本，禁止手动执行 DDL
- 每个 migration 必须有对应的 rollback 脚本
- 破坏性变更（删列、改类型、删表）必须分阶段执行：
  1. 先部署代码兼容新旧 Schema
  2. 执行 migration
  3. 清理兼容代码
- 大表变更必须评估锁表时间，超过 5 秒的变更需要使用 online DDL 工具

### 6.3 API 兼容性

- API 变更必须向后兼容，通过 `X-API-Version` header 区分版本
- 废弃接口标记 `@Deprecated`，保留至少一个版本周期后才能删除
- 新增字段默认可选（nullable 或有默认值），不破坏现有调用方
- 删除字段先标记废弃，下个版本才实际移除

### 6.4 依赖管理

- 依赖升级必须在独立 PR 中进行，不混合业务变更
- 使用精确版本号（不用 `^` 或 `~`），通过 lockfile 锁定
- 新增依赖必须评估：维护活跃度、安全记录、包大小、许可证兼容性
- 禁止引入与现有依赖功能重叠的新包

## 7. 可扩展性保障

### 7.1 模块边界

- 遵循设计文档中定义的 BC 边界和依赖方向（见 `架构-01`）
- 模块间通信只通过定义好的接口，禁止跨模块直接访问内部实现
- 依赖方向：Domain 不依赖 Infrastructure，Application 编排 Domain
- 新增模块前必须在 `架构-01` 中确认其 BC 归属

### 7.2 扩展点设计

- 预留扩展点通过接口/SPI 机制，不通过配置爆炸
- 不为单次使用做过度抽象（YAGNI）
- 扩展点必须有至少一个真实使用场景才能引入
- 策略模式、模板方法等设计模式的使用必须注释其扩展意图

### 7.3 复用优先

- 新增功能前先检查是否有现有抽象可复用
- 跨模块的通用能力提取到 framework 层
- 业务特有逻辑留在业务模块内，不过早泛化

## 8. 可维护性保障

### 8.1 代码自解释 + 注释双保险

- 代码结构和命名做到自解释（what）
- 中文注释补充意图和决策（why）
- 两者互补，不互相替代

### 8.2 设计文档对应

- 复杂流程（涉及 3 个以上模块协作）必须有对应的设计文档
- 设计文档在 muse-design-docs 仓维护，实现代码中注释引用文档路径
- 格式：`// 设计文档：muse-design-docs/后端-03-关键流程实现与接口契约.md#章节名`

### 8.3 模块 README

每个顶层模块目录下必须有 README.md，说明：
- 模块职责（一句话）
- 边界（负责什么、不负责什么）
- 依赖关系（依赖谁、被谁依赖）
- 关键入口（主要的 Service / Controller / Component）

### 8.4 代码卫生

- 废弃代码及时清理，不留 dead code
- TODO 必须标注负责人和预期处理时间：`// TODO(zizi): 2026-06 迁移到新接口后删除`
- 注释掉的代码禁止提交（用 git 管理历史）
- 临时调试代码（console.log、System.out.println）禁止提交

## 9. Agent 通用行为规则

### 9.1 先读后写

- 修改前必须读取相关代码理解上下文
- 理解现有模式后再动手，不凭假设编码
- 检查是否有现有的工具方法、常量、类型可复用

### 9.2 最小变更

- 只改当前任务直接相关的代码
- 不顺手重构无关的命名、格式、注释
- 不为改善代码风格而扩大变更范围
- 一个 PR 只做一件事

### 9.3 验证闭环

- 改完必须运行测试验证
- 无法运行测试时说明原因和替代验证方式
- 验证通过后才能声称"已完成"
- 验证失败时修复后重新验证，不跳过

### 9.4 失败处理

- 同一方法失败两次，停下来分析根因
- 分析后换方向，不做第三次相同尝试
- 记录失败原因和新方向的选择理由

### 9.5 安全意识

- 不硬编码密钥、token、密码
- 不跳过权限检查
- 不信任前端输入（所有输入必须后端校验）
- 不在日志中输出敏感信息
- SQL 必须使用参数化查询，禁止字符串拼接
- 文件操作必须校验路径，防止路径穿越

### 9.6 幂等与容错

- 涉及外部服务调用时，必须考虑超时和重试
- 涉及异步任务时，必须考虑失败补偿
- 涉及支付/通知时，必须保证幂等性
- 涉及文件操作时，必须考虑部分写入和清理

### 9.7 上下文管理

- 大任务主动拆分为可独立验证的子任务
- 每个子任务完成后评估是否需要留痕
- 恢复任务时先读 memorys 和 git log，不从零开始
- 不在单次会话中尝试完成超出上下文窗口的工作量