实战 A5：Codex 大型项目实战——微服务、多人协作与 Monorepo 策略

实战教程系列 系列 A：A1 配置实战 | A2 日常开发 | A3 审查与质量 | A4 自动化 CI/CD | A5 大型项目 ← 本文

Codex 在个人项目中用起来很顺手——但在 10 个微服务、20 个开发者的团队中，没有策略的使用会变成灾难。本文聚焦大型项目中的三个核心挑战：架构认知、团队协作、质量保障。

案例 1：10 个微服务的 Codex 配置策略

背景：一个电商平台由 10 个微服务组成：

platform/
  .codex/
    config.toml          # 全局默认配置
    AGENTS.md             # 全局架构说明（关键！）
    skills/
      db-migration/       # 共享数据库迁移 skill
      release/            # 共享发布流程 skill
  services/
    gateway/              # API 网关 (Go)
      .codex/config.toml
    users/                # 用户服务 (Go)
    orders/               # 订单服务 (Go)
    products/             # 商品服务 (Go)
    payment/              # 支付服务 (Go)
    notification/         # 通知服务 (Node.js)
      .codex/config.toml  # Node.js 专属配置
    analytics/            # 分析服务 (Python)
      .codex/config.toml  # Python 专属配置
    web/                  # 前端 (Next.js)
    admin/                # 管理后台 (Next.js)
    mobile-api/           # 移动端 BFF (Go)

全局 AGENTS.md——架构认知是大型项目的第一要务

在编写 AGENTS.md 之前，先理清服务间的依赖关系：

Codex 在大型项目中最容易犯的错误是缺乏架构边界意识——它可能在一个服务中引用了另一个服务的内部实现，或者修改了一个共享类型却不知道下游影响。

全局 AGENTS.md 的首要任务就是建立这个边界认知：

# Platform Architecture

## Service Map
| Service | Language | Port | Database | Depends On |
|---------|----------|------|----------|------------|
| gateway | Go | 8080 | — | users, orders, products |
| users | Go | 8081 | PostgreSQL | — |
| orders | Go | 8082 | PostgreSQL | users, products, payment |
| products | Go | 8083 | PostgreSQL | — |
| payment | Go | 8084 | PostgreSQL | orders |
| notification | Node.js | 8085 | Redis | users, orders |
| analytics | Python | 8086 | ClickHouse | orders, products |
| web | Next.js | 3000 | — | gateway |
| admin | Next.js | 3001 | — | gateway |
| mobile-api | Go | 8087 | — | gateway |

