企业官网建设流程全解析

这段时间 Claude Code、Codex 这类终端 Agent 编程工具非常火，很多团队已经从“用聊天助手写代码”转向“在终端里让 Agent 直接改代码、跑测试、提 PR”。但真正落地时大家会发现，光会安装工具远远不够，真正拉开效率差距的是 Agent Skill 的设计能力：怎么把团队规范、代码审查标准、项目上下文、质量检查流程打包成 Agent 能理解、能按需加载的“技能包”。这篇教程会从 Claude Code 与 Codex 的基本概念讲起，逐步拆解技能架构、工具管理、上下文控制、质量评估，再给出一套可以直接在企业内部复用的落地思路。适合刚接触 Agent 编程的新手，也适合已经在团队里做 AI 研发效能建设的同学。

先说明一下本文的定位：这不是一篇简单的安装教程，也不是纯概念科普。本文会尽量按照“是什么 → 为什么 → 怎么用 → 怎么落地 → 怎么排错”的顺序来写，每个关键步骤都会解释原理。文中的代码和配置以通用实践为主，遇到具体版本差异时，我会明确提示你以官方最新文档为准。

1. 背景：为什么 Agent 编程工具和 Skill 突然火了

1.1 从聊天助手到终端 Agent

过去两年，大家习惯的 AI 编程方式是：在网页对话框里描述需求，把生成的代码复制到项目里，再手动处理依赖和报错。这种方式本质上是“AI 辅助生成代码片段”，人仍然负责整个流程的上下文传递。Claude Code 和 Codex 这类工具出现后，交互方式发生了很大变化：它们直接运行在终端里，能读取项目目录、查看文件内容、执行命令、运行测试，甚至在你批准后修改文件并提交代码。AI 不再只是“生成代码的工具”，而是变成了“能在项目里干活的 Agent”。

这种变化带来的最大好处是上下文连续性。以前你在一个对话框里描述问题，往往要贴大量文件内容，而 Agent 工具可以自己打开相关文件、搜索关键函数、读取报错日志。它更像是“坐在你旁边的实习生”，而不是“一个只能回答问题的搜索引擎”。

不过，这也带来了新的工程问题：AI Agent 的能力越强，越需要约束和引导。如果没有清晰的技能定义和上下文规范，它可能读了大半个项目、做了很多无关操作、生成不符合团队风格的代码。这也是 Agent Skill 概念迅速流行起来的原因。

1.2 Claude Code 与 Codex 分别是什么

Claude Code 是 Anthropic 推出的终端编程 Agent，与 Claude 系列模型深度集成，强调长上下文理解、代码编辑和工具调用能力。你可以在项目目录里直接运行claude命令，它会根据项目文件、指令文件和你的对话逐步完成任务。

Codex 是 OpenAI 推出的命令行编程工具，同样以 Agent 方式工作。它可以连接 OpenAI 的模型服务，也支持通过自定义模型提供方接入其他兼容模型。Codex 适合已经有 OpenAI 生态使用习惯的团队，也适合希望通过命令行自动化完成编码任务的开发者。

两者在理念上非常接近：都是“让 Agent 在本地环境里安全地操作项目”。但在具体的技能格式、配置方式、支持的命令和模型策略上存在差异。团队落地时，不需要一开始就纠结“哪个更好”，而应该先明确你想要 Agent 完成什么任务，再选择工具。

1.3 Agent Skill 在其中的位置

Agent Skill 不是某个工具的专属功能，而是一种把“完成某类任务的方法论”封装成 Agent 可读取、可调用、可复用单元的方式。一个 Skill 通常包含：任务描述、适用场景、执行步骤、约束条件、示例、工具使用建议等。

你可以把 Skill 理解为“岗位说明书”或“SOP 手册”。Agent 本身是执行者，Skill 是给它预先写好的工作流程。团队里常见的高价值 Skill 包括：代码审查、单元测试生成、数据库迁移脚本编写、日志排查、依赖升级、安全扫描、接口文档生成等。

这类技能之所以突然被频繁讨论，是因为大家发现：同一个模型，没有 Skill 时表现很随机，有了 Skill 后输出稳定很多。原因是 Skill 把隐性经验显性化了。

