2026年前后AI编程工具早就不是“补全几行代码”的辅助插件了。以 Claude Code、Codex 为代表的 Agent 化编程助手正在改变 Java 开发者写接口、跑测试、做代码评审和排查故障的方式。与此同时企业级 Agent Skill 开发正在成为一个新的能力分水岭会用工具的人很多能把自己的开发流程沉淀成 Skill、让 Agent 稳定复现的人很少。这篇文章不是要堆八股文而是围绕 Java 技术栈把 Claude Code、Codex、Agent Skill、MCP 这几个概念放进真实开发链路里讲清楚并提供一套可以直接上手练习的 Skill 开发方法。读完你会明白“Agent 是怎么工作的”“Skill 为什么比每次手工写提示词可靠”“面试时该怎么把项目经验讲得不像背题”也能用三天时间完成一轮从安装、写第一个 Skill、到企业级优化和面试表达的完整练习。1. 先建立主线Claude Code、Codex 和 Agent Skill 到底是什么1.1 Agent 类编程工具解决了什么问题传统 IDE 的代码补全是根据当前光标上下文预测下一段代码。它不会主动帮你读整个项目的结构也不会自己去执行 Maven 命令。Claude Code 和 Codex 这类工具之所以被称为 Agent 类编程工具是因为它们具备“任务理解、工具调用、结果验证、错误修正”的完整执行链路你输入一个目标它会读取项目文件、搜索相关类、调用构建命令、看运行日志再根据结果调整下一步操作。这里的关键不是它“能写代码”而是它能像一位开发助手一样围绕一个任务反复尝试。比如面对一个 Spring Boot 项目你让它“给 UserController 生成接口文档并校验参数缺失”它可能会先找到 Controller 类、读取方法签名、再执行某个脚本生成 Markdown最后列出哪些接口缺少注释。这个过程中模型本身只负责推理真正落地靠的是它能够访问文件系统、终端和外部命令。1.2 Claude Code 与 Codex从命令到任务Claude Code 是 Anthropic 推出的命令行编程 Agent通常在终端里通过claude命令启动可以切换到项目目录后让它分析代码、修改代码、执行测试。Codex CLI 是 OpenAI 推出的类似产品通过codex命令启动可以执行代码修改、命令运行和文件操作。从开发者视角看两者最大的共同点是都强调“在项目上下文里工作”而不是像网页聊天那样脱离实际工程环境。实际使用中两者不等于只能互斥。有人习惯把 Claude Code 用于分析设计和代码生成把 Codex 用于需要与 OpenAI 模型能力深度配合的场景。也有人通过企业内部的统一网关让两个 CLI 使用同一套模型服务。更值得关注的是它们背后的扩展机制Claude Code 生态中强调 SkillsCodex 生态中强调AGENTS.md和自定义命令。核心目标是一致的——让 Agent 的行为可以被项目规范约束而不是每次自由发挥。对比维度Claude CodeCodex CLI交互方式终端命令行、交互式会话终端命令行、交互式会话核心能力文件读取、命令执行、任务拆解文件读取、命令执行、任务拆解扩展机制Skills、CLI 插件、MCP 工具AGENTS.md、自定义命令、MCP 工具常见使用场景代码生成、重构、测试、排障代码生成、仓库维护、自动化任务企业落地要点权限控制、日志审计、模型版本管理相同按企业规范统一配置1.3 Agent、Skill、MCP 的关系很多刚接触的人会被这三个词绕晕。先给一个直观比喻Agent 是“干活的人”Skill 是“这个人手里的操作手册”MCP 是“他能连接的外部工具接口”。Agent 负责理解目标并决定下一步动作Skill 负责把固定流程和判断标准固化成可复用的文件MCP 负责让 Agent 能调用数据库、内部系统、外部 API 等资源。所以“Claude Code”和“Codex”是 Agent 产品“Agent Skill”是给 Agent 使用的一套技能封装。Skill 解决的是“怎么做”的问题比如生成 Java 接口文档时先检查 Controller 注解、再提取方法签名、最后输出指定格式。MCP 解决的是“能做什么”的问题比如让 Agent 能查询 MySQL、读取 GitLab 合并请求、调用内部发布平台。没有 Skill 的时候每次都要在提示词里重新描述流程没有 MCP 的时候Agent 拿不到外部数据和工具能力上限会低很多。概念核心问题典型载体类比Agent理解目标、规划动作Claude Code、Codex CLI执行者Skill将稳定流程固化为操作手册SKILL.md、模板、脚本操作手册MCP连接外部数据与工具MCP Server、工具定义工具接口1.4 Java 开发者为什么值得学这一套Java 面试中谈到 AI 大模型最怕的是只会说“我用过 ChatGPT 写代码”。面试官真正想听到的是你能不能把 AI 能力接入一条实际业务链路能不能让工具行为受控能不能判断模型输出是否正确。Agent Skill 恰好提供了一个很好的切入角度它把提示词、脚本、校验规则、项目约定封装在一起既有工程味又能体现你对 AI 工作流的理解。从技术栈角度看Java 项目里已经有大量可被 Agent 调用的资产Maven 构建脚本、单元测试、Checkstyle 规则、API 文档模板。把这些资产封装成 Skill 并不需要重写系统只需要让 Agent 学会“按什么步骤调用这些资产”。这是门槛相对低、收益又明显的方向也是本篇后面要动手实践的核心。2. 环境准备把 Claude Code 和 Codex 安装到本机2.1 前置条件Node.js、npm、GitClaude Code 和 Codex CLI 通常通过 npm 安装所以第一步先检查 Node.js 环境。推荐使用 Node.js 18 或更高版本较老版本可能在安装依赖或运行 CLI 时出现兼容问题。Git 主要用于操作仓库也在很多安装场景中被依赖。node -v npm -v git --version确认输出后再检查是否已经有全局的代码目录和权限。如果在 macOS 或 Linux 上遇到全局安装权限问题不要直接用sudo npm install -g一把梭建议先调整 npm 的全局目录或者使用 nvm 管理 Node.js 版本避免破坏系统权限。注意学习阶段可以用本机全局安装快速跑通。生产环境或企业内部共享开发机应优先使用容器镜像、CI 基础镜像或统一工具链保证每个开发者环境一致。2.2 安装 Claude CodeClaude Code 的安装命令在不同版本中可能略有变化常见方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后执行claude --version如果这条命令能输出版本号说明安装成功。首次使用时CLI 会要求你完成认证。企业环境通常有两种方式一种是使用 Anthropic 账号登录另一种是通过环境变量配置 API Key。export ANTHROPIC_API_KEY你的API Key团队开发时不要把 Key 写死在项目或终端历史里。推荐使用本地环境变量文件或密钥管理服务并在.gitignore中排除相关文件。2.3 安装 Codex CLICodex CLI 的安装同样走 npmnpm install -g openai/codex验证codex --version如果环境中已经安装了 Codex但 Claude Code 或另外一个工具在调用时定位不到codex二进制常见报错是unable to locate the codex cli binary. Set CODEX_CLI_PATH or ensure the executable is in PATH。这个问题的本质是某个工具在启动子进程时找不到 Codex 可执行文件。此时先检查codex --version是否正常再确认环境变量CODEX_CLI_PATH是否正确指向可执行文件路径最后把包含codex的目录加入PATH。which codex echo $CODEX_CLI_PATH export PATH$PATH:/usr/local/bin export CODEX_CLI_PATH/usr/local/bin/codex2.4 验证安装和检查配置安装只是第一步更重要的是确认 CLI 能读取项目上下文。建议在一个普通 Java 项目里先执行一次轻量请求claude -p 请列出当前项目的 Maven 模块结构 codex exec 请查看当前项目有哪些 Spring Boot Controller如果 CLI 能准确回答项目结构说明文件读取和命令执行链路正常。如果输出为空或报错则优先检查当前目录、Git 仓库状态、密钥配置和网络连通性问题。还可以查看当前使用的模型和配置claude config list codex --help不同版本输出不同但至少能确认当前 CLI 的版本、模型配置和可用命令方便后面排错。2.5 学习环境与生产环境不一样个人电脑上跑通只说明工具本身没问题。企业级落地还要比这里多三层第一层是权限Agent 能读写哪些目录、能执行哪些命令不能无人看管第二层是日志用户输入、模型输出、执行过的命令都要有审计记录第三层是稳定性模型版本、Skill 版本、脚本版本都要锁定不能今天能跑明天就挂。后面所有案例的代码块在没有特别说明时都适合本地学习环境。生产环境需要配合 CI、监控、权限系统和回滚机制一起使用。3. 从零开发一个 Java 接口文档 Skill3.1 Skill 的核心文件组成Skill 的本质是把一段“容易在聊天里被遗忘的工作流”做成项目里的固定资产。常见结构如下.claude/skills/java-rest-doc/ ├── SKILL.md ├── scripts/ │ ├── generate_doc.sh │ └── validate_doc.sh └── references/ ├── api_template.md └── annotation_rules.mdSKILL.md是入口文件告诉 Agent 什么时候该使用这个技能、具体步骤是什么。scripts/里放可执行脚本负责那些模型不擅长的高精度操作比如格式化、批量扫描、校验。references/放参考模板和规则避免把大量样例塞进提示词导致上下文爆炸。不同版本的 Claude Code 或 Codex 对“Skill 放在哪里”的目录规范可能不完全一样落地前先根据你安装的版本确认细节。下文的示例更侧重设计思路你可以照着思路调整成自己项目里的结构。3.2 SKILL.md 怎么写以一个“Spring Boot Controller 接口文档生成”为例。SKILL.md 里需要包含触发条件、执行步骤、输入要求、输出格式、检查清单。核心原则是“可执行、可校验、不依赖模型临场发挥”。--- name: java-rest-doc description: 为 Spring Boot Controller 生成接口文档。当用户提供 Controller 文件路径或要求生成 API 文档时使用。 --- # 目标 根据 Java Controller 源码生成 Markdown 接口文档并校验接口参数是否完整。 # 输入 - Controller 文件路径例如 src/main/java/com/example/controller/UserController.java # 执行步骤 1. 读取 Controller 文件。 2. 检查是否为 Spring Web 组件 - 类上有 RestController 或 Controller 注解 - 类上有 RequestMapping 时记录基础路径 3. 遍历 public 方法解析 - GetMapping、PostMapping、PutMapping、DeleteMapping 对应的 HTTP 方法 - PathVariable、RequestParam、RequestBody 对应的参数 - 方法返回值类型 4. 调用 scripts/generate_doc.sh 生成 Markdown 文档。 5. 调用 scripts/validate_doc.sh 校验文档是否包含全部接口。 # 输出格式 输出到 docs/api/ 目录文件名为 ControllerName.md。 # 检查清单 - [ ] 每个接口都有 HTTP 方法 - [ ] 每个接口的路径完整 - - [ ] 请求参数和 Java 类型对应 - [ ] 没有把 Controller 的私有方法当作接口SKILL.md 不需要写得像小说但要把边界写清楚。尤其要写明“什么时候不能用”避免 Agent 在错误场景里强行使用技能。3.3 用脚本兜底不要让 Agent 自由发挥模型生成 JSON 或 Markdown 时可能会漏字段、改格式。要解决这个问题最好的方式不是靠提示词强调“请严格按照格式”而是写一段脚本做强校验。#!/usr/bin/env bash set -euo pipefail CONTROLLER_PATH${1:-} OUTPUT_DIR${2:-docs/api} if [ ! -f $CONTROLLER_PATH ]; then echo ERROR: Controller file not found: $CONTROLLER_PATH exit 1 fi mkdir -p $OUTPUT_DIR BASENAME$(basename $CONTROLLER_PATH .java) OUTPUT_FILE$OUTPUT_DIR/$BASENAME.md echo # $BASENAME API 文档 $OUTPUT_FILE echo $OUTPUT_FILE echo 自动生成时间$(date %Y-%m-%d %H:%M:%S) $OUTPUT_FILE echo $OUTPUT_FILE grep -nE (GetMapping|PostMapping|PutMapping|DeleteMapping) $CONTROLLER_PATH \ | sed s/^/接口方法: / $OUTPUT_FILE echo 文档已生成: $OUTPUT_FILE这个脚本只做最简单的示例。真正项目里你可以用 Shell、Python、Java 或 Node.js 写同样的逻辑。脚本的价值在于确定性不管模型怎么表达最终落盘的文件都由脚本控制。3.4 在 Codex 里复用同一套资产AGENTS.mdClaude Code 的 Skill 不能直接被 Codex 读取但企业级项目不希望同一套规范在两个工具里维护两遍。一个常见做法是在项目根目录维护AGENTS.md让 Codex 把 Skill 目录当作参考资料来使用。# AGENTS.md ## 接口文档生成规范 - 当需要生成接口文档时先阅读 .claude/skills/java-rest-doc/SKILL.md - 必须使用 .claude/skills/java-rest-doc/scripts/generate_doc.sh 生成文档 - 生成后必须执行 validate_doc.sh 校验 - 文档输出到 docs/api/ 目录这样设计之后Claude Code 原生读取 SkillCodex 通过 AGENTS.md 指引读取同一份资产。虽然触发机制不同但对团队来说规范是唯一的。3.5 触发技能与验证输出在 Claude Code 的交互终端里可以直接用自然语言描述需求如果当前版本支持技能选择也可以通过技能名称调用。在 Codex 中则通过 AGENTS.md 的描述让模型自动选择合适的流程。claude -p 使用 java-rest-doc 技能为 UserController.java 生成接口文档 codex exec 按照 AGENTS.md 中的接口文档规范为 UserController.java 生成文档生成完成后检查两个东西cat docs/api/UserController.md bash .claude/skills/java-rest-doc/scripts/validate_doc.sh docs/api/UserController.md如果文档缺失某个接口说明 SKILL.md 里的执行步骤描述不够严格或者脚本没有做完整性校验。此时应该改 Skill 而不是继续提示模型再跑一次。注意验证 Skill 是否生效不看“Agent 是否回答了”而看“产出物是否稳定”。多跑几次每次结果一致才算合格。4. 企业级 Skill 设计让结果稳定、可审计、可维护4.1 把“步骤”和“模板”固化下来个人用 Skill最容易犯的错误是 SKILL.md 里只写“生成一份接口文档”没有写步骤、没有写输入输出、没有写检查清单。结果就是 Agent 每次生成的结果都不一样。企业级 Skill 必须具备“过程可重复”和“产物可校验”两个特征。推荐在 SKILL.md 中写清楚以下内容触发条件用户说什么话、提供什么上下文时使用。输入要求需要哪些路径、哪些配置、哪些前置命令。执行步骤步骤的数量控制在 5 到 10 个每个步骤都要有检查点。输出格式文件路径、命名规则、格式模板。错误处理什么情况要停止并报错什么情况可以重试。检查清单最终输出前必须逐项验证。4.2 用 Java CLI 工具处理复杂逻辑当 Skill 需要解析 Java 源码、读取注解、调用 Maven 插件时Shell 脚本会变得难以维护。更推荐的方案是把复杂逻辑写成一个 Java 命令行工具Agent 只需要记住触发命令。mvn -q -f skill-tools/pom.xml compile exec:java \ -Dexec.mainClasscom.example.skill.ApiDocGenerator \ -Dexec.argssrc/main/java/com/example/controller/UserController.java docs/api这样做的最大优点是Java 代码可以复用项目里的既有类、测试基础设施和静态分析规则而且更容易写单元测试。对于企业级团队这比维护一长串 Shell 脚本更可靠。4.3 添加日志、校验和幂等性Agent 执行过程中谁也不知道模型会不会把命令参数传错。为了让问题可定位Skill 脚本至少要做到三点。第一记录关键输入和输出路径。比如生成文档前把 Controller 路径、输出目录、执行时间写入日志。第二对输入做校验文件不存在、参数为空时立即失败并提示而不是继续执行。第三保证幂等性同一个输入多次执行结果一致不能因为上一次生成的文件残留导致这次结果不同。LOG_DIR${SKILL_LOG_DIR:-.claude/skills/logs} mkdir -p $LOG_DIR LOG_FILE$LOG_DIR/java-rest-doc.log echo $(date %Y-%m-%d %H:%M:%S) input$CONTROLLER_PATH output$OUTPUT_FILE $LOG_FILE4.4 权限和密钥怎么管Skill 脚本里如果写死数据库连接串、API Key、云平台密钥一旦项目仓库泄露损失会非常大。企业落地时密钥必须走环境变量或密钥管理服务。Agent 本身可以读写项目文件更要限制它不能随意读取~/.ssh、~/.aws等敏感目录。建议在项目根目录维护一份.agentignore或类似文件明确告诉 Agent 哪些目录不能读取、哪些命令不能执行。即使 Skill 本身没有恶意也要防止模型在中间步骤中误操作。4.5 不同团队如何共享技能资产技能资产应该像代码一样做版本管理。常见做法是把.claude/skills/和AGENTS.md放进 Git 仓库通过分支和 Code Review 控制变更。一个 Skill 从上到下的演进可以这样划分个人实验在个人分支里写 SKILL.md。团队试用合入团队仓库让 3 到 5 个开发者试用。标准发布补充脚本测试、文档样例、日志规范后发布。定期维护每当项目结构或工具链变化时更新 Skill 并记录变更。这种流程和代码评审很接近进入团队的接受成本较低也容易被面试官认可。5. 常见报错与排查链路5.1 工具装不上、找不到二进制现象是执行codex --version正常但另一个工具提示unable to locate the codex cli binary。根因通常是子进程启动时没有继承正确的 PATH或者没有设置CODEX_CLI_PATH。先按顺序排查which codex echo $PATH echo $CODEX_CLI_PATH如果which codex能找到路径但外部工具仍然找不到大概率是 PATH 没有包含该路径。解决方式是显式设置CODEX_CLI_PATH指向绝对路径再重启当前终端或父进程。5.2 模型名称和权限报错报错形如xxxx is not a model this version of Claude Code recognizes常见原因是工具版本太旧或者配置里写了一个当前版本不认识的模型名。先升级 CLI再查看当前支持的模型列表或配置文档不要盲目把模型名写成最新模型因为 CLI 版本没跟上时不会生效。另一个常见问题是组织策略限制比如Your organization has disabled Claude subscription access for Claude Code。这通常不是本地配置错误而是账号或组织权限问题。处理顺序是先确认当前登录账号是否在允许名单再检查订阅类型最后联系管理员调整策略。5.3 资源不足与输出异常有时候 Agent 会启动多个 Java 进程执行 Maven 或单元测试导致内存不足。典型现象是java: OutOfMemoryError: insufficient memory。此时不要一上来就怀疑 Java 项目本身先看是不是 Agent 并发执行了太多任务。处理方式降低同时执行的任务数让 Maven 一次只跑一个模块。调整 JVM 内存参数但不要无脑调大先确认机器内存和容器限额。在 Skill 脚本里增加并发限制比如使用mvn -T 1C控制并行度。检查是否同时运行了多个 Agent 会话避免资源争抢。5.4 一条更稳的排查顺序遇到 Agent 相关报错建议按这个顺序排查不要一上来就怀疑网络或模型。排查层检查内容对应操作输入需求是否清晰、路径是否正确检查命令参数和文件是否存在文件路径是否在正确的项目目录pwd、ls确认目录结构二进制CLI 是否安装且可执行which claude、which codex配置模型名、密钥、路径配置claude config list、环境变量权限组织策略、目录访问权限检查账号角色、文件权限资源内存、CPU、并发数free -h、ps aux日志是否有明确异常栈查看.claude日志或终端输出工具版本CLI 是否太旧执行npm update -g相关命令这八层里前三层能解决大部分“装不上、找不到、跑不动”的问题后五层才需要深入工具链和代码。6. Java AI 大模型面试怎么把实战经验讲清楚6.1 被问到“Claude Code 和 Codex 有什么区别”怎么答不要只说“一个是 Anthropic 的一个是 OpenAI 的”。更有效的回答结构是先讲共同点再讲差异最后落到项目场景。可以用这个框架两者都是命令行 Agent能够读取项目、执行命令、修改代码。差异在于扩展生态和默认模型Claude Code 有 Skills 能力Codex 有 AGENTS.md 和自定义命令。我在实践中的选择标准是如果团队更依赖 Anthropic 模型就优先 Claude Code如果希望和 OpenAI 生态结合更紧密就优先 Codex。两者也可以在同一项目中共存通过统一规范约束行为。面试官听到你能从工程角度谈选型而不是只背产品名印象会好很多。6.2 被问到“Skill 和 MCP 有什么区别”怎么答这是搜索热度很高的一个问题也是面试高频题。推荐这样回答“Skill 解决的是怎么做事。它把完成一项任务的步骤、模板、检查清单写进一个文件让 Agent 在对应场景下按这套流程执行。MCP 解决的是能调用什么。它把外部 API、数据库、内部系统封装成 Agent 可以调用的工具。Skill 偏流程MCP 偏连接。实际项目中我会把业务规则做成 Skill把外部系统接入做成 MCP Server两者配合使用。”6.3 用 Java 项目把 Agent 实践讲具体面试时最有说服力的不是概念而是你亲手做过的案例。围绕一个 Spring Boot 项目你可以讲这条链路项目里维护了.claude/skills/java-rest-doc用于自动生成接口文档。SKILL.md 规定了解析注解、调用脚本、生成 Markdown 的步骤。脚本负责校验 Controller 方法是否都有 HTTP 注解。Codex 通过AGENTS.md读取同一套规范。合入仓库前必须跑validate_doc.sh否则不通过。上线后接口文档生成时间从人工 30 分钟缩短到自动 1 分钟。这里不需要夸大效果重点是你能讲清流程、校验、排错和迭代这比“我用 AI 写了 CRUD”有说服力得多。6.4 三天刻意练习安排标题里提到的“3 天学完”不能替代日常积累但可以作为一个高密度练习计划天数练习重点产出物Day 1安装 Claude Code 和 Codex学会交互和命令执行完成环境验证生成项目结构报告Day 2写第一个 Java Skill至少一个脚本校验SKILL.md 可执行脚本 文档示例Day 3把 Skill 接入 Codex AGENTS.md模拟面试讲述AGENTS.md、变更记录、面试回答稿每天结束前把跑通的命令、报错和修复过程记录成 Markdown。这些记录就是你面试时最好的项目素材。6.5 面试中最容易暴露的五个坑第一只说工具名不讲原理。面试官追问工作机制时就卡住。第二把 Skill 和 MCP 混为一谈甚至说“Skill 就是 MCP”。第三项目案例没有校验和排错环节一听就是 demo 而不是生产实践。第四为了追新模型把一些未经验证的配置写进项目。第五不会验证 Agent 输出生成什么就接受什么这是企业级最忌讳的。练习时可以专门针对这五个坑做一轮模拟问答让朋友扮演面试官反复追问。7. 最佳实践清单与下一步扩展7.1 Skill 开发前检查清单写一个 Skill 之前先用这张清单确认方向这个任务是否经常重复是否值得固化为 Skill。是否已经有一个确定的工作流而不是边写边想。SKILL.md 是否包含触发条件、执行步骤、输出格式和检查清单。不可靠的格式处理是否交给脚本而不是交给模型。脚本是否有输入校验、日志和幂等性。是否在 Codex 和 Claude Code 之间共享了同一套资产。敏感信息是否已通过环境变量或密钥服务管理。是否经过多人试用而不是只有作者能跑通。7.2 企业落地还要补什么个人项目里跑通 Skill不等于企业级落地。企业环境还要考虑配置外置化、统一模型网关、权限隔离、命令审计、监控告警和回滚方案。比如 Agent 执行了哪些命令、读取了哪些文件都要有日志可查。Skill 的版本要跟应用版本一起管理不能出现发布后 Skill 找不到脚本的情况。另外不要把 Agent 的产物直接放进生产链路。接口文档、测试代码、SQL 脚本都建议经过人工 Review 和自动校验两关。Agent 负责提效人负责兜底。7.3 扩展方向MCP Server、RAG、本地模型当 Skill 开发熟练之后可以继续向三个方向扩展。第一个是 MCP Server 开发把公司内部系统封装成标准工具接口让 Agent 能查询订单、创建发布单、读取监控指标。第二个是 RAG把团队技术文档、历史故障记录、代码规范做成可检索知识库Agent 在回答问题前先检索相关文档。第三个是本地模型部署在数据敏感场景下使用私有化模型作为 Agent 的推理引擎但需要额外处理模型版本、GPU 资源和服务稳定性。这些方向都可以继续使用“先固化流程、再工具化、再验证结果”的方法论。坚持把这套方法用到不同的 Java 项目里Claude Code、Codex、Agent Skill 就不再是面试里的名词而是你日常开发工具箱里真正能用上的一部分。