跳到主要内容

AI 研发基建

问题​

从零开始为一个 50-500 人的研发团队规划和搭建一个企业级可用的 AI 辅助开发环境——包括模型网关、Skill/Subagent/Slash Command 的沉淀和治理、如何把业务代码封装成可复用 Skills、如何让 AI 更"听话"、如何度量效能、如何合规安全、如何循序渐进推广。应该怎么做？

面试速答版

如何为 50-500 人团队搭建企业级 AI 研发基建？ 核心是把「每个人各自用 ChatGPT」升级到「团队有一套可复用、可管控、可度量的能力平台」，分 6 层动手：

  • L1 基础设施：账号认证、密钥管理（Vault）、代码托管、CI/CD。
  • L2 平台：模型网关（计费 / 限流 / 降级 / DLP / 审计）、MCP Server 托管。
  • L3 工具层：Claude Code / Cursor / Copilot 统一订阅与配置下发。
  • L4-L5 能力层：团队共享的 Rules / Skills / Subagents / Slash Commands / Hooks 资产仓。
  • L6 治理：使用规范、培训体系、效能度量（采纳率、成本、ROI）。
  • 推广走小范围试点 → 样板项目 → 然后才是全量推广，避免「建了没人用」。

答案​

一、为什么要做 AI 研发基建​

"每个工程师各自用 ChatGPT" 和 "团队有一套 AI 研发基建" 是两个时代。

没有基建时的典型问题：

  • 💸 成本失控：每人开各自的订阅，公司没法统一议价和控制
  • 🔓 安全风险：公司代码被发到第三方模型、被用于训练的风险
  • 🧩 能力割裂：A 把一个流程的 Prompt 打磨得很好，B 不知道，重复踩坑
  • 📉 质量波动：有人用得好有人用不好，团队交付质量参差
  • 🔍 不可度量：不知道 AI 到底帮了多少忙、花了多少钱
  • 🐢 新人冷启动慢：新人入职要自己摸索 AI 使用方式

AI 研发基建的价值：

价值没有基建有基建
成本每人独立订阅，不可控统一网关，按量计费、自动降级、限流
安全代码随意发第三方内部代理、审计、DLP
能力个人经验不沉淀Skills / Subagents / Slash Commands 团队共享
质量看个人水平强制 Rules + Hook + Review
效能拍脑袋说"AI 挺有用"量化指标：代码采纳率、PR 周期、ROI
新人自己摸索 2-4 周第一天即可用全套能力

二、整体蓝图​

一个完整的企业 AI 研发基建由 6 层 组成：

三、L1 + L2：基础设施 + 平台层​

3.1 模型网关（AI Gateway）​

最重要的一件事：公司内部所有对模型的调用都必须经过统一网关。

网关的核心职责：

  1. 多模型接入：统一 API 调用 Anthropic、OpenAI、Google、DeepSeek、Qwen、自部署模型
  2. 密钥管理：员工永远看不到真实的 API Key，只持有公司发的 Gateway Token
  3. 用量统计：按员工、项目、模型、任务类型统计 token 和花费
  4. 限流降级：防止单人/单进程失控消耗；某个模型不可用自动切到备用
  5. 缓存：Prompt Caching 跨员工共享（公共 system prompt 只缓存一次）
  6. 审计：默认归档元数据、调用摘要、策略命中结果；敏感请求按合规要求脱敏、采样或短期留存
  7. DLP：敏感数据识别和拦截（信用卡号、身份证号、密钥格式）
  8. 路由：按规则路由（如"敏感代码必须走本地模型"）

选型：

方案适用优势劣势
LiteLLM自建首选开源、100+ 模型、生产可用需自己运维
OpenRouter快速启动托管式、一个账单搞定有供应商锁定风险
Portkey企业级可观测性强、插件化付费
Helicone观测为主强大的分析面板网关能力一般
自建大厂定制完全可控研发成本高

推荐起步方案：LiteLLM Proxy + Postgres + Redis。开源、部署一天能跑起来、支持主流模型、有内置用量计费。

3.2 最小可用网关架构​

LiteLLM 配置示例：

模型 ID 会随供应商发布节奏变化

下面的 claude-sonnet-4-6、gpt-5、qwen3-coder 等只是示例命名，真实模型 ID、上下文窗口、Prompt Caching header 要以 Anthropic / OpenAI / Google / 开源模型服务和 LiteLLM 当前文档为准。文档中应该沉淀路由和治理方法，不要把某个时间点的模型名当成长期不变的事实。

litellm.config.yaml
model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: os.environ/ANTHROPIC_KEY
      # 启用 prompt caching（具体 header 以 Anthropic 当前文档为准）
      extra_headers:
        anthropic-beta: prompt-caching-2024-07-31

  - model_name: claude-opus-4-7
    litellm_params:
      model: anthropic/claude-opus-4-7
      api_key: os.environ/ANTHROPIC_KEY

  - model_name: gpt-5
    litellm_params:
      model: openai/gpt-5
      api_key: os.environ/OPENAI_KEY

  - model_name: internal-qwen3-coder
    litellm_params:
      model: openai/qwen3-coder
      api_base: http://internal-qwen-server/v1
      api_key: ignored

# 路由策略
router_settings:
  routing_strategy: simple-shuffle
  retry_policy:
    max_retries: 2
  fallbacks:
    - claude-opus-4-7: [claude-sonnet-4-6]
    - gpt-5: [claude-sonnet-4-6]

# 限流（按员工）
general_settings:
  database_url: os.environ/DB_URL
  master_key: os.environ/LITELLM_MASTER
  max_parallel_requests: 10

# 成本配额
budget_duration: 30d
budget_max_value: 1000  # 美元/月/人，超出自动拦截

员工配置：IDE 里把 ANTHROPIC_BASE_URL 指向公司 Gateway，ANTHROPIC_API_KEY 换成公司发的 Gateway Token。Claude Code、Cursor 都支持自定义 base URL。

3.3 密钥和敏感数据管理​

硬性规则：

  • ❌ 员工永远不直接持有真实的模型 API Key
  • ❌ 真实密钥只存在网关的 secrets manager（Vault、AWS Secrets Manager、1Password Connect）
  • ❌ 员工的 Gateway Token 随入离职自动发放/吊销
  • ❌ Token 有细粒度权限：某人只能用 Sonnet、不能用 Opus，某项目只能用特定模型
  • ✅ Token 绑定 SSO / SCIM / RBAC：按团队、项目、数据密级授予模型权限，离职或转岗自动回收
  • ✅ 审计日志默认脱敏：保存 request id、用户、项目、模型、token、策略命中、成本，不默认长期保存完整代码上下文

DLP 规则示例：

正则 DLP 只能作为第一道门

生产环境不要只靠正则。企业级 DLP 还应包含结构化识别、密钥熵检测、上下文规则、响应脱敏、误报申诉、审计留存周期和人工审批流程。命中高风险内容时，可以选择阻断、脱敏后放行，或路由到私有模型。

gateway-dlp.py
import re

