真正会工作的 AI，不靠提示词，而靠一套可执行的组织宪法

一个 AI 编程代理最危险的时刻，不是它完全不会写代码，而是它写得看起来很合理，却悄悄违反了项目真正的规则。

它可能选择了团队禁用的库，跳过了必须执行的测试，修改了不该碰的配置文件，或者生成了一段风格正确、架构错误的代码。问题往往不在模型的智力，而在于它不知道自己身处什么样的组织、系统和责任链条之中。

这揭示了一个常被忽略的事实：让 AI 变得可靠，核心不是继续堆积更聪明的提示词，而是把隐性的工作习惯转化为可执行的环境规则。 AGENTS.md、CLAUDE.md、斜杠命令、项目工作流和代码库集成，看似是不同的工具，实际上都在完成同一件事：把一个依赖个人经验的团队，重构为一个 AI 可以读取、遵守并参与的操作系统。

AI 真正缺少的不是知识，而是情境

传统软件通常只需要明确的输入和输出。给函数一个参数，它按照既定逻辑返回结果。但 AI 代理面对的是开放任务。所谓“修复这个问题”可能同时包含代码修改、测试要求、提交规范、安全限制、部署流程和团队沟通方式。

对人类而言，这些信息分散在许多地方。我们从代码结构中推断习惯，从历史提交中学习风格，从同事的提醒中理解禁区，再通过经验判断什么时候应该停下来询问。一个熟悉项目的工程师并不只是知道更多语法，他拥有一张情境地图。

代理通常缺少的正是这张地图。它看到的是文件、函数和报错，却未必知道：

1. 哪些目录可以自由修改，哪些目录必须经过批准。
2. 哪些命令是验证结果的最低要求。
3. 哪些设计选择虽然技术上可行，却不符合项目长期方向。
4. 完成任务后，应当如何提交、记录和通知其他人。
5. 面对不确定性时，是自行猜测，还是明确提出问题。

因此，一份好的 AGENTS.md 或 CLAUDE.md 并不是“给 AI 的说明书”，更像是项目的局部宪法。它定义的不是每个细节，而是代理在不确定情境下应该如何做判断。

优秀的代理不是永远知道答案，而是知道在什么情况下不能自作主张。

这也是为什么规则文件的质量会在一次工作过程中立刻显现。坏的规则只会增加文字，好的规则则会减少猜测。前者像把整本公司手册塞进代理的上下文，后者像在十字路口竖起三块准确的路牌。

从提示词到协议：工作的最小可执行单元

很多人使用 AI 的方式，仍然停留在对话思维：提出一个请求，等待一份答案，再根据答案继续补充要求。这种方式适合一次性问题，却不适合多步骤的软件工作。因为复杂工作不是由一句话组成，而是由一串相互依赖的决策组成。

例如，“修复一个 GitHub issue”至少可以拆成以下链条：

1. 阅读问题描述，确认复现条件。
2. 查找相关代码和已有测试。
3. 判断问题属于实现错误、接口误用还是环境配置。
4. 先添加或修改测试，再进行最小范围的实现调整。
5. 执行项目规定的测试和静态检查。
6. 检查是否产生无关改动。
7. 按团队约定生成提交信息。
8. 在拉取请求中说明原因、风险和验证结果。

如果只告诉代理“修复这个 issue”，它必须自行补齐整个流程。它的每一步都可能合理，但组合起来未必合格。斜杠命令、工作流模板和项目规则的价值，在于把这串隐性步骤变成一个可重复调用的协议。

协议和提示词的区别非常重要。提示词强调表达，协议强调状态变化。一个提示词说：“请认真修复问题。”一个协议则规定：“先复现，确认失败测试，修改前检查影响范围，完成后运行指定命令，未经测试不得提交。”前者要求代理表现得谨慎，后者让谨慎成为流程的一部分。

这可以用一个简单模型理解：

代理质量 = 模型能力 × 情境质量 × 验证强度

模型能力决定它能够提出多好的方案。情境质量决定它是否理解项目真正要什么。验证强度决定错误能否在进入主分支前被发现。任何一项接近零，最终结果都会接近零。

