团队 AI 工作流——.cursorrules 共享、成本管理与 AI Review 流程落地

第17章：团队 AI 工作流——.cursorrules 共享、成本管理与 AI Review 流程落地

个人用 AI 编程，配置随意、效果参差。团队用 AI 需要解决三个问题：一致性（所有人生成的代码风格相同）、安全性（不泄露生产数据）、可控成本（API 用量有人监控）。本章给出每个问题的具体方案：分层 .cursorrules 管理、GitHub Actions AI Review 集成、API Key 管控，以及分阶段推行策略。

本章学习目标： 掌握 .cursorrules 的分层结构和团队 Code Review 流程；能独立配置 GitHub Actions AI Review CI；了解 API Key 管理最佳实践和成本监控方法；拿到一份开箱即用的新人培训清单。

为什么团队场景和个人不同

三个核心问题：

1. 怎么让所有人的 AI 输出风格一致？→ 统一的 .cursorrules 提交到 Git
2. 怎么控制 AI 使用成本？→ API Key 管理 + 用量监控
3. 怎么把 AI Review 变成团队流程？→ GitHub Actions CI 集成

.cursorrules 的团队管理

分层结构设计

项目根目录/
├── .cursorrules          ← 所有人共用的项目规则（必须提交到 Git）
├── .cursorrules.local    ← 个人偏好（加入 .gitignore，不提交）
└── src/
    └── payments/
        └── .cursorrules  ← 支付模块的额外规则（敏感代码，更严格）

三层的作用不同：项目根的 .cursorrules 定义技术栈、命名规范、安全规范；个人 .cursorrules.local 存放个人偏好（比如"我喜欢注释中文"）；模块级 .cursorrules 处理特定业务域的额外规则（支付模块不能用 console.log 打印金额）。

团队 .cursorrules 最小有效模板

# ============================================================
# [公司名] 工程团队 AI 编码标准
# 最后更新：2026-04-26 | 维护人：架构组
# ============================================================

## 技术栈
- 后端：Python 3.12 + FastAPI + SQLAlchemy 2.0
- 前端：TypeScript 5 + React 18 + Tailwind CSS v3
- 数据库：PostgreSQL 16（主）+ Redis 7（缓存）
- 部署：Docker + Kubernetes + GitHub Actions CI

## 代码规范
- Python 遵循 PEP 8，使用 ruff 格式化，不手写 flake8 注释
- TypeScript strict: true，禁止 any，除非有注释说明原因
- 所有 public 函数必须有类型注解（Python）或 TypeScript 类型
- 单函数不超过 50 行；超过时拆分并注释拆分理由

## 安全规范（AI 生成代码必须遵守）
- 禁止字符串拼接构建 SQL，必须参数化查询或 ORM
- 禁止硬编码任何 API Key、密码、token——一律从环境变量读取
- 用户输入在使用前必须经过 Pydantic 或 Zod 校验
- 每个 API 端点必须有认证检查，除非明确标注 @public

## 错误处理
- 禁止空 except/catch 块（必须至少记录日志）
- 面向用户的错误信息不暴露堆栈跟踪或数据库细节
- 使用 structlog 记录日志，不用 print 调试

## AI 生成代码的额外要求
- 生成完代码后，主动检查是否有硬编码密钥或 SQL 拼接
- 复杂逻辑必须加注释，注释解释"为什么"而不只是"做什么"
- 如果有多种实现方式，选最可读的，并说明为什么不选其他方案

修改 .cursorrules 的 PR 规范

.cursorrules 的每次修改都影响全团队的 AI 行为，必须像修改核心架构一样认真对待。PR 描述里必须包含：

## .cursorrules 变更说明

### 变更内容
新增：禁止在 React 组件里直接使用 fetch，必须通过 useQuery

### 原因
过去两周有 3 个 PR 因为组件里直接 fetch 导致重复请求和页面闪烁
（见 PR #412、#438、#451）

### 对 AI 行为的影响
加这条规则后，Cursor 生成 API 调用代码时会自动用 useQuery
而不是 useEffect + fetch，避免重复请求问题

### 审批要求
需要至少 1 位 Tech Lead 或架构师审批后才能合并