## Critical Rules
- **Never** import from another service's internal packages
- Shared types live in services/shared-types/ — all services depend on this
- Service-to-service communication uses gRPC (proto files in each service's proto/ dir)
- Each service has its own database — no cross-service DB queries
- Config changes to a service require running its own test suite, not just the changed service

## When Working Across Services
1. Identify all affected services using the Service Map above
2. For each affected service, start Codex in that service's directory
3. Run that service's test suite before and after changes

全局 config.toml——默认值 + 按语言覆盖

# platform/.codex/config.toml — 全局默认
model = "gpt-5.5"
model_reasoning_effort = "high"
default_sandbox_mode = "workspace-write"

[features]
multi_agent = true
goals = true

Go 服务覆盖（services/orders/.codex/config.toml）：

model = "gpt-5.5"
[shell_environment_policy]
include_only = ["PATH", "HOME", "DATABASE_URL", "GRPC_TARGET"]

Node.js 服务覆盖（services/notification/.codex/config.toml）：

model = "gpt-5.4-mini"  # Node 服务用轻量模型
[shell_environment_policy]
include_only = ["PATH", "HOME", "REDIS_URL"]

案例 2：跨服务重构——保持一致性

场景：把用户 ID 从整数改为 UUID，涉及 6 个服务。

Step 1：影响分析

先在平台根目录启动 Codex：

/plan 分析将用户 ID 从 int 改为 UUID 的影响范围。
查看所有服务的代码和 proto 文件，列出：
1. 需要修改的 proto 定义
2. 需要修改的数据库 schema
3. 需要修改的 Go/Node/Python 代码
4. 修改的推荐顺序

Codex 输出影响分析：

1. services/shared-types/user.ts — ID 类型定义
2. services/users/proto/user.proto — gRPC 定义
3. services/users/ — 数据库 migration + handler
4. services/orders/ — 引用 user_id 的字段
5. services/payment/ — 引用 user_id 的字段
6. services/notification/ — 引用 user_id 的逻辑
7. services/web/ — 前端类型更新

Step 2：按依赖顺序逐个服务修改

关键原则：一次只改一个服务，改完就跑测试。用 Cloud Tasks 可以并行修改无依赖关系的服务。

# 在 services/users/ 目录
codex

/plan 将 users 服务的用户 ID 从 int 改为 UUID（PostgreSQL）。
先创建 migration，再修改 handler，最后更新 proto 定义。
运行 users 服务的完整测试套件。

# 同时——在另一个终端（或 Cloud Task）
# services/orders/ 和 services/payment/ 都依赖 users，但互不依赖

# 终端 2: orders
codex
/plan 将 orders 服务中所有 user_id 字段从 int 改为 UUID。
在 proto 和 Go 代码中同步修改。运行测试。

# 终端 3 (Cloud Task): payment
codex cloud exec --env go-env "
将 payment 服务中所有 user_id 字段从 int 改为 UUID。
运行测试并报告结果。
"

Step 3：集成验证

所有服务修改完成后，在平台根目录运行集成测试：

在 platform 根目录运行 docker compose up -d，
然后运行所有服务的集成测试套件。
如果有服务测试失败，定位原因并修复。

案例 3：20 人团队的 Codex 规范

团队级 AGENTS.md 分层

platform/
  AGENTS.md                 ← L1: 公司级工程规范（Git workflow, 通用约定）
  .codex/
    AGENTS.md               ← L2: 平台级架构约束（服务边界、通信协议）
  services/orders/
    .codex/
      AGENTS.md             ← L3: 服务级约定（Go 风格、测试策略）

L1——公司级（由工程 VP 维护）：

## Company-Wide Standards
- Commit format: type(scope): JIRA-123 description
- PR requires 1 approval + CI pass
- Production changes require a runbook entry
- Use Trunk-Based Development

L2——平台级（由 Tech Lead 维护）：

## Platform-Specific Rules
- See Service Map above for service boundaries
- gRPC proto changes are backward-compatible by default
- Database migrations are forward-compatible (additive only)

L3——服务级（由服务 Owner 维护）：

## Orders Service
- Use Repository pattern for data access
- All handlers must have OpenTelemetry spans
- Order state machine: pending → confirmed → shipped → delivered

Skills 共享与版本管理

团队 Skills 放在 platform/.codex/skills/，通过 Git 版本控制：

.codex/skills/
  db-migration/SKILL.md     ← v1.2: 添加了回滚方案生成
  incident-response/SKILL.md ← v2.0: 新增 Slack 通知步骤
  release/SKILL.md           ← v1.1: 更新了 ECR 仓库地址

当 Skills 更新时，团队成员通过 git pull 自动获取最新版本。

代码审查流水线

关键设计：Codex 自动审查做"可自动化的检查"（类型错误、测试缺失、常见模式违规），人工审查聚焦在高层次决策上。

核心原则：让 Codex 在大型项目中不跑偏

铁律 1：架构即 AGENTS.md

AGENTS.md 不是可选的——在大型项目中它是 Codex 理解项目边界的唯一来源。Service Map、通信协议、数据库归属——这些信息必须写在 AGENTS.md 中。

铁律 2：一次一个服务

永远不要在一个 Codex 会话中修改多个服务。切换服务就切换目录，开启新会话。Codex 的上下文窗口有限，跨服务的认知会随着对话增长而衰减。

铁律 3：修改前先分析

涉及跨服务变更时，先用 /plan 做影响分析。不要直接让 Codex"把 user_id 改成 UUID"——它可能不知道哪些文件需要改。

铁律 4：配置即文档

.codex/config.toml 和 AGENTS.md 随代码一起版本控制。新成员 clone 仓库后，Codex 环境立即可用——不需要口头传授配置经验。

铁律 5：渐进式信任

在一个服务上先用 Read Only 模式让 Codex 熟悉代码。几天后切换到 Auto。如果 Codex 持续做出正确决策，再考虑配合 Automations 做无人值守操作。

总结

大型项目中的 Codex 策略可以浓缩为一张表：

下一章：系列 C：双工具协同实战

实操清单

• 编写全局 AGENTS.md，包含 Service Map（服务名、语言、端口、数据库、依赖）
• 在全局 AGENTS.md 中写明跨服务规则（禁止跨服务 import、通信协议、数据库归属）
• 为每个服务创建独立的 .codex/config.toml
• 跨服务变更前先运行 /plan 做影响分析
• 按依赖顺序逐个修改服务，每个服务改完就跑测试
• 用 Cloud Tasks 并行修改无依赖关系的服务
• 建立团队级 AGENTS.md 分层：L1 公司级 → L2 平台级 → L3 服务级
• 团队 Skills 纳入 Git 版本控制，更新走正常 PR 流程
• 设计代码审查流水线：Codex 自动初审 → 人工聚焦架构决策