2. 概念区分：Agent、Skill、工具、上下文控制

2.1 Agent 与 Skill 的关系

很多初学者容易把 Agent 和 Skill 混在一起。Agent 是整个执行系统，它由模型、工具、上下文、对话循环组成。Skill 是 Agent 可加载的“能力包”，它告诉 Agent 在特定场景下应该遵循什么流程、调用哪些工具、输出什么格式。

可以这样理解：

• Agent：会思考、会调用工具、会执行操作的“工人”。
• Skill：工人手里的“操作手册”，不同任务对应不同手册。
• Tool：工人实际使用的“工具”，比如文件读写、命令行执行、网络请求。
• Context：工人当前看到的“工作环境”，包括项目文件、历史对话、全局规则。

举个实际例子：你做代码审查时，Agent 需要读取 diff、理解业务逻辑、检查安全漏洞、给出修改建议。如果你没有定义 Skill，Agent 会自由发挥；如果你把团队代码规范、审查重点、输出模板写进一个 Code Review Skill，Agent 就会按固定流程执行。

2.2 Skill 和系统提示词工程的区别

系统提示词工程大家比较熟悉，通常是在系统提示词里写“你是资深工程师，请遵循以下规范……”。这种方式适合约束 Agent 的通用行为，但它有一个明显的短板：随着规则增多，提示词变得冗长，Agent 每次对话都要处理大量固定文本，既消耗上下文，也容易“记不住重点”。

Skill 的思路不一样。它强调按需加载：Agent 在开始任务时，先根据用户意图判断需要哪些技能，再加载对应的说明文件。换句话说，系统提示词更像是“公司全体员工的通用入职手册”，Skill 则是“不同岗位的专项作业指导书”。通用手册要精简，专项指导书可以详细。

这也是为什么很多团队开始把冗长的“提示词工程文档”拆分成多个 Skill 文件。拆分之后，上下文占用减少，Agent 对当前任务的专注度反而更高。

2.3 Claude Code 与 Codex 中 Skill 的落地形态

在 Claude Code 中，常见的做法是使用项目级指令文件（如CLAUDE.md）来定义通用规则，同时把具体的技能说明放在独立目录中，由SKILL.md文件承载。当 Agent 遇到匹配任务时，可以读取对应的SKILL.md。在 Codex 中，类似机制通过项目指令文件（如AGENTS.md）和自定义命令实现，也可以把技能说明组织成可复用的文本文件。不同版本的工具对技能目录、加载机制的支持程度不一样，建议你以官方最新文档为准。

这里要强调一点：我们不需要纠结“到底是 Claude Code 的 Skill 更标准，还是 Codex 的 Skill 更标准”。真正重要的是掌握底层设计思路，然后根据工具的当前能力做适配。方法学会了，换工具也只是改一下文件格式。

3. 环境准备与安装

3.1 安装 Claude Code

Claude Code 的安装方式在不同阶段有所变化，目前比较常见的方式是通过 npm 全局安装。你需要先准备好 Node.js 环境，然后在终端执行：

npm install -g @anthropic-ai/claude-code

安装完成后，进入项目目录，执行：

claude

首次启动时会引导你完成登录和权限确认。登录成功后，Claude Code 就能读取当前目录下的项目文件了。

如果你是在 VS Code 中使用，可以到扩展市场搜索 Claude Code 官方扩展。装好后在扩展面板中登录，然后就可以在编辑器终端里直接启动会话。它的核心逻辑仍然是命令行工具，扩展只是提供了更友好的图形界面入口。

另外多说一句：Claude Code 的官方支持范围会根据服务条款和账号地区发生变化。如果启动时出现类似“Claude Code might not be available in your country”的提示，说明当前环境不在官方支持范围内。这时候不要尝试绕过限制，而是应该以官方支持列表为准，企业部署也应在合规网络环境下进行。

3.2 安装 Codex

Codex 同样可以通过 npm 安装：

npm install -g @openai/codex

安装完成后，运行：

codex

首次使用需要登录并验证账号。部分用户会遇到手机号验证，这通常和账号所属地区、安全策略有关。如果收不到验证码，优先检查账号信息是否完整，以及当前地区是否在服务范围内。