API Key 管理与成本控制

正确的 Key 管理流程

错误做法（团队里最常见）：每个开发者用自己的个人 API Key，Key 直接存在 .env.local，没有用量监控，月底对账单一无所知。

正确做法：

团队共用一个 Anthropic 组织账号
  ↓
在 Anthropic Console 为每个项目创建单独的 API Key
（项目A一个Key，项目B一个Key，便于追踪成本归属）
  ↓
API Key 存入公司密钥管理服务
（AWS Secrets Manager / HashiCorp Vault / Doppler）
  ↓
在 Anthropic Console 为每个 Key 设置月预算上限
（超出自动停用，不会无限扣费）
  ↓
每周发一次用量报告邮件到团队 Slack

成本监控脚本

"""
cost_monitor.py — 每周 AI API 成本报告
用法：python cost_monitor.py | mail -s "Weekly AI Cost Report" [email protected]
"""
import anthropic
from datetime import datetime, timedelta

# Claude 模型价格（美元/百万 tokens，2026年）
PRICING = {
    "claude-opus-4":     {"input": 15.0,  "output": 75.0},
    "claude-sonnet-4-6": {"input": 3.0,   "output": 15.0},
    "claude-haiku-4":    {"input": 0.8,   "output": 4.0},
}

def calc_cost(input_tokens: int, output_tokens: int, model: str) -> float:
    p = PRICING.get(model, {"input": 3.0, "output": 15.0})
    return input_tokens * p["input"] / 1_000_000 + output_tokens * p["output"] / 1_000_000

def weekly_report():
    end = datetime.now()
    start = end - timedelta(days=7)

    print(f"AI API 用量报告 ({start.date()} ~ {end.date()})")
    print("=" * 50)

    # 实际生产中从你的日志系统或 Anthropic Console 数据导出
    usage_by_model = {
        "claude-sonnet-4-6": {"input": 2_500_000, "output": 800_000},
        "claude-haiku-4":    {"input": 5_000_000, "output": 1_200_000},
    }

    total = 0.0
    for model, usage in usage_by_model.items():
        cost = calc_cost(usage["input"], usage["output"], model)
        total += cost
        print(
            f"{model}:\n"
            f"  输入: {usage['input']:,} tokens\n"
            f"  输出: {usage['output']:,} tokens\n"
            f"  费用: ${cost:.2f}"
        )

    print(f"\n本周合计: ${total:.2f}")
    if total > 500:
        print("[警告] 本周费用超过 $500，请核查用量异常")

if __name__ == "__main__":
    weekly_report()

AI Review 流程落地：分阶段推行

直接把 AI Review 设为 required check 会让团队反感。分三阶段，让大家先看到价值再逐步强化：

阶段1（第1个月）：可选的本地 Review

开发者自愿在提交前用命令行检查，不强制，先让大家习惯 AI Review 的存在：

# 在 package.json 或 Makefile 里加一个便捷命令
# 用法：make ai-review

ai-review:
    git diff origin/main...HEAD | \
    python -c "
import sys, anthropic
diff = sys.stdin.read()
if len(diff) < 50:
    print('No changes to review.')
    exit(0)
client = anthropic.Anthropic()
resp = client.messages.create(
    model='claude-haiku-4',
    max_tokens=1024,
    system='你是代码审查助手。扫描以下 diff，只报告安全漏洞和明显 bug。没问题就输出 LGTM。',
    messages=[{'role': 'user', 'content': diff[:4000]}]
)
print(resp.content[0].text)
"

阶段2（第2个月）：CI 集成，自动 PR Review

# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install deps
        run: pip install anthropic PyGithub

      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          REPO: ${{ github.repository }}
        run: python .github/scripts/ai_review.py

# .github/scripts/ai_review.py
import os
import subprocess
import anthropic
from github import Github

SYSTEM = """你是资深工程师，审查 PR diff。

输出格式：
## AI Review 摘要
（1句话说明变更内容）

## 问题
（按严重度排序：[HIGH] / [MEDIUM] / [LOW] 文件:行号 - 描述）
（如无问题，输出"未发现明显问题"）

## 建议
（具体改进建议，有代码示例更好）

只关注：安全漏洞、明显 bug、性能问题。不报告代码风格。"""