这也解释了一个反直觉现象：能力更强的模型，有时更需要严格的项目规则。弱模型往往很快暴露无能，强模型则能流畅地产生错误。它可以在几分钟内完成一套结构完整、命名漂亮、逻辑自洽的修改，同时偏离团队的真实意图。越能独立行动的代理，越需要清晰的边界。

规则文件不是文档，而是组织记忆的接口

一个团队的真正方法论，通常没有写在正式流程里。它存在于代码审查意见、重复出现的修复、资深工程师的口头提醒，以及某些“大家都知道但没人写下来”的习惯中。

比如，团队可能默认：所有外部输入必须在边界层校验；数据库迁移必须可回滚；测试优先使用现有的 fixture；错误信息不能暴露内部细节；一个小问题不应顺手重构相邻模块。这些规则如果只存在于人的记忆中，人员变化会让组织不断失忆。更重要的是，代理无法访问这种沉默的知识。

把它们写进项目规则文件，实际上是在建立一种组织记忆的接口。接口的意义不只是存储信息，而是让不同参与者以同样的方式使用信息。新工程师可以读它，自动化工具可以执行它，代理也可以在任务开始时加载它。

但这不意味着文件越长越好。规则文件最常见的失败方式，是把愿望清单误当成操作规范。例如：

请编写高质量、可维护、安全、优雅的代码，并遵守最佳实践。

这些话没有错，却几乎不能指导具体决策。真正有用的规则必须具备三个特征：触发条件明确，行动要求具体，验证方式可见。

例如，与其写“注意测试质量”，不如写：

修改业务逻辑时，先定位现有测试。若行为没有覆盖，先补充一个能够失败的测试。完成后运行 pnpm test 和 pnpm lint，在报告中说明结果。

与其写“避免不必要的改动”，不如写：

默认采用最小修改范围。若需要改变公共接口、数据库结构或认证逻辑，先停止实施并说明影响，不要自行扩大任务范围。

前一种写法描述价值观，后一种写法把价值观翻译成了决策规则。前者适合演讲，后者适合执行。

规则的另一面：不要把代理训练成服从机器

然而，标准化并不等于把所有判断都锁死。一个充满规则的仓库，也可能制造新的风险：代理机械地执行过时流程，团队成员不再思考规则是否合理，所有异常都被当成“违反规范”。

因此，好的项目宪法必须同时规定两件事：什么可以自动化，什么必须升级为人的判断。

可以把任务分成三层。

第一层是低风险、可验证的动作，例如格式化、生成统一的提交信息、运行测试、从数据库结构生成图表。这些动作适合通过命令自动完成，因为结果容易检查，出错成本较低。

第二层是有上下文依赖的分析，例如定位问题、提出重构方案、生成文档。这些工作可以让代理执行，但必须附带证据和验证结果。代理不能只说“已经修复”，而应指出修改了什么、为什么修改、运行了哪些检查、还存在哪些假设。

第三层是高风险决策，例如改变权限模型、删除数据、调整公共 API、修改支付或加密逻辑。这些工作不应仅靠规则文件授权。规则的作用是让代理及时停下，明确列出风险，并请求人工确认。

这构成了一个简单的自动化阶梯：

自动执行低风险动作，辅助分析中风险问题，升级高风险决策。

许多团队只关注如何让代理多做事，却没有设计它何时必须不做事。实际上，可靠性的一半来自行动，另一半来自克制。一个懂得停止的代理，比一个永远给出答案的代理更接近成熟的同事。

从资源集合到团队操作系统

围绕 Claude Code 的资源库之所以有价值，并不只是因为它收集了许多命令、插件和模板。更深层的价值在于，它展示了 AI 工具如何从单点助手演变成一套协作基础设施。

一个用于分析 token 和费用的 CLI 工具，让团队能够观察代理的资源消耗。与 GitHub webhook 集成的工具，把代理从个人终端带入 issue 和拉取请求。管理多个代理的终端应用，则把单一对话扩展为并行任务。编辑器插件让代理进入开发者原本的工作界面。语言和领域专属的规则模板，则把通用模型放进特定技术语境。

