企业官网建设流程全解析

很多项目里最麻烦的事情，往往不是“写代码”本身，而是写完之后还要做代码评审、跑测试、整理变更记录、输出报告这一整串重复劳动。手动干几轮之后，你会发现这些工作其实非常有规律：有输入、有规则、有输出、可验证。既然有规律，那就可以沉淀成流程，而流程，正好是 AI 智能体最擅长处理的部分。

过去一年里，Claude Code 成了我日常开发中很常用的一款命令行 AI 工具。它不只是“在终端里聊天的 Claude”，而是能够直接读取项目文件、修改代码、执行命令、运行测试的主动智能体。配合上工作流设计，完全可以把“拉取改动 → 自动评审 → 生成报告 → 写变更日志”这类链路自动化。

这篇文章会完整拆解如何用 Claude Code 搭建一个主动智能体工作流，包括安装配置、核心机制、项目级指令、Skills 技能封装、Hooks 自动触发，以及一个可以直接跑起来的实战案例。新手可以照着从头配，有基础的开发者可以直接跳到第 4 节看工作流设计思路。

1. 为什么要用“主动智能体工作流”

1.1 从对话式 AI 到主动智能体

早期我们使用 AI 的方式，基本都是“对话式”的：问一个问题，它给一段回答；不满意再追问，它再补充。这种模式适合知识问答，但在工程场景里效率并不高。比如项目里有一段代码出了 bug，你复制粘贴进去让 AI 分析，它给出建议后，你还得自己打开文件修改、执行测试、再看结果。

主动智能体（Agent）不太一样。它拿到的是一个目标，而不是一句话。它自己拆解步骤、选择工具、执行操作，并根据执行结果调整下一步。举个例子：

• 对话式 AI：你问“这段代码哪里有问题？”它告诉你“第 10 行可能出现空指针”。
• 主动智能体：你告诉它“帮我检查最近一次提交的代码，定位问题并修复，然后跑一遍测试确认没挂”。它会自己执行git diff、打开相关文件、修改代码、运行测试、报告结果。

这种“目标驱动 + 工具调用 + 结果反馈”的闭环，就是主动智能体工作流的核心。

1.2 Claude Code 是什么

Claude Code 是 Anthropic 推出的命令行 AI 编程智能体。它并不是另一款聊天网页产品，而是运行在你项目目录里的编程助手，可以做到：

• 读取项目文件，理解代码结构；
• 修改代码文件，完成重构或修 bug；
• 执行终端命令，比如运行构建、测试、格式检查；
• 管理任务队列，在多步骤场景中按计划执行；
• 通过CLAUDE.md文件记住项目级约定。

简单理解：Claude Code 把 AI 从“建议者”变成了“执行者”。

1.3 主动智能体工作流适合做什么

不是所有任务都适合交给主动智能体。适合的典型场景有这些：

如果你手头的工作符合这些特征，那就可以考虑封装成主动智能体工作流。本文后面会以一个“自动代码评审 + 变更日志生成”的例子展开。

2. 环境准备与安装

2.1 安装前置条件

在使用 Claude Code 之前，建议先确认环境满足以下条件：

• 操作系统：macOS、Linux，或 Windows 的 PowerShell / WSL；
• Node.js 18 及以上版本，npm 可用；
• 终端中已安装 Git（非必需，但大多数工作流会用到）；
• 拥有一个 Anthropic 账号，或准备 API Key。

版本要求需要根据你实际安装时的官方说明为准，本文以常见环境为例，重点是演示配置思路。

可以先检查当前环境：

node -v npm -v git --version

如果 node 或 npm 未安装，先到 Node.js 官网安装 LTS 版本，再继续后续操作。

2.2 安装 Claude Code

Claude Code 的安装方式比较统一，使用 npm 全局安装即可：

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

如果你是第一次安装，安装完成后验证一下版本：

claude --version

如果之前安装过旧版本，可以用下面的命令升级：

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

在 Windows 环境下，如果 PowerShell 执行策略限制脚本运行，可能会提示执行策略错误。可以用管理员权限允许当前用户执行脚本，或换到 WSL 中使用。

2.3 登录与验证

安装完成后，在项目目录下直接运行：

claude

首次运行会进入登录引导流程，终端会提示你在浏览器中完成登录授权。登录成功后，回到终端即可开始对话。

验证是否可用，可以直接在 Claude Code 的交互界面里问一句：

请介绍一下当前目录的项目结构

如果 Claude Code 能正常读取文件并回答，说明环境已经就绪。接下来就可以配置主动智能体工作流了。

