agency-agents-zh Documentation

1. Project Overview & Quickstart (jnMetaCode/agency-agents-zh) Copy Chapter

File: README.md Copy Chapter

agency-agents 中文版（AI 智能体专家团队）

🌐 简体中文 | 繁體中文 | English (upstream)

268 个即插即用的 AI 专家角色 — 覆盖工程、设计、营销、产品、游戏、安全、GIS、金融等 20 个部门。不是通用提示词模板，每个智能体都有独立的人设、专业流程和可交付成果。支持 Claude Code / Cursor / Copilot 等 18 种 AI 编程工具。

agency-agents 的中文社区版。在完整翻译上游的基础上，新增了 50 个中国市场原创智能体（小红书、抖音、微信、B站、飞书、钉钉等平台运营，以及跨境电商、政务ToG、医疗合规、Qt 工业上位机、机械设计、畜禽养殖档案核对等垂直领域）。

想更好地用起来，或想给团队打造统一的智能体工作台？下载桌面客户端（原生 App，免装 Node，macOS / Windows / Linux），或在线体验 ao.aiolaola.com/experts。

📊 项目规模 Copy Section

📖 官方配套课程 → AI 专家团队实战（33 节，免费）：手把手把这仓 268 位专家用成一支团队——单兵点名、自动组队、一人公司全流程，桌面端零代码教学。另有 从零学会 AI 编程（180 节）＋ 从零构建 AI 智能体（40 节）

🌍 Also available in English · 日本語 · Español · 한국어 · 繁體中文

🙏 赞助商  _{想出现在这里？联系 [[email protected]](mailto:[email protected])} Copy Chapter

感谢 APINEBULA 大屏赞助本项目！APINEBULA 是银河录像局旗下的企业级 AI 聚合平台，背靠大平台资源，面向开发者、团队与企业用户提供稳定、高性价比的大模型 API 接入服务。平台聚合 Claude、GPT、Gemini 等主流满血模型，一个接口接入全球顶尖 AI 大模型，各大模型价格低至 1 折起，支持企业级高并发、正式合同、对公打款与开票服务，适合 AI 编程、Agent 开发、业务系统集成等多种场景！

🎁 通过此链接注册并在充值时填写 "agent" 优惠码可享九折优惠！

| | 感谢 火山引擎 赞助了本项目！火山引擎AI巅峰盛惠来袭！豆包大模型限时5折起，19元即可入手约440万Tokens文本模型，新客首单再享AI统一节省计划。从文本生成、图像创作到视频合成、语音复刻，全模态AI能力一站式配齐。开发者专属编程模型套餐2.5折订阅，支持Kimi-K2.7、GLM-5.2等主流模型。

🎁 注册即领2500万Tokens，立即访问火山引擎活动页面抢购。 |
| --- | --- |

🚀 让角色库跑起来 · Agency Orchestrator Copy Chapter

一句话，让多个 AI 专家自动组队协作，几分钟交付完整方案。

npm install agency-orchestrator
ao compose "帮我写一篇关于 AI Agent 的深度分析文章" --run

不想用命令行？ 下载桌面客户端（原生 App，免装 Node，macOS / Windows / Linux），或在线体验 ao.aiolaola.com/experts。

零代码编排 · DAG 并行 · 断点续跑 · 10 种大模型（7 种免 key）· 现成模板开箱即用 —— 了解 Agency Orchestrator →

🖼️ 在线浏览全部专家（无需安装） Copy Chapter

搜索 / 按部门筛选 / 查看与复制每位专家的完整提示词 —— 全部 268 位，直接在浏览器里看：

这是什么？ Copy Chapter

一套开箱即用的 AI 角色库。每个智能体都有明确的身份定义、关键规则、工作流程和交付物，安装到你的 AI 编程工具后用自然语言激活。

和普通提示词的区别：普通提示词告诉 AI "你是一个专家"；这里的智能体定义了专家怎么思考、怎么做事、交付什么。例如安全工程师会按 OWASP Top 10 逐项审查代码，小红书运营专家会输出完整的种草笔记策略和达人合作方案。

快速开始 Copy Chapter

方式一：一键安装到你的 AI 工具 Copy Section

支持 18 种主流 AI 编程工具，一条命令搞定：

# 自动检测已安装的工具，一键安装
./scripts/install.sh

# 或指定安装到特定工具
./scripts/install.sh --tool openclaw       # OpenClaw ⭐ 推荐
./scripts/install.sh --tool claude-code    # Claude Code
./scripts/install.sh --tool copilot        # GitHub Copilot
./scripts/install.sh --tool cursor         # Cursor
./scripts/install.sh --tool kiro           # Kiro (Amazon)
./scripts/install.sh --tool trae           # Trae
./scripts/install.sh --tool opencode       # OpenCode
./scripts/install.sh --tool aider          # Aider
./scripts/install.sh --tool windsurf       # Windsurf
./scripts/install.sh --tool antigravity    # Antigravity
./scripts/install.sh --tool gemini-cli     # Gemini CLI
./scripts/install.sh --tool qwen           # Qwen Code
./scripts/install.sh --tool codex          # Codex CLI
./scripts/install.sh --tool deerflow       # DeerFlow 2.0 (ByteDance)
./scripts/install.sh --tool workbuddy      # WorkBuddy (Tencent)
./scripts/install.sh --tool codewhale      # CodeWhale (原 DeepSeek-TUI)
./scripts/install.sh --tool hermes         # Hermes Agent (NousResearch)
./scripts/install.sh --tool qoder          # Qoder

Claude Code 和 GitHub Copilot 可直接安装；其他工具需先运行 ./scripts/convert.sh 转换格式。

🔥 OpenClaw 用户快速上手 Copy Section

OpenClaw 是目前社区用户最多的集成方式，每个智能体会拆分为三个文件：SOUL.md（身份人设）+ AGENTS.md（业务能力）+ IDENTITY.md（简介），天然支持多智能体协作编排。

./scripts/convert.sh --tool openclaw   # 第一步：转换为 SOUL.md 格式
./scripts/install.sh --tool openclaw   # 第二步：安装到 ~/.openclaw/

安装后重启 OpenClaw 网关即可使用。

方式二：手动复制 Copy Section

