团队协作新范式：如何在团队中高效使用 Opencode

当你个人使用 Opencode 获得效率提升后，下一个自然的问题就是：如何让整个团队都能享受到 AI 编程的红利？

本文将分享团队使用 Opencode 的最佳实践，帮助你的团队建立统一的 AI 协作规范。

为什么团队需要统一的 Opencode 配置？

在没有统一配置的情况下，团队成员各自使用 Opencode 可能会遇到以下问题：

• 代码风格不一致：每个人的 AI 生成的代码风格不同
• 重复配置工作：新成员需要花时间摸索最佳配置
• 上下文缺失：AI 不了解项目架构和团队规范
• 安全隐患：没有统一的权限控制和敏感信息保护

通过建立团队级别的配置规范，可以让所有成员在同一个"频道"上与 AI 协作。

团队配置的三个层级

1. 项目级配置（必须）

项目级配置存储在代码仓库中，所有团队成员共享。

配置文件位置：.opencode/ 目录

project-root/
├── .opencode/
│   ├── config.json          # 项目配置
│   ├── AGENTS.md            # 项目上下文
│   ├── prompts/             # 自定义提示词
│   └── mcp.json             # MCP 工具配置
├── .gitignore
└── ...

关键配置项：

{
  "modelPreferences": {
    "default": "claude-3-5-sonnet-20241022",
    "fast": "claude-3-5-haiku-20241022"
  },
  "codeStyle": {
    "language": "typescript",
    "framework": "react",
    "testFramework": "vitest"
  },
  "security": {
    "allowedDomains": ["api.company.com"],
    "sensitivePatterns": ["API_KEY", "SECRET", "PASSWORD"]
  }
}

2. 团队级规范（推荐）

通过 AGENTS.md 文件定义团队的开发规范和项目上下文。

AGENTS.md 示例：

# 项目上下文

## 项目简介
这是一个基于 React + TypeScript 的电商管理后台系统。

## 技术栈
- 前端：React 18 + TypeScript + Vite
- 状态管理：Zustand
- UI 组件：Ant Design 5.x
- 请求库：Axios + React Query
- 测试：Vitest + Testing Library

## 代码规范

### 命名约定
- 组件文件：PascalCase (UserProfile.tsx)
- 工具函数：camelCase (formatDate.ts)
- 常量：UPPER_SNAKE_CASE (API_BASE_URL)
- CSS Modules：kebab-case (user-profile.module.css)

### 组件结构
```typescript
// 1. 导入依赖
import React from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. 类型定义
interface Props {
  userId: string;
}

// 3. 组件实现
export const UserProfile: React.FC<Props> = ({ userId }) => {
  // hooks
  const { data, isLoading } = useQuery(...);
  
  // 事件处理
  const handleClick = () => {};
  
  // 渲染
  return <div>...</div>;
};

API 调用规范

• 所有 API 请求必须使用 React Query
• 错误处理统一使用 ErrorBoundary
• 接口定义放在 src/api/types/ 目录

测试要求

• 所有公共组件必须有单元测试
• 测试覆盖率不低于 80%
• 使用 describe 和 it 组织测试用例

项目结构

src/
├── api/              # API 接口定义
├── components/       # 公共组件
├── features/         # 功能模块
├── hooks/            # 自定义 Hooks
├── stores/           # 状态管理
├── utils/            # 工具函数
└── types/            # 类型定义

常见任务

创建新页面

1. 在 src/features/ 下创建功能目录
2. 创建页面组件、API 接口、类型定义
3. 在路由配置中注册
4. 编写单元测试

添加新 API

1. 在 src/api/types/ 定义接口类型
2. 在 src/api/ 实现请求函数
3. 使用 React Query 封装
4. 添加错误处理

注意事项

• 不要直接修改 node_modules
• 敏感信息使用环境变量
• 提交前运行 npm run lint 和 npm test
• commit message 遵循 Conventional Commits 规范

### 3. 个人级配置（可选）

个人配置存储在用户目录，不影响其他成员。

**配置文件位置**：`~/.config/opencode/config.json`

```json
{
  "apiKeys": {
    "anthropic": "sk-ant-xxx",
    "openai": "sk-xxx"
  },
  "shortcuts": {
    "quickChat": "Cmd+K",
    "inlineEdit": "Cmd+I"
  },
  "ui": {
    "theme": "dark",
    "fontSize": 14
  }
}

团队协作最佳实践

1. 建立 AI 使用规范

创建团队的 AI 使用指南文档：

AI_GUIDELINES.md：

# AI 编程使用指南

## 何时使用 AI

✅ 推荐使用：
- 生成样板代码（组件模板、API 接口）
- 重构现有代码
- 编写单元测试
- 生成文档和注释
- 代码审查和优化建议

❌ 不推荐使用：
- 涉及敏感数据的操作
- 核心业务逻辑的首次实现（需人工审查）
- 安全相关的代码
- 性能关键路径

## 提示词模板

### 创建组件
"创建一个 {组件名} 组件，功能是 {功能描述}。
要求：
- 使用 TypeScript
- 遵循项目的组件结构规范
- 包含 Props 类型定义
- 添加必要的注释"

### 重构代码
"重构以下代码，要求：
- 提取重复逻辑
- 改善可读性
- 保持功能不变
- 添加类型注解"