3. Claude Code 的核心机制

要搭建工作流，光会启动交互界面还不够。得先理解 Claude Code 的几个关键能力点。

3.1 交互模式与命令模式

Claude Code 支持两种主要使用方式。

交互模式

直接运行claude进入对话界面，适合日常探索、写代码、逐步调试。在交互模式下，Claude 可以读取工作目录中的文件，并执行终端命令。

命令模式（非交互）

使用-p参数可以直接传入 prompt，让 Claude 执行后输出结果并退出。这种模式非常适合脚本化和自动化工作流。

claude -p "请用三句话总结当前目录下的 README.md 内容"

如果需要控制最多执行多少步，可以配合--max-turns参数，防止 Agent 过度执行：

claude -p "检查代码风格问题并修复" --max-turns 10

在自动化脚本中，还可以使用--output-format json输出结构化结果，方便后续程序处理。需要注意：不同版本的输出格式和参数名可能有差异，建议以你当前安装版本的官方文档为准。

3.2 CLAUDE.md：项目的“长期记忆”

Claude Code 最重要的一个机制就是CLAUDE.md文件。可以把它理解为“给 AI 看的项目文档”。

在项目根目录下创建CLAUDE.md后，Claude Code 启动时会自动读取里面的内容，并在整个会话中遵循这些约定。这个文件通常用来写：

• 项目架构说明；
• 代码风格规范；
• 测试命令和构建命令；
• AI 在执行任务时需要注意的安全边界。

例如一个后端项目的CLAUDE.md可能是这样：

# 项目指令 ## 项目简介 这是一个基于 Python FastAPI 的订单服务项目。 ## 技术栈 - Python 3.11 - FastAPI - SQLAlchemy 2.x - PostgreSQL ## 常用命令 - 运行测试：pytest tests/ -v - 启动服务：uvicorn app.main:app --reload ## 约定 - 新增接口必须添加 Pydantic 校验模型 - 数据库操作必须放在 service 层，禁止直接在路由层写 SQL - 代码提交前必须跑一遍测试 ## 安全边界 - 不要删除任何 migration 文件 - 不要直接修改生产环境配置

这样，Claude Code 在每一次干活之前都会先“读一遍”项目规则，不需要你在每次对话里重复说明。

除了项目根目录，用户主目录下的~/.claude/CLAUDE.md也可以作为全局配置，存放个人通用的偏好，而项目级配置优先级更高。

3.3 Skills：把经验封装成能力

Skills 是 Claude Code 比较新的扩展机制，可以理解为“预置任务模板”。你可以把一个经常要做的任务封装成一个 Skill，以后每次让 Claude 调用即可。

典型的 Skills 目录结构如下：

.claude/ └── skills/ ├── code-review/ │ └── SKILL.md └── changelog/ └── SKILL.md

每个技能目录下有一个SKILL.md，使用 Markdown 描述：

• 技能的用途；
• 输入参数；
• 执行步骤；
• 输出格式。

Skills 的最大价值是“一次封装、重复使用”。比如你定义了“代码评审”技能，以后只要说“执行 code-review”，Claude 就会按技能里的步骤走，而不是每次重新总结一套流程。

不过，Skills 的格式要求发展比较快，配置前建议先查一下你所用版本的官方文档说明。

3.4 Hooks：在关键节点介入

Hooks 是 Claude Code 提供的事件钩子机制。你可以设置在某个操作之前或之后，自动执行一段命令。常见用途包括：

• 在 Claude 执行 Bash 命令前检查是不是高危命令；
• 在 Claude 修改文件后自动执行格式化；
• 在 Agent 完成任务后把结果写入日志。

配置文件通常放在项目的.claude/settings.json中。下面是一个简化示例，表示在每次执行 Bash 命令前运行一个检查脚本：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python scripts/check_command.py" } ] } ] } }

这里的matcher和钩子类型需要按你安装的 Claude Code 版本确认，不同版本可能支持的事件名称不一样。关键是理解它的用途：把人类规则注入到 Agent 的自动执行流程中。

4. 实战：搭建一个主动智能体工作流

理论部分讲了不少，接下来进入核心实操环节。我们来搭建一个比较典型的主动智能体工作流：代码提交评审 + 变更日志自动生成。

4.1 场景设计

假设我们的项目有一个规矩：

• 每次提交代码前，需要先对当前改动做一轮代码评审；
• 每次发布版本时，要根据提交记录生成变更日志；
• 这些工作全部通过 Claude Code 完成，不需要人工写评审意见和变更日志。