这些组件共同改变了一个关键问题：我们不再问“代理能不能写代码”，而开始问“代理如何嵌入一个真实的生产系统”。

可以把这个系统看成四层：

1. 记忆层：项目规则、领域知识、架构约束和历史决策。
2. 动作层：斜杠命令、脚本、工具调用和编辑器集成。
3. 流程层：从问题到代码、测试、审查和部署的工作流。
4. 反馈层：测试结果、代码审查、费用统计、失败记录和人工修正。

没有记忆层，代理会猜。没有动作层，代理只能聊天。没有流程层，代理会在局部最优中迷路。没有反馈层，团队无法知道哪些规则有效，哪些规则只是制造噪音。

这四层也提供了一个评估 AI 工程成熟度的框架。不要只看团队使用了多少模型，或者能生成多少代码。更值得观察的是：项目是否把经验变成规则，是否把重复决策变成命令，是否把命令嵌入工作流，是否根据失败持续更新规则。

让规则像代码一样接受维护

如果规则文件是组织记忆的接口，那么它也应该像代码一样被维护，而不是写完后永久放在仓库角落里。

首先，规则应当尽量靠近它适用的范围。整个仓库的根目录可以放通用原则，某个服务目录可以放该服务的测试和部署要求，特定模块则可以补充更细的限制。这样，代理在处理局部任务时，不必被无关信息淹没。

其次，每条重要规则都应当有对应的验证机制。写着“必须通过类型检查”，却没有统一命令，仍然会产生歧义。写着“提交信息必须规范”，却没有检查工具，规则就会逐渐退化为建议。

再次，规则需要记录例外和来源。并不是所有约定都同等重要。哪些是安全底线，哪些是历史遗留，哪些是暂时性的迁移要求，应该有所区分。否则代理可能把一条为了应付旧系统的临时措施，误认为永恒架构原则。

最后，要根据代理的失败更新规则。每一次错误都可以追问：这是模型能力不足，还是情境信息缺失？是命令没有覆盖，还是验证环节太弱？如果问题可以通过一句清晰规则避免，就把它沉淀下来。如果规则越来越长，却没有减少错误，说明团队可能正在用文字掩盖流程设计的缺陷。

最好的规则文件不是最完整的文件，而是让同一种错误越来越难发生的文件。

Key Takeaways

1. 先写决策边界，再写任务描述。 明确哪些文件、命令和行为受到限制，告诉代理什么时候必须停止并询问。
2. 把重复工作封装成协议。 将问题修复、代码审查、测试、提交和文档生成写成可重复调用的命令，而不是每次重新解释。
3. 让每条重要规则都能被验证。 规则必须对应具体命令、测试、检查器或审查步骤，否则很快会变成口号。
4. 建立自动化阶梯。 低风险动作自动执行，中风险分析要求证据，高风险决策必须人工确认。
5. 用失败维护规则。 每次代理犯错后，判断缺失的是知识、流程还是反馈，再决定是补充文档、编写命令，还是增强验证。

真正的 AI 生产力，不是让一个代理替你完成更多孤立任务，而是让它进入一个有记忆、有边界、有反馈的组织系统。

过去，优秀工程师的价值很大一部分来自脑中的隐性规则。他们知道哪些地方不能碰，哪些测试不能省，哪些看似简单的改动会引发连锁反应。未来，团队竞争力将越来越取决于能否把这种判断力转化为代理可读取、可执行、可审查的结构。

这意味着，AGENTS.md 和 CLAUDE.md 并不是配置文件的边角料。它们正在成为一种新的管理技术：把组织文化压缩成可操作的约束，把经验转化为工作流，把个人判断变成团队基础设施。

当 AI 代理越来越能行动时，最重要的问题也会从“它有多聪明”转向“它在什么规则中变得聪明”。一个没有宪法的强大代理，只是更高效地制造偏差。一个拥有清晰边界和反馈系统的代理，才可能真正成为组织能力的一部分。