“演示是一个文件。生产是这个。”
当你从原型迈向生产级应用时，代码复杂度会指数级增长。这张架构图揭示了一个完整的 AI 生产系统所需的核心层次。
一层：Services（服务层）#
职责：核心 AI 管道的模块化构建块
1
2
3
4
5
6
| services/
├── RAG pipeline # 检索增强生成管道
├── semantic cache # 语义缓存
├── memory # 记忆系统
├── query rewriter # 查询重写器
└── router # 路由器
|
关键认知：不是单个文件，而是五个独立服务。
语义缓存可以避免重复计算，记忆系统保存对话上下文，RAG 管道负责知识检索，查询重写器优化用户意图表达，路由器智能分发请求。
二层：Agents（智能体层）#
职责：自主决策与自我纠正
1
2
3
4
| agents/
├── document grader # 文档评分器
├── decomposer # 任务分解器
└── adaptive router # 自适应路由器
|
设计原则：Self-correcting by design（设计即自我纠正）
文档评分器过滤低质量内容，分解器将复杂查询拆解为可处理的子任务，自适应路由器根据上下文动态选择最佳路径。
三层：Prompts（提示层）#
职责：提示词的管理与版本控制
1
2
3
4
| prompts/
├── versioned # 版本化
├── typed # 类型化
└── registered # 注册
|
核心原则：Never hardcoded（永不硬编码）
所有提示词都需要版本控制以便回滚，类型化确保参数传递安全，注册机制实现统一管理和可发现性。
四层：Security（安全层）#
职责：多层防护保障系统安全
1
2
3
4
| security/
├── input guard # 输入守卫
├── content guard # 内容守卫
└── output guard # 输出守卫
|
关键洞察：Three guards not one（三个守卫而非一个）
- 输入守卫：过滤恶意注入、限制令牌长度、防止 prompt injection
- 内容守卫：检测有害内容、版权风险、敏感信息
- 输出守卫：格式化验证、质量检查、合规性审查
五层：Evaluation（评估层）#
职责：全面评估模型性能
1
2
3
4
| evaluation/
├── golden dataset # 金色数据集
├── offline eval # 离线评估
└── online monitor # 在线监控
|
残酷现实：Most people skip this entire layer and ship blind.
- 金色数据集：高质量标注数据，用于回归测试
- 离线评估：持续集成中验证模型更新
- 在线监控：生产环境实时追踪指标
六层：Observability（可观测性层）#
职责：深度可见性与成本控制
1
2
3
4
| observability/
├── per-stage tracing # 每阶段追踪
├── feedback linked # 反馈关联追踪
└── cost per query # 每查询成本
|
核心能力：
- 追踪每个处理阶段的延迟与准确性
- 将用户反馈与具体 trace 关联
- 精确计算每次查询的成本，优化 ROI
七层：.claude/（代理上下文层）#
职责：为 AI 编程助手提供项目上下文
1
2
| .claude/
└── agent context
|
目的：让 AI 编码助手在修改文件之前充分理解代码库
包括架构文档、编码规范、依赖关系，确保 AI 生成的代码符合项目约定。
架构全景图#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
| ┌─────────────────────────────────────────────────────┐
│ User Interface │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 1. Services (RAG/Cache/Memory) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 2. Agents (Grader/Decomposer) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 3. Prompts (Versioned/Typed) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 4. Security (Input/Content/Output) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 5. Evaluation (Golden/Offline/Online) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 6. Observability (Tracing/Cost) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 7. .claude/ (Agent Context) │
└─────────────────────────────────────────────────────┘
|
从原型到生产的跨越#
| 维度 | 原型（Demo） | 生产（Production） |
|---|
| 代码组织 | 单文件 | 九层架构 |
| Prompt 管理 | 硬编码 | 版本化注册 |
| 安全 | 忽略 | 三层防护 |
| 评估 | 无 | 金数据集+在线监控 |
| 可观测性 | 无 | 全链路追踪 |
| 自我纠正 | 无 | 内置机制 |
从 1 个文件到 9 层架构，这是 AI 应用从"能跑"到"能打"的必经之路。每一层都有其不可替代的价值：
- Services 提供模块化能力
- Agents 实现智能决策
- Prompts 确保可维护性
- Security 保障系统安全
- Evaluation 验证产品质量
- Observability 实现深度可见
.claude/ 让 AI 理解自身
当你准备发布一个 AI 应用时，问自己：我的架构完整吗？