这个场景非常适合主动智能体，因为它包含清晰的输入（git diff）、处理规则（评审标准 / 日志格式）、输出（报告 / Markdown 文档）以及验证方式（代码能通过测试）。

4.2 创建项目结构

先创建一个示例项目目录：

mkdir ai-workflow-demo cd ai-workflow-demo git init

然后创建目录结构：

ai-workflow-demo/ ├── .claude/ │ ├── CLAUDE.md │ ├── settings.json │ └── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── changelog/ │ └── SKILL.md ├── scripts/ │ ├── auto_review.sh │ └── auto_changelog.sh ├── src/ │ └── demo.py └── README.md

依次创建对应目录：

mkdir -p .claude/skills/code-review mkdir -p .claude/skills/changelog mkdir -p scripts mkdir -p src

4.3 编写 CLAUDE.md：定义工作流规则

在.claude/CLAUDE.md中定义整个工作流的上下文。这是 Claude Code 每次启动都会读取的文件，相当于给 AI 一套“岗位说明书”。

# AI 工作流 Demo 项目指令 ## 项目简介 这是一个演示主动智能体工作流的示例项目，包含 Python 函数和一些自动化工件。 ## 工作流规则 ### 代码评审工作流 1. 用户要求执行 code-review 时，调用 code-review 技能。 2. 评审对象通常是 git diff 或者指定文件内容。 3. 评审报告必须包含：问题等级、问题位置、修改建议。 4. 如果检查到严重问题，必须明确提示“建议修复后重新提交”。 ### 变更日志工作流 1. 用户要求生成 changelog 时，调用 changelog 技能。 2. 日志格式必须遵循 Keep a Changelog 风格。 3. 每个版本条目包含：版本号、日期、类型（Added/Changed/Fixed）。 ## 通用约束 - 所有命令都在项目根目录执行。 - 不要修改 .git 目录下的文件。 - 不要在代码中写入真实密钥或敏感配置。

这样设定之后，Claude Code 在项目里执行任务时，就会自动遵守这些工作流规则。

4.4 定义 Skills：封装两个核心任务

接下来定义两个 Skill。

首先是代码评审技能，文件路径：.claude/skills/code-review/SKILL.md

--- name: code-review description: 对 git diff 或指定代码执行代码评审，输出结构化问题清单 --- # Code Review 技能 ## 输入 - 代码 diff 内容，或具体文件路径 ## 执行步骤 1. 读取当前 git diff，或读取指定文件。 2. 检查以下维度： - 逻辑正确性 - 边界条件处理 - 异常处理 - 命名与可读性 - 安全性 3. 逐个问题输出。 ## 输出格式 ```markdown ## 评审结论 - 总评：通过 / 不通过 / 需要修改 ## 发现问题 | 等级 | 位置 | 问题描述 | 修改建议 | | --- | --- | --- | --- | | 中 | src/demo.py:12 | 空列表未处理 | 增加 if 判断 | ## 建议 - 补充边界条件的单元测试

再创建变更日志技能，文件路径：`.claude/skills/changelog/SKILL.md` ```markdown --- name: changelog description: 根据 git 提交记录生成变更日志 --- # Changelog 技能 ## 输入 - 版本号 - 时间范围或 git 提交范围 ## 执行步骤 1. 使用 git log 获取提交记录。 2. 根据提交信息归类：Added、Changed、Fixed、Removed。 3. 生成标准 Markdown 变更日志。 ## 输出格式 ```markdown ## [版本号] - 日期 ### Added - 新增功能描述 ### Changed - 变更说明 ### Fixed - 修复说明

这两个技能封装好之后，Claude 只需要调用 `code-review` 或 `changelog` 就能按标准执行任务。 ### 4.5 编写自动执行脚本 Skills 适合在会话中调用，但如果希望整个工作流完全自动化，就需要命令脚本把 Claude Code 串起来。 创建 `scripts/auto_review.sh`： ```bash #!/usr/bin/env bash set -euo pipefail # 获取最近一次提交的 diff，如果没有提交，则获取工作区 diff DIFF=$(git diff HEAD~1 2>/dev/null || git diff) if [ -z "$DIFF" ]; then echo "没有检测到代码变更，跳过评审。" exit 0 fi # 使用 Claude Code 命令模式执行 code-review 技能 claude -p "请基于以下 git diff 执行 code-review 技能，输出评审报告： $DIFF"

创建scripts/auto_changelog.sh：