DANGEROUS_PATTERNS = [
    # API Keys
    (r'sk-ant-api03-[A-Za-z0-9_-]{80,}', 'Anthropic API Key'),
    (r'sk-proj-[A-Za-z0-9_-]{80,}', 'OpenAI API Key'),
    # AWS
    (r'AKIA[0-9A-Z]{16}', 'AWS Access Key'),
    (r'aws_secret_access_key\s*=\s*[A-Za-z0-9/+]{40}', 'AWS Secret'),
    # 身份证、银行卡
    (r'\b[1-9]\d{5}(19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]\b', 'PRC ID Card'),
    (r'\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\b', 'Credit Card'),
]

def scan_payload(body: str) -> list[str]:
    hits = []
    for pattern, label in DANGEROUS_PATTERNS:
        if re.search(pattern, body):
            hits.append(label)
    return hits

# 在 Gateway 入站时扫描，命中就返回 400

3.4 可观测性​

必备看板：

推荐技术栈：LiteLLM 的 Postgres 日志 → Metabase 自建看板（免费）或 Grafana。

四、L3 协议层：MCP Servers​

为什么要建内部 MCP Server？让所有 AI 工具（Claude Code、Cursor、自建 Agent）复用同一套企业能力。

4.1 企业应该建哪些 MCP Server​

MCP Server能力替代了什么
github-mcp读 PR/Issue、查 commit、评论每个工程师复制粘贴 PR 链接到 AI
jira-mcp / linear-mcp查任务、更新状态手动贴任务描述给 AI
docs-mcp查内部知识库（Wiki/Confluence/Notion）AI 不知道内部文档
sentry-mcp查线上错误手动贴错误日志
grafana-mcp查监控指标手动贴图表数据
k8s-mcp查 Pod、日志、事件切到终端查 kubectl
design-system-mcp查组件库 API、设计 TokenAI 不知道内部设计系统
api-schema-mcp查内部 API 定义、类型手动贴接口定义
db-schema-mcp查数据库 Schema（只读）猜表结构
monorepo-mcp查包依赖、工作流在巨型 monorepo 中手动找

开发成本：大部分 MCP Server 只需要 100-300 行代码，1-2 天能实现一个 MVP。

4.2 MCP Server 模板​

mcp-server-template.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
  { name: 'internal-jira', version: '1.0.0' },
  { capabilities: { tools: {} } },
);

// 列出工具
server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: 'get_ticket',
      description: '根据 ticket ID 获取 Jira 任务详情',
      inputSchema: {
        type: 'object',
        properties: {
          ticketId: { type: 'string', description: '如 ABC-1234' },
        },
        required: ['ticketId'],
      },
    },
    {
      name: 'search_tickets',
      description: '搜索 Jira 任务',
      inputSchema: {
        type: 'object',
        properties: {
          jql: { type: 'string', description: 'JQL 查询' },
          limit: { type: 'number', default: 10 },
        },
        required: ['jql'],
      },
    },
  ],
}));

// 处理工具调用
server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'get_ticket') {
    const ticket = await jiraApi.getIssue(args.ticketId);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          id: ticket.key,
          title: ticket.fields.summary,
          status: ticket.fields.status.name,
          description: ticket.fields.description,
          assignee: ticket.fields.assignee?.displayName,
        }, null, 2),
      }],
    };
  }
  // ...
});

const transport = new StdioServerTransport();
await server.connect(transport);

部署：开发态走 stdio（本地子进程），生产态走 HTTP。员工配置 .claude/config.json 引用公司内部 MCP Server URL。

详见 MCP 协议。

五、L5 能力层：团队共享的 Skills / Subagents / Slash Commands / Hooks​

这是 AI 研发基建最有价值、最有差异化的部分。它把团队每个工程师的经验沉淀为永久资产。

5.1 把业务代码封装成 Skills 的方法论​

Step 1：识别可封装对象

团队开一个"AI Skill 候选"会议，每人列出：

  • 「我每周要写 5 次以上的代码模式是什么？」
  • 「新人经常问/踩坑的操作是什么？」
  • 「涉及业务规则或设计系统的操作？」
  • 「手写容易错的模板化代码？」

通常一个团队能挖出 10-30 个候选。前端团队的典型候选：

Skill高频度复杂度价值
创建 React 组件（含 shadcn 约定、props、测试）⭐⭐⭐⭐⭐中高
创建 API 路由（含 auth、Zod、错误处理）⭐⭐⭐⭐⭐中高
创建表单（React Hook Form + Zod + 设计系统）⭐⭐⭐⭐高高
数据库 migration（含回滚、全文索引、约束）⭐⭐⭐高极高
添加 i18n 文案⭐⭐⭐⭐低中
生成 OpenAPI 类型⭐⭐中中
添加埋点（含事件命名规范）⭐⭐⭐中高
发布组件库版本⭐⭐高极高
接入新的 OAuth Provider⭐高中

Step 2：设计 Skill 结构

一个 Skill 的完整结构：

.claude/skills/api-route/
├── SKILL.md                     # 元数据 + 核心指令
├── templates/
│   ├── rest-route.ts            # REST 路由模板
│   └── server-action.ts         # Server Action 模板
├── scripts/
│   └── generate-route.ts        # 自动生成脚本
├── reference/
│   ├── auth-patterns.md         # 鉴权模式详解
│   ├── error-codes.md           # 错误码规范
│   └── rate-limiting.md         # 限流规范
└── examples/
    ├── user-crud/               # 完整的用户 CRUD 示例
    └── payment-callback/        # 支付回调示例

Step 3：写好 SKILL.md

.claude/skills/api-route/SKILL.md
---
name: api-route
description: |
  创建 Next.js 15 App Router 的 API 路由或 Server Action。
  当用户需要"新建 API"、"创建接口"、"添加后端路由"、"实现 Server Action"时自动调用。
  自动遵循团队的鉴权、校验、错误处理、限流约定。
---

# API 路由构建 Skill

## 使用场景

- 创建新的 REST API 路由
- 创建 Server Action
- 修改现有 API 使其符合团队规范

## 工作流程

1. **明确类型**：询问用户需要的是 REST 路由还是 Server Action（如果用户没说）
2. **选择模板**：
   - REST → `templates/rest-route.ts`
   - Server Action → `templates/server-action.ts`
3. **生成 Zod Schema**：根据字段生成严格的校验
4. **添加必要层**：
   - `auth()` 鉴权检查（所有非公开接口）
   - `rateLimiter()` 限流（见 `reference/rate-limiting.md`）
   - 错误处理（见 `reference/error-codes.md`）
5. **生成测试**：为每个接口生成正向、异常、边界测试

## 强制约定

- ❌ 禁止直接 `await request.json()`，必须用 Zod 校验
- ❌ 禁止 `throw new Error('...')`，用统一错误码（见 reference）
- ❌ 禁止在 API 内直接操作数据库，必须走 `lib/db/` 封装
- ✅ 所有 API 必须有 rate limit
- ✅ 所有非公开 API 必须先 `auth()` 检查
- ✅ 所有响应必须是 `{ ok: true, data }` 或 `{ ok: false, error: { code, message } }`

## 自动化脚本

