企业官网建设流程全解析

1. 这不是“又一个AI插件”：Claude Code 的本质是一套可编程的智能协作操作系统

你有没有试过让 Claude 帮你写一段 Python 脚本，结果它生成了逻辑正确但路径硬编码、缺少异常处理、没考虑跨平台兼容性的代码？你复制粘贴过去一运行，报错；改两行再问，它又给你新版本，但测试用例还是漏了三个边界条件；你反复来回十几次，时间过去了四十分钟，最终交付物依然卡在“基本能跑通”这个模糊状态——这根本不是 AI 不够聪明，而是你一直在用单步聊天的模式，强行把一个需要多角色协同、持续验证、自动修正的工程化任务，塞进一个线性对话框里。Claude Code 的核心价值，从来就不是“让 Claude 在 VS Code 里多聊几句”，而是提供了一套可声明、可编排、可闭环、可脚本化的智能体协作基础设施。它把“写代码”这件事，从“人和模型的一对一问答”，升级为“人定义规则，多个专业 Agent 各司其职、互相校验、自动修复”的流水线作业。关键词里的“多 Agent”不是噱头，“闭环自愈”不是宣传语，“Routine”更不是简单的快捷指令——它们共同构成了一个微型的、可嵌入开发环境的“智能协作操作系统”。我第一次用 Routine 脚本让一个 Agent 负责写单元测试、另一个 Agent 负责执行并分析失败原因、第三个 Agent 根据错误日志反向修改源码，整个过程无人工干预，三轮迭代后测试全部通过，耗时 2 分 17 秒。那一刻我才真正理解，Claude Code 的安装包里，装的不是一个聊天窗口，而是一套轻量级的、面向开发者的“智能工作流引擎”。它解决的不是“怎么调用 API”，而是“怎么让 AI 真正像一个有分工、有流程、有质量意识的团队一样，在你的 IDE 里持续工作”。

2. 多 Agent 编排：不是堆砌角色，而是构建有职责边界的协作网络

2.1 为什么必须是“多 Agent”，而不是“一个全能 Agent”？

很多人初看“多 Agent”概念，第一反应是：“是不是把一个大模型拆成几个小模型来用？”这是个典型误区。Claude Code 的多 Agent 架构，其底层逻辑并非物理隔离的模型实例，而是同一强大模型（Claude）在不同上下文约束、不同提示词模板、不同工具权限下的逻辑分身。它的价值不在于算力分散，而在于职责隔离与能力聚焦。举个最直观的例子：当你让一个 Agent 同时负责“写代码”、“写测试”、“检查安全漏洞”、“生成文档”，它的注意力必然被稀释，每个任务的 prompt 都要妥协，最终产出是平庸的平均值。而采用多 Agent 编排，你可以为“测试生成 Agent”专门设计一套包含 pytest 最佳实践、覆盖率要求、Mock 规则的 prompt，并赋予它只读源码、只写 test_*.py 文件的权限；为“安全扫描 Agent”配置 OWASP Top 10 的检查清单和 SAST 工具调用接口；为“文档生成 Agent”绑定项目 README 模板和 API 文档规范。它们共享同一个知识底座（Claude），但各自拥有清晰的“岗位说明书”。这就像一个真实的软件团队：前端工程师不会去写数据库迁移脚本，SRE 不会直接修改业务逻辑——职责边界越清晰，协作效率越高，出错率越低。Claude Code 的编排器，就是那个能把这些“虚拟工程师”按需召集、分配任务、传递中间产物、监督交付质量的项目经理。

2.2 编排的核心：Role、Tool、Context 三要素的精准控制

在 Claude Code 中，定义一个 Agent 的最小完备单元，由三个不可分割的要素构成：

• Role（角色）：这不是一句空泛的“你是一个资深 Python 工程师”，而是精确到技术栈、经验年限、工作习惯的描述。例如，一个用于“重构遗留代码”的 Agent，其 Role 可能是：“你是一位有 8 年 Django 开发经验的高级工程师，专精于将基于 class-based view 的旧代码迁移到基于 function-based view 和 class-based generic view 的现代模式。你厌恶全局变量，坚持使用 type hints，对 Django 4.2+ 的新特性（如 async views）持谨慎但开放态度。” 这段描述直接决定了模型在生成代码时的风格偏好、API 选择倾向和重构粒度。