#!/usr/bin/env bash set -euo pipefail VERSION=${1:-"0.1.0"} SINCE=${2:-$(git log --oneline -10 | tail -1 | awk '{print $1}')} git log --oneline "$SINCE"..HEAD > /tmp/commit_list.txt claude -p "请读取 /tmp/commit_list.txt 中的提交记录，执行 changelog 技能，为版本 $VERSION 生成变更日志。 日期请使用今天。"

这两个脚本就是工作流的“触发入口”。开发者只需在终端跑一行命令，Claude Code 就会自动完成之前需要人工阅读、分析和总结的工作。

4.6 配置 Hooks：提交前自动触发评审

如果想再进一步，在每次git commit前自动执行评审，可以在.claude/settings.json里配置 Hook。这里我们先用一个保守的示例：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "bash scripts/auto_review.sh" } ] } ] } }

需要注意：这个配置表示每次 Claude Code 内部尝试执行 Bash 工具时，都会先跑一遍自动评审。实际项目中需要根据自己的需求和版本调整 Hook 事件，避免在每次执行命令时都触发，导致效率下降。

对于纯 Git 流程的场景，更简单的方式是使用 Git 自带的 pre-commit 钩子：

cat > .git/hooks/pre-commit << 'EOF' #!/usr/bin/env bash bash scripts/auto_review.sh EOF chmod +x .git/hooks/pre-commit

这个配置不依赖 Claude Code 的 Hook 事件，更容易控制触发时机。但要注意，这种钩子只在当前仓库生效，不会随项目提交到远程仓库。

4.7 运行与验证

先给脚本添加执行权限：

chmod +x scripts/auto_review.sh chmod +x scripts/auto_changelog.sh

创建一个最简单的示例代码文件src/demo.py：

def get_first_item(items): return items[0]

然后提交代码：

git add src/demo.py git commit -m "feat: 添加获取首个元素函数"

运行自动评审脚本：

bash scripts/auto_review.sh

Claude Code 会拉取 diff，执行 code-review 技能，最后输出类似这样的评审报告（示意输出，实际内容根据代码和 Claude 版本会不同）：

## 评审结论 - 总评：需要修改 ## 发现问题 | 等级 | 位置 | 问题描述 | 修改建议 | | --- | --- | --- | --- | | 高 | src/demo.py:1 | 未处理空列表，会抛 IndexError | 先判断 items 是否为空 | ## 建议 - 补充空列表用例

这说明工作流已经跑通了。接下来修改代码：

def get_first_item(items): if not items: return None return items[0]

再次提交，运行评审，如果没问题，就可以继续执行变更日志生成：

bash scripts/auto_changelog.sh 0.2.0

Claude Code 会根据提交记录生成变更日志。整个过程里，AI 按照预设的规则自主完成评审、输出报告、整理日志，这就是一个完整的主动智能体工作流。

5. 进阶：多步骤编排与省 Token 技巧

5.1 多步骤任务的拆分思路

在实际项目中，工作流往往比代码评审复杂得多。比如“新需求开发完成后，自动执行测试、生成文档、提交 PR”。面对这类任务，最好把大目标拆成小步骤，每一步都能被验证：

1. 第一步：让 Claude 读取需求文件和相关代码；
2. 第二步：执行测试命令，确认当前基线；
3. 第三步：修改代码实现功能；
4. 第四步：再次运行测试，确认不回归；
5. 第五步：生成文档或 PR 描述。

每个步骤之间要有“检查点”。Claude Code 支持在会话内保持上下文，因此可以让它在一个会话里完成整个流程，也可以通过--continue参数接续上一次会话。

5.2 省 Token 的实用技巧

不少同学关心 Claude Code 的 Token 消耗。这里分享几个实测有效的思路。

技巧一：把项目规范写进 CLAUDE.md

项目级约束提前写入CLAUDE.md，AI 每次都会自动读取，不用在 prompt 里重复描述项目背景、代码风格和常用命令。一段 50 字的规范，能省下每轮对话里重复的几百字说明。

技巧二：尽量用命令模式配合精炼 prompt

自动化脚本中使用claude -p时，prompt 要尽量精炼，避免无关上下文。比如直接说“执行 code-review 技能”比长篇描述“请你作为一名资深后端工程师，仔细检查以下代码的健壮性……”更节省 Token。

技巧三：控制--max-turns

多步骤任务中，Agent 可能会反复尝试某些操作，白白消耗 Token。设置--max-turns可以限制最大执行轮数，防止失控。

claude -p "完成功能并跑测试" --max-turns 15

技巧四：只喂必要的代码片段

