传统开发规范在AI项目上全废了——做了PrismAI一年，我理出了这套10条红线+11领域规范的三层金字塔

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 特有的架构约束和容错策略。

二、规范体系架构：三层金字塔模型

经过多轮迭代，最有效的结构是 三层金字塔：

arduino 复制代码

                    ┌──────────────┐
                    │  开发红线     │  ← "宪法"------绝对禁止事项，Code Review 一票否决
                    │  (10 条)     │
                    ├──────────────┤
                    │  详细规范     │  ← "法律"------每个领域的具体操作标准
                    │  (11 个文件)  │
                    ├──────────────┤
                    │  自动化守卫   │  ← "警察"------Hook/Skill 自动拦截违规
                    │  (Hook+State) │
                    └──────────────┘

2.1 第一层：开发红线 ------ 宪法

红线文件是规范体系的最高优先级文档。每条都是不可违反、不可豁免、不可推后的绝对禁令，Code Review 时命中即一票否决。

每条红线的标准格式：

markdown 复制代码

## 一、红线名称
**原则**：一句话说明为什么

### 禁止
// ❌ 红线违规（附带具体代码示例）

### 正确做法
// ✅ 正确（附带对应修正代码）

**铁律**：
- 具体可检查的规则

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 触发词自检

markdown 复制代码

用户消息 → 扫描关键词（实现/修改/新增功能）
         → 命中 → 强制执行 implement-feature 五阶段工作流
         → 未命中 → 正常对话

防线二：Pre-edit Hook 阶段守卫

bash 复制代码

编辑核心文件前：
  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 项目的外部依赖远比传统项目多且不稳定：

arduino 复制代码

传统项目依赖：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 层的业务规则完全不感知。

scss 复制代码

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：

ini 复制代码

[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 应用启动依赖顺序

多应用平台的启动有严格的拓扑依赖：

markdown 复制代码

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 强制在写代码前先定义表结构：

sql 复制代码

收到需求 → ① 写 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 级别记录：

ini 复制代码

[Beam] LLM 调用完成 | model=deepseek-chat | prompt_tokens=340 | completion_tokens=80 | total_tokens=420 | latency_ms=2300

SSE 流式场景分两次记录（流开始 + 流结束），确保即使流中断也能知道消耗了多少 Token。

5.2 SSE 7 种事件类型标准化

python 复制代码

# ✅ 标准 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 中释放

5.3 RAG 混合检索流水线

scss 复制代码

文档上传 → 解析(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 重启

降级日志统一格式：WARNING [降级] {原因} | {降级路径} | {影响范围} | {恢复条件}

六、Git 工作流 ------ AI 项目特别需要 Conventional Commits

AI 项目的 Commit 混杂模型配置、Prompt 调整、代码逻辑变更。Conventional Commits 强制区分变更类型：

scss 复制代码

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 项目直接套用。
上一篇 ：《我与AI的一次思考》（番外） | 🎉 系列完结 系列合集 ：掘金AI合集 配套代码 ：PrismAI