• Tool（工具）：这是 Agent 的“手”和“眼”。Claude Code 支持声明式地为每个 Agent 绑定特定工具集。一个“部署检查 Agent”可能只被允许调用kubectl get pods和curl -I命令，而禁止执行任何kubectl delete或ssh操作；一个“数据验证 Agent”则被授予访问本地 SQLite 数据库的sqlite3工具和预设的 SQL 查询模板。工具权限的精细化控制，是实现“闭环自愈”的前提——没有权限，Agent 就无法执行修复动作，只能停留在“发现问题”的层面。

• Context（上下文）：这是 Agent 的“记忆”和“视野”。它不仅包括当前编辑的文件内容，更关键的是跨 Agent 共享的结构化上下文。比如，当“代码生成 Agent”完成任务后，它会输出一个 JSON 格式的元数据包，包含：{"function_name": "calculate_tax", "input_schema": {"amount": "float", "country_code": "str"}, "output_schema": {"total": "float", "breakdown": "dict"}}。这个元数据包会自动注入到后续“测试生成 Agent”的 Context 中，后者无需重新解析代码，就能精准生成覆盖所有输入组合的 pytest 参数化测试。这种结构化上下文的自动流转，彻底消除了传统工作流中因信息衰减导致的重复劳动和理解偏差。

提示：不要试图在一个 Agent 的 prompt 里塞进所有规则。我踩过的最大坑，就是给“文档生成 Agent”同时规定 Markdown 格式、API 参数顺序、错误码列表格式、以及公司内部术语表。结果它要么忽略术语表，要么把错误码列表写成表格而非列表。后来我把“术语表校验”单独拆成一个“文档合规性 Agent”，它只做一件事：扫描生成的文档，比对术语表，输出差异报告。两个 Agent 协作，质量反而更高。职责越单一，效果越稳定。

2.3 实战编排：一个真实场景的 Agent 协作链路

我们以“为一个新 REST API 端点添加完整的端到端支持”为例，拆解一个典型的五步 Agent 协作流程：

1. 需求澄清 Agent：接收用户自然语言描述（如“加一个 /api/v1/users/{id}/profile 接口，返回用户头像 URL 和最近三条动态”），主动向用户提出 2-3 个关键澄清问题（如“动态是否需要分页？头像 URL 是绝对路径还是相对路径？如果用户不存在，HTTP 状态码返回 404 还是 400？”）。它不生成代码，只确保需求无歧义。

2. 接口设计 Agent：基于澄清后的需求，生成 OpenAPI 3.0 YAML 规范，严格遵循公司标准（如所有x-*扩展字段、错误响应格式、认证方式）。它会调用openapi-validator工具校验语法，并将生成的 YAML 存入共享 Context。

3. 后端实现 Agent：读取 OpenAPI YAML，自动生成 FastAPI 的路由函数、Pydantic 模型、依赖注入逻辑。它被限制只能修改app/routers/目录下的文件，并强制使用@router.get装饰器和Depends(get_current_user)。生成后，它会输出一个包含所有新增文件路径的清单。

4. 测试生成 Agent：读取上一步的文件清单和 OpenAPI YAML，为每个端点生成test_routers/test_users.py，覆盖成功场景、404 用户不存在、401 未认证、422 参数校验失败等所有标准用例。它会调用pytest --collect-only验证测试发现。

5. 集成验证 Agent：启动一个临时的 FastAPI 测试服务器，执行所有新生成的测试，并捕获详细的pytest -v --tb=short输出。如果测试失败，它会分析错误日志，定位是 schema 定义问题、实现逻辑 bug 还是测试用例缺陷，并将诊断结果反馈给对应 Agent（如将“422 错误”详情发给“接口设计 Agent”，将“断言失败”详情发给“后端实现 Agent”）。

这个链条不是线性的瀑布模型，而是一个带反馈回路的网状结构。第 5 步的失败诊断，会触发第 2 或第 3 步的重新执行，形成真正的“闭环”。整个过程，用户只需在初始阶段回答几个澄清问题，后续所有 Agent 的调度、数据传递、失败重试，均由 Claude Code 的编排引擎自动完成。

