AI 项目开发规范体系设计指南：三层金字塔 + 10 条红线 + 11 领域规范
AI 项目最乱的不是代码写得差——是传统软件工程规范根本不覆盖 AI 项目特有的问题。Prompt 版本怎么管？LLM 调用日志要记哪些字段？SSE 流式中断了怎么恢复？GPU 资源调度规范怎么写？这些问题传统规范模板里一个都没有。做了 PrismAI（多应用 AI 中台，4 个服务 Java+Python 异构）一年，我把踩过的坑全提炼成了这套三层金字塔——10 条开发红线 + 11 个领域详细规范 + 自动化 Hook 守卫。每条红线都是在实际踩坑后补上的，可直接复制到你的项目。
阅读约 15 分钟 | 系列扩展篇
一、为什么 AI 项目需要"不一样的"开发规范
传统软件项目的规范聚焦于代码风格、测试覆盖、CI/CD 流水线。AI 项目在此基础上叠加了独特的复杂度：
| 维度 | 传统项目 | AI 项目额外挑战 |
|---|---|---|
| 架构 | 单体/微服务，确定性输入输出 | 多模型协作、GPU 资源调度、推理管线 |
| 数据流 | OLTP/OLAP，确定性查询 | 向量检索 + 关键词检索混合、嵌入模型管理、文档解析流水线 |
| 通信 | REST/gRPC，毫秒级超时 | SSE 流式长连接（分钟级）、MCP 工具调用、Agent 编排 |
| 可观测性 | 请求/响应日志 | Token 消耗追踪、模型推理耗时、RAG 召回率 |
| 开发流程 | 代码→编译→测试 | + 模型下载/缓存 + Prompt 版本管理 + 向量索引重建 |
| 降级策略 | 熔断、限流 | LLM 不可用→降级为非 AI 响应、Milvus 不可用→跳过 RAG |
核心结论：AI 项目的规范体系需要在传统软件工程纪律之上，叠加 AI 特有的架构约束和容错策略。
二、规范体系架构：三层金字塔模型
经过多轮迭代，最有效的结构是 三层金字塔：
┌──────────────┐
│ 开发红线 │ ← "宪法"——绝对禁止事项，Code Review 一票否决
│ (10 条) │
├──────────────┤
│ 详细规范 │ ← "法律"——每个领域的具体操作标准
│ (11 个文件) │
├──────────────┤
│ 自动化守卫 │ ← "警察"——Hook/Skill 自动拦截违规
│ (Hook+State) │
└──────────────┘
2.1 第一层：开发红线 —— 宪法
红线文件是规范体系的最高优先级文档。每条都是不可违反、不可豁免、不可推后的绝对禁令，Code Review 时命中即一票否决。
每条红线的标准格式：
## 一、红线名称
**原则**：一句话说明为什么
### 禁止
// ❌ 红线违规（附带具体代码示例）
### 正确做法
// ✅ 正确（附带对应修正代码）
**铁律**：
- 具体可检查的规则
10 条红线的设计逻辑：
| # | 红线 | 覆盖维度 | 设计意图 |
|---|---|---|---|
| 1 | 魔法数字零容忍 | 可读性 | 代码即文档——6 个月后的自己必须能读懂 |
| 2 | 配置强制外部化 | 可维护性 | 环境差异收敛到配置，不在代码中 if env==prod |
| 3 | 异常处理结构化 | 兼容性 | 错误响应格式统一，前端/网关/监控都能解析 |
| 4 | 日志与 SQL 调试分离 | 可观测性 | 生产不泄露 SQL/DEBUG，同时保留排查能力 |
| 5 | 代码结构层级纪律 | 可维护性 | Domain 层零框架依赖，依赖方向不可逆 |
| 6 | 安全不可妥协 | 安全性 | SQL 注入/Sensitive Data 泄漏 → 零容忍 |
| 7 | API 契约不可打破 | 兼容性 | 响应格式/分页参数/owner_id 提取全应用统一 |
| 8 | DDL 先行与索引强制 | 可靠性 | 表结构有审计记录，外键不缺索引 |
| 9 | 无测试不合并 | 可靠性 | 新增 Public 方法无测试 → Code Review 直接拒 |
| 10 | Git 提交纪律 | 可追溯性 | Conventional Commits → 自动化 CHANGELOG |
关键设计：Enum > Constants >
@ConfigurationProperties。枚举类型安全、编译期校验；字符串常量"SUCCESS"拼写错误到运行时才发现——这是多数项目缺失的优先级指导。
2.2 第二层：详细规范 —— 法律
详细规范是领域-specific 的操作标准，共 11 个文件：
| 文件 | 职责 | 关键内容 |
|---|---|---|
architecture.md | 架构边界与通信 | DDD+六边形架构、服务间通信矩阵（含超时/重试/TraceID） |
maven-conventions.md | Maven 依赖管理 | 最小引用五原则、根 POM 统一定义版本 |
api-style.md | API 设计 | {code, message, data} 三元组、错误码体系、SSE 规范 |
db-conventions.md | 数据库 | DDL-First 范式、双轨 ID 策略、多态关联 |
ai-conventions.md | AI 能力 | LLM 调用规范、SSE 流式、RAG 流水线、MCP Server 管理 |
frontend-conventions.md | 前端 | Vue 3 Composition API、Pinia Store、SSE 消费 |
git-conventions.md | Git | Conventional Commits、分支命名、操作权限分级 |
error-handling.md | 异常处理 | 4 分支 9 类异常层级、各层抛出规则 |
testing-conventions.md | 测试 | 测试金字塔（Unit 70%/Integration 25%/E2E 5%） |
logging-conventions.md | 日志 | 键值对格式、敏感数据保护、LLM 必记字段 |
coding-red-lines.md | 红线 | 10 条红线详细说明 + 速查表 |
文件规模设计：核心文件 500-670 行（覆盖大主题但每个子节独立可读），常规文件 140-270 行（单一主题，读完只需 5-10 分钟）。超过 700 行时触发拆分。
2.3 第三层：自动化守卫 —— 警察
规范写得再好，没有自动拦截就是纸老虎。两道防线：
防线一：CLAUDE.md 触发词自检
用户消息 → 扫描关键词（实现/修改/新增功能）
→ 命中 → 强制执行 implement-feature 五阶段工作流
→ 未命中 → 正常对话
防线二：Pre-edit Hook 阶段守卫
编辑核心文件前：
1. 读取 workflow.json 的 active 和 phase 字段
2. active != true → 空闲态，放行所有编辑
3. active == true && phase < 2 → 拒绝（尚未进入编码阶段）
4. active == true && phase >= 2 → 放行
设计关键：必须有"空闲态"概念。如果工作流完成后不清除状态，下次正常修改会被拦截——Hook 就从"守卫"变成了"障碍"。
三、AI 项目特有的六大架构决策
3.1 DDD + 六边形架构 —— 为什么 AI 项目尤其需要
AI 项目的外部依赖远比传统项目多且不稳定：
传统项目依赖：Database + Cache + MQ
AI 项目依赖：Database + Cache + LLM API + Embedding Model + Vector DB + MCP Server + GPU
六边形架构的核心价值在于 Domain 层零外部依赖。当 LLM Provider 从 DeepSeek 切换到 GLM、当 Milvus 升级索引类型、当 MCP Server 从 stdio 改为 SSE——这些变化只影响 Infrastructure 层，Domain 层的业务规则完全不感知。
Interfaces (FastAPI Router)
│
▼
Application (Use Case 编排)
│
▼
Domain (纯业务规则 — 零外部依赖)
│
▲
Infrastructure (LLM Client / Vector DB / MCP Runner)
关键纪律：
- Domain 层 import 中搜不到
fastapi/sqlalchemy/openai/pymilvus - 所有外部 SDK 调用封装在 Infrastructure 层的 Adapter 中
- Application 层只依赖 Domain 定义的接口（Port），不依赖具体实现
3.2 双轨 ID 策略
AI 项目中常见多语言异构系统（Java + Python）。ID 策略必须由语言和存储引擎决定，不能一刀切：
| 应用 | 语言 | ID 类型 | 原因 |
|---|---|---|---|
| 平台门户 | Java | BIGINT AUTO_INCREMENT | JPA 默认，B-Tree 插入性能最优 |
| AI 中台 | Python | VARCHAR(50) 前缀格式（pt_xxx） | JWT sub 是字符串，跨服务引用无需转换 |
| 图像中台 | Python | VARCHAR(50) 前缀格式（proj_xxx） | 同上 |
前缀规则让 ID 本身携带类型信息——看到 pt_abc123 就知道是 Prompt 模板，无需查表。
3.3 服务间通信矩阵 —— AI 长连接场景的挑战
AI 项目的通信场景远比传统项目复杂：
| 通信方向 | 协议 | 超时 | 重试 | 特殊处理 |
|---|---|---|---|---|
| 平台→AI 中台（查列表） | REST | 5s | 2次 | Redis 缓存 5min |
| 平台→AI 中台（资源授权） | REST | 5s | 1次 | 写操作不缓存 |
| 考试→AI 中台（对话） | REST/SSE | 60s | 0次 | SSE 长连接不重试 |
| AI Agent→图像中台 | MCP SSE | 30s | 0次 | 图像生成工具调用 |
核心原则：拉/查/搜 → 缓存；改/删/写 → 不缓存；流式 → 不缓存不重试（Nginx proxy_buffering off）。
3.4 Trace ID 全链路传播
多应用 + 多服务 + 异步调用 = 必须有 Trace ID：
[Hub] trace_id=hub-001-abc
→ [Beam] trace_id=hub-001-abc (沿用)
→ [LLM API] trace_id=hub-001-abc (沿用)
→ 所有日志行包含 trace_id
实现：接收方检查 X-Trace-Id 请求头 → 有则沿用，无则生成。Java 用 Filter + MDC，Python 用 Middleware + ContextVar。
3.5 共享包：跨应用中台复用
当两个中台需要相同能力时，抽取到 shared/ 而非各自实现：
| 包 | 语言 | 用途 |
|---|---|---|
shared/prism-auth/ | Python | FastAPI JWT 认证中间件（可插拔 Provider） |
shared/prism-review/ | Python | 策略模式审核服务 |
shared/prism-ui-shared/ | Vue 3 | 共享组件（ResourceList/ReviewQueue/VisibilityBadge） |
3.6 应用启动依赖顺序
多应用平台的启动有严格的拓扑依赖：
1. Infrastructure: MySQL, Redis, Nacos, Milvus, MinIO
│
2. Hub (8080) ← 其他应用认证依赖 Hub
│
3. Beam (8000), Canvas (8001) ← 可并行启动
│
4. Drill (8081) ← 依赖 Beam 就绪
关键策略：Drill 启动时检查 Beam /health，不可用时记录 WARN 但不阻塞启动——降级为 AI_SERVICE_UNAVAILABLE。Beam Agent → Canvas MCP 是可选依赖：Canvas 不可用时 Beam 仍可处理纯文本对话。
四、DDL-First 开发范式 —— AI 项目最易忽视的纪律
AI 项目常因"快速实验"心态而跳过数据库设计。DDL-First 强制在写代码前先定义表结构：
收到需求 → ① 写 DDL SQL → ② DDL 评审通过 → ③ 写 Entity/Model → ④ 写 Repository → ⑤ 写 Service
为什么：
- DDL 是 Schema 的唯一真源——JPA
ddl-auto: update生成的表可能缺索引/约束 - 每次变更有可审计的 SQL diff——Code Review 时直接看表结构变化
- 多环境一致性——dev/staging/prod 执行同一套 SQL
DDL 编写铁律：
- 所有建表语句包含
ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 - 外键列必须有索引（MySQL 不会自动建）
- 使用
CREATE TABLE IF NOT EXISTS（幂等可重复执行） - 表注释 + 字段注释完整
五、AI 场景特有的代码规范
5.1 LLM 调用必记字段
每次 LLM 调用必须在 INFO 级别记录：
[Beam] LLM 调用完成 | model=deepseek-chat | prompt_tokens=340 | completion_tokens=80 | total_tokens=420 | latency_ms=2300
SSE 流式场景分两次记录（流开始 + 流结束），确保即使流中断也能知道消耗了多少 Token。
5.2 SSE 7 种事件类型标准化
# ✅ 标准 SSE 流式返回
async def event_generator():
try:
async for chunk in llm_client.stream(messages):
yield f"event: delta\ndata: {json.dumps({'content': chunk})}\n\n"
yield f"event: done\ndata: {json.dumps({'total_tokens': total})}\n\n"
except asyncio.TimeoutError:
yield f"event: error\ndata: {json.dumps({'code': 'LLM_TIMEOUT', 'message': '...'})}\n\n"
finally:
release_connection() # ← 必须在 finally 中释放
事件类型：delta | tool_call | tool_result | sources | done | error | resume
5.3 RAG 混合检索流水线
文档上传 → 解析(PDF/Word/MD/TXT) → 语义分块(chunk=500, overlap=50)
→ 嵌入向量(bge-large-zh-v1.5, dim=1024)
→ Milvus 存储(IVF_FLAT, nlist=128, metric=IP)
检索：用户问题 → 向量化 → Milvus Top-K
→ BM25 关键词检索(并行)
→ 加权融合(向量 0.7 + BM25 0.3) → 返回 Top-N
5.4 降级策略标准化
AI 项目的降级比传统项目更复杂且更关键：
| 场景 | 策略 | 日志格式 |
|---|---|---|
| LLM API 超时 | 返回友好错误 + 记录完整上下文 | ERROR [Beam] LLM API 不可用（3次重试全部失败） |
| Milvus 不可用 | 跳过 RAG，仅用 LLM 训练数据 | WARN [降级] Milvus 不可用 → 跳过 RAG |
| 嵌入模型 OOM | 降级为 CPU-only 推理 | WARN [降级] GPU OOM → 切换 CPU 推理 |
| MCP Server 崩溃 | 自动重启最多 3 次 | WARN [降级] MCP Server 重启 | retry=2/3 |
降级日志统一格式：WARNING [降级] {原因} | {降级路径} | {影响范围} | {恢复条件}
六、Git 工作流 —— AI 项目特别需要 Conventional Commits
AI 项目的 Commit 混杂模型配置、Prompt 调整、代码逻辑变更。Conventional Commits 强制区分变更类型：
feat(beam-chat): 实现 SSE 流式对话接口
fix(hub-auth): 修复 JWT 刷新时旧 Token 未加入黑名单
refactor(beam-rag)!: 重构检索接口，返回格式改为 DTO ← ! 表示 BREAKING CHANGE
chore(beam-config): 调整 LLM 默认模型为 deepseek-v4
AI 项目 Scope 设计（22 个 scope）：应用粒度（hub/beam/canvas/drill）、模块粒度（beam-chat/beam-rag/beam-prompt/beam-mcp）、共享包（shared/infra/docs/deps）。
七、规范体系的四阶段演进路径
| 阶段 | 核心任务 | 里程碑 |
|---|---|---|
| 一：骨架期 | 规范先行于代码，红线+核心 Rules+Hook 到位 | 16 个文件，~4,100 行 |
| 二：开发期 | 按 implement-feature 五阶段执行，纠错记录持续追加 | 每 3-5 个 Feature 评估是否新增红线 |
| 三：CI/CD 接入 | checkstyle/ruff/eslint + commitlint + husky | 红线 #1 #4 #5 #10 自动化检查上线 |
| 四：稳定运营 | 红线演进为团队肌肉记忆，新人 Onboarding 从 CLAUDE.md 开始 | 每季度评估规范是否需要更新 |
核心要点回顾
AI 项目需要"不一样的"规范——传统规范的六维度差异（架构/数据流/通信/可观测性/开发流程/降级策略）决定了不能简单套用模板。
三层金字塔模型是经过验证的结构：10 条开发红线作为"宪法"（Code Review 一票否决），11 个领域详细规范作为"法律"（架构/Maven/API/数据库/AI/前端/Git/异常/测试/日志/红线），Hook+Skill 自动化守卫作为"警察"（触发词自检 + 工作流阶段守卫）。
六大架构决策是 AI 项目特有的：① DDD+六边形架构保证 Domain 层零外部依赖（LLM Provider 切换只改 Infrastructure 层）；② 双轨 ID 策略按语言选型（Java→BIGINT 自增，Python→VARCHAR 前缀）；③ 通信矩阵区别对待 SSE 长连接（60s 超时/0 次重试/不缓存）；④ TraceID 全链路传播（跨 Java+Python）；⑤ 共享包跨应用中台复用（prism-auth/prism-review/prism-ui-shared）；⑥ 启动依赖拓扑顺序（Infra→Hub→Beam/Canvas→Drill）。
DDL-First + 降级标准化 + Conventional Commits 是三个最容易被忽视但最重要的纪律——DDL 是 Schema 唯一真源、降级日志统一格式、AI 项目尤其需要区分模型配置变更和代码逻辑变更。
AI 项目开发规范不是"把传统规范加几条 AI 条款"——是在代码、Prompt、模型三个版本维度上重建体系。这套三层金字塔模板在 PrismAI 上跑了完整开发周期，收藏下来下次新开 AI 项目直接套用。