Codex 支持通过配置自定义模型提供方。很多团队会把 Codex 接入第三方兼容模型，例如 DeepSeek 或自建模型网关。具体配置方法会随版本变化，整体思路是在 Codex 的配置文件中声明一个自定义提供方，并指定模型名称、接口地址、鉴权方式等。下面的示例只是展示配置结构，你需要按实际版本调整：

{ "model_providers": { "my_provider": { "name": "My Provider", "base_url": "https://your-model-endpoint.example.com", "env_key": "MY_PROVIDER_API_KEY", "wire_api": "chat" } } }

配置完成后，通过-p或相关参数指定提供方和模型即可。这类自定义配置改动频繁，强烈建议查阅官方文档中的最新配置说明。

3.3 版本与运行时注意事项

无论安装哪个工具，都要注意三点：

第一，工具版本更新非常快。今天可用的参数，下个月可能就会废弃。如果你的项目里既有稳定版本要求，又有新功能需求，建议把 CLI 工具的版本固定下来，而不是每次都装 latest。

第二，Node.js 环境要保持干净。如果你之前装过其他命令行工具，环境变量 PATH 可能存在冲突。执行which claude或which codex可以查看命令实际指向的位置。

第三，企业内部安装时，尽量使用统一版本，并把安装步骤写进团队文档。否则不同开发者的工具行为不一致，Agent 生成的结果也会有很大差异。

4. 核心机制拆解：Skill 架构设计

4.1 Skill 的标准结构

虽然不同工具对 Skill 的具体实现有差异，但社区里已经形成了一套比较通用的结构约定。一个 Skill 通常是一个独立目录，目录里包含：

skills/ code-review/ SKILL.md examples/ 01-安全漏洞.md 02-性能问题.md

其中SKILL.md是核心文件，它用 Markdown 编写，顶部包含元信息，下面是对 Agent 的详细指令。元信息一般包括技能名称、描述、适用场景，部分实现还支持声明允许使用的工具。

编写时要注意：描述信息要具体且可匹配。Agent 能否在合适的时机加载这个 Skill，很大程度上取决于description是否写得清楚。如果描述是“用于代码审查”，太宽泛；如果写成“当用户要求审查 Pull Request、检查代码安全性或提交规范时使用，输入通常包含 git diff”，效果会好很多。

4.2 如何编写一个 SKILL.md

下面给出一个SKILL.md的示例骨架，你可以直接参考这个结构来写自己的技能：

--- name: code-review description: 当需要审查代码变更、检查代码规范、发现安全风险和性能隐患时使用。适用于 Pull Request 审查、提交前自检、他人代码走查等场景。 allowed-tools: - read_file - run_command --- # Code Review 技能 ## 目标 对当前代码变更进行系统性审查，输出可执行的修改建议，而不是泛泛而谈。 ## 执行步骤 1. 获取代码变更范围（git diff 或指定文件）。 2. 识别变更涉及的核心模块和风险点。 3. 按安全、性能、可读性、测试覆盖四个维度检查。 4. 输出结构化审查意见。 ## 输出格式 - 问题列表：按严重程度排序。 - 每个问题包含：文件位置、问题描述、修改建议、示例代码。 - 最终给出整体结论：通过 / 需修改后通过。 ## 常见红线 - 禁止直接修改生产环境配置。 - 敏感信息必须使用环境变量，不得硬编码。 - 不改变原有业务逻辑的前提下，优先做最小改动。

这里的关键不是格式本身，而是“可执行”。很多新手写的 Skill 只有抽象原则，比如“请认真审查代码”。这种描述 Agent 无法转换为具体动作。好的 Skill 应该包含步骤、判断条件、输出格式和红线约束。

另外，Skill 里可以写“何时不要使用”。例如：如果用户只是问一个概念问题，就不需要加载代码审查技能。这类负向描述能减少 Agent 误用技能的概率。

4.3 Skill 与工具管理的关系