3. 闭环自愈：让 AI 不仅能“发现问题”，更能“自主修复问题”

3.1 “自愈”不是魔法，而是可定义的修复策略与可执行的修复动作

“闭环自愈”这个词听起来很玄，但落到 Claude Code 的实操层面，它就是一个**“检测-诊断-修复-验证”四步循环的自动化流水线**。关键在于，每一步都必须是开发者可预见、可配置、可审计的。它绝不是让模型“自由发挥”去修 Bug，而是开发者预先定义好：“当出现某类特定错误时，执行哪几条确定的修复指令”。

以最常见的“Python 导入错误”为例。传统做法是：看到ModuleNotFoundError: No module named 'pandas'，手动打开终端，敲pip install pandas，再重启环境。在 Claude Code 的闭环自愈体系里，这个过程被拆解为：

• 检测（Detect）：当 Agent 执行python -c "import pandas"失败时，编排引擎捕获到这个ModuleNotFoundError异常，并提取出缺失模块名pandas。

• 诊断（Diagnose）：引擎查询内置的“常见依赖映射表”，确认pandas属于“数据科学基础库”，其标准安装命令是pip install pandas，且该命令在当前 Python 环境下是安全的（不会破坏现有依赖）。

• 修复（Repair）：引擎自动调用shell工具，执行pip install pandas。注意，这里调用的不是 Agent 的“建议”，而是引擎预设的、经过验证的修复动作。

• 验证（Verify）：修复命令执行后，引擎再次执行python -c "import pandas"，确认导入成功。只有验证通过，流程才继续；否则，进入下一个诊断层级（如检查 pip 是否可用、网络是否通畅）。

这个过程之所以可靠，是因为“诊断”和“修复”环节的规则，是由开发者在healing_rules.yaml文件中明确定义的。你可以为ImportError、SyntaxError、KeyError、甚至git push失败等数百种常见错误，编写对应的修复策略。这本质上是一种面向错误的领域特定语言（DSL），它把运维经验固化成了可复用、可版本控制的代码。

3.2 自愈的边界：什么能修，什么必须人来决策？

一个成熟可靠的自愈系统，其价值不仅在于它能修多少 Bug，更在于它清晰地划定了“自动区”和“人工区”的边界。Claude Code 的设计哲学是：所有涉及业务逻辑、数据一致性、安全策略的决策，必须由人做出；所有重复性、机械性、有明确规则的修复动作，交给系统自动完成。

• 可自动修复的典型场景：

  • 环境依赖缺失（pip install,npm install,brew install）
  • 代码格式问题（black .,prettier --write）
  • 基础类型错误（将int改为float，添加缺失的from typing import Optional）
  • 常见语法补全（闭合括号、引号、冒号）

• 必须人工介入的典型场景：

  • 业务逻辑冲突（“订单状态从‘已支付’变为‘已发货’，但库存不足”）
  • 数据迁移风险（“删除一个被 12 个微服务引用的数据库字段”）
  • 安全策略变更（“将 JWT 过期时间从 1 小时延长到 24 小时”）
  • 第三方 API 兼容性（“Stripe API v3 不再支持card对象，需迁移到payment_method”）

注意：我曾见过一个团队把“自愈”滥用，为KeyError设置了自动添加默认值的规则（如data.get('user_id', 0)）。结果在生产环境中，一个本该抛出异常的空用户 ID，被静默替换为 0，导致下游服务创建了一个 ID 为 0 的幽灵用户。教训是：任何自愈规则，都必须附带一条“影响评估”注释。比如，KeyError的修复规则后面，必须注明：“仅适用于非关键业务字段，如user_preferences.theme；对于user_id,order_id等主键字段，必须保留原始异常，交由人工处理”。规则越细，风险越可控。

3.3 构建你的第一个自愈规则：从requirements.txt同步开始

让我们动手创建一个实用的自愈规则，解决开发中最烦人的依赖同步问题：requirements.txt与实际代码中import的模块不一致。

1. 创建规则文件：在项目根目录下新建.claude/healing_rules.yaml。