def run():
    diff = subprocess.run(
        ["git", "diff", "origin/main...HEAD"],
        capture_output=True, text=True
    ).stdout[:6000]

    if not diff:
        print("No diff, skipping.")
        return

    client = anthropic.Anthropic()
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system=SYSTEM,
        messages=[{"role": "user", "content": f"请审查：\n\n{diff}"}]
    )
    comment = resp.content[0].text

    gh = Github(os.environ["GITHUB_TOKEN"])
    repo = gh.get_repo(os.environ["REPO"])
    pr = repo.get_pull(int(os.environ["PR_NUMBER"]))
    pr.create_issue_comment(
        f"**AI Code Review** (claude-sonnet-4-6)\n\n{comment}\n\n"
        f"---\n*自动生成，仅供参考，最终决定由人工审查者负责。*"
    )

if __name__ == "__main__":
    run()

阶段2 注意： 不要设为 required check。只作为 PR comment 存在，供人工审查者参考。这样即使 AI Review 有误判，也不会阻塞正常发布。等团队对 AI Review 的准确率建立信任后，再考虑升级。

阶段3（第3个月+）：定期全库安全扫描

不只看 diff，每周对整个代码库做一次安全扫描，找出历史遗留的安全问题：

# .github/workflows/weekly-security-scan.yml
name: Weekly Security Scan
on:
  schedule:
    - cron: '0 9 * * 1'  # 每周一早9点
  workflow_dispatch:       # 支持手动触发

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run security scan
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 收集所有 Python 和 TypeScript 文件
          find src/ -name "*.py" -o -name "*.ts" -o -name "*.tsx" | \
          head -50 | \
          xargs cat | \
          python .github/scripts/security_scan.py

Cursor Business vs 个人版：采购决策

决策规则： 公司代码涉及用户个人数据、金融数据、商业机密，必须选 Business 版。Business 版的强制 Privacy Mode 是合规前提，每人多付 $20 值得。纯内部工具、开源项目可以用个人版。

新人培训清单

第1天
□ 申请 Cursor Business 席位（联系 IT）
□ 从团队模板库初始化 .cursorrules：
    curl -sL https://raw.githubusercontent.com/your-org/cursorrules/main/python-fastapi.cursorrules -o .cursorrules
□ 阅读 .cursorrules 全文，理解每条规则的原因
□ 用 Cursor 完成一个小任务：修复一个 bug，感受 AI 辅助流程

第1周
□ 掌握 Chat + @文件引用（用于问代码问题）
□ 掌握 Composer 多文件修改流程（用于实现新功能）
□ 跑一次 make ai-review，看看 AI Review 输出什么
□ 了解项目的安全红线：哪些数据不能粘给 AI

第1个月
□ 建立自己的 Prompt 模板（代码审查、文档生成、调试各一个）
□ 能判断什么任务适合用 Composer，什么任务应该手写
□ 参与一次 .cursorrules 变更的 PR 审查，理解规则演进过程

本章要点

1. .cursorrules 必须提交到 Git： 不在版本控制里的团队规则，就是没有规则。分层结构（项目级/个人级/模块级）让共性和个性各得其所。
2. 修改 .cursorrules 要像修改架构一样认真： 每条规则都影响全团队 AI 输出，PR 描述必须说明修改原因和对 AI 行为的具体影响。
3. API Key 按项目隔离，设预算上限： 在 Anthropic Console 为每个项目创建独立 Key，设月预算上限，用密钥管理服务存储，不要用个人 Key 跑公司业务。
4. AI Review 分阶段推行，不要一步到位： 先可选命令行工具 → 再 CI 自动 comment → 最后定期全库扫描。强制 required check 会让团队反感，先建立信任再强化。
5. 涉及敏感数据必须用 Business 版： 强制 Privacy Mode 不是可选项，是合规前提。每人多 $20 换来代码不用于训练和统一管理能力，值得。

下一章讲 AI 生成代码的安全审查：6 类常见安全漏洞的识别与修复，每类附可运行的反例和正例代码。