如果用户只是常见 CRUD，直接调用 `scripts/generate-route.ts`：
\`\`\`bash
node .claude/skills/api-route/scripts/generate-route.ts \
  --entity User --operations "create,read,update,delete"
\`\`\`

## 示例

<example>
用户：给用户模块加一个重置密码接口
Claude:
  1. 判定：REST 路由（有明确的 POST /api/users/[id]/reset-password 路径）
  2. 加载 templates/rest-route.ts
  3. 生成 Zod schema（包含 oldPassword、newPassword、confirmPassword）
  4. 添加 auth() 确认是本人或管理员
  5. 添加 rateLimiter('password-reset', 5/hour)
  6. 写入 app/api/users/[id]/reset-password/route.ts
  7. 生成 reset-password.test.ts
</example>

关键要点：

  • description 必须包含用户会说的原话（"新建 API"、"创建接口"、"添加后端路由"）
  • SKILL.md 主体保持精简（< 500 字），详细内容放 reference/
  • 强制约定要写得具体到禁止什么、必须做什么
  • 有脚本的优先用脚本（比 AI 生成可靠 10 倍）

Step 4：可执行脚本（高级）

对于强约束的重复代码，写脚本而不是让 AI 生成。以表单生成为例：

.claude/skills/form-builder/scripts/generate-form.ts
// 接收 JSON schema，输出完整的表单组件
// 调用方式：node generate-form.ts --spec form-spec.json

import { z } from 'zod';

const FormSpec = z.object({
  name: z.string(),
  fields: z.array(z.object({
    name: z.string(),
    label: z.string(),
    type: z.enum(['text', 'email', 'password', 'number', 'date', 'select', 'checkbox']),
    required: z.boolean().default(false),
    validation: z.object({ min: z.number().optional(), max: z.number().optional() }).optional(),
    options: z.array(z.object({ value: z.string(), label: z.string() })).optional(),
  })),
});

// 根据 spec 生成：
// 1. Zod schema
// 2. React Hook Form 组件
// 3. 单元测试
// ...

AI 调用时：

用户：加一个用户注册表单，邮箱、密码、确认密码、同意协议
AI:
  1. 识别是表单 → 加载 form-builder Skill
  2. 生成 JSON spec
  3. 调用 scripts/generate-form.ts --spec /tmp/spec.json
  4. 脚本生成 RegisterForm.tsx + RegisterForm.test.tsx
  5. AI 只需要写集成代码（挂到 app/register/page.tsx）

Step 5：测试和迭代

写 Skill 后要验证触发准确性：

skill-test-cases.md
# api-route Skill 触发测试

## 应该触发（true positives）
- "给用户模块加一个重置密码接口" ✅
- "创建一个 /api/search 接口" ✅
- "实现购物车的 Server Action" ✅
- "加一个公开的健康检查路由" ✅

## 不应该触发（true negatives）
- "优化 /api/users 的性能" ❌ （是优化不是新建）
- "查一下我们的 API 文档" ❌ （是查询不是创建）

## 边界情况
- "把 fetch 换成 apiClient" → 不触发（不是新建路由）
- "给接口加鉴权" → 可触发（修改接口使符合规范）

每月 review Skill 触发准确率，优化 description 关键词。

5.2 让 AI 更"听话"的系统性手段​

让 AI 按团队意愿行事，有 6 层工具，从轻到重：

层 1：Rules（最轻量）

写清规范。但 AI 不一定 100% 遵守，像"说服"而非"强制"。

层 2：Skills 的强制约定

在触发 Skill 的场景下，用 ❌ 禁止、✅ 必须 这种硬措辞。

层 3：Slash Commands

用户输入 /new-api → 固化的 Prompt + 工作流。AI 严格按步骤执行，不会跳步。

层 4：Subagent 限权

Subagent 只给它"必要的工具"。例如 security-reviewer 只给 Read/Grep，物理上就不能乱改代码。

---
name: security-reviewer
tools: [Read, Grep, Glob]    # 只读
---

层 5：PreToolUse Hook（强制）

#!/bin/bash
# 拦截不符合约定的操作
CMD=$(cat)
if echo "$CMD" | grep -qE "npm install"; then
  echo "BLOCKED: use pnpm, not npm" >&2
  exit 1  # 阻断工具调用
fi

层 6：Sandbox（物理隔离）

用 Git worktree 或 Docker 把 AI 完全隔离在独立空间，改错了直接丢弃。

听话层级选型
  • 大多数规范用 Rules + Skill 约定（层 1-2）
  • 有确定性流程的场景用 Slash Command（层 3）
  • 防范特定风险用 限权 Subagent + Hook（层 4-5）
  • 完全不受控场景（YOLO 模式）用 Sandbox（层 6）

不是层级越高越好——Hook 写得过度会导致 AI 寸步难行。按实际风险选择。

5.3 Slash Commands 标准库​

一个成熟团队的 Slash Commands 大致分 4 类：

.claude/commands/
├── workflow/              # 研发流程
│   ├── new-feature.md     # /new-feature → 完整功能开发流程
│   ├── review-pr.md       # /review-pr → PR 审查
│   ├── ship-release.md    # /ship-release → 发布流程
│   └── debug.md           # /debug → 调试模板
├── code-gen/              # 代码生成
│   ├── new-component.md   # /new-component
│   ├── new-api.md         # /new-api
│   ├── new-page.md        # /new-page
│   └── new-migration.md   # /new-migration
├── quality/               # 质量工具
│   ├── lint-all.md        # /lint-all → 全项目修复
│   ├── gen-tests.md       # /gen-tests → 为选中文件生成测试
│   └── audit-security.md  # /audit-security → 安全审查
└── ops/                   # 运维
    ├── triage.md          # /triage → 分析告警
    ├── rollback.md        # /rollback → 回滚指引
    └── onboard.md         # /onboard → 新人引导

样例：/new-feature

.claude/commands/workflow/new-feature.md
---
name: new-feature
description: 完整的新功能开发流程（需求分析 → 设计 → 实现 → 测试 → PR）
argument-hint: "[feature description]"
---

我们要开发一个新功能：$ARGUMENTS

请严格按以下步骤执行，**每步完成后等我确认再进行下一步**：

## 步骤 1：需求理解（只读）
- 阅读 .claude/memory/product_context.md 了解产品背景
- 阅读相关 Jira ticket（如果我提供了 ID）
- 用 3-5 句话总结你理解的需求
- 提 2-3 个可能的需求澄清问题

**等我确认后进入步骤 2**

## 步骤 2：技术方案（只读）
- 调查现有代码中相关的文件和模式
- 给出 2-3 种实现方案对比
- 推荐一种并说明理由
- 列出需要改动/创建的文件清单

**等我确认后进入步骤 3**

## 步骤 3：实现
- 按计划逐个文件实现
- 每个文件实现后调用 PostToolUse Hook 自动 lint/tsc
- 遇到错误立即修复，不要继续
- 优先使用已注册的 Skills（如 api-route、form-builder）

## 步骤 4：测试
- 调用 `gen-tests` Skill 为每个新建文件生成测试
- 运行 `pnpm test` 确保通过

## 步骤 5：PR
- 生成 commit 和 PR 描述（使用 conventional commits）
- 不要直接 push，等我审查本地改动

5.4 Subagents 标准库​

.claude/agents/
├── security-reviewer.md        # 安全审查（Opus + 只读）
├── test-writer.md              # 测试生成（Sonnet + __tests__ 写权限）
├── doc-writer.md               # 文档生成（Haiku + docs 写权限）
├── pr-summarizer.md            # PR 总结（Haiku + 只读）
├── db-query-reviewer.md        # DB 查询审查（Opus + 只读）
└── i18n-extractor.md           # 文案提取和翻译（Haiku）

六、L6 治理与文化​

6.1 使用规范（Policy）​

企业级必须有一份明确的 AI 使用规范，写入员工手册：

AI 使用规范（样例）
# AI 辅助开发规范 v1.2

## 允许使用
- ✅ 通过公司 Gateway 访问模型
- ✅ 非敏感代码发送给 AI
- ✅ 使用官方推荐的 IDE 插件（Claude Code、Cursor）

## 禁止使用
- ❌ 绕过 Gateway 直接使用个人 API Key
- ❌ 把包含用户数据/密钥的代码发给 AI
- ❌ 部署 AI 生成的代码到生产前未经人工审查
- ❌ 使用未在白名单上的 AI 工具

## 必须做
- ✅ 所有 AI 生成的代码必须过 Code Review
- ✅ 使用公司提供的 CLAUDE.md / Rules / Skills
- ✅ 严重 Bug 怀疑是 AI 导致的，必须报 AI 基建团队

## 分级
- 公开代码（开源/文档）：Tier 1，可以自由使用 AI
- 内部代码（业务逻辑）：Tier 2，走 Gateway
- 敏感代码（支付、鉴权、加密）：Tier 3，AI 只能辅助，关键逻辑必须人工
- 合规代码（医疗、金融、政务）：Tier 4，禁用 AI 或只用本地模型

违规处理：首次警告、二次与主管面谈、屡次违规影响绩效

6.2 培训体系​

新人入职：Day 1 必修

## 新人 AI 培训（2 小时）

### 第 1 小时：环境配置
- 安装 Claude Code + Cursor
- 配置公司 Gateway
- clone 公司 .claude/ 配置仓库到 ~/.claude/
- 做第一个任务：用 `/new-component` 创建一个 Demo 组件

### 第 2 小时：能力概览
- 演示 Rules / Skills / Subagents / Slash Commands / Hooks 的作用
- 演示几个典型工作流（/new-api、/review-pr、/gen-tests）
- 讲解使用规范和红线
- Q&A

在职培训：双月技术分享

  • 每个工程师分享一个"我最近做的一个高效 AI 使用案例"
  • AI 基建团队分享新上线的 Skills / 工具
  • 疑难问题讨论

6.3 效能度量​

每月发布一份"AI 研发效能月报"：

AI 效能月报（模板）
# 2026 年 X 月 AI 研发效能月报

## 成本
- 总花费：$XXX（上月 $XXX，环比 +X%）
- 按团队：前端 $XX、后端 $XX、移动端 $XX
- 按模型：Sonnet 60%、Opus 20%、Haiku 20%
- Prompt Cache 命中率：XX%（节省约 $XX）

## 使用率
- 活跃员工：XX / XX（XX%）
- 人均 Token 消耗：XXK/天
- Top 3 Skills 触发次数：
  1. api-route: XXX 次
  2. new-component: XXX 次
  3. form-builder: XXX 次
- Top 3 Slash Commands 使用次数：...

## 效率
- Feature 平均交付时间：X.X 天（上月 X.X 天）
- PR 平均 Review 时间：X 小时（上月 X 小时）
- AI 代码采纳率：XX%（Copilot 原生指标）

## 质量
- AI 代码引入的 Bug 数：XX（其中严重 X）
- CI 自动修复的 Lint 错误：XXX
- 安全审查 Subagent 发现的问题：XX

## 本月亮点
- 新上线 3 个 Skills（列出）
- XX 团队的 /new-api 流程使他们的 API 开发时间缩短 40%

## 问题与改进
- Opus 使用率偏高，建议引导更多任务到 Sonnet
- ...

## 下月计划
- ...

6.4 推广策略：循序渐进​

不要一口气铺到全团队。推荐分阶段：

关键里程碑：

月阶段里程碑
1MVPGateway 跑通、3-5 个 Skill 上线、5 人试点
2MVP试点反馈、迭代 Skill、采纳率 > 80%
3扩大MCP Servers + Slash Commands + Subagents，50 人试点
4扩大Hooks 自动化、Bug 率下降数据初现
5全面规范发布、看板上线、全团队推广
6全面月报机制运行、持续优化

七、常见坑和避坑指南​

坑 1：一上来就追求完美体系​

症状：打算一次性建 10 个 MCP、30 个 Skill、全套 Hook。结果 3 个月后啥都没上线。

避坑：从最小 MVP 起（Gateway + 3 个 Skill + 1 个 Slash Command），边用边加。

坑 2：忽视模型网关就发订阅​

症状：公司给每人发了 Claude Code 账号，3 个月后：

  • 不知道钱花在哪
  • 没法审计哪些代码发给了模型
  • 有人拿公司账号跑个人项目

避坑：日 1 就要有 Gateway。哪怕只是套一层 LiteLLM，也比裸发账号好百倍。

坑 3：Skill 写得太"聪明"​

症状：Skill 的 SKILL.md 写得像论文，各种条件分支、复杂指引。AI 经常不按预期触发。

避坑：

  • SKILL.md 主体 < 500 字
  • description 用最朴素的原话（"创建 API"、"新建接口"）
  • 复杂逻辑放到脚本里，让 Skill 只负责决策是否调脚本

坑 4：Hook 越写越多变成性能地狱​

症状：PostToolUse 每次写文件都跑全量 pnpm test，Agent 等 30 秒才能下一步。

避坑：

  • Hook 只做"快速、幂等、低风险"操作
  • 重活（全量 test、build、安全扫描）交给 CI
  • 定期 audit hook 的平均耗时

坑 5：不做度量，"感觉"AI 有用​

症状：推广半年，有人说"效率翻倍"，有人说"没啥用"。老板问 ROI，拿不出数据。

避坑：Day 1 就接 Gateway 日志到 Metabase，Week 1 就出一张看板。数据驱动是 AI 基建的生命线。

坑 6：不纳入 Git，Skill 成了个人资产​

症状：某个工程师写了特别好用的 Skill，放在自己的 ~/.claude/skills/。离职了，Skill 没了。

避坑：所有团队 Skill / Subagent / Slash Command / Rules 都必须纳入 Git，有专门的仓库或 monorepo 里的 .claude/ 目录。新员工入职 git clone 就有全套能力。

坑 7：Gateway 不做限流就上线​

症状：某个实习生写了个死循环脚本，一晚上花了 $5000 API 费。

避坑：

  • Gateway 必须有人均月配额（默认 $100-500，根据团队）
  • 必须有单次请求上限（如单次 input > 500K 直接拒绝）
  • 超 80% 配额发通知

坑 8：追求全员统一 IDE​

症状：强制所有人用 Cursor，VS Code 老用户怨声载道。

避坑：

  • 工具层自由（Cursor / Claude Code / Copilot 任选）
  • 但 Rules / Skills / Slash Commands 必须统一（格式兼容性足够）
  • Gateway 层必须统一（都走公司代理）

八、成熟度评估模型​

用这个模型评估团队 AI 基建成熟度：

Level名称特征
L0裸用个人开账号用 ChatGPT，没治理
L1有网关统一 Gateway，成本可控
L2有规范Rules + 使用规范文档
L3有能力库Skills + Subagents + Slash Commands 纳入 Git
L4有自动化Hooks + CI/CD 集成
L5有度量效能看板 + 月报机制
L6有生态内部 MCP Server + 跨工具复用
L7有文化培训体系 + 持续迭代 + 全员日常使用

大多数团队在 L0-L2 之间。目标是 L5+。从 L2 到 L5 通常需要 3-6 个月，投入 1-2 个全职工程师。

九、最小可行 MVP（你下周就能做的）​

如果你是团队技术负责人，下周可以做这 5 件事：

Day 1-2：跑通 LiteLLM Gateway

  • Docker compose 起 LiteLLM + Postgres
  • 配置 Anthropic + OpenAI 两个模型
  • 给自己和一位同事发 Gateway Token

Day 3：写第一版 CLAUDE.md

  • 提交到仓库根目录
  • 包含技术栈、强制规范、命名约定

Day 4：做第一个 Skill

  • 挑团队最高频的操作（通常是"创建 API 路由"或"创建组件"）
  • 写好 SKILL.md、放一个模板文件
  • 提交到 .claude/skills/

Day 5：做第一个 Slash Command

  • 把你最常用的 Prompt 固化成 /review-pr 或 /gen-tests
  • 提交到 .claude/commands/

Day 6-7：跑一周，收集数据

  • 自己用，邀请 1-2 位愿意尝鲜的同事用
  • 记录：哪些场景好用？哪些不好用？想要什么新能力？

下周的下一步：

  • 加 3 个新 Skill
  • 接个 Grafana 看 Gateway 成本
  • 写使用规范初稿

基建是滚雪球：从 5 个人 3 个 Skill 开始，坚持 3 个月就是完全不同的团队。

十、面试速答与追问清单​

3 分钟速答版​

如果面试官问“如何从 0 搭建团队 AI 研发基建”，可以这样答：

  1. 先建 Gateway：统一模型入口，解决 API Key、配额、审计、DLP、缓存、路由和 fallback。
  2. 再沉淀团队资产：Rules 放项目常识，Skills 放高频能力，Subagents 做专业审查，Slash Commands 固化流程，Hooks 做质量门禁。
  3. 接内部系统：通过 MCP 连接 GitHub/GitLab、Jira/Linear、知识库、Sentry、设计系统和内部 API Schema。
  4. 做治理和安全：SSO/SCIM/RBAC、数据分级、敏感代码路由、日志脱敏、权限审批、供应商 DPA/零留存策略。
  5. 用数据推广：从 5 人试点开始，看使用率、成本、交付周期、PR 周期、Bug 率和新人 onboarding 时间，再逐步推广。

10 分钟展开版​

按“基础设施层 → 协议层 → 能力层 → 治理层 → 文化层”讲：基础设施是 Gateway 和可观测性；协议层是 MCP；能力层是 Skills/Subagents/Commands/Hooks；治理层是权限、审计、DLP、预算；文化层是培训、月报和持续迭代。强调不要一开始追求 30 个 Skill，先做 Gateway + 3 个高频 Skill + 1 个审查 Subagent。

高频追问​

追问回答要点
为什么第一步是 Gateway？没有 Gateway 就没有统一密钥、成本、审计、缓存、路由和 DLP
直接发 Cursor/Copilot 订阅不行吗？个人效率有提升，但团队经验、合规、成本和审计无法沉淀
如何做数据分级？公开代码、内部代码、敏感代码、合规代码分层，不同层用不同模型和权限
是否要自建模型？大多数不需要；先做 Gateway + RAG/代码检索，合规或高频成本明确后再私有部署
如何治理 100+ Skills？命名空间、owner、版本、触发日志、准确率评估、废弃机制
如何算 ROI？模型成本节省 + 效率提升等价人力 + 质量收益 + onboarding 提速
最大风险是什么？数据泄露、权限失控、AI 生成漏洞、成本失控、组织不采纳
阅读分工

本篇回答“团队平台怎么建”。具体工具使用见 AI 辅助开发，端到端研发流程见 AI 全流程研发实战。

常见面试问题​

Q1: 为什么需要 AI 研发基建？直接发 Cursor/Copilot 订阅不行吗？​

答案：

直接发订阅在 5 人以下团队可以，50 人以上团队会出问题：

  1. 成本失控：每人独立订阅，不能统一议价；没法按项目/团队做成本归集；没法降级到便宜模型
  2. 安全风险：代码随意发给第三方；没法审计谁把什么代码发给了 AI；密钥/敏感数据可能被发出去
  3. 能力割裂：A 把"生成表单"的 Prompt 打磨得很好，B 不知道；经验无法沉淀为团队资产
  4. 质量波动：Rules/规范只靠口头传达，执行不一致；新人上手慢
  5. 不可度量：拿不出数据证明 AI 的 ROI；老板问效果时只能靠主观感受

AI 研发基建 解决这些问题：统一网关控成本和安全、Skills/Subagents 沉淀团队经验、Rules+Hook 保质量、可观测性提供数据。

投入产出比：1-2 个工程师 3-6 个月建设，50 人团队通常能省 30%+ 模型成本 + 30-50% 研发效率提升。

Q2: 从零开始，AI 研发基建的第一步应该做什么？​

答案：

第一步永远是模型网关（Gateway）。

理由：

  1. 没有网关 = 没有一切其他能力的基础（审计、配额、缓存、路由都依赖网关）
  2. 风险最大的问题（成本失控、数据泄露）都需要网关才能管
  3. 成本最低，LiteLLM + Postgres 用 Docker 一天能跑通

网关到位后，按这个顺序建设：

Gateway（Week 1）
  → Rules 规范（Week 2）
  → 3-5 个核心 Skills（Week 3-4）
  → 5-10 人试点（Week 5-7）
  → 扩大 Skills + Slash Commands（Month 2）
  → MCP Servers（Month 3）
  → Hooks 自动化（Month 4）
  → 可观测性 + 全员推广（Month 5-6）

不要一开始就搞大而全——建过最小可用就上线试点，根据反馈迭代。

Q3: 怎么把业务代码封装成可复用的 Skill？​

答案：

5 步方法论：

1. 识别候选

团队开一次"AI Skill 候选"会议，每人列：

  • 每周要写 5 次以上的代码模式
  • 新人容易踩坑的操作
  • 涉及业务规则或设计系统的操作

前端团队典型候选：创建 API 路由、创建组件、创建表单、数据库 migration、添加 i18n、生成 OpenAPI 类型、添加埋点。

2. 设计结构

.claude/skills/<name>/
├── SKILL.md          # 元数据 + 核心指令（< 500 字）
├── templates/        # 代码模板
├── scripts/          # 可执行脚本（比 AI 写更可靠）
├── reference/        # 详细文档
└── examples/         # 完整示例

3. 写好 SKILL.md

关键是 description 必须包含用户会说的原话：

description: |
  创建 Next.js API 路由或 Server Action。
  当用户需要"新建 API"、"创建接口"、"添加后端路由"时自动调用。

SKILL.md 里用 "❌ 禁止"、"✅ 必须" 写硬约束：

## 强制约定
- ❌ 禁止直接 `await request.json()`，必须用 Zod 校验
- ✅ 所有 API 必须有 rate limit

4. 能用脚本就用脚本

强约束的重复代码写成脚本，让 AI 调脚本而非自己生成：

scripts/generate-form.ts --spec form-spec.json

比 AI 逐行生成快 10 倍，结果确定性强。

5. 验证和迭代

写 Skill 测试用例（应该触发/不应该触发的场景），每月 review Skill 触发准确率，优化 description。

Q4: 怎么让 AI 更听话，按团队规范行事？​

答案：

6 层工具，按强度从轻到重：

层手段强度适用
1Rules弱（说服）项目常识
2Skills 约定中（场景化）特定任务规范
3Slash Commands较强（流程固化）有确定流程的任务
4Subagent 限权强（工具限定）让 AI 物理上做不了某些事
5PreToolUse Hook强（拦截）防范特定风险
6Sandbox最强（物理隔离）YOLO 模式或不受控场景

常见组合：

  • 项目规范 → Rules
  • "创建 API 必须有鉴权" → Skill 约定
  • "PR 审查流程" → Slash Command
  • "安全审查不能改代码" → Subagent 只读限权
  • "禁止 npm install，必须用 pnpm" → PreToolUse Hook 拦截
  • "大规模重构探索" → Git worktree Sandbox

反模式：层级用过高。Hook 写得到处都是会让 Agent 寸步难行。按实际风险选择最小必要层级。

Q5: 企业应该建哪些内部 MCP Server？​

答案：

优先级排序：

第一批（Must Have）：

  1. GitHub/GitLab MCP — 读 PR/Issue/commit
  2. Jira/Linear MCP — 查任务、更新状态
  3. 内部知识库 MCP — 查 Wiki/Confluence/Notion
  4. Sentry MCP — 查线上错误

第二批（High Value）： 5. 设计系统 MCP — 查组件库 API、Token 6. 内部 API Schema MCP — 查接口定义、类型 7. DB Schema MCP（只读） — 查表结构

第三批（Nice to Have）： 8. Grafana MCP — 查监控指标 9. K8s MCP（只读） — 查 Pod/日志 10. Monorepo MCP — 查包依赖

开发成本：大部分 MCP Server 100-300 行代码，1-2 天 MVP。

为什么值得：让 Claude Code、Cursor、自建 Agent 等所有 AI 工具复用同一套能力。不做 MCP 就要每个工具各自集成一次。

详见 MCP 协议。

Q6: 怎么度量 AI 研发基建的效能？​

答案：

5 大维度看板：

成本：

  • 总花费、按员工/团队/模型分布
  • Prompt Cache 命中率
  • 对标：基建前 vs 后，人均成本变化

使用率：

  • 活跃员工比例
  • Skill/Slash Command 使用次数排行
  • Top 用户 vs 低频用户差异

效率：

  • Feature 平均交付时间
  • PR 平均 Review 时间
  • AI 代码采纳率

质量：

  • AI 代码引入的 Bug 数
  • CI 自动修复的 Lint 错误
  • Subagent 发现的安全问题

安全：

  • DLP 拦截次数
  • 异常使用模式（超配额、异常时段）

核心工具：LiteLLM 的 Postgres 日志 → Metabase 自建看板（免费）。

月报机制：每月发一份 AI 效能月报给技术 VP 和团队。用数据而非感觉推动迭代。

Q7: 推广 AI 基建，哪些是常见大坑？​

答案：

8 个高频坑：

  1. 一上来追求完美：规划 10 个 MCP + 30 个 Skill，3 个月什么都没上线。避坑：最小 MVP（Gateway + 3 Skill），边用边加
  2. 裸发订阅没网关：钱花得不清楚、安全无法审计、无法沉淀经验。避坑：Day 1 必有 Gateway
  3. Skill 写得太复杂：SKILL.md 像论文，AI 经常不正确触发。避坑：< 500 字，description 用原话
  4. Hook 性能灾难：PostToolUse 每次写文件跑全量 test。避坑：Hook 只做快速幂等操作
  5. 不做度量：说不清 ROI，老板不买账。避坑：Day 1 就接日志到 Metabase
  6. 不纳入 Git：好 Skill 在个人电脑上，离职带走。避坑：强制 Git 管理，团队共享
  7. Gateway 不做限流：有人死循环烧 $5000。避坑：必须有人均配额 + 单次上限
  8. 追求统一 IDE：强制全员 Cursor，老用户反感。避坑：工具层自由，规范层统一

Q8: 新人入职，AI 基建能做什么帮助？​

答案：

好的 AI 基建能让新人从入职第 1 天就达到老员工 70% 的产出水平：

Day 1 配置（2 小时内）：

  • 安装 Claude Code / Cursor
  • git clone 公司 .claude/ 配置
  • 配置 Gateway Token
  • 跑通第一个任务（用 /new-component 创建 Demo 组件）

Day 1 获得的能力：

  • 项目技术栈、编码规范、禁忌（来自 CLAUDE.md）
  • 30+ 个研发场景的 Skills（创建 API、组件、表单、migration）
  • 20+ 个 Slash Commands 固化流程（/new-feature、/review-pr、/gen-tests）
  • 所有内部 API、Jira、知识库通过 MCP 访问

对比没有基建的新人：

  • 第 1 周：被动读文档、看代码
  • 第 2-3 周：交付第一个任务（质量存疑）
  • 第 4 周：开始独立产出

有基建的新人：

  • 第 1 天：环境就绪，能跑 /new-feature
  • 第 3 天：交付第一个任务（质量有 Skill/Hook 保底）
  • 第 2 周：产出稳定

数据：某团队推广 AI 基建后，新人 onboarding 时间从 4 周缩短到 1.5 周。

Q9: 企业是否应该自建模型？​

答案：

大多数企业不需要。自建成本高、模型能力比不上 Claude/GPT、维护复杂。

例外情况：

  1. 合规要求：金融、医疗、政务等行业数据不能出境/出内网 → 必须用私有部署的 Qwen3 Coder / DeepSeek V3.2
  2. 极高频使用：月 API 消耗 $100K+，自部署的摊销成本可能更低
  3. 有强定制需求：需要在自有代码上做 LoRA 微调
  4. 数据敏感到极端程度：绝对不能有任何外泄风险

推荐架构：Hybrid

  • 绝大部分请求 → 闭源强模型（以当前可用的 Claude / GPT / Gemini 等企业版模型为主）
  • 敏感代码 → 内部部署或企业零留存策略下的模型（如 Qwen / DeepSeek / 自托管 Code 模型）
  • Gateway 做路由：根据代码打标签（敏感/非敏感）自动选模型

更稳妥的路径通常是：先做 Gateway + RAG / 代码检索 + 权限治理，等确实有合规、成本或领域效果问题，再评估私有部署或微调。不要把“自建模型”当作 AI 基建的第一步。

判断标准：如果你不确定要不要自建，答案就是暂时不要。等明确需要时再上。

Q10: AI 基建的 ROI 应该怎么算？​

答案：

多维度综合：

直接成本节省：

  • 统一网关议价（比个人订阅省 30-50%）
  • Prompt Caching 共享（省 50-80% 输入成本）
  • 模型路由降级（简单任务用 Haiku 代替 Sonnet，省 80%+）

效率提升（等价人力成本）：

节省人月 = 团队规模 × 每月 × 效率提升比

例如 50 人团队、效率提升 30%、人均月薪 3 万：

  • 月等价节省：50 × 3 万 × 30% = 45 万/月

质量提升（避免 Bug 成本）：

  • AI 生成代码 + Hook 自动 lint + Subagent 安全审查 → Bug 率下降
  • 一个生产 P0 事件的成本通常是 10-50 万
  • 每月减少 1 个 P0 事件 = 10-50 万节省

新人 Onboarding 提速：

  • 从 4 周缩短到 1.5 周 = 每个新人节省 2.5 人月 × 人均成本

ROI 公式：

ROI = (成本节省 + 效率提升 + 质量提升) / 基建投入

基建投入 = 2 人 × 6 个月 × 人均成本 + 模型费用

典型 50 人团队：

  • 基建投入：人力 ~100 万 + 模型费用 ~30 万/年 = 130 万
  • 年节省：模型成本 15 万 + 效率 540 万 + 质量 120 万 + 新人 60 万 = 735 万
  • ROI ≈ 5.6 倍

实际数据会随团队规模、业务复杂度变化，但 3-10 倍 ROI 是合理预期。

Q11: AI 基建能支撑多大规模？什么时候会撞墙？​

答案：

规模天花板：

  • LiteLLM Proxy：可撑 500-2000 人团队
  • Postgres 日志：可撑百万级请求/天
  • Metabase 看板：可撑千人级用户

典型撞墙点：

  1. 单 Gateway 性能：超过 1000 QPS 时 LiteLLM 单实例会成瓶颈 → 上 K8s 多副本
  2. 日志量爆炸：Postgres 单库超 1TB 后查询变慢 → 迁到 ClickHouse
  3. Skill 管理混乱：100+ Skill 时 AI 触发准确率下降 → 需要分命名空间、Skill search
  4. 权限复杂度：多团队多产品时，权限模型变复杂 → 引入 RBAC
  5. 组织阻力：100+ 人时文化统一变难 → 需要专门的 DevRel / AI 平台运营

对应升级：

  • 100 人以下：LiteLLM + Postgres 够了
  • 100-500 人：K8s 多副本 + ClickHouse 日志
  • 500-2000 人：多 Gateway 集群 + RBAC + AI 平台运营
  • 2000+ 人：可能需要考虑自研 Gateway 和深度定制

Q12: 项目搭建阶段，怎么让 AI 从 Figma 设计稿反向提取设计系统并归纳到代码？​

答案：

这是基建的典型场景——一次性投入、永久受益。新项目启动时（或老项目做 UI 大改版），设计师给一份 Figma 设计稿，AI 可以在 1-2 天内把完整设计系统翻译成代码（传统手工需要 1-2 周）。

一、明确产出物（6 个文件）​

项目搭建阶段的目标是把 Figma 一次性转化成：

产出作用
tokens/tokens.json设计 Token 单一事实源（SSOT），W3C Design Tokens 规范
tailwind.config.tsTailwind 配置（从 tokens.json 生成）
styles/tokens.cssCSS 变量，支持 light/dark mode 切换
types/tokens.d.tsTypeScript 类型，让 bg-primary-500 有自动补全
docs/design-inventory.md组件清单（哪些用 shadcn/ui、哪些自建）
.github/workflows/sync-design-tokens.ymlCI 定时从 Figma 同步，漂移自动 PR

原则：tokens.json 是唯一事实源，其他 5 个都由它派生。设计师改一个色值，跑一次构建脚本，其他文件全部更新。

二、Slash Command /bootstrap-design-system​

把整个流程固化：

.claude/commands/workflow/bootstrap-design-system.md
---
name: bootstrap-design-system
description: 从 Figma 反向提取完整设计系统到项目代码
argument-hint: "[figma-file-url]"
---

从 Figma 文件 $ARGUMENTS 反向提取设计系统。

**严格 7 步流程，每步等我确认再进行下一步**。

## Step 1：扫描原始 Token（只读）

调用 `figma__get_file($1)` 拿完整文件结构，扫描所有：
- **颜色**：fill、stroke、background
- **字号/字重/行高**：textStyle
- **间距**：所有独立的 padding/margin/gap 数值
- **圆角**：cornerRadius
- **阴影**：effect (DROP_SHADOW、INNER_SHADOW)
- **透明度**：opacity

输出 `.claude/bootstrap/raw-tokens.json`（原始，未去重）。

**报告**：
- 找到 N 个独立颜色、M 个独立字号、K 个独立间距
- **预警**：独立值数量（如果颜色 > 50 或间距 > 20 通常有噪音）

## Step 2：归纳去重（AI 做重活）

对原始 Token 做聚类和归纳：

**颜色**：
- 合并 deltaE < 2 的相近色（设计师手误）
- ⚠️ **绝不合并 deltaE > 5 的**（那是有意设计）
- 推断调色板结构：是 50-950 tailwind scale？还是 lighter/light/base/dark/darker？
- 识别语义分组：primary/secondary/success/warning/danger/neutral

**间距**：
- 检测是否符合 4pt / 8pt grid
- 如不符合，找出 base unit（最大公约数）
- 输出 spacing scale：`0/1/2/3/4/5/6/8/10/12/16/20/24` 这种

**字号**：
- 推断 typography scale
- 识别语义：display/heading/body/caption

**异常值**：
- 只使用过 1-2 次的值标记为"可能误用"
- 等设计师确认

输出 `.claude/bootstrap/summary.md`（人类可读的归纳报告）。

**必须停下等我审核**：归纳阶段 AI 可能误判（比如把 brand-blue 和 info-blue 合并），我看过才能继续。

## Step 3：分层（Core / Semantic）

按 W3C Design Tokens 规范分两层：

**Core Tokens**（原始原子，不携带语义）：
```
color.blue.500 = #3B82F6
color.gray.900 = #111827
spacing.4 = 16px
```

**Semantic Tokens**（语义引用 core）：
```
color.action.primary → {color.blue.500}
color.text.body → {color.gray.900}
color.background.surface → {color.gray.50} [dark: {color.gray.900}]
spacing.card.padding → {spacing.6}
```

**关键**：
- 业务代码**只用 semantic**，不直接用 core
- Dark mode 只改 semantic 指向，core 不变
- 换主题：新建一套 semantic 映射即可

输出 `tokens/tokens.json`（W3C 格式）。

## Step 4：生成项目代码

配置 [Style Dictionary](https://amzn.github.io/style-dictionary/) 作为构建工具：

- `tokens/config.ts` — Style Dictionary 配置
- `tailwind.config.ts` — 从 tokens.json 生成
- `styles/tokens.css` — CSS 变量 + dark mode 切换
- `types/tokens.d.ts` — TypeScript 自动补全

package.json 加脚本：
```json
"build:tokens": "style-dictionary build"
```

## Step 5：组件清单盘点

扫描 Figma `Components` 页面（不是样式，是组件实例）：
- 读取所有命名组件
- **映射到 shadcn/ui**：Button/Input/Card/Dialog/Select 等已有的直接用
- **标记自建**：业务定制的（UserAvatar/PriceTag/InviteCard）

输出 `docs/design-inventory.md`：
```
## 使用 shadcn/ui（12 个）
- [x] Button → @/components/ui/button
- [x] Input → @/components/ui/input
- ...