2. 定义检测逻辑：我们利用 Python 的ast模块静态分析所有.py文件，提取所有import和from ... import语句，汇总成一个模块集合code_imports。同时，解析requirements.txt，得到req_modules集合。

3. 定义修复动作：当code_imports - req_modules非空时（即代码用了但 requirements 没列），执行pip freeze | grep -i <missing_module>获取精确版本，然后追加到requirements.txt；当req_modules - code_imports非空时（即 requirements 列了但代码没用），直接从requirements.txt中删除该行。

4. 编写 YAML 规则：

   - name: "Sync requirements.txt with actual imports" trigger: "on_save: *.py" # 当任意 .py 文件保存时触发 detect: script: | import ast import sys from pathlib import Path # 1. 提取所有 .py 文件中的 import code_imports = set() for py_file in Path(".").rglob("*.py"): if py_file.name == "__init__.py": continue try: tree = ast.parse(py_file.read_text()) for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: code_imports.add(alias.name.split(".")[0]) elif isinstance(node, ast.ImportFrom): if node.module: code_imports.add(node.module.split(".")[0]) except: pass # 2. 解析 requirements.txt req_modules = set() if Path("requirements.txt").exists(): for line in Path("requirements.txt").read_text().splitlines(): line = line.strip() if line and not line.startswith("#"): req_modules.add(line.split("==")[0].split(">=")[0].split("<=")[0].split("[")[0].lower()) # 3. 计算差集 missing_in_req = code_imports - req_modules unused_in_req = req_modules - code_imports # 4. 返回检测结果 result = {} if missing_in_req: result["missing"] = list(missing_in_req) if unused_in_req: result["unused"] = list(unused_in_req) print(result) repair: - if: "{{ missing }}" then: - shell: | for mod in {{ missing | join(' ') }}; do echo "Finding version for $mod..." pip show "$mod" 2>/dev/null | grep "Version:" | cut -d' ' -f2 | xargs -I {} echo "$mod=={}" >> requirements.txt done - shell: "sort -u requirements.txt -o requirements.txt" - if: "{{ unused }}" then: - shell: | for mod in {{ unused | join(' ') }}; do sed -i '' "/^$mod/d" requirements.txt 2>/dev/null || sed -i "/^$mod/d" requirements.txt done verify: script: | # 再次运行检测逻辑，确认差集为空 # （此处省略重复代码，实际应复用 detect 脚本） exit 0 # 简化示意，实际需判断

这个规则的价值在于，它把一个每天都要手动做的、枯燥且易出错的任务，变成了一个后台静默运行的守护进程。开发者专注写代码，系统自动保证依赖清单的准确性。这就是闭环自愈带来的真实生产力提升——不是替代思考，而是解放思考。

4. Routine 脚本化：用声明式语法，把复杂工作流变成一行命令

4.1 Routine 不是宏，而是可组合、可参数化、可调试的智能工作流

如果你把 Routine 理解成 VS Code 的“宏录制”，那你就完全错过了它的精髓。Routine 的本质，是一种面向开发者的、声明式的智能工作流编程语言。它用 YAML 或 JSON 这样的结构化格式，清晰地描述“做什么”（What），而不是“怎么做”（How）。这带来了三个革命性优势：

• 可组合性（Composability）：一个 Routine 可以无缝调用另一个 Routine。比如，你有一个build-and-testRoutine，它内部会先调用lint-code，再调用run-unit-tests，最后调用generate-coverage-report。每个子 Routine 都是独立开发、独立测试、独立版本管理的。这就像 Unix 哲学——“让每个程序只做好一件事，然后让它能与其他程序协作”。

• 可参数化（Parameterization）：Routine 支持丰富的参数类型。你可以定义一个deploy-to-envRoutine，它接受--env（staging/prod）、--branch（main/feature-x）、--dry-run（true/false）三个参数。当用户执行claude routine deploy-to-env --env staging --branch main时，Claude Code 会自动将参数注入到 Routine 的各个步骤中，比如kubectl apply -f manifests/staging/ --dry-run=client。

