AI Friendly Architecture

AI 友善架构指南

语言: English | 简体中文

版本: 1.0.0 最后更新: 2026-01-25 适用范围: Claude Code Skills

核心标准: 本技能实现 AI 友善架构。完整方法论文档请参阅核心标准。

目的

本技能协助设计项目架构，通过明确模式、分层文档和语义边界，最大化 AI 协作效能。

快速参考

核心原则

上下文层级

建议结构

project/
├── .ai-context.yaml          # AI 上下文配置
├── docs/
│   ├── QUICK-REF.md          # 第 1 层文档
│   └── ARCHITECTURE.md       # 第 2 层文档
├── src/
│   └── auth/
│       ├── index.ts          # 入口点与模块头部
│       ├── QUICK-REF.md      # 模块快速参考
│       └── README.md         # 模块文档
└── CLAUDE.md                 # AI 指令文件

模块头部模板

/**
 * ═══════════════════════════════════════════════════════════
 * 模块: [模块名称]
 * ═══════════════════════════════════════════════════════════
 *
 * 目的: [单句描述]
 *
 * 依赖:
 *   - [dep1]: [原因]
 *   - [dep2]: [原因]
 *
 * 导出:
 *   - [function1](params): [描述]
 *   - [function2](params): [描述]
 *
 * 配置:
 *   - [CONFIG_VAR]: [描述]
 *
 * ═══════════════════════════════════════════════════════════
 */

详细指南

完整标准请参阅：

• AI 友善架构标准

AI 优化格式（Token 效率）

AI 助手可使用 YAML 格式文件以减少 Token 使用：

• 基础标准：ai/standards/ai-friendly-architecture.ai.yaml

.ai-context.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

  - name: api
    path: src/api/
    entry: routes.ts
    description: REST API 端点
    dependencies: [auth, database]
    priority: high

analysis-hints:
  entry-points:
    - src/main.ts
    - src/index.ts
  ignore-patterns:
    - node_modules
    - dist
    - "*.test.ts"
  architecture-type: layered

documentation:
  quick-ref: docs/QUICK-REF.md
  detailed: docs/ARCHITECTURE.md
  examples: docs/examples/

上下文优先顺序指南

应避免的反模式

实现检查清单

快速开始（< 1 小时）

• 创建 .ai-context.yaml 含模块清单
• 在项目根目录添加 QUICK-REF.md
• 在 README 中记录入口点
• 为主要文件添加模块头部

标准实现（< 1 天）

• 完成 .ai-context.yaml 配置
• 为每个主要模块添加 QUICK-REF.md
• 记录所有公开 API 及类型信息
• 为大型文件添加区段分隔

配置侦测

本技能支持项目特定配置。

侦测顺序

1. 检查是否存在 .ai-context.yaml
2. 检查是否存在 QUICK-REF.md 文件
3. 若未找到，建议创建 AI 友善结构

首次设置

若未找到配置：

1. 建议：「此项目尚未为 AI 协作进行配置。是否要设置 AI 友善结构？」
2. 创建 .ai-context.yaml 模板
3. 在项目根目录创建 QUICK-REF.md

相关标准

• AI 友善架构 - 核心架构标准
• 项目结构 - 目录组织
• 文档结构 - 文档分层
• 反幻觉 - AI 准确性标准

版本历史

授权

本技能以 CC BY 4.0 授权发布。

来源: universal-dev-standards

Next Steps Guidance | 下一步引導

After /ai-friendly-architecture completes, the AI assistant should suggest:

AI 友善架構指南已掌握。建議下一步 / AI-friendly architecture guide understood. Suggested next steps:

• 執行 /sdd 將 AI 友善架構設計納入正式規格 ⭐ Recommended / 推薦 — 確保架構決策有規格追蹤 / Ensure architecture decisions are tracked in specs
• 建立 .ai-context.yaml 和 QUICK-REF.md — 立即實作 AI 友善結構 / Implement AI-friendly structure immediately
• 執行 /ai-instruction-standards 更新 CLAUDE.md 以反映架構配置 — 讓 AI 指令檔案與架構保持同步 / Keep AI instruction files in sync with architecture

Related Standards

• AI-Friendly Architecture - Core architecture standard
• Project Structure - Directory organization
• Documentation Structure - Documentation layering
• Anti-Hallucination - AI accuracy standards

Version History

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards