#实战案例

本章给出三个由浅入深的端到端场景，展示 AGENTS.md、沙箱、Skills 与 MCP 如何组合。

#案例 1：遗留模块重构

背景： legacy/billing.js 单文件 2000 行，无测试。

#步骤

1. 分支与 AGENTS.md

git checkout -b refactor/billing-module

在 legacy/AGENTS.md：

# legacy/AGENTS.md
- 重构时保持对外 export 名称不变
- 每拆出一个模块必须补对应单元测试
- 测试命令：`npm test -- legacy/billing`

2. 只读探索（可选 Subagent 或首轮只读）

codex --sandbox read-only --ask-for-approval on-request

分析 legacy/billing.js 的职责边界， propose 拆分为 payment、invoice、tax 三个模块的文件树，不要改文件。

3. 实施重构

codex --sandbox workspace-write --ask-for-approval on-request

按上一步方案拆分 legacy/billing.js，补测试，运行 npm test -- legacy/billing 直到通过。

4. 审查

git diff --stat
npm test
# 或使用 Codex 本地 code review 能力

要点： 探索与实施 分阶段 + 目录级 AGENTS.md 约束行为。

#案例 2：自动化 Code Review Skill

目标： 每次 PR 前用固定清单审查 staged diff。

#创建 Skill .agents/skills/pre-commit-review/SKILL.md

---
name: pre-commit-review
description: 审查 git staged diff。用户提到 review、提交前检查、PR 自检时使用。
---

1. 运行 `git diff --cached` 获取变更。
2. 检查：是否有 debug 语句、密钥、过大文件、缺少测试。
3. 按严重程度输出：BLOCKER / WARN / INFO。
4. 不要修改文件，仅输出报告。

#使用

git add -p
codex

$pre-commit-review

扩展： 结合 GitHub MCP，在 Skill 中增加「对比 base 分支 diff」步骤。

#案例 3：Issue → 分支 → PR（Cloud + 本地混合）

背景： 团队在 GitHub 用 Issue 跟踪，希望 Codex Cloud 异步实现，本地只做验收。

#Cloud 侧

1. 在 chatgpt.com/codex 连接 GitHub 仓库
2. 选择环境（Node 版本、测试命令与 AGENTS.md 一致）
3. 发起任务：「Fix #42: 登录超时未刷新 token」

#本地侧

git fetch
git checkout codex/issue-42-fix
npm test
codex --sandbox read-only "对照 Issue #42 验收标准做 checklist"

#PR 评论

在 PR 中 @codex add regression test for token refresh 追加迭代。

要点： AGENTS.md 在 Cloud 与 CLI 同源，避免环境漂移。

#案例 4：CI 中生成 Release Notes

# .github/workflows/release-notes.yml（示意）
- name: Codex release notes
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    codex exec \
      --sandbox read-only \
      --ask-for-approval never \
      --output-last-message \
      "根据 git log $(git describe --tags --abbrev=0)..HEAD 生成用户向 changelog，Markdown 格式" \
      > RELEASE_NOTES.md

要点： CI 用 read-only + 无审批，且 checkout 应限制写权限。

#反模式（避免）

#下一步

• 资源与延伸阅读：官方文档与社区
• Agent Skills：把案例 2 打包成 Plugin