• 可调试性（Debuggability）：每一个 Routine 的执行，都会生成一份详尽的、带时间戳和上下文的执行日志。你可以清晰地看到：第 3 步的test-generation-agent因为超时被终止；第 5 步的integration-verification-agent在执行curl http://localhost:8000/health时收到了 503 响应；日志里还记录了当时所有 Agent 的输入 prompt、输出内容、调用的工具命令及其返回码。这让你能像调试一个 Python 函数一样，精准定位工作流的瓶颈和故障点。

4.2 从零开始：编写一个“一键生成 API 客户端 SDK”的 Routine

假设你的团队维护着一个内部的 RESTful 微服务，每次 API 变更，都需要手动更新 Python、TypeScript、Java 三种语言的客户端 SDK。这是一个典型的、高重复、易出错、强依赖的工作流。下面是如何用 Routine 将其自动化：

1. 规划 Routine 结构：我们需要一个主 Routinegenerate-sdk，它包含四个逻辑步骤：

   • fetch-openapi: 从https://api.yourcompany.com/openapi.json下载最新的 OpenAPI 规范。
   • validate-openapi: 使用spectral工具校验 OpenAPI 文件的合规性。
   • generate-python: 调用openapi-generator-cli generate -i openapi.json -g python -o sdk/python。
   • generate-typescript: 调用openapi-generator-cli generate -i openapi.json -g typescript-axios -o sdk/typescript。

2. 编写generate-sdk.yaml：

   name: "generate-sdk" description: "Generate Python and TypeScript SDKs from the latest OpenAPI spec." parameters: - name: "api_url" type: "string" default: "https://api.yourcompany.com/openapi.json" description: "The URL to fetch the OpenAPI specification from." - name: "output_dir" type: "string" default: "./sdk" description: "The directory to output the generated SDKs." steps: - name: "fetch-openapi" agent: "http-client-agent" input: url: "{{ api_url }}" method: "GET" output: file: "{{ output_dir }}/openapi.json" timeout: 60 - name: "validate-openapi" agent: "openapi-validator-agent" input: file: "{{ output_dir }}/openapi.json" tools: - "spectral" on_failure: - notify: "OpenAPI validation failed. Please check the spec." - abort: true - name: "generate-python" agent: "code-generator-agent" input: spec_file: "{{ output_dir }}/openapi.json" generator: "python" output_dir: "{{ output_dir }}/python" tools: - "openapi-generator-cli" command: | openapi-generator-cli generate \ -i {{ output_dir }}/openapi.json \ -g python \ -o {{ output_dir }}/python \ --additional-properties=packageName=yourcompany_api_client - name: "generate-typescript" agent: "code-generator-agent" input: spec_file: "{{ output_dir }}/openapi.json" generator: "typescript-axios" output_dir: "{{ output_dir }}/typescript" tools: - "openapi-generator-cli" command: | openapi-generator-cli generate \ -i {{ output_dir }}/openapi.json \ -g typescript-axios \ -o {{ output_dir }}/typescript \ --additional-properties=npmName=@yourcompany/api-client

3. 执行与验证：在终端中，只需一行命令：

   claude routine generate-sdk --api_url https://staging-api.yourcompany.com/openapi.json --output_dir ./staging-sdk

   Claude Code 会自动拉取规范、校验、生成两种 SDK，并将所有中间产物和日志存放在指定目录。整个过程无需人工干预，且每一步都可追溯、可重放。

实操心得：Routine 的调试，我最常用的方法是“分步执行”。当一个复杂的 Routine 报错时，我不会立刻去看整个日志，而是先用claude routine generate-sdk --step fetch-openapi只执行第一步，确认openapi.json下载成功；再执行--step validate-openapi，确认校验通过；以此类推。这比在长日志里大海捞针高效得多。另外，务必为每个on_failure事件配置notify，这样即使你在喝咖啡，也能第一时间收到 Slack 通知，知道哪个环节出了问题。

4.3 Routine 的进阶：条件分支与循环，构建真正的智能工作流

Routine 的强大之处，在于它支持类似编程语言的控制流。这使得它能处理更复杂的、需要决策的场景。

• 条件分支（Conditional Logic）：假设你的 CI 流程需要根据 Git 分支决定部署目标：

  - name: "deploy" if: "{{ git_branch == 'main' }}" then: agent: "k8s-deployer-agent" command: "kubectl apply -f manifests/prod/" else_if: "{{ git_branch == 'develop' }}" then: agent: "k8s-deployer-agent" command: "kubectl apply -f manifests/staging/" else: notify: "Unknown branch {{ git_branch }}. Deployment skipped."