### 编写测试
"为以下组件编写单元测试：
- 测试所有 Props 组合
- 测试用户交互
- 测试边界情况
- 使用 Vitest 和 Testing Library"

## 代码审查清单

AI 生成的代码提交前必须检查：
- [ ] 符合项目代码规范
- [ ] 类型定义完整
- [ ] 没有硬编码的敏感信息
- [ ] 错误处理完善
- [ ] 有必要的注释
- [ ] 通过所有测试

2. 统一模型选择策略

根据不同场景选择合适的模型：

配置示例：

{
  "modelPreferences": {
    "default": "claude-3-5-sonnet-20241022",
    "fast": "claude-3-5-haiku-20241022",
    "review": "gpt-4-turbo",
    "local": "qwen2.5-coder:7b"
  }
}

3. 建立代码审查流程

AI 生成的代码也需要人工审查：

审查流程：

1. AI 生成代码 → 开发者审查
2. 提交 PR → 团队成员 Code Review
3. CI 检查 → 自动化测试和 Lint
4. 合并主分支 → 部署

Code Review 重点：

• AI 是否正确理解了需求？
• 代码是否符合团队规范？
• 是否有安全隐患？
• 测试覆盖是否充分？
• 性能是否有问题？

4. 知识沉淀与分享

建立团队的 AI 使用知识库：

知识库结构：

docs/
├── ai-guidelines.md          # AI 使用指南
├── prompt-templates/         # 提示词模板库
│   ├── component.md
│   ├── api.md
│   └── test.md
├── best-practices/           # 最佳实践
│   ├── refactoring.md
│   └── testing.md
└── troubleshooting.md        # 常见问题

定期分享会：

• 每周分享一个 AI 使用技巧
• 展示优秀的 AI 协作案例
• 讨论遇到的问题和解决方案

新成员入职指南

第一天：环境配置

1. 安装 Opencode

   brew install opencode  # macOS
   

2. 克隆项目并安装依赖

   git clone <repo-url>
   cd project
   npm install
   

3. 配置 API Key

   • 从团队管理员获取 API Key
   • 配置到 ~/.config/opencode/config.json

4. 验证配置

   opencode --version
   opencode doctor  # 检查配置是否正确
   

第一周：熟悉规范

1. 阅读 AGENTS.md 了解项目上下文
2. 阅读 AI_GUIDELINES.md 了解 AI 使用规范
3. 尝试使用 AI 完成一个简单任务
4. 参加团队的 AI 使用分享会

第一个月：实战应用

1. 使用 AI 完成至少 3 个功能开发
2. 提交至少 5 次 Code Review
3. 分享一次自己的 AI 使用经验
4. 为知识库贡献至少 1 个提示词模板

成本控制策略

团队使用 AI 需要考虑成本：

1. 混合模型策略

{
  "modelPreferences": {
    "default": "claude-3-5-haiku-20241022",      // 日常开发用便宜的
    "complex": "claude-3-5-sonnet-20241022",     // 复杂任务用贵的
    "local": "qwen2.5-coder:7b"                  // 简单任务用本地
  }
}

2. 使用本地模型

对于简单任务，使用本地模型可以零成本：

# 安装 Ollama
brew install ollama

# 下载模型
ollama pull qwen2.5-coder:7b

# 配置 Opencode 使用本地模型

3. 设置使用配额

在团队配置中设置每月使用限额：

{
  "billing": {
    "monthlyLimit": 100,  // 美元
    "alertThreshold": 80  // 达到 80% 时提醒
  }
}

4. 监控使用情况

定期查看团队的 API 使用统计：

opencode usage --team --month 2025-06

安全与合规

1. 敏感信息保护

在 .opencode/config.json 中配置敏感信息模式：

{
  "security": {
    "sensitivePatterns": [
      "API_KEY",
      "SECRET",
      "PASSWORD",
      "TOKEN",
      "PRIVATE_KEY",
      ".*_SECRET.*"
    ],
    "redactInLogs": true
  }
}

2. 代码审查要求

所有 AI 生成的代码必须经过人工审查才能合并：

# .github/workflows/pr-check.yml
name: PR Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Check AI Generated Code
        run: |
          # 检查是否有 AI 生成的代码
          # 确保有人工审查记录

3. 数据隐私

• 不要将客户数据发送给 AI
• 使用本地模型处理敏感代码
• 定期审查 API 调用日志

效果评估

量化指标

• 开发效率：功能开发时间减少 30-50%
• 代码质量：Bug 率下降 20-30%
• 测试覆盖率：提升至 80% 以上
• 文档完整性：代码注释覆盖率 90% 以上

定性反馈

• 团队成员满意度调查
• Code Review 质量评估
• 新成员上手速度

小结

团队使用 Opencode 的关键是建立统一的规范和流程：

1. 统一配置：项目级配置 + 团队规范 + 个人偏好
2. 明确规范：什么时候用 AI，什么时候不用
3. 代码审查：AI 生成的代码也需要人工把关
4. 知识沉淀：建立团队的 AI 使用知识库
5. 成本控制：混合使用不同模型，控制开支
6. 安全合规：保护敏感信息，遵守公司规定

通过这些实践，你的团队可以在保证代码质量的前提下，大幅提升开发效率。

想了解更多团队协作技巧？查看 最佳实践指南。