工具管理是 Skill 设计中容易被忽略的一环。Agent 本身可以调用很多工具，但并不是每个场景都需要全部工具。例如代码审查 Skill 需要读取文件、执行 git diff，但可能不需要写文件；数据库迁移 Skill 需要执行 SQL 脚本，但必须限制在测试库。

如果你使用的工具支持在 Skill 中声明allowed-tools，一定要善用这个能力。它相当于给技能设置了权限边界。即便工具不支持这种声明，你也应该在 Skill 正文中明确写清楚：本技能可以调用哪些命令、禁止调用哪些命令、如果要执行破坏性操作必须停下来等待用户确认。

4.4 在 Claude Code 和 Codex 中接入 Skill

在 Claude Code 中，整体流程是：先在项目下创建skills目录，把 Skill 文件夹放进去，然后在对话中描述任务，Agent 会根据描述决定是否加载对应技能。你也可以把常用技能的说明写入CLAUDE.md，让 Agent 在启动时就了解项目里有哪些技能可用。

在 Codex 中，常用做法是利用项目指令文件AGENTS.md描述项目背景和可复用技能，再通过自定义命令把复杂的技能调用封装成一条短命令。例如把一个代码审查流程写成自定义命令后，每次执行都可以复用同一套标准。

需要注意的是，这两个工具的加载机制都还在快速演进。我建议你采用“先读官方文档 → 再建最小 Demo → 再团队推广”的路径。不要照搬网上的某个配置文件，因为那很可能已经过时了。

5. 完整实战：搭建一个团队级 Code Review Skill

5.1 需求与设计

下面我们通过一个完整案例，把前面的概念串起来。假设团队需要统一代码审查标准，希望 Claude Code 或 Codex 在审查代码时能输出固定格式的报告，并且自动检查常见安全红线。

我们先设计 Skill 的目标和范围。目标不是“替代人工审查”，而是“让人工审查更高效”。因此 Skill 的输出要结构化，直接暴露风险点，而不是输出一篇散文。范围限定在 Java 后端项目的 Pull Request 审查，重点关注：SQL 注入、空指针、事务边界、敏感信息泄露、异常吞掉等问题。

5.2 编写 Skill 文件

按照上面的结构，我们创建一个java-pr-review的 Skill：

--- name: java-pr-review description: 用于 Java 后端项目的 Pull Request 代码审查。当用户以 git diff、PR 链接或代码片段方式请求审查时使用。重点检查安全漏洞、事务问题、空指针风险、敏感信息泄露。 --- # Java PR 代码审查 ## 审查范围 - 只审查本次变更涉及的代码，不扩展审查无关模块。 - 同时读取关联的测试文件，检查变更是否有对应测试覆盖。 ## 审查维度 ### 1. 安全 - 拼接 SQL 字符串必须使用 PreparedStatement 或参数化查询。 - 文件上传路径必须校验，防止目录穿越。 - 日志中不得打印身份证号、手机号、密码、token 等敏感信息。 ### 2. 事务 - 涉及多表更新的方法，检查是否标注 @Transactional。 - 事务方法内部不得捕获异常后继续执行，避免事务失效。 - 长事务需要拆分为短事务，避免锁竞争。 ### 3. 空指针与异常 - 外部接口返回值使用前必须判空。 - catch 块不能为空，至少要记录日志。 - 不要吞掉 InterruptedException。 ### 4. 性能 - 循环内不得执行 SQL 查询，必须改批量查询。 - 大批量数据操作检查是否有分页或分批处理。 ## 输出格式 输出包含三部分： 1. 变更概述：一句话说明变更内容和涉及模块。 2. 问题列表：按严重程度从高到低排列，每个问题必须包含文件路径、行号、问题描述、修改建议。 3. 结论：通过 / 需要修改后通过。 ## 红线约束 - 不修改任何代码，只输出审查意见。 - 如果变更中存在敏感信息硬编码，必须标记为阻断项。 - 审查意见必须基于实际代码事实，禁止猜测。

这个 Skill 的关键点在于：把团队过去积累的常见问题显性化了。Agent 看到这条指令后，不再自由发挥，而是按四个维度逐项检查。每个维度的结论都必须基于代码事实，这也能减少虚假报告。

5.3 接入 Claude Code 与 Codex