有的新人会把整个文件甚至整个项目粘贴进 prompt，这会消耗大量 Token。正确做法是让 Claude 自己读取文件，只传入文件路径和关键需求；需要分析 diff 时，只让它看git diff的结果，而不是全量代码。

技巧五：用标准输出格式做机器处理

当工作流只是为了生成结构化结果时，使用--output-format json获得机器可读输出，再配合后续 Python 脚本处理，比在终端里来回复制文本更高效，也能减少无效交互的 Token 消耗。

5.3 与其他工具的配合

很多同学也在了解 Claude Code 和 Codex 之间的差异。简单来说，Codex 是 OpenAI 发布的编程智能体，Claude Code 是 Anthropic 发布的编程智能体，两者定位相似，都希望帮助开发者在终端里完成自动化编程工作。区别主要体现在底层模型、配置生态和具体执行能力上。Claude Code 的CLAUDE.md、Skills、Hooks 机制，让它比较容易和项目工作流深度绑定。

实际选型时，建议都试一下，看哪种更符合你自己的开发习惯。工具没有绝对好坏，关键在于能不能真正融入你的工程流程。

6. 常见问题与排查思路

在配 Claude Code 工作流时，大家容易遇到几个问题，这里整理成表格：

6.1 安装后命令找不到

这通常是因为 npm 的全局安装目录不在系统的 PATH 中。可以先找到全局目录：

npm prefix -g

然后把这个目录的 bin 子目录加入 PATH，或者直接用 nvm 安装 Node.js 来避免权限和路径问题。

6.2 会话上下文混乱

如果发现 Claude 在项目中开始“忘记”你之前定下的规则，优先检查CLAUDE.md是否写得足够明确。另一个做法是定期使用--reset清理上下文，让新会话重新读取配置，避免上下文太长影响准确性。

6.3 自动化脚本执行时卡住

命令模式执行时如果长时间没有输出，可能是 Agent 正在执行某个命令或等待确认。可以检查脚本中是否有关交互式命令，比如git commit可能会触发编辑器。自动化场景建议使用--max-turns限制执行步数，并在关键命令中加--no-edit等参数避免交互等待。

7. 最佳实践与工程建议

7.1 为 Agent 设置清晰的安全边界

主动智能体能执行命令，就意味着它能造成危害。工程上一定要设置安全边界：

• 限制 Agent 的工作目录，避免它跑到无关路径修改文件；
• 在CLAUDE.md中写明哪些操作绝对禁止；
• 涉及删除、生产环境变更、数据库操作等高风险动作时，必须有授权和备份机制；
• 在 CI 或生产环境中使用命令模式时，不要给 Agent 超出必要范围的权限。

7.2 Skills 要小而专

Skill 是工作流封装的利器，但不要设计成“万能技能”。一个 Skill 只做好一件事，输入输出明确，规则可执行。这样既能降低维护成本，也方便单独替换或扩展。

7.3 结果需要二次校验

智能体不是绝对可靠的。AI 生成的代码、自动化评审结论，最终仍要通过人工或 CI 检查。例如：

• 自动评审可以定位问题，但“是否要改”还是由人来定；
• 自动生成的变更日志要检查版本号和日期是否准确；
• 自动修改的代码必须通过测试门禁。

7.4 配置纳入版本管理

.claude目录、scripts目录都应该纳入 Git 管理。这样团队其他成员克隆项目后，会自动获得相同的工作流配置。如果某些 Hook 包含敏感路径或密钥，记得不要把敏感内容提交到仓库。

7.5 善用日志与审计

自动化流程执行后，建议把每次执行的关键信息写入日志文件，例如时间、输入 diff、评审结论、执行耗时。这样出了问题可以回溯，也方便后续优化工作流。

8. 总结

用 Claude Code 搭建主动智能体工作流，核心不在于记住多少命令，而在于把“流程意识”放进 AI 的使用方式里。你会渐渐发现，让 AI 真正介入开发和项目管理，不是简单地问它问题，而是给它一套明确的规则、技能和触发方式，让它成为团队里“能干活的执行者”。

这套配置非常适合从代码评审、变更日志生成开始上手，因为这两个场景规则清楚、风险低、效果立即可见。等熟悉之后，可以逐步扩展到自动测试、自动文档生成、依赖升级等更复杂的流程。

如果你正在做的项目里也有大量“规则明确、重复度高、验证简单”的流程，建议把它们逐步沉淀成 Skills 和自动化脚本。工作流这种东西，一旦用顺了，就很难再回到纯手工操作的时代。