## 需要自建（8 个，按优先级）
- [ ] UserCard (P0, 出现在 42 个页面)
- [ ] PriceTag (P0, 出现在结账流程)
- ...
```

## Step 6：设计师 Review

生成 `docs/design-system-review.md` 发给设计师：
- 我推断的 Token 清单
- 我合并的相近色（列表 + 原因）
- 我的分层决策
- 命名约定建议
- **待你确认**的异常值 / 歧义项

**必须等设计师书面确认再进 Step 7**。

## Step 7：建立 Sync 流程

生成：
- `.github/workflows/sync-design-tokens.yml`：每天凌晨从 Figma 拉取，有变化自动提 PR
- `scripts/sync-figma-tokens.ts`：核心同步逻辑

这样**后续设计变更走 PR 流程**，不会出现"设计和代码漂移"。

三、AI 价值最大的一步：Step 2 归纳去噪​

这一步人工要做 2-3 天，AI 可以压缩到 20 分钟。因为 Figma 原始数据充满噪音：

  • 手误偏差：#3B82F6 vs #3B82F7（肉眼看不出但都存在）
  • 历史遗留：早期 Token 已被替代但没删
  • 同意图不同值：Primary Blue 和 Brand Primary 实际相同
  • 一次性试验：设计师做 AB 测试留下的孤儿色

AI 做归纳的关键 Prompt：

我给你 ~200 个从 Figma 扫到的颜色值。请：

1. **聚类**：deltaE < 2 的合并（设计师手误）
2. **不要过度合并**：deltaE > 5 绝不合并，那是有意设计
3. **推断结构**：tailwind 50-950 scale？lighter/light/default/dark？
4. **识别语义**：primary/secondary/success/warning/danger/neutral 有没有成组？
5. **标记异常**：只用过 1-2 次的可能是误用，标出来等设计师确认
6. **输出**：
   - 建议的 Token 清单（core + semantic）
   - 合并决策列表（每条附原因）
   - 待人工确认清单

四、让 AI 更准确的 4 个实战技巧​

1. 给 AI 看参考项目

让 AI 读你用过的成熟项目（如 shadcn 官网、Linear、Stripe Dashboard）的 tokens.json，学习"好的设计系统长什么样"：

Read https://ui.shadcn.com/registry/styles/default/index.json
读完之后，再归纳我的 Figma tokens

2. 用 Subagent 并行处理

Figma 文件大，扫描 + 归纳耗时。分派并行 Subagent：

  • token-scanner Subagent：专门调 figma_ MCP 扫描
  • token-analyzer Subagent：Opus 深度推理归纳
  • code-generator Subagent：生成 Style Dictionary 配置

主 Agent 编排 + 等待结果，总耗时 = max 而非 sum。

3. Hook 拦截"AI 自创 Token"

.claude/hooks/no-invent-tokens.sh
#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == tokens/tokens.json ]]; then
  # 检查是否引入了 Figma 中不存在的值
  NEW_VALUES=$(diff <(jq -r '..|.value?' tokens/tokens.json 2>/dev/null) \
                   <(jq -r '..|.value?' .claude/bootstrap/raw-tokens.json))
  if [ -n "$NEW_VALUES" ]; then
    echo "🚫 BLOCKED: 检测到 Figma 中没有的值，请设计师确认后再加" >&2
    echo "$NEW_VALUES" >&2
    exit 2
  fi
fi

4. 多轮渐进式 Review

不要一次让 AI 输出完美方案。分 3 轮：

  • 第 1 轮：「给我 Token 清单的初稿」→ 你标注"这个分组不对、那个命名需改"
  • 第 2 轮：「按我的反馈调整」→ 再过一遍
  • 第 3 轮：「生成最终代码」

五、真实案例时间线​

某团队从 0 搭建设计系统的对比：

传统人工流程（耗时 8-10 人天）：

  • Day 1-2：设计师对着 Figma 手工导出 Token 到 Excel
  • Day 3-4：前端按 Excel 配 tailwind.config，互相对值
  • Day 5-6：手写 CSS 变量支持 dark mode
  • Day 7-8：盘点组件，和 shadcn 对照
  • Day 9-10：修 bug、对齐细节

AI 基建化流程（耗时 1.5 人天）：

  • 上午 2h：/bootstrap-design-system 跑 Step 1-3（AI 30 分钟 + 人审核 1.5h）
  • 下午 2h：设计师过 review.md、微调
  • 次日上午 2h：生成代码（Step 4）+ 组件清单（Step 5）
  • 次日下午 2h：CI 同步 workflow + 初始化 shadcn/ui

提升约 6 倍，更关键的是质量更高——AI 不会漏掉偏色、命名更一致、Dark Mode 从 Day 1 就有。

六、核心原则​

  1. Figma 是事实源，代码是派生物：永远不反向改代码硬编码
  2. 人确认每一个关键决策：设计系统是项目根基，错了后患无穷
  3. AI 不能自创 Token：找不到对应就停下来问
  4. 分层不可省：core + semantic 两层，否则后续做不了主题切换
  5. 建立 Sync 流程：bootstrap 只是开始，持续同步才是长期价值

七、反模式​

反模式后果正解
把 Figma 颜色值直接写到 tailwind.config设计改色要改 50 处Style Dictionary 单一事实源
一次性搞完美3 周后才开始写组件先搞 80% 上线，Sync 流程兜底
AI 自创 Token设计系统碎片化Hook 拦截 + 设计师确认
跳过 semantic 层Dark Mode / 主题切换做不了从 Day 1 就分 core/semantic
不建 Sync 流程半年后设计和代码严重漂移bootstrap 完就配 CI

八、延伸：老项目的设计系统审计​

同样的 /bootstrap-design-system 思路也适用于老项目审计——但目标不是"生成新代码"而是"发现漂移"：

/bootstrap-design-system figma.com/file/XXX --audit

# AI 会：
# 1. 扫描 Figma 的 "真实" 设计系统
# 2. 扫描代码的 "实际" 设计系统（grep hex colors、px values）
# 3. 对比出漂移：
#    - Figma 有但代码没用的 Token
#    - 代码有但 Figma 没的硬编码（红旗！）
#    - 语义不一致（Figma 的 primary vs 代码的 primary 不同）
# 4. 生成 refactor-plan.md

老项目做一次审计，通常能发现 20-40 个硬编码漏洞。

Q13: 一句话总结 AI 研发基建的核心原则​

答案：

"让好的 AI 使用方式成为默认选项，让差的使用方式成为困难选项。"

展开：

  • 通过 Gateway，让合规使用成为唯一选项（bypass 很麻烦）
  • 通过 Rules + Skills，让遵守规范成为默认（AI 自动按规范生成）
  • 通过 Slash Commands，让高效工作流变成一键操作
  • 通过 Hooks，让质量检查自动发生
  • 通过度量，让每个人都能看到进步

反过来说：不要依赖个人纪律。基建的价值就是把依赖纪律的事变成"自动发生"或"默认正确"。

相关链接​