在 Claude Code 中，把上面的目录放到.claude/skills/java-pr-review/下，并确保文件名是SKILL.md。然后在CLAUDE.md中增加一行说明：

## 技能列表 - java-pr-review：Java 后端 PR 代码审查，当收到 PR 审查请求时使用。

在 Codex 中，可以把技能正文放到项目文档目录中，并在AGENTS.md中引用。如果 Codex 自定义命令可用，还可以在配置文件中注册一条review命令，让用户通过codex review直接触发。

接入时最容易出问题的不是格式，而是路径。很多同学把 Skill 文件写好了，但是目录名和文件名不对，导致 Agent 扫描不到。建议先做一个最小验证：直接问 Agent“项目里有哪些技能可用”，看看它能否正确列出你刚添加的 Skill。

5.4 运行与效果验证

接入完成后，找一个小型 Pull Request 做实验。让 Agent 获取 diff 并执行审查，观察输出是否符合预期。第一次运行很可能不够好，这时不要急着改 Skill 文件，而是先看 Agent 在哪个环节出了问题：

• 如果它没有按四个维度检查，可能是描述不够明确，或 Skill 没有被加载。
• 如果它输出了错误的行号，可能是 diff 上下文不足，需要在 Skill 中增加“先读取完整文件再定位行号”的步骤。
• 如果它报了不存在的安全问题，可能是检查项过于模糊，需要补充正反例。

一个可用的 Skill 往往需要迭代几天。建议团队里由一个人先负责把 Skill 版本管理起来，像维护代码一样维护 Skill。

6. 企业落地：上下文控制、质量评估与团队级提效

6.1 上下文控制的工程手段

企业使用 Agent 编程时，上下文控制是最大的成本与质量杠杆。这里的“上下文”包含两层含义：一是模型能看到的项目信息量，二是模型需要处理的对话历史长度。上下文过长会导致费用上升、响应变慢、注意力分散；上下文过短又会导致 Agent 缺少必要信息，做出错误判断。

常见的控制手段有五个：

第一，精简全局指令文件。CLAUDE.md或AGENTS.md中只写稳定且高价值的规则，例如：项目结构说明、常用命令、代码风格、禁止事项。不要把所有团队规范全部堆进去。

第二，按需加载技能。把大段流程说明从全局指令移到 Skill 文件中，让 Agent 只在特定任务加载它。这样可以减少每次请求的基础 token 消耗。

第三，控制文件读取范围。在 Skill 中明确指出“只读取 src/main/java 下的相关文件，不扫描 node_modules、build、target 目录”。你也可以在调用命令时通过工具参数限制搜索范围。

第四，拆分会话。一个会话只做一件事。如果任务是“先审查代码再重构再写测试”，尽量拆成多个独立会话，避免历史对话积累过多无效信息。

第五，建立索引式文档。在项目指令文件中维护一张表格，列出“什么类型的问题到哪个文档查”。Agent 第一次看到问题描述时，先查索引，再决定是否读取详细文档。

6.2 质量评估：如何判断 Agent 输出是否合格

很多团队引入 Agent 后，最大的困惑是“如何评估效果”。这里推荐一套比较轻量的评估方式：准备一组黄金测试用例，定期把它交给 Agent 执行，然后人工打分。

例如针对代码审查 Skill，可以准备三个历史 PR：一个有 SQL 注入风险、一个有事务失效风险、一个规范但有小问题。每次 Skill 更新后，都让 Agent 跑一遍这三个用例，检查它能否发现固有风险，以及是否存在误报。分数可以分三档：完全命中、部分命中、未命中。

这种评估方式看起来简单，但能解决两个关键问题：一是技能迭代是否有正向效果；二是不同模型接入后行为是否稳定。团队规模较大时，可以把黄金用例的执行结果自动记录到表格里，形成回归测试集。

需要注意的是，Agent 的输出天然有一定随机性。单次测试通过不代表每次都通过，建议在评估时让同一个用例运行三次，取多数结果。如果随机性太大，优先从上下文和 Skill 指令的确定性上找原因。

6.3 团队级落地流程

