---
source: ../../../core/ai-friendly-architecture.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-04-22
status: current
---

# AI 友好架构标准

> **语言**: [English](../../../core/ai-friendly-architecture.md) | 简体中文

**版本**: 1.0.0
**最后更新**: 2026-01-21
**适用范围**: 所有与 AI 助手协作的软件项目

---

## 目的

本标准定义能最大化 AI 辅助开发效能的架构与文档实践。遵循这些指南，项目将更容易被 AI 工具分析、理解和修改，同时保持人类可读性。

**参考概念**:
- RLM（递归语言模型）上下文管理原则
- 考虑 Token 的文档设计
- 支持 AI 理解的模块化架构

---

## 目录

1. [核心原则](#核心原则)
2. [模块设计标准](#模块设计标准)
3. [上下文边界标记](#上下文边界标记)
4. [文档分层](#文档分层)
5. [元数据标准](#元数据标准)
6. [查询接口设计](#查询接口设计)
7. [AI 上下文配置](#ai-上下文配置)
8. [反模式](#反模式)
9. [实施清单](#实施清单)

---

## 核心原则

### 1. 明确胜过隐含

AI 助手在行为和结构明确记录时表现最佳，而非依赖惯例推测。

```
┌─────────────────────────────────────────────────────────────┐
│                   明确 vs 隐含                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ❌ 隐含（AI 难以理解）                                      │
│  └── 魔术命名惯例                                            │
│  └── 未记录的文件夹结构                                      │
│  └── 基于惯例的路由                                          │
│  └── 假定框架行为已知                                        │
│                                                              │
│  ✅ 明确（AI 友好）                                          │
│  └── 记录模块职责                                            │
│  └── 清楚标注进入点                                          │
│  └── 明确声明依赖关系                                        │
│  └── 自我说明的配置文件                                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 2. 分层上下文

以层次结构组织文档，让 AI 可以根据任务复杂度存取适当的详细程度。

```
┌─────────────────────────────────────────────────────────────┐
│                  上下文分层策略                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  第一层：快速参考（< 500 tokens）                            │
│  └── 单行描述                                                │
│  └── 仅 API 签名                                             │
│  └── 关键进入点                                              │
│                                                              │
│  第二层：详细指南（< 5,000 tokens）                          │
│  └── 完整 API 文档                                           │
│  └── 使用范例                                                │
│  └── 配置选项                                                │
│                                                              │
│  第三层：完整范例（无限制）                                  │
│  └── 完整实现范例                                            │
│  └── 边界案例文档                                            │
│  └── 迁移指南                                                │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 3. 语义边界

设计清楚的模块边界，让 AI 可以独立分析组件，而不需要完整项目上下文。

### 4. 可探索的结构

确保项目结构可以通过分析配置文件和进入点来理解，而不需阅读所有源代码。

---

## 模块设计标准

### 模块级别单一职责

每个模块应有明确定义的单一目的，可以用一句话总结。

```
┌─────────────────────────────────────────────────────────────┐
│                   模块头部模板                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  /**                                                         │
│   * @module auth                                             │
│   * @description 处理应用程序的用户验证和                    │
│   *              Session 管理。                              │
│   *                                                          │
│   * @responsibility 验证和授权                               │
│   * @dependencies [database, crypto, config]                │
│   * @exports {login, logout, verify, refreshToken}          │
│   * @entrypoint ./index.ts                                  │
│   */                                                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 清楚的输入/输出契约

每个公开接口都应有明确的类型定义或文档说明。

| 元素 | 要求 | 范例 |
|------|------|------|
| 函数参数 | 类型 + 描述 | `@param {string} email - 用户电子邮件` |
| 返回值 | 类型 + 可能值 | `@returns {Promise<User \| null>}` |
| 副作用 | 明确记录 | `@sideeffect 写入数据库` |
| 错误条件 | 所有可能错误 | `@throws {AuthError} 无效凭证` |

### 明确的依赖声明

依赖应在模块级别声明，而非隐藏在实现细节中。

---

## 上下文边界标记

### 模块头部注释

使用 AI 可以解析的标准化头部注释，快速理解模块。

```javascript
/**
 * ═══════════════════════════════════════════════════════════
 * 模块：付款处理
 * ═══════════════════════════════════════════════════════════
 *
 * 用途：处理所有付款相关操作，包括
 *       处理、退款和订阅管理。
 *
 * 依赖：
 *   - stripe: 付款网关集成
 *   - database: 交易存储
 *   - events: 付款事件发布
 *
 * 导出：
 *   - processPayment(amount, method): 处理单笔付款
 *   - refund(transactionId): 发出退款
 *   - createSubscription(plan): 开始订阅
 *
 * ═══════════════════════════════════════════════════════════
 */
```

---

## 文档分层

### 第一层：快速参考（< 500 tokens）

在每个主要模块创建 `QUICK-REF.md`：

```markdown
# Auth 模块 - 快速参考

## 用途
用户验证和 Session 管理。

## 关键函数
- `login(email, password)` → `Promise<Session>`
- `logout(sessionId)` → `void`
- `verify(token)` → `Promise<User | null>`

## 配置
- `AUTH_SECRET`: JWT 签名密钥
- `SESSION_DURATION`: Session 生命周期（默认：24h）

## 进入点
`src/auth/index.ts`
```

### 第二层：详细指南（< 5,000 tokens）

主要 `README.md` 包含完整文档。

### 第三层：完整范例（无限制）

独立的 `examples/` 目录包含完整实现。

---

## 元数据标准

### .ai-context.yaml 配置

专用的 AI 上下文配置文件：

```yaml
# .ai-context.yaml - AI 上下文配置
version: 1.0.0

project:
  name: my-project
  type: web-app  # web-app | library | cli | api | monorepo
  primary-language: typescript

modules:
  - name: auth
    path: src/auth/
    entry: index.ts
    description: 验证和授权
    dependencies: [database, crypto]
    priority: high

analysis-hints:
  entry-points:
    - src/main.ts
  ignore-patterns:
    - node_modules
    - dist

context-strategy:
  max-chunk-size: 50000
  overlap: 500
  analysis-pattern: hierarchical
```

---

## 反模式

### ❌ 应避免的模式

| 反模式 | 问题 | 解决方案 |
|--------|------|----------|
| **魔术字符串** | AI 无法追踪常量 | 使用有文档的类型常量 |
| **隐含路由** | 隐藏行为 | 明确记录路由映射 |
| **全局状态** | 不可预测的依赖 | 依赖注入，明确连接 |
| **循环依赖** | 上下文混乱 | 清楚的层次依赖 |
| **巨大文件** | 上下文溢出 | 分割成专注的模块 |

---

## 实施清单

### 快速开始（< 1 小时）

- [ ] 创建 `.ai-context.yaml` 包含模块清单
- [ ] 在项目根目录新增 `QUICK-REF.md`
- [ ] 在 README 中记录进入点
- [ ] 在主要文件中新增模块头部

### 标准实施（< 1 天）

- [ ] 完成 `.ai-context.yaml` 配置
- [ ] 为每个主要模块新增 `QUICK-REF.md`
- [ ] 记录所有公开 API 的类型信息
- [ ] 在大型文件中新增区段分隔
- [ ] 创建依赖文档

### 完整实施（< 1 周）

- [ ] 所有模块的三层文档
- [ ] 可搜索的代码注释
- [ ] 使用案例的范例目录
- [ ] 架构图
- [ ] 集成 CI 进行文档验证

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-01-21 | 初始版本 |

---

## 相关标准

- [项目结构](./project-structure.md) - 目录组织
- [文档结构](./documentation-structure.md) - 文档组织
- [反幻觉](./anti-hallucination.md) - AI 准确性标准

---

## 许可

本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。

**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