• 循环（Looping）：为一组微服务批量生成 SDK：

  - name: "generate-all-sdks" loop: over: ["auth", "payment", "notification"] item: "service" steps: - name: "fetch-{{ service }}-spec" agent: "http-client-agent" input: url: "https://api.yourcompany.com/{{ service }}/openapi.json" output: file: "./specs/{{ service }}.json"

这些特性，让 Routine 超越了简单的脚本，成为一种可以表达复杂业务逻辑的、可执行的、可协作的“活文档”。它既是自动化工具，也是团队知识的载体——新成员阅读一个deploy-prodRoutine，就能立刻理解生产环境部署的完整步骤、依赖关系和安全检查点。

5. 常见问题与排查技巧实录：那些官方文档不会告诉你的实战陷阱

5.1 “Claude Code 安装后，VS Code 里看不到插件图标” —— 权限与沙箱的隐形墙

这个问题在 macOS 和 Ubuntu 上尤为常见。表面看是插件没加载，根源往往是VS Code 的沙箱机制与 Claude Code 的本地服务通信被拦截。

• macOS 的 Gatekeeper 问题：Claude Code 的桌面版是一个.app包，首次运行时会被 macOS 的 Gatekeeper 阻止。即使你右键“打开”绕过了警告，VS Code 插件仍可能无法与之建立 WebSocket 连接。解决方案：在终端中执行sudo xattr -rd com.apple.quarantine /Applications/Claude\ Code.app，清除所有隔离属性，然后重启 Claude Code 和 VS Code。

• Ubuntu 的 Snap 版本限制：很多用户通过snap install code --classic安装 VS Code，而 Snap 应用默认运行在严格的 confinement 沙箱中，无法访问/tmp目录或 localhost 的其他端口。Claude Code 的本地服务默认监听localhost:3000，Snap 版 VS Code 插件无法连接。解决方案：卸载 Snap 版，改用官方.deb包安装：wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > /usr/share/keyrings/microsoft-archive-keyring.gpg && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft-archive-keyring.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list && apt-get update && apt-get install -y code。

• Windows 的防火墙误报：Claude Code 的本地服务进程claude-code-server.exe有时会被 Windows Defender SmartScreen 误判为潜在威胁，阻止其监听端口。解决方案：在 Windows 安全中心 -> “病毒和威胁防护” -> “管理设置” -> 关闭“基于声誉的保护”，或在防火墙高级设置中，为claude-code-server.exe创建一个入站规则，允许 TCP 端口 3000。

排查技巧：最快速的诊断方法是，在终端中手动启动 Claude Code 服务，并观察日志。执行claude-code-server --port 3000 --verbose，如果看到Server started on http://localhost:3000，说明服务正常；如果卡在Starting server...，大概率是端口被占用或权限不足。此时，用lsof -i :3000(macOS/Linux) 或netstat -ano | findstr :3000(Windows) 查看端口占用情况。

5.2 “多 Agent 协作时，Agent A 的输出，Agent B 总是读不到” —— Context 传递的三大雷区

Context 是多 Agent 协作的生命线，但它的传递极易出错。以下是三个最隐蔽的雷区：

• 雷区一：文件路径的相对性陷阱。Agent A 生成了一个文件./src/utils/helpers.py，它在自己的 Context 中记录的路径是src/utils/helpers.py。但 Agent B 的工作目录可能是./tests/，它尝试读取src/utils/helpers.py时，就会失败。解决方案：所有 Agent 必须统一使用项目根目录作为工作目录。在 Routine 的steps中，显式设置working_directory: "."。

• 雷区二：JSON 输出的格式污染。Agent A 的 prompt 要求它输出一个 JSON 对象，但它在结尾处多加了一行// Done.。这导致 Agent B 用json.loads()解析时抛出JSONDecodeError。解决方案：为所有需要结构化输出的 Agent，强制启用output_format: "json"，并在其 prompt 中加入严格指令：“请只输出纯 JSON，不包含任何解释性文字、代码块标记（```json）、或注释。JSON 必须是有效的、可直接被 Python json.loads() 解析的字符串。”

• 雷区三：Context 大小的隐式截断。Claude Code 默认对每个 Agent 的 Context 有大小限制（通常是 128KB）。当一个大型 OpenAPI YAML 文件（>100KB）被注入到 Context 后，后续 Agent 的 prompt 可能被截断，导致它“看不见”完整的规范。解决方案：对于大文件，不要直接注入全文，而是注入一个指向该文件的 URI（如file:///path/to/openapi.json），并为 Agent 配置tools: ["file-reader"]，让它在需要时自行读取。这既节省 Context 空间，又保证了数据完整性。

5.3 “自愈规则写了，但从来不触发” —— 触发器（Trigger）的精确匹配艺术

自愈规则的trigger字段，是它的“开关”。写得不精确，规则就形同虚设。

• on_save的文件模式陷阱：on_save: "*.py"看似能匹配所有 Python 文件，但它不会匹配__init__.py（因为*不匹配下划线开头的文件），也不会匹配Dockerfile或Makefile。解决方案：使用更宽泛的模式on_save: "**/*.py"，或者明确列出on_save: ["*.py", "__init__.py", "Dockerfile"]。

• on_command的命令名混淆：你想在执行git commit后触发一个规则，但on_command: "git commit"是无效的，因为 VS Code 插件捕获的是底层的git.commit命令 ID，而不是终端里敲的字符串。解决方案：查阅 VS Code 的 Command Palette，找到对应命令的 ID。例如，git.commit的 ID 就是git.commit，workbench.action.terminal.runActiveFile的 ID 就是workbench.action.terminal.runActiveFile。在trigger中使用 ID，而非自然语言。

• on_error的异常类型粒度：on_error: "Exception"太宽泛，会捕获所有异常，包括KeyboardInterrupt（Ctrl+C）这种用户主动中断。on_error: "ModuleNotFoundError"又太窄，可能漏掉ImportError（它是ModuleNotFoundError的父类）。解决方案：查阅 Python 的异常继承树，选择最合适的粒度。对于导入问题，on_error: "ImportError"是最佳选择，因为它能捕获ModuleNotFoundError和ImportError本身。

5.4 “Routine 执行一半卡住，CPU 占用 100%” —— Agent 超时与资源限制的硬性保障

一个失控的 Agent，会拖垮整个工作流。Claude Code 提供了关键的“熔断”机制。

• timeout参数是生命线：每个step都必须设置timeout。默认值往往不够用。对于需要调用外部 API 的步骤（如fetch-openapi），timeout: 30秒是底线；对于需要编译或运行测试的步骤（如run-unit-tests），timeout: 300秒（5 分钟）更合理。没有timeout，一个网络请求失败的 Agent 会无限等待，导致整个 Routine 挂起。

• memory_limit与cpu_limit的必要性：对于可能产生大量中间数据的 Agent（如一个负责解析大型 CSV 并生成统计图表的 Agent），仅靠timeout不够。它可能在 30 秒内没完成，但已占满 4GB 内存，导致系统卡顿。解决方案：在agent的定义中，添加资源限制：

  agents: - name: "csv-analyzer" memory_limit: "2G" cpu_limit: "1.0"

  这会强制该 Agent 在内存超过 2GB 或 CPU 使用率持续超过 100% 时被终止。

• retry策略的智慧：对于网络请求类的步骤，简单的retry: 3可能不够。你需要指数退避（Exponential Backoff）：第一次失败后等 1 秒，第二次失败后等 2 秒，第三次失败后等 4 秒。Claude Code 支持retry: { max_attempts: 3, backoff: "exponential" }。这能有效避免在服务短暂抖动时，所有请求在同一毫秒内重试，造成雪崩。

最后一个独家技巧：当你遇到一个难以复现的、偶发性的 Routine 卡死问题时，不要急于修改代码。先检查你的~/.claude/logs/目录。里面有一个system.log，记录了 Claude Code 主进程的所有活动。打开它，搜索CRASH或OOM（Out Of Memory），往往能找到根本原因——比如某个旧版本的openapi-generator-cli在处理特定 schema 时存在内存泄漏。日志，永远是你最忠实的战友。