企业级落地不能只靠几个开发者自己用，一定要形成流程。这里给出一个经过实践检验的落地顺序：

第一步，选定一个高价值、低风险场景试点。推荐从“代码审查”或“单元测试生成”开始，因为这两类任务边界清晰、结果可评估、不会直接改动生产环境。

第二步，指定专人负责维护 Skill 模板。Skill 本质上是团队知识资产，不应该散落在个人目录里。建议在 Git 仓库中单独建一个skills/目录，把技能纳入版本管理。

第三步，建立“Agent 操作安全边界”。原则上，Agent 不能直接操作生产环境，不能读取未授权的密钥，不能修改环境变量。如果工具支持权限审批，必须开启人工确认。团队应该明确列出“Agent 禁止执行名单”，例如禁止执行rm -rf、禁止直接连接生产数据库执行 DML。

第四步，设计人机协作流程。例如：Agent 负责生成代码草稿和单元测试，人负责审查和合并；Agent 负责定位日志中的错误，人负责决定修复方案。不要把 Agent 的结论当成最终结论。

第五步，定期复盘错误案例。每次 Agent 产生严重错误，都要复盘是模型问题、Skill 描述问题还是权限配置问题。把错误案例补充到对应的 Skill 中，形成“负面清单”。

6.4 成本与权限管理

成本控制是团队落地时必须面对的问题。Agent 编程工具调用模型的方式和普通聊天不同，它会不断读取文件、生成多轮对话，单次任务的 token 消耗可能很高。建议从三方面控制：

首先是上下文长度限制。设置单次会话的项目文件扫描上限，禁止 Agent 读取整个仓库。其次是任务拆分。大任务拆小任务，每个任务控制在可预期的范围内。最后是模型分级。简单任务用便宜模型，复杂推理用强模型，在工具配置中按技能类型切换。

权限管理则遵循最小权限原则。Agent 能读的目录尽量少，能执行的命令尽量窄，能调用的外部服务尽量少。特别是当 Codex 接入第三方模型接口时，API Key 必须通过环境变量注入，不能写进 Skill 文件或代码仓库。这里补充一句：企业落地时，所有涉及生产环境变更的操作，必须经过授权审批流程，并在测试环境完整验证后才能执行。

7. 常见问题与排查思路

下面列出使用 Claude Code 和 Codex 过程中常见的问题，覆盖安装、登录、配置和运行几个阶段。

排错时建议按“环境 → 配置 → 模型 → 技能”的顺序排查。先确认命令能正常运行，再检查配置是否被正确加载，然后确认模型提供方是否可用，最后才排查 Skill 本身的问题。因为 Skill 问题通常不会报错，而是表现为输出不符合预期，不容易直接发现。

另外，不要忽略日志。Claude Code 和 Codex 通常会在本地保存会话日志，日志中能看到 Agent 实际读取了哪些文件、调用了哪些工具、模型返回了什么内容。养成“看日志”的习惯，比反复猜测配置有效得多。

8. 总结与学习路线

这篇文章从 Claude Code 和 Codex 的基础概念开始，重点拆解了 Agent Skill 的设计思想，并通过一个 Java PR 审查的例子演示了从编写到接入的完整过程。你可以把本文的核心内容归纳为五点：Agent 是执行者，Skill 是执行手册；技能要按需加载，而不是塞进系统提示词；上下文控制决定质量和成本；质量评估需要黄金用例；团队落地必须做好权限和安全边界。

如果接下来想继续深入，建议按这个顺序学习：先把你手头最重复的一项开发任务写成 Skill 并跑通；然后尝试用评估用例量化效果；再研究工具的配置项，优化模型选择和上下文长度；最后在团队内小范围推广，逐步沉淀团队专属技能库。

最后给你一个比较实在的建议：不要一开始就追求“让 Agent 自动修所有 Bug”，也不要轻易让 Agent 直接操作生产环境。从代码审查、单测生成这类低风险任务开始，把 Skill、上下文、评估三个环节打磨顺了，再逐步扩展到更复杂的开发任务。如果你正在团队里推动 Agent 编程落地，不妨先建一个只有几个人的试点小组，把这套方法论跑通，再推广到全团队。