# Claude Code / GitHub Copilot（直接复制即可）
cp -r marketing/*.md ~/.claude/agents/

# 在 Claude Code 中激活：
# "激活前端开发者模式，帮我构建一个 React 组件"

方式三：作为提示词参考 Copy Section

浏览下方智能体列表，复制/改编你需要的内容！

智能体阵容 Copy Chapter

🛠️ 工程部 Copy Section

构建未来，一个 commit 一个脚印。

🎨 设计部 Copy Section

让产品好看、好用、有惊喜。

📢 营销部 Copy Section

一个真实互动一个粉丝地增长。

国内平台：

⭐ 标记的是本项目原创，更贴合国内实操。其余为上游英文版翻译。

出海营销：

通用：

💰 付费媒体部 Copy Section

精准投放，每一分预算都花在刀刃上。

💼 销售部 Copy Section

从线索到成交，让每一单都有章法。

🏦 金融部 Copy Section

让每一笔钱都清清楚楚。

👔 人力资源部 Copy Section

找对人、用好人、留住人。

⚖️ 法务部 Copy Section

合规是底线，风控是生命线。

🚚 供应链部 Copy Section

从工厂到用户，每一环都不掉链子。

📦 产品部 Copy Section

在正确的时间做正确的事。

📋 项目管理部 Copy Section

让项目按时按质交付。

🧪 测试部 Copy Section

打破一切，让用户不必承受。

🤝 支持部 Copy Section

运营的中流砥柱。

🔬 专项部 Copy Section

不走寻常路的专家。

🥽 空间计算部 Copy Section

构建下一代空间交互体验。

🎮 游戏开发部 Copy Section

从独立游戏到 3A 大作，全引擎覆盖。

通用：

Unity：

Unreal Engine：

Blender：

Godot：

Roblox Studio：

📖 学术部 Copy Section

为叙事设计、世界构建和文化研究提供学术级支撑。

🎯 战略部 Copy Section

从发现到运营的全流程战略指导。详见 strategy/ 目录。

工具集成 Copy Chapter

支持 18 种主流 AI 编程工具，通过 scripts/ 目录下的脚本实现格式转换和一键安装。

支持的工具 Copy Section

使用方法 Copy Section

# 第一步：转换格式（Claude Code 和 GitHub Copilot 可跳过此步）
./scripts/convert.sh                    # 转换为所有工具格式
./scripts/convert.sh --tool cursor      # 只转换 Cursor 格式

# 第二步：安装到本地
./scripts/install.sh                    # 自动检测并安装
./scripts/install.sh --tool cursor      # 安装到指定工具

# 检查智能体文件格式
./scripts/lint-agents.sh

各工具安装说明 Copy Section

⭐ OpenClaw（推荐）

OpenClaw 会将每个智能体拆分为三个文件，天然支持多智能体协作：

• SOUL.md — 身份、记忆、沟通风格、关键规则
• AGENTS.md — 核心使命、技术交付物、工作流程
• IDENTITY.md — 名称与简介

./scripts/convert.sh --tool openclaw
./scripts/install.sh --tool openclaw

# 安装后重启 OpenClaw 网关
openclaw gateway restart

Claude Code

智能体直接从仓库复制到 ~/.claude/agents/，无需转换。

./scripts/install.sh --tool claude-code

在 Claude Code 中激活：

激活前端开发者模式，帮我审查这个组件。

GitHub Copilot

智能体直接从仓库复制到 ~/.github/agents/ 和 ~/.copilot/agents/，无需转换。

./scripts/install.sh --tool copilot

在 GitHub Copilot 中激活：

使用前端开发者智能体帮我审查这个组件。

Antigravity (Gemini)

转换为 Antigravity skill 格式并安装到 ~/.gemini/antigravity/skills/。

./scripts/convert.sh --tool antigravity
./scripts/install.sh --tool antigravity

Gemini CLI

转换为 Gemini CLI 扩展格式并安装到 ~/.gemini/extensions/agency-agents/。

./scripts/convert.sh --tool gemini-cli
./scripts/install.sh --tool gemini-cli

Qwen Code

转换为 Qwen Code SubAgent 格式并安装到项目目录 .qwen/agents/。

./scripts/convert.sh --tool qwen
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool qwen

在 Qwen Code 中激活：

使用前端开发者智能体帮我审查这个组件。

提示：安装后在 Qwen Code 中运行 /agents manage 刷新，或重启会话。

Cursor

每个智能体会变成一个 .mdc 规则文件，安装到项目目录 .cursor/rules/。

Cursor 使用 "智能匹配"模式（alwaysApply: false）：AI 根据每个规则的 description 字段自动判断是否相关，相关时自动引用完整内容。

安装：

# 第一步：转换格式（在仓库目录运行）
./scripts/convert.sh --tool cursor

# 第二步：安装到项目（在你的项目目录运行）
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool cursor

⚠️ 重要：建议精选安装

全部安装 186 个规则会导致 Cursor 需要扫描大量 description 来判断相关性，可能影响匹配准确度。推荐做法：

# 方法一：全量安装后删除不需要的
/path/to/agency-agents-zh/scripts/install.sh --tool cursor
# 然后手动删除 .cursor/rules/ 中不需要的 .mdc 文件，保留 10-20 个常用的

# 方法二：只复制你需要的智能体（转换后）
./scripts/convert.sh --tool cursor
mkdir -p /your/project/.cursor/rules
cp integrations/cursor/rules/engineering-frontend-developer.mdc /your/project/.cursor/rules/
cp integrations/cursor/rules/engineering-code-reviewer.mdc /your/project/.cursor/rules/
# ... 按需复制

安装后如何使用：

1. 安装后 .cursor/rules/ 中的 .mdc 文件会自动被 Cursor 识别
2. 在 Chat 或 Composer 中正常提问，Cursor 自动匹配相关智能体：
   text Copy

   帮我审查这个组件的性能问题   → 自动匹配前端开发者
   这段代码有安全漏洞吗         → 自动匹配安全审计员

3. 也可以在 Cursor Settings（Cmd+,）→ Rules → Project Rules 中查看所有规则
4. 还可以在 Chat 中用 @规则名 手动指定引用某个智能体

排查：如果看不到规则，确认 .cursor/rules/ 在项目根目录、文件扩展名是 .mdc、已重新打开项目。

Trae

转换为 Trae rule 文件并安装到项目目录 .trae/rules/。格式与 Cursor 同源（仅扩展名 .md 不同）。

./scripts/convert.sh --tool trae
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool trae

⚠️ 关于"装了但几乎不自动触发"（见 issue #59）：

转换出的 rule 默认 alwaysApply: false + 空 globs:，属于 "agent-requested rule"——Trae 模型读 description 自行决定是否加载。全装 268 条 rule 会让 description 互相稀释、几乎命中不到任何一条，这是设计行为不是 bug。

正确姿势：

1. 精选安装（推荐）：只挑 10–20 条常用 rule 放进 .trae/rules/，自动匹配才会真正起作用。
2. @ 显式调用：对话里输入 @engineering-pc-host-engineer ... 强制加载某条 rule。
3. 核心 rule 改 alwaysApply：把代码审查、git 工作流之类的 1–3 条改成 alwaysApply: true 长期生效。

详细说明见 integrations/trae/README.md。

OpenCode

转换为 OpenCode agent 文件并安装到项目目录 .opencode/agents/。

./scripts/convert.sh --tool opencode
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool opencode

Aider

所有智能体编译为单个 CONVENTIONS.md 文件，Aider 会自动读取。

./scripts/convert.sh --tool aider
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool aider

在 Aider 会话中激活：

使用前端开发者智能体帮我重构这个组件。

Windsurf

所有智能体编译为单个 .windsurfrules 文件。

./scripts/convert.sh --tool windsurf
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool windsurf

Codex CLI

转换为 OpenAI Codex CLI agent 文件（TOML 格式）并安装到项目目录 .codex/agents/。

./scripts/convert.sh --tool codex
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool codex

在 Codex 中使用时，智能体会作为 subagent 被调用。也可以在 AGENTS.md 中引用。

Kiro (Amazon)

Amazon 的 Spec 驱动 AI IDE，基于 Claude 模型。每个智能体转换为 JSON 配置 + 提示词文件，安装到 ~/.kiro/agents/（全局）。

./scripts/convert.sh --tool kiro
./scripts/install.sh --tool kiro

在 Kiro 中切换智能体：

/agent swap

或启动时直接指定：

kiro-cli --agent engineering-frontend-developer

WorkBuddy (腾讯)

腾讯推出的全场景 AI 桌面智能体，兼容 OpenClaw 技能，支持多模型切换。每个智能体转换为 SKILL.md 技能文件，安装到 ~/.workbuddy/skills/（全局）。

./scripts/convert.sh --tool workbuddy
./scripts/install.sh --tool workbuddy

安装后重启 WorkBuddy 即可在技能列表中看到所有智能体。

CodeWhale（原 DeepSeek-TUI）

专为 DeepSeek 优化、对国内网络友好的终端编程 Agent（Rust 实现，原名 DeepSeek-TUI）。每个智能体转换为 SKILL.md 技能文件，安装到 ~/.codewhale/skills/（全局），在 CodeWhale 里用 /skills 加载。

./scripts/convert.sh --tool codewhale
./scripts/install.sh --tool codewhale

安装后在 CodeWhale 中输入 /skills 即可看到并调用所有智能体。

Hermes Agent (NousResearch)

NousResearch 的开源 AI 智能体框架，支持技能系统、子代理编排、会话记忆。每个智能体转换为 SKILL.md 技能文件，按分类目录安装到 ~/.hermes/skills/（全局）。

./scripts/convert.sh --tool hermes
./scripts/install.sh --tool hermes

安装后推荐在 Hermes CLI 中通过 hermes skills 查看和管理所有技能，或在对话中自然语言激活。

⚠️ Discord 模式下不要一次性全量安装

Hermes 的 Discord 集成会把每一个 skill 注册成 Discord 斜杠命令，Discord API 对 bot 所有命令的 JSON 序列化总长度有 8000 字符硬上限，超过后会返回 error code 50035（见 issue #45）。本仓库有近 200 个 skill，一次装全会直接炸 Discord。

解决办法：在 Discord 中使用时请按分类分批安装，用 --category 参数（可多次传入）：

bash Copy

# 只装 marketing 分类
./scripts/install.sh --tool hermes --category marketing

# 同时装 engineering 和 design
./scripts/install.sh --tool hermes --category engineering --category design

可选分类：academic, blender, design, engineering, finance, game-development, godot, hr, legal, marketing, paid-media, product, project-management, roblox-studio, sales, spatial-computing, specialized, supply-chain, support, testing, unity, unreal-engine。

Hermes CLI 本身没有此限制，全量安装可以继续使用。

DeerFlow 2.0 (字节跳动)

字节跳动的开源 SuperAgent 框架，支持子代理、沙箱、持久记忆。每个智能体转换为 SKILL.md 技能文件。

./scripts/convert.sh --tool deerflow
./scripts/install.sh --tool deerflow

默认安装到当前目录的 skills/custom/。可通过环境变量自定义路径：

DEERFLOW_SKILLS_DIR=/path/to/deerflow/skills/custom ./scripts/install.sh --tool deerflow

安装后在 DeerFlow 的任务中，相关技能会自动加载。

Qoder

转换为 Qoder SubAgent 格式（Markdown + YAML frontmatter）并安装到 ~/.qoder/agents/（全局）或项目目录 .qoder/agents/。

./scripts/convert.sh --tool qoder
./scripts/install.sh --tool qoder

在 Qoder 中使用：

• 自动触发：用自然语言描述任务，Qoder 根据 description 自动选择智能体
• 手动触发：输入 /agent-name（如 /engineering-frontend-developer）

官方文档：https://docs.qoder.com/zh/extensions/subagent

修改智能体后重新生成 Copy Section

添加新智能体或编辑现有智能体后，重新生成集成文件：

./scripts/convert.sh               # 重新生成所有工具
./scripts/convert.sh --tool cursor  # 只重新生成指定工具

🇨🇳 中国市场原创智能体 Copy Chapter

除翻译外，本项目包含 50 个原创智能体，专为中国平台和业务场景打造：

• 平台运营：小红书、抖音、微信公众号/视频号/小程序、B站、快手、微博、知乎
• 企业协作：飞书、钉钉集成开发
• 垂直领域：跨境电商、政务ToG、医疗合规、高考志愿、留学规划、Qt 工业上位机、通用机械设计、畜禽养殖档案核对
• 业务支撑：私域流量、直播电商、库存预测、合同审查、发票管理

在上方智能体阵容中标有 ⭐ 的即为原创智能体。

实战案例 Copy Chapter

场景一：出海产品 MVP Copy Section

你的团队：

1. 前端开发者 — 构建 React 应用
2. 后端架构师 — 设计 API 和数据库
3. 增长黑客 — 规划用户获取
4. 快速原型师 — 快速迭代
5. 现实检验者 — 上线前质量把关

场景二：[小红书品牌推广](examples/workflow-xiaohongshu-launch.md)（完整流程） Copy Section

你的团队：

1. 小红书运营专家 — 种草内容策略和达人合作
2. 内容创作者 — 产出种草笔记
3. 品牌守护者 — 品牌调性把关
4. 数据分析师 — 追踪投放数据、出复盘报告
5. 增长黑客 — 设计转化和裂变路径

贡献 Copy Chapter

欢迎参与！翻译智能体、改进内容、新增中国平台智能体都行。详见 CONTRIBUTING.md。

交流 · Community Copy Chapter

| 微信扫码关注 | 微信公众号 「AI不止语」（微信搜索 AI_BuZhiYu）— 技术问答 · 项目更新 · 实战文章

渠道 加入方式

QQ 2群 点击加入（群号 1071280067）

微信群 关注公众号后回复「群」获取入群方式 |
| --- | --- |

姊妹项目 Copy Chapter

致谢 Copy Chapter

• 原始英文版：msitarzewski/agency-agents（MIT 协议）
• 感谢原作者 @msitarzewski 创建了这个优秀的项目

许可证 Copy Chapter

MIT License — 自由使用，商业或个人均可。

⭐ Star 趋势 Copy Chapter

File: examples/README.md Copy Chapter

Examples

This directory contains example outputs demonstrating how the agency's agents can be orchestrated together to tackle real-world tasks.

Why This Exists Copy Chapter

The agency-agents repo defines dozens of specialized agents across engineering, design, marketing, product, support, spatial computing, and project management. But agent definitions alone don't show what happens when you deploy them all at once on a single mission.

These examples answer the question: "What does it actually look like when the full agency collaborates?"

Contents Copy Chapter

[nexus-spatial-discovery.md](./nexus-spatial-discovery.md) Copy Section

What: A complete product discovery exercise where 8 agents worked in parallel to evaluate a software opportunity and produce a unified plan.

The scenario: Web research identified an opportunity at the intersection of AI agent orchestration and spatial computing. The entire agency was then deployed simultaneously to produce:

• Market validation and competitive analysis
• Technical architecture (8-service system design with full SQL schema)
• Brand strategy and visual identity
• Go-to-market and growth plan
• Customer support operations blueprint
• UX research plan with personas and journey maps
• 35-week project execution plan with 65 sprint tickets
• Spatial interface architecture specification

Agents used:

Key takeaway: All 8 agents ran in parallel and produced coherent, cross-referencing plans without coordination overhead. The output demonstrates the agency's ability to go from "find an opportunity" to "here's the full blueprint" in a single session.

Adding New Examples Copy Chapter

If you run an interesting multi-agent exercise, consider adding it here. Good examples show:

• Multiple agents collaborating on a shared objective
• The breadth of the agency's capabilities
• Real-world applicability of the agent definitions

File: integrations/opencode/README.md Copy Chapter

OpenCode Integration

OpenCode agents are .md files with YAML frontmatter stored in
.opencode/agents/. The converter maps named colors to hex codes and adds
mode: subagent so agents are invoked on-demand via @agent-name rather
than cluttering the primary agent picker.

Install Copy Chapter

# Run from your project root
cd /your/project
/path/to/agency-agents/scripts/install.sh --tool opencode

This creates .opencode/agents/<slug>.md files in your project directory.

Activate an Agent Copy Chapter

In OpenCode, invoke a subagent with the @ prefix:

@frontend-developer help build this component.

@reality-checker review this PR.

You can also select agents from the OpenCode UI's agent picker.

Agent Format Copy Chapter

Each generated agent file contains:

---
name: Frontend Developer
mode: subagent
color: "#00FFFF"
---

• mode: subagent — agent is available on-demand, not shown in the primary Tab-cycle list
• color — hex code (named colors from source files are converted automatically)

Project vs Global Copy Chapter

Agents in .opencode/agents/ are project-scoped. To make them available
globally across all projects, copy them to your OpenCode config directory:

mkdir -p ~/.config/opencode/agents
cp integrations/opencode/agents/*.md ~/.config/opencode/agents/

Regenerate Copy Chapter

./scripts/convert.sh --tool opencode

File: integrations/openclaw/README.md Copy Chapter

OpenClaw Integration

OpenClaw agents are installed as workspaces containing SOUL.md, AGENTS.md,
and IDENTITY.md files. The installer copies each workspace into
~/.openclaw/agency-agents/ and registers it when the openclaw CLI is
available.

Before installing, generate the OpenClaw workspaces:

./scripts/convert.sh --tool openclaw

Install Copy Chapter

./scripts/install.sh --tool openclaw

Activate an Agent Copy Chapter

After installation, agents are available by agentId in OpenClaw sessions.

If the OpenClaw gateway is already running, restart it after installation:

openclaw gateway restart

Regenerate Copy Chapter

./scripts/convert.sh --tool openclaw

File: integrations/mcp-memory/README.md Copy Chapter

MCP Memory Integration

Give any agent persistent memory across sessions using the Model Context Protocol (MCP).

What It Does Copy Chapter

By default, agents in The Agency start every session from scratch. Context is passed manually via copy-paste between agents and sessions. An MCP memory server changes that:

• Cross-session memory: An agent remembers decisions, deliverables, and context from previous sessions
• Handoff continuity: When one agent hands off to another, the receiving agent can recall exactly what was done — no copy-paste required
• Rollback on failure: When a QA check fails or an architecture decision turns out wrong, roll back to a known-good state instead of starting over

Setup Copy Chapter

You need an MCP server that provides memory tools: remember, recall, rollback, and search. Add it to your MCP client config (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "memory": {
      "command": "your-mcp-memory-server",
      "args": []
    }
  }
}

Any MCP server that exposes remember, recall, rollback, and search tools will work. Check the MCP ecosystem for available implementations.

How to Add Memory to Any Agent Copy Chapter

To enhance an existing agent with persistent memory, add a Memory Integration section to the agent's prompt. This section instructs the agent to use MCP memory tools at key moments.

The Pattern Copy Section

## Memory Integration

When you start a session:
- Recall relevant context from previous sessions using your role and the current project as search terms
- Review any memories tagged with your agent name to pick up where you left off

When you make key decisions or complete deliverables:
- Remember the decision or deliverable with descriptive tags (your agent name, the project, the topic)
- Include enough context that a future session — or a different agent — can understand what was done and why

When handing off to another agent:
- Remember your deliverables tagged for the receiving agent
- Include the handoff metadata: what you completed, what's pending, and what the next agent needs to know

When something fails and you need to recover:
- Search for the last known-good state
- Use rollback to restore to that point rather than rebuilding from scratch

What the Agent Does With This Copy Section

The LLM will use MCP memory tools automatically when given these instructions:

• remember — store a decision, deliverable, or context snapshot with tags
• recall — search for relevant memories by keyword, tag, or semantic similarity
• rollback — revert to a previous state when something goes wrong
• search — find specific memories across sessions and agents

No code changes to the agent files. No API calls to write. The MCP tools handle everything.

Example: Enhancing the Backend Architect Copy Chapter

See backend-architect-with-memory.md for a complete example — the standard Backend Architect agent with a Memory Integration section added.

Example: Memory-Powered Workflow Copy Chapter

See ../../examples/workflow-with-memory.md for the Startup MVP workflow enhanced with persistent memory, showing how agents pass context through memory instead of copy-paste.

Tips Copy Chapter

• Tag consistently: Use the agent name and project name as tags on every memory. This makes recall reliable.
• Let the LLM decide what's important: The memory instructions are guidance, not rigid rules. The LLM will figure out when to remember and what to recall.
• Rollback is the killer feature: When a Reality Checker fails a deliverable, the original agent can roll back to its last checkpoint instead of trying to manually undo changes.

File: integrations/github-copilot/README.md Copy Chapter

GitHub Copilot Integration

The Agency works with GitHub Copilot out of the box. No conversion needed —
agents use the existing .md + YAML frontmatter format.

Install Copy Chapter

# Copy all agents to your GitHub Copilot agents directories
./scripts/install.sh --tool copilot

# Or manually copy a category
cp engineering/*.md ~/.github/agents/
cp engineering/*.md ~/.copilot/agents/

Activate an Agent Copy Chapter

In any GitHub Copilot session, reference an agent by name:

Activate Frontend Developer and help me build a React component.

Use the Reality Checker agent to verify this feature is production-ready.

Agent Directory Copy Chapter

Agents are organized into divisions. See the main README for
the full current roster.

File: integrations/gemini-cli/README.md Copy Chapter

Gemini CLI Integration

Packages all 61 Agency agents as a Gemini CLI extension. The extension
installs to ~/.gemini/extensions/agency-agents/.

Install Copy Chapter

# Generate the Gemini CLI integration files first
./scripts/convert.sh --tool gemini-cli

# Then install the extension
./scripts/install.sh --tool gemini-cli

Activate a Skill Copy Chapter

In Gemini CLI, reference an agent by name:

Use the frontend-developer skill to help me build this UI.

Extension Structure Copy Chapter

~/.gemini/extensions/agency-agents/
  gemini-extension.json
  skills/
    frontend-developer/SKILL.md
    backend-architect/SKILL.md
    reality-checker/SKILL.md
    ...

Regenerate Copy Chapter

./scripts/convert.sh --tool gemini-cli

File: integrations/cursor/README.md Copy Chapter

Cursor Integration

Converts all 180 Agency agents into Cursor .mdc rule files. Rules are
project-scoped — install them from your project root.

Install Copy Chapter

# Convert first, then install from your project root
./scripts/convert.sh --tool cursor
cd /your/project
/path/to/agency-agents-zh/scripts/install.sh --tool cursor

This creates .cursor/rules/<agent-slug>.mdc files in your project.

Finding and Activating Rules Copy Chapter

After installation, rules default to alwaysApply: false, meaning they
won't activate automatically. You need to enable them manually:

1. Open Cursor Settings (Cmd+, / Ctrl+,) → Rules → Project Rules
2. You'll see all installed agent rules listed there
3. Toggle on the agents you need (avoid enabling all 180 at once — too much context)
4. Once enabled, the rules automatically apply in Cursor Chat and Composer

Alternatively, reference an agent in your prompt:

@rules Use the frontend developer standards to review this component.

Or enable a rule as always-on by editing its frontmatter:

---
globs: "**/*.tsx,**/*.ts"
alwaysApply: true
---

Troubleshooting Copy Chapter

If you can't see rules in Cursor:

• Ensure .cursor/rules/ is in your project root (not a global directory)
• Files must have .mdc extension (not .md)
• Try reopening the project or restarting Cursor

Regenerate Copy Chapter

./scripts/convert.sh --tool cursor

File: integrations/claude-code/README.md Copy Chapter

Claude Code Integration

The Agency was built for Claude Code. No conversion needed — agents work
natively with the existing .md + YAML frontmatter format.

Install Copy Chapter

# Copy all agents to your Claude Code agents directory
./scripts/install.sh --tool claude-code

# Or manually copy a category
cp engineering/*.md ~/.claude/agents/

Activate an Agent Copy Chapter

In any Claude Code session, reference an agent by name:

Activate Frontend Developer and help me build a React component.

Use the Reality Checker agent to verify this feature is production-ready.

Agent Directory Copy Chapter

Agents are organized into divisions. See the main README for
the full current roster.

File: integrations/antigravity/README.md Copy Chapter

Antigravity Integration

Installs all 61 Agency agents as Antigravity skills. Each agent is prefixed
with agency- to avoid conflicts with existing skills.

Install Copy Chapter

./scripts/install.sh --tool antigravity

This copies files from integrations/antigravity/ to
~/.gemini/antigravity/skills/.

Activate a Skill Copy Chapter

In Antigravity, activate an agent by its slug:

Use the agency-frontend-developer skill to review this component.

Available slugs follow the pattern agency-<agent-name>, e.g.:

• agency-frontend-developer
• agency-backend-architect
• agency-reality-checker
• agency-growth-hacker

Regenerate Copy Chapter

After modifying agents, regenerate the skill files:

./scripts/convert.sh --tool antigravity

File Format Copy Chapter

Each skill is a SKILL.md file with Antigravity-compatible frontmatter:

---
name: agency-frontend-developer
risk: low
source: community
date_added: '2026-03-08'
---

2. Official Technical Reference & Guides (jnMetaCode/ai-coding-guide) Copy Chapter

File: README.md Copy Chapter

AI 编程工具实战指南

简体中文 | English

10 款主流 AI 编程工具的中文最佳实践 — 不讲概念，只讲怎么用好。从提示词技巧到工作流设计，从单工具精通到多工具协作，帮你把 AI 编程效率拉满。

📖 免费配套学习 → 从零学会 AI 编程（180 节）＋ 从零构建 AI 智能体（40 节）· 🌍 English / 日本語 / Español / 한국어 / 繁體中文

📖 免费配套学习 → 从零学会 AI 编程：180 节免费实操课 + 《AI 编程实战三卷书》在线阅读（卷一·入门 / 卷二·工作流 / 卷三·架构 / 别册·速查）+ 实战社区 · 永久免费 · 有想法或需求，欢迎来社区一起拆解

🚀 快速开始 Copy Chapter

先看一眼 📋 速查表 — 10 款工具一页横向对比：类型、上下文、配置文件、常用命令。知道自己选哪个、怎么配、怎么用。

按画像走推荐路径：

已经在用了？ 直接看：速查表 · 进阶技巧 · 实战工作流 · 生态项目

🔧 10 款工具教程 Copy Chapter

每个工具都有：核心概念 → 快速上手 → 提示词技巧 → 进阶用法 → 配置模板

📚 通用方法论 Copy Chapter

不管用哪个工具，这些方法都能让你写出更好的提示词、设计更高效的工作流：

🔗 实战工作流 Copy Chapter

真实项目怎么跑完整流程，以及不同工具怎么各展所长。

🌐 相关项目 Copy Chapter

以下项目均由「AI不止语」品牌持续维护，构成从 AI 编程到 AI 视频创作的完整链路：

AI 编程线：
读书 → 学工具 → 注入方法论 → 加载专家 → 多角色编排 → 安全防护
(book)  (guide)  (superpowers) (agents)   (orchestrator)  (shellward)

AI 视频线：
方法论 + 案例 + Skill
(ai-shortfilm-prompts)

👉 完整安装教程和组合使用指南 →

交流 · Community Copy Chapter

| 微信扫码关注 | 微信公众号 「AI不止语」（微信搜索 AI_BuZhiYu）— 技术问答 · 项目更新 · 实战文章

渠道 加入方式

QQ 2群 点击加入（群号 1071280067）

微信群 关注公众号后回复「群」获取入群方式 |
| --- | --- |

商业合作 · 内训咨询 Copy Chapter

仓库主体（教程 / 模板 / 脚本）永久 Apache-2.0 免费开源，欢迎个人无障碍使用。

但以下场景建议先沟通：

联系方式：

• 微信公众号 「AI不止语」（搜索 AI_BuZhiYu）后台留言「合作」
• GitHub Issue（标题加 [BUSINESS] 前缀）：提交咨询

关于 license：仓库主体 Apache-2.0 永远不变；book/ 目录下的书用 CC BY-NC-SA 4.0（个人免费 / 商业使用需授权）。

如果你只是个人学习、研究、写博客、做 demo——尽情使用，不用打招呼，注明来源就好。

贡献 Copy Chapter

欢迎参与！详见 CONTRIBUTING.md。

简单来说：补技巧、修过时内容、分享协作经验，提 Issue 或 PR 都可以。

📚 延伸学习 Copy Chapter

本项目讲"怎么用好 9 款工具"，要继续深入推荐看 延伸学习资源——精选了 20+ 个高质量 GitHub 仓库 / 博客 / 播客，按主题分类（Prompt 工程 / MCP 生态 / Claude Code 进阶 / Agent 工程 / 中文优秀资源 / 官方博客）。

🆕 更新日志 Copy Chapter

查看 CHANGELOG 了解项目重要更新。最近一次重大更新：2026-04 新增速查表、31 个深度陷阱合集、端到端实战脚本、画像推荐路径、20+ 外部学习资源。

致谢 Copy Chapter

本指南参考了以下优秀的开源项目：

• claude-code-best-practice — Claude Code 最佳实践
• awesome-cursorrules — Cursor 规则集合
• awesome-copilot — GitHub Copilot 官方资源
• gemini-cli-tips — Gemini CLI 技巧
• Everything Claude Code — 本能评分、AgentShield、多语言规则
• BMAD-METHOD — 完整 SDLC、Agent 角色、多平台

File: aider/README.en.md Copy Chapter

简体中文 | English

Aider Best Practices

Aider is an open-source CLI AI coding tool. Its defining feature is being Git-native — every change is auto-committed, with built-in version control support. It works with virtually all major LLMs (Claude, GPT, DeepSeek, Qwen, local models), making it the most flexible AI coding CLI out there.

Core Concepts Copy Chapter

Getting Started Copy Chapter

Installation Copy Section

pip install aider-chat

# Set an API key (pick one)
export ANTHROPIC_API_KEY=sk-xxx    # Claude
export OPENAI_API_KEY=sk-xxx       # GPT
export DEEPSEEK_API_KEY=sk-xxx     # DeepSeek

Basic Usage Copy Section

cd /your/project
aider

# Specify a model
aider --model claude-sonnet-4-5

# Use DeepSeek (cheaper)
aider --model deepseek/deepseek-chat

# Use a local model (free)
aider --model ollama/qwen2.5-coder

Three Chat Modes Copy Section

# code mode (default) — directly edits code
/code Add a retry decorator to utils.py

# ask mode — read-only, no changes
/ask What's the time complexity of this function?

# architect mode — design first, implement later
/architect Design a task queue system. Give me the plan, don't write code yet

Prompting Tips Copy Chapter

1. Adding Files to Context Copy Section

# Manually add files
/add src/models/user.py src/api/auth.py

# Add an entire directory
/add src/services/

# Remove files you don't need
/drop src/legacy/old_auth.py

Aider only modifies files that have been added. This is how you precisely control scope.

2. Architect Mode for Large Tasks Copy Section

/architect

I need to add a WebSocket real-time notification system to the project.
Requirements:
1. User online/offline notifications
2. Real-time new message push
3. Channel subscribe/unsubscribe support
4. Handle disconnect and reconnect

Give me a technical plan first, including:
- Which libraries to use
- Data flow design
- Which new files to create
- Which existing files to modify

Once confirmed, I'll switch to code mode to implement.

3. Leverage Auto Git Commits Copy Section

# Every change gets its own commit — roll back anytime
git log --oneline  # View Aider's commit history
git diff HEAD~1    # See the last change
git revert HEAD    # Not happy? One-command rollback

# Set a custom commit prefix
aider --commit-prefix "[ai] "

4. Multi-Model Strategy Copy Section

# Complex architecture design — use the strongest model
aider --model claude-sonnet-4-5
/architect Design a microservices split plan

# Daily coding — use a cost-effective model
aider --model deepseek/deepseek-chat
/code Implement user-service according to the plan

# Code review — use a free local model
aider --model ollama/qwen2.5-coder
/ask Any issues with this code?

Advanced Tips Copy Chapter

.aider.conf.yml — Project Configuration Copy Section

# .aider.conf.yml
model: claude-sonnet-4-5
auto-commits: true
auto-lint: true
auto-test: true
test-cmd: pytest
lint-cmd: ruff check

Lint + Test Automation Copy Section

# After every change, automatically:
# 1. Run the linter
# 2. Run related tests
# 3. If either fails, auto-fix and retry
auto-lint: true
auto-test: true
lint-cmd: "ruff check --fix"
test-cmd: "pytest -x"

Git Workflow Integration Copy Section

# Work on a feature branch
git checkout -b feature/add-notifications
aider

# Every Aider change stays on this branch
# When done, follow your normal PR process
git push -u origin feature/add-notifications

How It Differs from Other CLI Tools Copy Chapter

Common Pitfalls Copy Chapter

👉 Deep dive: Aider Pitfalls — 7 real-world traps, each with Symptom / Cause / Recovery / Prevention

Configuration Templates Copy Chapter

Further Reading Copy Chapter

• Aider Official Docs
• Aider GitHub (42k+ stars)
• superpowers-zh — Skills methodology (also supports Aider)

File: aider/README.md Copy Chapter

Aider 最佳实践

Aider 是一个开源的 CLI AI 编程工具，核心特色是 Git 原生 — 每次修改自动提交，天然支持版本控制。支持几乎所有主流 LLM（Claude、GPT、DeepSeek、Qwen、本地模型），是最灵活的 AI 编程 CLI。

核心概念 Copy Chapter

快速上手 Copy Chapter

安装 Copy Section

pip install aider-chat

# 设置 API Key（选一个）
export ANTHROPIC_API_KEY=sk-xxx    # Claude
export OPENAI_API_KEY=sk-xxx       # GPT
export DEEPSEEK_API_KEY=sk-xxx     # DeepSeek

基本使用 Copy Section

cd /your/project
aider

# 指定模型
aider --model claude-sonnet-4-5

# 用 DeepSeek（便宜）
aider --model deepseek/deepseek-chat

# 用本地模型（免费）
aider --model ollama/qwen2.5-coder

三种 Chat 模式 Copy Section

# code 模式（默认）— 直接修改代码
/code 给 utils.py 加一个 retry 装饰器

# ask 模式 — 只问不改
/ask 这个函数的时间复杂度是多少？

# architect 模式 — 先设计再实现
/architect 设计一个任务队列系统，先给方案不要写代码

提示词技巧 Copy Chapter

1. 添加文件到上下文 Copy Section

# 手动添加文件
/add src/models/user.py src/api/auth.py

# 添加整个目录
/add src/services/

# 移除不需要的文件
/drop src/legacy/old_auth.py

Aider 只会修改已添加的文件。这是精确控制范围的方式。

2. Architect 模式做大任务 Copy Section

/architect

我要给项目加一个 WebSocket 实时通知系统。
要求：
1. 用户上线/下线通知
2. 新消息实时推送
3. 支持频道订阅/退订
4. 需要考虑断线重连

先给出技术方案，包括：
- 用什么库
- 数据流设计
- 需要新建哪些文件
- 需要修改哪些现有文件

确认后切到 code 模式实现。

3. 利用自动 Git 提交 Copy Section

# 每次修改都有独立 commit，随时回滚
git log --oneline  # 看 Aider 的提交记录
git diff HEAD~1    # 看最后一次修改
git revert HEAD    # 不满意？一键回滚

# 设置自定义提交前缀
aider --commit-prefix "[ai] "

4. 多模型策略 Copy Section

# 复杂架构设计 — 用最强模型
aider --model claude-sonnet-4-5
/architect 设计微服务拆分方案

# 日常编码 — 用性价比模型
aider --model deepseek/deepseek-chat
/code 按方案实现 user-service

# 代码审查 — 用免费本地模型
aider --model ollama/qwen2.5-coder
/ask 看看这段代码有没有问题

进阶技巧 Copy Chapter

.aider.conf.yml — 项目配置 Copy Section

# .aider.conf.yml
model: claude-sonnet-4-5
auto-commits: true
auto-lint: true
auto-test: true
test-cmd: pytest
lint-cmd: ruff check

Lint + Test 自动化 Copy Section

# 每次修改后自动：
# 1. 跑 linter 检查
# 2. 跑相关测试
# 3. 如果失败，自动修复再重试
auto-lint: true
auto-test: true
lint-cmd: "ruff check --fix"
test-cmd: "pytest -x"

与 Git 工作流集成 Copy Section

# 在 feature 分支上工作
git checkout -b feature/add-notifications
aider

# Aider 的每次修改都在这个分支上
# 完成后正常走 PR 流程
git push -u origin feature/add-notifications

与其他 CLI 工具的区别 Copy Chapter

常见陷阱 Copy Chapter

👉 深度展开版：Aider 陷阱合集 — 7 个真实踩坑场景，每个带症状 / 根因 / 出坑 / 预防

配置模板 Copy Chapter

延伸阅读 Copy Chapter

• Aider 官方文档
• Aider GitHub（42k+ star）
• superpowers-zh — Skills 方法论（也支持 Aider）

File: book/README.md Copy Chapter

book/ — AI 编程实战三卷书脚手架

把 ai-coding-guide 仓库的现成内容重组成 3 卷 + 1 别册 的渐进式读本。
用 mdBook 编译成静态 HTML 网站 + PDF。

结构 Copy Chapter

book/
├── README.md          ← 你正在看
├── book.toml          ← mdbook 配置
├── .gitignore         ← 忽略 book/book/ 输出目录
└── src/
    ├── SUMMARY.md     ← 主目录（决定章节顺序）
    ├── intro.md       ← 总序
    ├── v1-intro.md    ← 卷一·入门 序
    ├── v2-intro.md    ← 卷二·工作流 序
    ├── v3-intro.md    ← 卷三·架构 序
    ├── about.md       ← 关于本书
    │
    ├── cheatsheet.md  ← 软链 → ../../cheatsheet.md
    ├── changelog.md   ← 软链 → ../../CHANGELOG.md
    ├── resources.md   ← 软链 → ../../resources.md
    ├── methods/       ← 软链 → ../../common/   (7 套方法论)
    ├── workflows-src/ ← 软链 → ../../workflows/ (协作 + 场景)
    ├── pitfalls-src/  ← 软链 → ../../pitfalls/  (踩坑合集)
    └── tools/
        ├── claude-code/ ← 软链 → ../../../claude-code/
        ├── codex/       ← 软链 → ../../../codex/
        ├── cursor/      ← 软链 → ../../../cursor/
        └── ...（10 工具全部）

关键设计：所有内容都是 symlink 而不是复制。仓库主目录改了，重新 mdbook build 立刻同步。零内容重复维护。

怎么本地预览 Copy Chapter

# 一次性装 mdbook
brew install mdbook
# 或 cargo install mdbook

# 预览（实时热更新，浏览器自动打开）
cd book
mdbook serve --open

# 编译成静态 HTML（输出在 book/book/）
mdbook build

怎么发布 Copy Chapter

选项 1：GitHub Pages ⭐ 已配置 Copy Section

CI 已经接好——.github/workflows/book.yml 在每次 push 到 main 时自动 build 并 deploy。

只需在仓库 Settings 里开 Pages 一次。完整步骤 + 自定义域名教程见 DEPLOY.md。

默认 URL：https://aibuzhiyu.com/

选项 2：Netlify / Vercel（PR preview 友好） Copy Section

仓库根目录加 netlify.toml：

[build]
  command = "cd book && mdbook build"
  publish = "book/book"
[build.environment]
  RUST_VERSION = "1.78"

netlify 会自动装 mdbook（用 cargo install mdbook build 命令前面手动加一下）。

选项 3：Leanpub / GitBook 商业版 Copy Section

如果想出电子书赚钱：mdbook build 出 HTML 之后，用 pandoc 转成 epub / mobi / PDF：

mdbook build
cd book/book
# 把所有 HTML 串起来转 PDF
pandoc -o ../../ai-coding-guide.pdf $(find . -name "*.html" | sort) \
  --pdf-engine=xelatex \
  -V mainfont="PingFang SC" -V CJKmainfont="PingFang SC"

节奏 Copy Chapter

这是 v0.1 脚手架——目录结构、3 卷序、symlink 就位，可以 build 出能看的版本了，但内容主要靠的是仓库里既有的章节。后续要加的：

• 各卷之间的"过渡章"（卷一末→卷二首的承上启下）
• 卷三的「CI 集成 / 团队治理」实战章节（仓库里还没有，需要新写）
• 端到端项目案例（"用 Claude Code + Codex CLI 做完一个真实小项目"）
• 出版用的封面 / ISBN / 版式（如果要走出版社）
• PDF 导出脚本调优（中文字体 / 代码块换行）

每一项都可以独立 PR 进来。

License Copy Chapter

CC BY-NC-SA 4.0 — 个人免费 / 禁商业 / 派生开源。详见 LICENSE 或 中文友好版。

与主仓库 Apache-2.0 是双 license 关系：book/ 目录下用 CC，其他都是 Apache。

上游 Copy Chapter

GitHub: jnMetaCode/ai-coding-guide

File: claude-code/README.en.md Copy Chapter

简体中文 | English

Claude Code Best Practices

Claude Code is Anthropic's official CLI AI coding tool. It's not just a code completion tool — it's an Agent that understands your entire project and executes complex tasks autonomously.

Core Concepts Copy Chapter

Before diving into tips, get familiar with these core concepts:

Getting Started Copy Chapter

Installation Copy Section

# Install globally via npm
npm install @anthropic-ai/claude-code

# Or run directly with npx
npx @anthropic-ai/claude-code

First Run Copy Section

cd /your/project
claude

Once in interactive mode, try these:

# Understand the project
> What does this project do? Walk me through the architecture.

# Small task
> Add a truncate function to utils/string.ts that cuts strings at a given length and appends an ellipsis.

# Big task (just describe it — Claude Code plans and executes automatically)
> Refactor all endpoints under src/api/ to use a unified error handling format.

CLAUDE.md — Project Configuration File Copy Section

Create a CLAUDE.md in your project root. Claude Code reads it on every startup:

# Project Overview
This is an e-commerce admin dashboard built with Next.js 14 + TypeScript.

# Code Conventions
- Use TypeScript strict mode
- Components use PascalCase
- API routes go under src/app/api/
- Tests use Vitest, placed in __tests__/

# Common Commands
- Dev server: pnpm dev
- Run tests: pnpm test
- Type check: pnpm typecheck
- Lint: pnpm lint

# Important Notes
- Do NOT modify anything under src/legacy/ — it's a compatibility layer for the old version
- Database migrations must be generated via drizzle-kit — never write raw SQL

Prompting Tips Copy Chapter

1. Provide Full Context in One Go Copy Section

❌ Bad: Add a login feature.
✅ Good: Add a JWT login endpoint under src/app/api/. Use bcrypt for password
    verification, set token expiry to 7 days, and return errors in a unified
    { code, message } format. Follow the style of src/app/api/register/route.ts.

2. Point to Reference Files Copy Section

Follow the style of src/components/UserTable.tsx.
Create a new src/components/OrderTable.tsx with
pagination, sorting, and search using TanStack Table.

3. Analyze First, Act Second Copy Section

Read src/services/payment.ts and src/services/order.ts first.
Analyze the current payment flow for issues,
propose improvements, and wait for my confirmation before making changes.

4. Limit the Scope Copy Section

Only modify src/utils/date.ts.
Don't touch other files. Don't add new dependencies.

5. Draw Red Lines with Negatives Copy Section

Implement a caching layer.
Don't use Redis — use in-memory caching.
Don't add new dependencies — use a plain Map.
Don't change any existing function signatures.

Advanced Techniques Copy Chapter

Agent Capabilities Copy Section

Claude Code is an Agent by design — describe the task and it plans and executes autonomously:

> Add unit tests to the entire project, targeting 80% coverage.

Claude Code will: read code → make a plan → write tests → run tests → fix failures → verify passing.

Tip: No special commands or flags needed. Just describe the desired outcome. Claude Code decides on its own whether multi-step execution is necessary.

Subagent Parallelism Copy Section

Split large tasks across multiple Subagents running in parallel:

Do these three things in parallel:
1. Add pagination parameters to src/api/users.ts
2. Add date filtering to src/api/orders.ts
3. Add search to src/api/products.ts
Use subagents to execute each one independently.

Skill Files Copy Section

Skills are one of the most powerful features. Place methodology files under .claude/skills/ and the AI loads them automatically:

.claude/skills/
├── brainstorming.md      # Requirements analysis workflow
├── debugging.md          # Debugging methodology
├── code-review.md        # Code review standards
└── verification.md       # Pre-completion verification

Quick-install superpowers-zh (20 battle-tested skills):

cd /your/project
npx superpowers-zh
# Auto-detects project type, installs to .claude/skills/
# Also supports Cursor, Gemini CLI, etc.

After installation, Claude Code loads these skills automatically. Invoke them with / commands — e.g., /brainstorming for requirements analysis, /debugging for systematic debugging. See superpowers-zh.

Need specialized roles? Use the 211 AI expert personas from agency-agents-zh:

# Copy role files to .claude/skills/ to use them
# Examples: database optimizer, security engineer, code reviewer, etc.

Reference roles in CLAUDE.md:

# Roles
When I say "review as a security expert", act according to .claude/skills/security-engineer.md.

Hook Automation Copy Section

Hooks run scripts automatically before or after tool calls:

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "echo 'About to run a command'" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "pnpm lint --fix" }
        ]
      }
    ]
  }
}

Hook trigger points include PreToolUse, PostToolUse, Notification, etc. Each trigger uses matcher to match tool names. See the official docs.

Use cases:

• Auto-run related tests after every file edit
• Auto-lint before every commit
• Auto-add copyright headers to new files

Git Worktree Isolation Copy Section

Use worktrees for experimental changes without affecting the main branch:

Do this refactor in a git worktree.
If the result is good, merge it. If not, discard it.

Memory Across Conversations Copy Section

Claude Code stores memory under ~/.claude/ for cross-conversation use:

Remember: this project deploys on Vercel,
CI uses GitHub Actions, and the database is Supabase PostgreSQL.
Factor these in for all deployment-related tasks going forward.

Multi-Agent Orchestration Copy Section

When tasks are complex enough to need multiple AI roles collaborating (e.g., architect designs → developer implements → reviewer audits), use agency-orchestrator for YAML-based orchestration:

# workflow.yaml
name: New Feature Development
steps:
  - agent: Software Architect
    task: Analyze requirements, produce technical design
    output: design.md

  - agent: Backend Developer
    task: Implement code per design.md
    input: design.md

  - agent: Code Reviewer
    task: Review code quality and security

Best for: team-scale complex tasks, deliverables requiring multiple review rounds, standardized development workflows.

Debugging Tips Copy Chapter

1. Let It Read Logs — Don't Let It Guess Copy Section

❌ Bad: Tests are failing, fix them.
✅ Good: Run pnpm test src/api/users.test.ts,
    show me the failure output, analyze the root cause, then fix.

2. Narrow the Scope Copy Section

Look only at lines 45-80 of src/services/auth.ts.
A user reports "token still shows expired after refresh".
Analyze possible causes first — don't change anything yet.

3. Diff Analysis Copy Section

Check git log for recent changes to src/api/payment.ts.
Compare logic before and after to find which commit introduced this bug.

Tips Cheat Sheet (60+) Copy Chapter

Organized by category, one tip per row. Bookmark this section — it's all you need.

Prompting (12) Copy Section

CLAUDE.md (10) Copy Section

Agent & Subagent (10) Copy Section

Hooks (8) Copy Section

Workflow (12) Copy Section

Git & PRs (8) Copy Section

Debugging (10) Copy Section

Cost & Performance (6) Copy Section

For more tips, see claude-code-best-practice.

Common Pitfalls Copy Chapter

👉 Deep dive: Claude Code Pitfalls — 8 real-world traps, each with Symptom / Cause / Recovery / Prevention

Configuration Templates Copy Chapter

Copy these directly into your project:

Further Reading Copy Chapter

• Claude Code Official Docs
• superpowers-zh — 20 AI coding skills
• agency-agents-zh — 211 AI expert personas

File: claude-code/README.md Copy Chapter

Claude Code 最佳实践

Claude Code 是 Anthropic 官方的 CLI AI 编程工具。它不只是一个代码补全工具，而是一个能理解整个项目、执行复杂任务的 Agent。

核心概念 Copy Chapter

在深入技巧之前，先搞清楚 Claude Code 的几个核心概念：

快速上手 Copy Chapter

安装 Copy Section

# npm 全局安装
npm install @anthropic-ai/claude-code

# 或者直接用 npx
npx @anthropic-ai/claude-code

第一次使用 Copy Section

cd /your/project
claude

进入交互模式后，试试这几个命令：

# 了解项目
> 这个项目是做什么的？帮我梳理一下架构

# 做一个小任务
> 给 utils/string.ts 加一个 truncate 函数，超过指定长度截断并加省略号

# 做大任务（直接描述，Claude Code 会自动规划执行）
> 重构 src/api/ 下所有接口，统一错误处理格式

CLAUDE.md — 项目配置文件 Copy Section

在项目根目录创建 CLAUDE.md，Claude Code 每次启动都会读取：

# 项目说明
这是一个 Next.js 14 + TypeScript 的电商后台管理系统。

# 代码规范
- 使用 TypeScript strict mode
- 组件用 PascalCase 命名
- API 路由放在 src/app/api/ 下
- 测试用 Vitest，放在 __tests__/ 下

# 常用命令
- 启动开发：pnpm dev
- 跑测试：pnpm test
- 类型检查：pnpm typecheck
- Lint：pnpm lint

# 注意事项
- 不要修改 src/legacy/ 下的代码，那是旧版本兼容层
- 数据库 migration 必须通过 drizzle-kit 生成，不要手写 SQL

提示词技巧 Copy Chapter

1. 给足上下文，一次说清楚 Copy Section

❌ 差：加个登录功能
✅ 好：给 src/app/api/ 加一个 JWT 登录接口。用 bcrypt 验证密码，
    token 过期时间 7 天，错误返回统一的 { code, message } 格式。
    参考 src/app/api/register/route.ts 的风格。

2. 指定参考文件 Copy Section

参考 src/components/UserTable.tsx 的风格，
给 src/components/ 新建一个 OrderTable.tsx，
支持分页、排序、搜索，用 TanStack Table。

3. 先让它分析，再让它动手 Copy Section

先读 src/services/payment.ts 和 src/services/order.ts，
分析一下现在的支付流程有什么问题，
给出改进方案，确认后再改。

4. 限制范围 Copy Section

只改 src/utils/date.ts 这一个文件。
不要动其他文件，不要加新依赖。

5. 用否定句划红线 Copy Section

实现缓存功能。
不要用 Redis，用内存缓存。
不要引入新依赖，用 Map 实现。
不要修改现有接口的签名。

进阶技巧 Copy Chapter

Agent 能力 Copy Section

Claude Code 本身就是 Agent——直接描述任务，它会自主规划和执行：

> 给整个项目加上单元测试，覆盖率目标 80%

Claude Code 会自己：读代码 → 制定计划 → 写测试 → 跑测试 → 修复失败 → 验证通过

提示：不需要特殊命令或 flag。直接描述你想要的结果，Claude Code 会自动决定是否需要多步骤执行。

Subagent 并行 Copy Section

大任务可以拆成多个 Subagent 并行执行：

同时做这三件事：
1. 给 src/api/users.ts 加分页参数
2. 给 src/api/orders.ts 加日期筛选
3. 给 src/api/products.ts 加搜索功能
用 subagent 并行执行，每个独立完成。

Skill 文件 Copy Section

Skill 是最强大的功能之一。在 .claude/skills/ 下放方法论文件，AI 会自动加载：

.claude/skills/
├── brainstorming.md      # 需求分析流程
├── debugging.md          # 调试方法论
├── code-review.md        # 代码审查规范
└── verification.md       # 完成前验证

快速安装 superpowers-zh（20 个经过实战验证的 skill）：

cd /your/project
npx superpowers-zh
# 自动检测项目类型，安装到 .claude/skills/
# 也支持 Cursor、Gemini CLI 等工具

安装后 Claude Code 会自动加载这些 skill，你可以用 / 命令调用，比如 /brainstorming 做需求分析、/debugging 做系统化调试。详见 superpowers-zh。

需要专业角色？ 用 agency-agents-zh 的 211 个 AI 专家角色：

# 把角色文件复制到 .claude/skills/ 即可使用
# 比如数据库优化师、安全工程师、代码审查员等

在 CLAUDE.md 里引用角色：

# 角色
当我说"用安全专家审查"时，按 .claude/skills/security-engineer.md 的角色行事。

Hook 自动化 Copy Section

Hook 在工具调用前后自动执行脚本：

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "echo 'About to run a command'" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "pnpm lint --fix" }
        ]
      }
    ]
  }
}

Hook 的触发点有 PreToolUse、PostToolUse、Notification 等，每个触发点下用 matcher 匹配工具名。详见 官方文档。

用途：

• 每次修改文件后自动跑相关测试
• 每次提交前自动 lint
• 每次创建文件后自动加版权头

Git Worktree 隔离开发 Copy Section

做实验性改动时，用 worktree 隔离，不影响主分支：

在 git worktree 里做这个重构。
如果效果好就合并，不好就丢弃。

Memory 跨对话记忆 Copy Section

Claude Code 可以在 ~/.claude/ 下存储记忆，跨对话使用：

记住：这个项目的部署用的是 Vercel，
CI 用 GitHub Actions，数据库是 Supabase PostgreSQL。
以后做部署相关的任务都要考虑这些。

多智能体编排 Copy Section

当任务复杂到需要多个 AI 角色协作时（比如架构师设计 → 开发者实现 → 审查员审查），可以用 agency-orchestrator 做 YAML 编排：

# workflow.yaml
name: 新功能开发
steps:
  - agent: 软件架构师
    task: 分析需求，输出技术方案
    output: design.md

  - agent: 后端开发者
    task: 按 design.md 实现代码
    input: design.md

  - agent: 代码审查员
    task: 审查代码质量和安全性

适合场景：团队级复杂任务、需要多轮审查的交付、标准化开发流程。

调试技巧 Copy Chapter

1. 让它看日志，不要让它猜 Copy Section

❌ 差：测试挂了，帮我修
✅ 好：跑 pnpm test src/api/users.test.ts，
    把失败的测试输出贴出来，分析根因后再修。

2. 缩小范围 Copy Section

只看 src/services/auth.ts 第 45-80 行的逻辑，
用户反馈说"刷新 token 后还是提示过期"。
先分析可能的原因，不要直接改。

3. 对比分析 Copy Section

git log 看看 src/api/payment.ts 最近的改动，
对比改动前后的逻辑，找出哪次改动引入了这个 bug。

技巧速查表（60+） Copy Chapter

按场景分类，一行一个技巧。收藏这一页就够了。

提示词（12） Copy Section

CLAUDE.md（10） Copy Section

Agent 与 Subagent（10） Copy Section

Hook（8） Copy Section

工作流（12） Copy Section

Git 与 PR（8） Copy Section

调试（10） Copy Section

性能与成本（6） Copy Section

更多技巧参考 claude-code-best-practice。

常见陷阱 Copy Chapter

👉 深度展开版：Claude Code 陷阱合集 — 8 个真实踩坑场景，每个带症状 / 根因 / 出坑 / 预防

配置模板 Copy Chapter

直接复制到你的项目里用：

延伸阅读 Copy Chapter

• Claude Code 官方文档
• superpowers-zh — 20 个 AI 编程 skills
• agency-agents-zh — 211 个 AI 专家角色

File: codex/README.en.md Copy Chapter

简体中文 | English

OpenAI Codex CLI Best Practices

Codex CLI is OpenAI's open-source terminal coding agent, written in Rust — sitting alongside Claude Code and Gemini CLI as the "big three" terminal agents. This guide is verified against the official docs (developers.openai.com/codex) and the openai/codex repo at v0.125.0 (April 2026).

⚠️ Note: this is the new Codex CLI released in 2025 (open-source, terminal agent), not the original Codex model that was deprecated in 2023. The product family also includes Codex App (desktop) and Codex Web (cloud agent at chatgpt.com/codex); this doc covers the CLI only.

Core Concepts Copy Chapter

Getting Started Copy Chapter

Installation Copy Section

# npm (recommended)
npm install @openai/codex

# or Homebrew (macOS)
brew install --cask codex

# or download a GitHub Release binary (macOS arm64/x64, Linux x64/arm64)
# https://github.com/openai/codex/releases/latest

System requirements (from official install docs): macOS 12+, Ubuntu 20.04+ / Debian 10+, Windows 11 (WSL2), 4 GB RAM (8 GB recommended), optional Git 2.23+.

Authentication Copy Section

codex            # On first launch, choose "Sign in with ChatGPT"

Two options:

• ChatGPT account login (officially recommended) — uses your ChatGPT Plus / Pro / Business / Edu / Enterprise quota; opens a browser for OAuth.
• API key — for CI, corporate proxies, or precise per-token billing; needs extra setup (see developers.openai.com/codex/auth).

Your First Run Copy Section

cd /your/project
codex

Inside the TUI, try these (from the official quickstart):

> Tell me about this project
> Find and fix bugs in my codebase with minimal, high-confidence changes
> Build a classic Snake game in this repo

💡 Official advice: git commit or create a checkpoint before any non-trivial task. If Codex's changes aren't what you want, you can roll back instantly.

AGENTS.md — Project Instruction File Copy Section

Drop an AGENTS.md at your repo root (or run /init to scaffold one):

# Project
Next.js 14 + TypeScript admin dashboard.

# Layout
- src/app/api/      route handlers
- src/components/   UI components (PascalCase)
- src/lib/db/       Drizzle data access layer

# Build / Test / Lint
- Dev:    pnpm dev
- Test:   pnpm test         (Vitest — must pass after every change)
- Types:  pnpm typecheck
- Lint:   pnpm lint --fix

# Conventions
- TS strict mode
- All DB access through Drizzle, no raw SQL
- Don't bypass husky pre-commit hooks

# Don't
- Don't touch src/legacy/
- Don't add runtime deps without asking

Discovery order (important):

~/.codex/AGENTS.override.md   ← temp global override
~/.codex/AGENTS.md            ← personal global
<git root>/AGENTS.md          ← team-shared
<subdir>/AGENTS.md            ← module-local (overrides parents)

Files are concatenated from shallow to deep; closer-to-cwd files win. Default 32 KiB cap per file, tunable via project_doc_max_bytes.

Prompting Tips Copy Chapter

OpenAI's recommended four-element prompt template (from developers.openai.com/codex/learn/best-practices):

Goal:        what to change or build
Context:     which files, docs, errors matter
Constraints: standards, architecture, safety rules
Done when:   the completion bar

1. Be precise, not verbose Copy Section

❌ optimize the login flow
✅ Goal: switch src/app/api/login/route.ts from bcrypt.compareSync to async compare
   Context: called by src/components/LoginForm.tsx; error shape { code, message } must stay
   Constraints: don't touch the schema, don't add deps
   Done when: pnpm test passes; 100 concurrent logins show no event-loop blocking warnings

2. Reference files with `@`, don't paste Copy Section

@src/services/payment.ts @src/services/order.ts
Read both, analyze the retry logic in the failure path, propose a fix, wait for my OK before editing.

Letting Codex pull files itself saves tokens and avoids accidental truncation.

3. Tune reasoning effort Copy Section

Push harder for hard problems, dial back for easy ones:

• low — small edits, formatting
• medium / high — most refactors and bugfixes
• xhigh — architectural, multi-file, deeply coupled

Switch in the TUI via shortcut, or set the default in config.toml.

4. Plan first, act second Copy Section

/plan
  Walk src/api/, unify all routes onto the new error-handling middleware

Or hit Shift+Tab to enter Plan Mode. Codex lays out the plan and asks clarifying questions before writing code — strongly recommended for multi-file work.

5. Make it test and self-review Copy Section

After your changes:
1) Run pnpm test, paste any failing output
2) Run pnpm typecheck, confirm no new type errors
3) Use /review to self-audit the diff and flag risks

Quoting the official guide verbatim: Don't stop at asking Codex to make a change. Ask it to create tests when needed, run checks, confirm results, and review work before accepting.

Approval & Sandbox (the two big safety knobs) Copy Chapter

Codex's distinguishing design — two independent dimensions.

Sandbox (what it can touch) Copy Section

Enforcement (verified against codex-rs/cli/src/debug_sandbox.rs):

• macOS — Seatbelt (built-in)
• Linux / WSL2 — Landlock kernel LSM + seccomp filtering (requires Linux 5.13+ with Landlock enabled)
• Windows — Restricted-token sandbox (active in PowerShell)

Tip: codex sandbox seatbelt|landlock|windows -- <cmd> is the debug subcommand to verify whether a single command would survive the sandbox.

Approval (when it asks) Copy Section

Common Combos Copy Section

# Local dev — just run `codex` (defaults are already workspace-write + on-request)
codex

# Explicit form (equivalent to the above)
codex --sandbox workspace-write

# Just look around, don't edit
codex --sandbox read-only

# Add a few writable dirs outside the workspace (without going full-open)
codex --add-dir ../sibling-repo --add-dir /tmp/scratch

# Non-interactive in CI / scripts
codex exec --sandbox workspace-write --ask-for-approval never "run tests and fix failures"

# Open the sandbox fully (you understand the consequences)
codex --sandbox danger-full-access --ask-for-approval never

# Full YOLO: skip approvals AND drop the sandbox (only when externally sandboxed, e.g. Docker)
codex --yolo
# equivalent to: codex --dangerously-bypass-approvals-and-sandbox

⚠️ --full-auto is deprecated and removed (v0.125.0 still keeps it inside codex exec only to print a migration warning). Use --sandbox workspace-write — that's the official replacement; approval defaults to on-request already.

🚨 CI gotcha: the default approval mode is interactive — CI will hang on the prompt and time out. codex exec + --ask-for-approval never is the canonical CI shape.

Advanced Copy Chapter

1. config.toml — Persistent Preferences Copy Section

~/.codex/config.toml (user) / .codex/config.toml (project):

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
web_search = "cached"     # cached by default; --search switches to live
multi_agent = true

[profiles.review]
model = "gpt-5.5"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

[mcp_servers.github]
command = "npx @modelcontextprotocol/server-github"
enabled = true

Switch profiles:

codex --profile review              # read-only review pass
codex exec --profile ci "..."       # CI / scripted run

2. Slash Commands Cheat Sheet Copy Section

Complete list (46 commands) lives in source codex-rs/tui/src/slash_command.rs::SlashCommand. Just press / in the TUI for autocomplete.

3. Non-interactive Execution (`exec`) Copy Section

Treat Codex as a script tool:

# Single prompt
codex exec "replace all console.log with logger.debug"

# Pipe in
git diff main..HEAD | codex exec "review this diff for bugs"

# Pin model + skip approvals
codex exec -m gpt-5.5 --ask-for-approval never "add unit tests for new files"

# Stream events as JSONL (one JSON object per line)
codex exec --json "..." | jq -c .

# Capture only the final message to a file (handy for scripting)
codex exec -o /tmp/answer.txt "..."

4. Subagents — Parallel Subtasks Copy Section

.codex/agents/explorer.toml:

name = "explorer"
description = "Read-only codebase explorer; gathers evidence before any change."
model = "gpt-5.3-codex"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace execution paths, cite files and symbols with file:line.
Never propose changes — just report findings.
"""

Invoke from the main thread:

Spawn an explorer subagent and have it map all auth logic under src/api/, then report back.

Each subagent runs in its own sandbox + model and returns its summary to the main thread. Great for "explore + execute" splits on complex changes.

5. MCP — External Tools Copy Section

codex mcp add github --command "npx @modelcontextprotocol/server-github"
codex mcp list

STDIO and HTTP/OAuth servers supported. Common picks: GitHub, Linear, Slack, databases (Postgres / Supabase). Rule of thumb: only add tools that remove a real manual loop — don't pad the list.

6. Skills — Reusable Workflows (note: a folder, not a single file) Copy Section

Package recurring tasks as a Skill directory. Codex reads the description to decide when to fire and only loads the body on demand ("progressive disclosure"):

~/.agents/skills/release-notes/      ← personal (canonical)
.codex/skills/release-notes/         ← project, Codex-only
.agents/skills/release-notes/        ← project, cross-tool (Claude Code/Codex)
└── SKILL.md           # required: name + description + steps
└── references/        # optional: long docs, specs, schemas
└── scripts/           # optional: helper scripts
└── examples/          # optional: I/O examples
└── agents/openai.yaml # optional: Codex-specific metadata

Note: ~/.codex/skills/ still works but is deprecated; new installs should use ~/.agents/skills/.

How to invoke (from shanraisshan battle-tested patterns):

$skill-creator                # explicit trigger with $ prefix
/skills                       # list all available skills
> draft this week's release notes  # description match auto-fires; no $ needed

Skill writing rules (consensus across high-star community repos):

• The description field is a trigger, not a summary — write "when should I fire?" not "what is this?"
• A skill is for the model, not human readers — skip filler
• Give goals + constraints, don't railroad the model with prescriptive steps
• Add a ## Gotchas section per skill with Codex's failure modes in this domain — highest-signal content

Ready-made skill libraries: ComposioHQ/awesome-codex-skills, VoltAgent/awesome-agent-skills (cross-tool).

7. Hooks — Inject Custom Scripts into the Agent Loop (beta) Copy Section

Enable [features] codex_hooks = true and Codex will invoke your shell scripts at 6 event points:

💡 The hooks JSON schema reuses Claude Code's hooks.json format directly (the source engine is literally named ClaudeHooksEngine), so migrating from Claude Code is zero-change.

Config goes in .codex/hooks.json. Reference impl: shanraisshan/codex-cli-hooks.

The two highest-leverage uses:

• PostToolUse → run prettier / ruff / clang-format — Codex edits, hook formats, CI stays green
• PreToolUse → intercept rm -rf / git push --force / DB DROP — belt-and-suspenders safety

8. Memories — Cross-Session Long-Term Memory (beta) Copy Section

Enable [features] memories = true and Codex carries facts you've confirmed across sessions ("this project uses pnpm — don't suggest npm").

/memories             # TUI: view / generate / reset

Stored under ~/.codex/memories/ — per-user, not per-project. Safety toggles (from the source MemoriesToml struct):

[memories]
disable_on_external_context = true   # mark thread "polluted" when external data is touched (MCP / web search) — prevents leaking
                                     # (legacy alias `no_memories_if_mcp_or_web_search` still works)
generate_memories = true             # default true; set to false to stop generating memories from new threads
use_memories = true                  # default true; set to false to skip injecting memories into prompts

If a session touches untrusted content (parsed an unfamiliar PDF, ran an unaudited MCP), run /memories → Reset immediately.

9. Plugins / Marketplace — Distribution (v0.121.0+) Copy Section

Bundle skills + apps + MCP servers as a distributable plugin (.codex-plugin/plugin.json):

codex plugin marketplace add user/repo            # GitHub shorthand
codex plugin marketplace add ./local-marketplace  # local dir works too
codex plugin marketplace upgrade
codex plugin marketplace remove <name>

# In the TUI
/plugins              # browse installed / available plugins

Community marketplace index: hashgraph-online/awesome-codex-plugins.

10. Fast Mode — 1.5× speed, 2× credits (gpt-5.4 only) Copy Section

/fast on            # enable
/fast status        # current
/fast off           # disable

Best when "I know roughly what to change, I just need a fast typist." Pro subscribers can also use gpt-5.3-codex-spark for near-realtime micro-iteration.

11. Web Search Copy Section

On by default in cached mode (OpenAI's pre-indexed snapshot). For real-time, add --search:

codex --search "Latest React 19 useActionState best practices"

12. Image Input Copy Section

codex -i screenshot.png "match this design in src/components/Pricing.tsx"

PNG / JPEG; you can also paste screenshots directly into the TUI composer. Combined with Chrome DevTools / Playwright MCP, Codex can read browser console output itself:

codex mcp add chrome-devtools --command "npx chrome-devtools-mcp"
codex mcp add playwright --command "npx @playwright/mcp"

13. Local Open-Source Models (`--oss`) Copy Section

Source utils/oss/src/lib.rs confirms Codex natively supports two local providers:

# Ollama route
codex --oss --local-provider ollama -m qwen2.5-coder
codex --oss --local-provider ollama -m deepseek-coder-v2

# LM Studio route
codex --oss --local-provider lmstudio

Fully offline, zero API cost. Trade-off: local models are noticeably weaker than GPT-5.5. Best for: sensitive on-premise data, no-network environments, bulk low-complexity tasks.

Model IDs follow Ollama / LM Studio naming (run ollama list to see what's local). Codex doesn't maintain a separate catalog.

14. CI Integration (Official GitHub Action) Copy Section

openai/codex-action is the official Apache-2.0 action with a built-in restricted sandbox proxy. The canonical PR auto-review workflow:

# .github/workflows/codex-review.yml
name: Codex PR review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
      - run: git fetch --no-tags origin "${{ github.event.pull_request.base.ref }}"
      - id: codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Review only the changes in PR #${{ github.event.pull_request.number }}:
              git diff ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}
            Be concise. Flag bugs, missing tests, and security risks.
      - if: steps.codex.outputs.final-message != ''
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `${{ steps.codex.outputs.final-message }}`
            })

⚠️ The sandbox blocks network by default — if your review prompt needs to run tests or install deps, do npm ci in a step before invoking codex-action.

15. Codex as an MCP Server (Reverse Integration) Copy Section

codex mcp-server                    # expose Codex as an MCP server

Source confirms this exposes codex() and codex-reply() MCP tools. Use case: let Claude Code, Cursor, or any other agent call Codex as "a colleague" for parallel work or cross-verification.

16. Rules / Execpolicy (Advanced Safety) Copy Section

Starlark DSL defining command allow/prompt/forbid lists (prefix_rule() + host_executable()). Drop rule files into .codex/rules/*.rules, validate with codex execpolicy check:

prefix_rule(
    pattern = ["git", ["push", "force-with-lease"]],
    decision = "prompt",
    justification = "force pushes need a human eyeball",
)
prefix_rule(
    pattern = ["rm", "-rf", "/"],
    decision = "forbidden",
    justification = "absolutely not",
)

codex execpolicy check --rules .codex/rules/safety.rules git push --force
# {"matchedRules":[{...}],"decision":"prompt"}

Best for enterprise / team setups — finer-grained than approval modes. See codex-rs/execpolicy/README.md.

High-Signal Prompting & Workflow Patterns Copy Chapter

Distilled from high-star community guides (shanraisshan/codex-cli-best-practice etc.):

Prompting Copy Section

✅ "Prove to me this works" — make Codex run the tests + git diff main..HEAD itself
✅ "Knowing everything you know now, scrap this and implement the elegant solution"
   (use after a mediocre fix; pushes Codex past local minima)
✅ Codex debugs well by itself — paste the error, say "fix", don't micromanage

Planning Copy Section

✅ /plan for explicit planning on multi-step tasks (Codex auto-plans too, but explicit is more controllable)
✅ Phase-gated plans, each phase has tests — never let it touch 30 files in one shot
✅ Spin up another Codex (or Claude Code) as a "staff engineer" to review your plan
✅ Write detailed specs, kill ambiguity — better input → better output

AGENTS.md Copy Section

✅ Heuristic: a fresh dev should be able to launch codex → "run the tests" → it works first try
   If not, your AGENTS.md is missing build/setup/test commands
✅ Aim for ~150 lines (hard limit is 32 KiB byte-wise) — longer ≠ better
✅ Behavior rules (approval / sandbox / model) belong in config.toml, NOT AGENTS.md
✅ AGENTS.override.md for personal preferences — keeps team's AGENTS.md clean

Multi-Agent & Parallelism Copy Section

✅ Multi-agent = throw more compute at the problem; offload chores to subagents
✅ Test-time compute: one agent writes, another finds bugs — separate context windows help
✅ Use git worktrees for parallel agents to avoid clobbering each other

Debugging Copy Section

✅ Have Codex run the service whose logs you want to watch as a background task
✅ Stuck? Screenshot the issue and feed it in (image input is the most underrated capability)
✅ Agentic search (glob + grep) beats RAG — code drifts faster than indexes refresh

Common Pitfalls Copy Chapter

Codex CLI vs Claude Code Copy Chapter

These two are the closest analogs, but they optimize differently:

Community rule of thumb (echoed across builder.io / datacamp / multiple comparison posts):

Codex for keystrokes, Claude Code for commits.
Codex shines at "fast iterations + sandboxed execution"; Claude Code shines when one change touches 12 files and the dependency graph matters.

Already paying for ChatGPT and budget-sensitive → Codex comes practically free. Doing a big refactor where code quality is paramount → Claude Code is still the pick. Many teams use both.

Templates Copy Chapter

The templates/ directory provides:

• AGENTS.md — generic project instruction template
• config.toml — user-level config with profiles
• agent-explorer.toml — read-only exploration subagent
• SKILL.md — Skill template (with Gotchas + trigger-style description)

References Copy Chapter

Official Copy Section

• Repo: openai/codex (Apache-2.0, Rust)
• Docs: developers.openai.com/codex
• Install guide: docs/install.md
• Best practices: Best practices
• Sandboxing internals: Sandboxing
• Slash commands: Slash commands
• Official GitHub Action (CI integration): openai/codex-action
• Official skills catalog: openai/skills

High-quality community indexes (verified high-star) Copy Section

• RoggeOhta/awesome-codex-cli — 280+ resources (subagents, skills, plugins, MCP, IDE integrations, CI), categorized
• shanraisshan/codex-cli-best-practice — 50 battle-tested prompting tips + complete .codex/ reference impl (aligned with v0.125.0)
• ComposioHQ/awesome-codex-skills — 38 commonly-used skills (dev tools, data analysis, Composio 1000+ SaaS integrations)
• VoltAgent/awesome-codex-subagents — 136+ subagents across 10 domains
• hashgraph-online/awesome-codex-plugins — first Plugin marketplace index
• agents.md — cross-tool AGENTS.md standard (60k+ adopting projects; works in Codex / Claude Code / Gemini CLI)

Mainstream workflow frameworks Copy Section

Compared to Claude Code Copy Section

In this repo: workflows/tool-selection.en.md

Verified through: 2026-04-30 (codex CLI v0.125.0). Every CLI flag, subcommand, slash command, and config field in this guide was cross-checked against the codex-rs source code; models and pricing change quickly — the OpenAI docs are always the source of truth.

File: codex/README.md Copy Chapter

OpenAI Codex CLI 最佳实践

简体中文 | English

Codex CLI 是 OpenAI 官方的开源终端编程 Agent，用 Rust 写成，与 Claude Code、Gemini CLI 同属"终端 Agent 三巨头"。本文基于官方文档（developers.openai.com/codex）和仓库 openai/codex 的 v0.125.0（2026-04）核实整理。

⚠️ 注意：这里讲的是 2025 年发布的新 Codex CLI（开源、终端 Agent），不是 2023 年退役的旧 Codex 模型。同名产品系列还包括 Codex App（桌面端）和 Codex Web（云端 Agent，chatgpt.com/codex），本文只覆盖 CLI。

核心概念 Copy Chapter

快速上手 Copy Chapter

安装 Copy Section

# npm（推荐）
npm install @openai/codex

# 或 Homebrew (macOS)
brew install --cask codex

# 或下载 GitHub Release 二进制（macOS arm64/x64、Linux x64/arm64）
# https://github.com/openai/codex/releases/latest

系统要求（来自官方 install 文档）：macOS 12+、Ubuntu 20.04+/Debian 10+、Windows 11（WSL2），4 GB 内存（建议 8 GB），可选 Git 2.23+。

认证 Copy Section

codex            # 第一次启动，按提示选 "Sign in with ChatGPT"

两种方式：

• ChatGPT 账号登录（官方推荐）—— 走 ChatGPT Plus / Pro / Business / Edu / Enterprise 订阅额度，开浏览器走 OAuth。
• API Key —— 适合 CI、企业代理或想精确按量计费的场景，需要额外设置（详见 developers.openai.com/codex/auth）。

第一次跑 Copy Section

cd /your/project
codex

进入 TUI 后试这几条（来自官方 quickstart）：

> Tell me about this project
> Find and fix bugs in my codebase with minimal, high-confidence changes
> Build a classic Snake game in this repo

💡 官方建议：执行任务前先 git commit 或建 checkpoint，Codex 改完不满意可以一键回滚。

AGENTS.md — 项目指令文件 Copy Section

在项目根目录建 AGENTS.md（或运行 /init 让 Codex 自动 scaffold）：

# 项目说明
Next.js 14 + TypeScript 电商后台。

# 目录约定
- src/app/api/      接口路由
- src/components/   UI 组件（PascalCase）
- src/lib/db/       Drizzle 数据访问层

# 构建 / 测试 / Lint
- 启动：pnpm dev
- 测试：pnpm test         （Vitest，必须在改完后跑）
- 类型：pnpm typecheck
- Lint：pnpm lint --fix

# 工程约束
- TS strict mode
- DB 操作只走 Drizzle，禁止裸 SQL
- 提交前自动 lint，不要绕过 husky

# 不要做的事
- 不要修改 src/legacy/
- 不要新增运行时依赖前不询问

加载顺序（重要）：

~/.codex/AGENTS.override.md   ← 临时全局覆盖
~/.codex/AGENTS.md            ← 个人全局
项目 git root/AGENTS.md       ← 团队共享
子目录/AGENTS.md              ← 模块级局部规则（覆盖父级）

文件按目录从浅到深拼接，越靠近当前目录的越优先生效。默认每个文件最多 32 KiB，可通过 project_doc_max_bytes 调。

提示词技巧 Copy Chapter

Codex 官方推荐"四元素"提示模板（来源：developers.openai.com/codex/learn/best-practices）：

Goal:        要做什么？要改什么？
Context:     涉及哪些文件、文档、错误信息？
Constraints: 约束有哪些？规范、架构、安全要求？
Done when:   完成判定条件是什么？

1. 精确而不啰嗦 Copy Section

❌ 优化下登录功能
✅ Goal: 把 src/app/api/login/route.ts 的密码比对从 bcrypt.compareSync 换成异步 compare
   Context: 该接口被 src/components/LoginForm.tsx 调用，错误返回需保持 { code, message } 结构
   Constraints: 不动 schema、不加新依赖
   Done when: pnpm test 全绿，且并发 100 次登录无 event loop 阻塞警告

2. 用 `@` 引文件而不是粘贴 Copy Section

@src/services/payment.ts @src/services/order.ts
读完这两个文件，分析支付流程的失败重试有什么漏洞，先给方案，确认后再改。

让 Codex 自己拉文件比你粘进 prompt 更省 token，也避免"截断到一半"。

3. 推理强度按需调 Copy Section

复杂问题让 Codex "think harder"，简单任务用低推理省钱：

• low — 简单改动、风格调整
• medium / high — 大多数日常重构、Bug 修复
• xhigh — 架构级、多文件复杂逻辑

可在 TUI 里通过快捷键切换，或在 config.toml 里设默认。

4. 先 Plan 后 Act Copy Section

/plan
  分析 src/api/ 下所有路由，统一改成新的错误处理中间件

或者按 Shift+Tab 切到 Plan Mode。Codex 会先列计划、问澄清问题，确认后才写代码——多文件任务强烈建议用。

5. 让它跑测试 + 自查 Copy Section

做完改动后：
1) 跑 pnpm test，把失败用例的输出贴给我
2) 跑 pnpm typecheck，确认没有新增类型错误
3) 用 /review 自查 diff，列出风险点

官方原话：Don't stop at asking Codex to make a change. Ask it to create tests when needed, run checks, confirm results, and review work before accepting.

Approval & Sandbox（最重要的两个安全旋钮） Copy Chapter

这是 Codex 最有特色的设计。两个维度独立配置：

Sandbox（能动什么） Copy Section

技术实现（核实自 codex-rs/cli/src/debug_sandbox.rs 源码）：

• macOS — Seatbelt（系统自带）
• Linux / WSL2 — Landlock 内核 LSM + seccomp 过滤（需要 Linux 5.13+ 且 Landlock 已启用）
• Windows — Restricted token sandbox（PowerShell 下生效）

提示：可以用 codex sandbox seatbelt|landlock|windows -- <cmd> 这组调试子命令，单独验证某条命令在沙箱里能不能跑。

Approval（什么时候问你） Copy Section

常用组合 Copy Section

# 本地开发：直接 `codex` 即可（默认就是 workspace-write + on-request）
codex

# 显式指定（与上面等价）
codex --sandbox workspace-write

# 只想让它探一下、不要动手
codex --sandbox read-only

# 加几个 workspace 外的可写目录（不需要全开）
codex --add-dir ../sibling-repo --add-dir /tmp/scratch

# 在 CI / 脚本里非交互执行
codex exec --sandbox workspace-write --ask-for-approval never "跑测试并修复失败用例"

# 临时完全放开沙箱（明白后果再用）
codex --sandbox danger-full-access --ask-for-approval never

# 完全 YOLO：连询问都跳过、不沙箱（仅在外部已隔离环境下用，例如 Docker）
codex --yolo
# 等价于：codex --dangerously-bypass-approvals-and-sandbox

⚠️ --full-auto 已废弃移除（v0.125.0 仍在 codex exec 里保留作迁移提示）。直接 --sandbox workspace-write 就是同义；approval 默认本就是 on-request。

🚨 CI 踩坑：默认 approval 是交互式的，CI 里会卡死等输入超时。codex exec + --ask-for-approval never 是 CI 的标准姿势。

进阶用法 Copy Chapter

1. config.toml — 持久化偏好 Copy Section

~/.codex/config.toml（用户级）/ .codex/config.toml（项目级）：

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
web_search = "cached"     # 默认走缓存；--search 切 live
multi_agent = true

[profiles.review]
model = "gpt-5.5"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

[mcp_servers.github]
command = "npx @modelcontextprotocol/server-github"
enabled = true

切换 profile：

codex --profile review              # 只读模式跑代码审查
codex exec --profile ci "..."       # CI 用脚本模式

2. Slash 命令速查 Copy Section

TUI 内常用：

完整表（46 个）见源码 codex-rs/tui/src/slash_command.rs::SlashCommand 枚举。在 TUI 里按 / 也会弹自动补全。

3. 非交互执行（exec） Copy Section

把 Codex 当脚本工具用：

# 单 prompt
codex exec "把所有 console.log 改成 logger.debug"

# 管道
git diff main..HEAD | codex exec "审查这份 diff，找出潜在 bug"

# 指定模型 + 不询问
codex exec -m gpt-5.5 --ask-for-approval never "为新文件补单测"

# 输出 JSONL（每行一个事件）给后续程序处理
codex exec --json "..." | jq -c .

# 把最后一条 message 单独写到文件（便于脚本提取最终结果）
codex exec -o /tmp/answer.txt "..."

4. Subagent — 并行子任务 Copy Section

.codex/agents/explorer.toml：

name = "explorer"
description = "Read-only codebase explorer; gathers evidence before any change."
model = "gpt-5.3-codex"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace execution paths, cite files and symbols with file:line.
Never propose changes — just report findings.
"""

主 Agent 调用：

派一个 explorer subagent 把 src/api/ 所有路由的鉴权逻辑梳理一遍，回来汇总。

子 Agent 独立 sandbox + 模型，跑完返回主 thread。适合"探索 + 实施"分离的复杂改动。

5. MCP — 外部工具 Copy Section

# CLI 直接添加
codex mcp add github --command "npx @modelcontextprotocol/server-github"
codex mcp list

支持 STDIO 和 HTTP/OAuth 两类 server。常用：GitHub、Linear、Slack、数据库（Postgres / Supabase）。原则：只接能消除手工动作的工具，不要凑数。

6. Skill — 可复用方法论（注意：是文件夹，不是单文件） Copy Section

把重复任务封装成一个 Skill 目录，Codex 看 description 决定何时触发，只在需要时才载入正文（"渐进披露"）：

~/.agents/skills/release-notes/      ← 个人（canonical 路径）
.codex/skills/release-notes/         ← 项目 Codex 专属
.agents/skills/release-notes/        ← 项目跨工具（Claude Code / Codex 等共享）
└── SKILL.md           # 必须：name + description + 主体步骤
└── references/        # 可选：长文档、规范、API schema
└── scripts/           # 可选：辅助脚本（lint / parser / generator）
└── examples/          # 可选：示范输入/输出
└── agents/openai.yaml # 可选：Codex 专属元数据（如限制权限）

注：~/.codex/skills/ 也能用但已废弃（向后兼容），新装统一放 ~/.agents/skills/。

调用方式（来自 shanraisshan 实战经验）：

$skill-creator                 # 用 $ 前缀显式触发某个技能
/skills                        # 列出所有可用技能
> 给我做这周 release notes     # 描述匹配会自动触发，无需 $

写 Skill 的要点（社区高 star 项目共识）：

• description 是触发器，不是摘要——写"什么时候应该 fire"而不是"这是什么"
• Skill 是给模型看的指引，不是给人看的文档——别罗列废话
• 给目标和约束，别 railroad（强制每一步怎么做），让模型自己决策路径
• 加一个 ## Gotchas 段，把 Codex 在这个领域常踩的坑记下来——这是最高信号的内容

现成 Skill 库可以直接抄：ComposioHQ/awesome-codex-skills、VoltAgent/awesome-agent-skills（跨工具）

7. Hooks — 在 Agent 循环里挂自定义脚本（beta） Copy Section

启用 [features] codex_hooks = true 后，Codex 在 6 个事件点会调用你定义的 shell 脚本：

💡 hook schema 直接复用 Claude Code 的 hooks.json 格式（源码引擎名 ClaudeHooksEngine），所以从 Claude Code 迁移过来零改动。

配置文件 .codex/hooks.json，参考实现：shanraisshan/codex-cli-hooks。

最常见的两个 use case：

• PostToolUse 跑 prettier/ruff — Codex 改完代码自动格式化，避免 CI 红
• PreToolUse 拦截 rm -rf / git push --force / 数据库 DROP — 双保险

8. Memories — 跨 session 的长期记忆（beta） Copy Section

启用 [features] memories = true，Codex 会在 session 之间保留你确认过的事实（"这个项目用 pnpm，不要建议 npm"）。

/memories             # TUI 里查看 / 生成 / 重置

存在 ~/.codex/memories/（per-user，不是 per-project）。安全开关（来自源码 MemoriesToml 结构）：

[memories]
disable_on_external_context = true   # 触发外部数据（MCP / web 搜索）时把当前 thread 标"polluted"，防记忆泄漏
                                     # （旧别名 no_memories_if_mcp_or_web_search 仍可用）
generate_memories = true             # 默认就是 true；置 false 则不再为新 thread 生成记忆
use_memories = true                  # 默认 true；置 false 跳过把记忆注入提示

如果某个 session 接触了不可信内容（解析了陌生 PDF、跑了未审计的 MCP），跑 /memories → Reset 立即清掉。

9. Plugins / Marketplace — 插件分发（v0.121.0+） Copy Section

把 skills + apps + MCP servers 打包成可分发的 plugin（.codex-plugin/plugin.json）：

codex plugin marketplace add user/repo            # GitHub shorthand
codex plugin marketplace add ./local-marketplace  # 本地目录也行
codex plugin marketplace upgrade
codex plugin marketplace remove <name>

# 在 TUI 里
/plugins              # 浏览已装 / 可装的 plugin

社区 marketplace 索引：hashgraph-online/awesome-codex-plugins。

10. Fast Mode — 1.5× 速度，2× 额度（gpt-5.4 限定） Copy Section

/fast on            # 开启
/fast status        # 看当前
/fast off           # 关

适合"知道大致怎么改、就缺打字员"的场景。Pro 订阅还能用 gpt-5.3-codex-spark 做近实时的小改动迭代。

11. Web 搜索 Copy Section

默认开启，cached 模式（OpenAI 预索引）。需要实时结果加 --search：

codex --search "React 19 useActionState 的最新最佳实践"

12. 图片输入 Copy Section

codex -i screenshot.png "按这张设计稿改 src/components/Pricing.tsx"

PNG / JPEG，可在 TUI 里直接粘贴截图。配 Chrome DevTools / Playwright MCP，让 Codex 自己看浏览器控制台日志：

codex mcp add chrome-devtools --command "npx chrome-devtools-mcp"
codex mcp add playwright --command "npx @playwright/mcp"

13. 本地开源模型（`--oss`） Copy Section

源码 utils/oss/src/lib.rs 确认 Codex 原生支持两个本地 provider：

# Ollama 路线
codex --oss --local-provider ollama -m qwen2.5-coder
codex --oss --local-provider ollama -m deepseek-coder-v2

# LM Studio 路线
codex --oss --local-provider lmstudio

完全离线、零 API 成本。代价是模型能力比 GPT-5.5 弱不少，适合：本地敏感数据 / 没网环境 / 跑批量低复杂度任务。

模型 ID 跟着 Ollama / LM Studio 自己的命名（ollama list 看本地有什么），Codex 不维护独立清单。

14. CI 集成（官方 GitHub Action） Copy Section

openai/codex-action 是官方 Apache-2.0 Action，自带受限沙箱代理。最常用的 PR 自动 review 工作流：

# .github/workflows/codex-review.yml
name: Codex PR review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
      - run: git fetch --no-tags origin "${{ github.event.pull_request.base.ref }}"
      - id: codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Review only the changes in PR #${{ github.event.pull_request.number }}:
              git diff ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}
            Be concise. Flag bugs, missing tests, and security risks.
      - if: steps.codex.outputs.final-message != ''
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `${{ steps.codex.outputs.final-message }}`
            })

⚠️ 沙箱默认禁网——如果你的 review prompt 需要跑测试 / 装依赖，先在 Action 步骤里 npm ci 再调 codex-action。

15. Codex 作为 MCP server（反向接入） Copy Section

codex mcp-server                    # 把 Codex 暴露成 MCP server

源码确认这会 expose codex() 和 codex-reply() 两个 MCP 工具。用法：让 Claude Code、Cursor 等其他 Agent 把 Codex 当成"我的同事"调用，做并行任务或交叉验证。

16. Rules / Execpolicy（高级安全） Copy Section

Starlark DSL 定义命令白/灰/黑名单（prefix_rule() + host_executable()）。规则文件放 .codex/rules/*.rules，可用 codex execpolicy check 离线验证：

prefix_rule(
    pattern = ["git", ["push", "force-with-lease"]],
    decision = "prompt",
    justification = "force pushes need a human eyeball",
)
prefix_rule(
    pattern = ["rm", "-rf", "/"],
    decision = "forbidden",
    justification = "absolutely not",
)

codex execpolicy check --rules .codex/rules/safety.rules git push --force
# {"matchedRules":[{...}],"decision":"prompt"}

适合企业 / 团队场景，比单纯 approval 更细粒度。详见 codex-rs/execpolicy/README.md。

高质量提示词与工作模式 Copy Chapter

来自 GitHub 高 star 实战教程（shanraisshan/codex-cli-best-practice 等）的高信号技巧：

提示词层面 Copy Section

✅ "证明给我看这能用" — 让 Codex 自己跑测试 + git diff main..HEAD 验证
✅ "用你现在掌握的所有信息，重新审视这个方案，给出更优雅的实现"
   （在一次平庸修复后用，能逼出更好的设计）
✅ Codex 自己调试能力强 — 把报错日志贴进去说"修"，别微管理过程

Plan 层面 Copy Section

✅ /plan 多文件任务先列计划 — Codex 也会自动 plan，但显式触发更可控
✅ 分阶段 + 每阶段 gated test —— 别让它一次改 30 个文件
✅ 让另一个 Codex（或 Claude Code）以 staff engineer 视角审查计划
✅ 写规格、降歧义 —— 越具体的输入越能给出可用的输出

AGENTS.md 层面 Copy Section

✅ 经验法则：随便一个新人能跑 codex → "run the tests" → 一次过
   不行就说明 AGENTS.md 漏了 build/test/setup 命令
✅ 控制在 150 行附近（硬上限是 32 KiB）—— 长 ≠ 好
✅ 行为约束（approval / sandbox / model）写 config.toml，不要写 AGENTS.md
✅ AGENTS.override.md 放个人偏好，别污染团队共享的 AGENTS.md

多 Agent 与并行 Copy Section

✅ 用 multi-agent 给问题扔更多算力 —— 把杂活外包给 subagent，主 thread 保持干净
✅ Test-time compute：一个 agent 写代码，另一个 agent 找 bug —— 独立 context 效果更好
✅ 长开发用 git worktree 给每个 agent 一个隔离的 working tree，避免互相覆盖

调试 Copy Section

✅ 让 Codex 在后台跑你想看日志的服务（codex 的 PTY exec 会正确处理）
✅ 卡住就截图扔给它（图片输入是最被低估的能力）
✅ Agentic search（glob + grep）打 RAG —— 代码漂移得太快，索引永远不准

常见踩坑（社区高频） Copy Chapter

Codex 与 Claude Code 怎么选 Copy Chapter

两者最像，但定位不同：

经验法则（社区共识，参考 builder.io / datacamp 等多篇对比）：

Codex for keystrokes, Claude Code for commits.
Codex 适合"快速迭代 + 沙箱执行"，Claude Code 适合"一次改 12 个文件且依赖图复杂"的精修。

预算敏感且已订阅 ChatGPT → Codex 就是顺手白送的；做大重构、要最强代码质感 → Claude Code 仍是首选。两者并用也很常见。

模板与配置 Copy Chapter

templates/ 目录提供：

• AGENTS.md — 通用项目指令模板
• config.toml — 用户级配置模板（含 profiles）
• agent-explorer.toml — 只读探索 subagent 模板
• SKILL.md — Skill 模板（含 Gotchas / 触发器写法范本）

参考资料 Copy Chapter

官方 Copy Section

• 仓库：openai/codex（Apache-2.0，Rust）
• 文档：developers.openai.com/codex
• 安装详解：docs/install.md
• 最佳实践：Best practices
• 沙箱原理：Sandboxing
• Slash 命令：Slash commands
• 官方 GitHub Action（CI 集成）：openai/codex-action
• 官方 Skills 目录：openai/skills

社区高质量索引（高 star，每条都核实过） Copy Section

• RoggeOhta/awesome-codex-cli — 280+ 资源大全（Subagent / Skill / Plugin / MCP / IDE 集成 / CI），按类别整理
• shanraisshan/codex-cli-best-practice — 50 条战场验证的提示词技巧 + 完整 .codex/ 实现样例（已对齐 v0.125.0）
• ComposioHQ/awesome-codex-skills — 38 个常用 Skill（开发工具 / 数据分析 / Composio 1000+ SaaS 集成）
• VoltAgent/awesome-codex-subagents — 136+ subagent 跨 10 个领域（开发 / 安全 / 基建 / 数据 / DX）
• hashgraph-online/awesome-codex-plugins — 第一个 Plugin marketplace 索引
• agents.md — 跨工具 AGENTS.md 标准（已被 60k+ 项目采用，Codex / Claude Code / Gemini CLI 通用）

主流 Workflow 框架 Copy Section

与 Claude Code 对比 Copy Section

本项目内：workflows/tool-selection.md

信息核实截止：2026-04-30（codex CLI v0.125.0）。本教程的每条 CLI flag、子命令、slash 命令、config 字段都对照 codex-rs 源码核实过；模型能力和定价变化快，最终以 OpenAI 官方文档为准。

File: copilot/README.en.md Copy Chapter

简体中文 | English

GitHub Copilot Best Practices

GitHub Copilot is the built-in AI coding assistant for VS Code and JetBrains IDEs. Its core strength is seamless integration — no tool switching needed, just write code in your editor and get completions and suggestions naturally. Copilot Agent mode evolves it from a completion tool into an autonomous agent that can tackle tasks independently.

Core Concepts Copy Chapter

Getting Started Copy Chapter

Copilot Instructions — Project Configuration Copy Section

Create .github/copilot-instructions.md in your project root:

# Project Guidelines

## Tech Stack
- Python 3.12 + FastAPI + SQLAlchemy 2.0
- Database: PostgreSQL
- Cache: Redis
- Testing: pytest

## Code Standards
- Type annotations must be complete, using Python 3.10+ syntax
- Prefix all async functions with `async_`
- All endpoints must use Pydantic models for input validation
- Use custom exception classes for errors, never bare Exception

## Directory Conventions
- src/api/     — FastAPI routes
- src/models/  — SQLAlchemy models
- src/schemas/ — Pydantic models
- src/services/ — Business logic
- tests/       — Tests (mirrors src structure)

# Reference Tips Copy Section

# Reference a file
#file:src/models/user.py Write a user registration endpoint based on this model

# Reference selected code
#selection What performance issues does this code have?

# Reference terminal output
#terminal Check the error and help me fix it

# Reference VS Code problems panel
#problems Fix these type errors for me

Agent Mode Copy Chapter

Copilot Agent was the biggest update of 2025. Enter a task in the chat, and Agent will:

1. Analyze requirements -> 2. Search relevant files -> 3. Create a plan -> 4. Execute step by step -> 5. Run tests to verify

Using Agent Mode Copy Section

Select Agent mode in Chat (or just describe a complex task):

@workspace Add rate limiting to all endpoints under src/api/,
using Redis as the counter. Max 60 requests per user per minute.
Requirements:
1. A reusable rate_limit decorator
2. Redis connection config
3. Return 429 status when limit exceeded
4. Add tests for each endpoint

Agent + MCP for Extended Capabilities Copy Section

Use MCP Servers to give Agent access to external tools:

// .vscode/settings.json
{
  "github.copilot.chat.mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://..."]
    }
  }
}

Then you can say:

Look up the structure of the users table in the database,
then generate a SQLAlchemy model and Pydantic schema based on the actual columns.

Prompting Tips Copy Chapter

1. Write Good Comments for Better Completions Copy Section

# Completion quality depends on context. A single comment tells Copilot what you need:

# Count the number of business days between two dates, excluding weekends and public holidays
def count_business_days(start: date, end: date) -> int:
    # Copilot will auto-complete the full implementation

2. Custom Agents for Specialized Reviews Copy Section

Create .github/agents/security-reviewer.agent.md: