意图即代码

一个简单的 Claude Code 实战，讲述从“写指令”到“Agent 工程化”的范式升级。

在现在这个时间点，如果说你唯一需要学习的 AI 工具，那可能就是 Claude Code（或类似的 OpenCode 框架）。

虽名字里有个 "Code"，但它其实是一个通用的 Agent 框架，你可以用它来做任何事。

前段时间，我基于它做了 SuitAgent 的框架，一个用于诉讼案件分析的智能体。这个小工具对我本人的律师工作提效良多。具体文章可参见开源了首个用于诉讼的智能体框架 SuitAgent。

但随着研究的深入，我也越来越清楚它的不足。框架一旦变大，最先崩的是“可维护性”。

本文是我在元旦期间基于 Claude Code 的新功能，对 SuitAgent 框架升级后的复盘心得。写得不成熟的地方先留在这里，方便之后继续迭代。

一、 规则解耦：迈向标准的 "/rules"

在使用 Claude Code 早期，我们会编写冗长的 Prompt，或者庞大的单体规则文件来约束行为。

这套方式在项目刚起步时确实有效。但复杂度一旦上来，“万字长文”很快就会成为瓶颈：人类难以维护，模型也容易在海量信息里迷失。

规则管理的工程化路径正在收敛

这次升级的核心并不复杂，就是顺应 AI 行业规则管理的标准化趋势，用逻辑隔离的思维重构 Agent 配置。

Claude Code 最新的功能支持在根目录保留 claude. md，同时通过 .claude/rules/ 文件夹进行精细化管理。它把项目共识和可维护规则库切成了两个层级。

这两种文件的优先级相同，都会在对话一开始的时候就注入。

我利用 .claude/rules/ 建立了逻辑隔离的规则矩阵，目前的文件夹结构如下：

拆分哲学：边界比内容更重要

claude. md 里放共识。它负责回答项目是什么、边界在哪里、默认遵守哪些约束。不写场景路径，也不写 SOP 细节。

入口文件一旦承担太多职责，后续改动都会牵一发动全身。

拆到 rules 目录，按生效范围去切规则。

全局且稳定的规则放在 WorkflowSystem 这类文件里。会随着业务频繁变动的规则，则放在 WorkflowScenarios 里。

这样系统的变动会呈现出一种更清晰的结构：你是在改地基，还是在加场景，还是只是在补某个领域能力。

当然，目前的这个结构依然还是有很大的迭代空间，比如部分 rules 并非总是需要，随着部分功能的膨胀，后续可以再次拆封或修正为渐进式披露的 skills。

二、 范式转型：意图即代码，定义身份而非编写程序

在重构 SubAgents 的设计文档过程中，我深刻感知到 Agent 开发正在进入意图即代码（Intent as Code）的时代。

这里的“代码”不再是某种编程语言的语法，而是一种可执行的意图描述。你把 SOP、边界、检查点写清楚，它就能按照这套结构去运行。

身份先于能力

先把"身份"写清楚，身份里至少包含职责边界、行为偏好和交付口径。

职责边界明确它该做什么，不该做什么。行为偏好决定了遇到信息缺失或冲突时如何取舍。交付口径则规定了输出的组织形式与材料引用规范。

身份定义清楚了，协作才成立，框架才有扩展空间。塑造的角色就可协作了。

Debug 方式的演进

在 Claude Code 里，很多偏差表现为"跑偏"或"不稳定"。这种时候我最常做的不是切换环境变量中的模型，而是回到意图文档里修正。

我会检查规则是否具备可执行性，优先级是否清晰，以及有没有明确的检查点。

当你把规则写成能被复盘、能被验证的句子，系统就会从 玄学调参 变成 工程迭代。

这种语境下，修正文档本质上就是在修正程序。

三、 上下文治理：提取能力阶梯的最大公约数

随着规则库膨胀，我发现很多原本写在私有文档里的内容可以进行"上下文迁移"。

迁移的核心逻辑是提取能力的最大公约数。

如果某些能力是所有 SubAgents 都会用到的，它就不该继续躺在某个角色的私有文档里。

Rules、Skills 还是 User Context？

我目前的迁移标准分为三层。项目上下文存放于 rules 文件夹，涵盖所有角色都需要的最大公约数。

技能上下文则抽象为独立的 Skills，处理高度专业化且低频的能力，如复杂的外部 API 联调。跨项目的个人偏好则沉淀在用户目录的全局文档中。

这套分层解决的是一个现实问题：每次运行时，模型的大脑里到底应该装哪些东西。

具体的上下文分层理论，可以参见Skills Instead Of Agents：不做智能体，先把你的专业能力写成 Skills。

逻辑隔离是为了跑得更稳健

物理位置与逻辑层级的映射，是在辅助 Claude 执行其原生的渐进式披露逻辑。

重要且通用的规则始终在场，专业且低频的能力按需加载。

模型注意力资源有限，你把所有东西塞进去，它就必须先做筛选。筛选成本高了，稳定性自然就下来了。

系统会更像一个有统一底座的组织，而不是各自为政的散装智能体。

逻辑隔离也是一种解耦，能让系统在规模增长之后仍然能跑得稳健（或者说具有鲁棒性吧，不太喜欢这个词）。

结语 ：从指令随从到意图架构师

这次架构升级的复盘，让我感知到一个范式变化。

过去，我们更像是在驯服AI，试图通过海量的指令灌输让它听话。而在 Claude Code 这类工具的加持下，我们正在进入一个意图即代码的时代。

Agent 开发正经历从散装指令到标准工程的变化。在这个新时代，开发者最核心的资产不再是写出某段特定功能的代码，而是对业务逻辑的极致抽象与解耦能力。

当我们学会提取最大公约数，学会用逻辑隔离去治理上下文，Agent 才会从一个能对话的工具，变成一套能持续交付的系统。

在 AI 原生时代，逻辑的严密性就是最高的生产力。当你的思路足够结构化，文档才能演变为驱动无限可能的生命体。

新增微信交流群

如果人满或者过期了，可以添加我微信我手动拉群

作者

杨卫薪律师/专利代理师/律所 AI 部门负责人/ SuitAgent 框架开发者专注知识产权、数据与 AI 方向的法律业务探索法律 AI 工程化、Vibe Working、Context Engineering