1. 项目概述：为什么我们需要给Coding Agent“立规矩”？

最近几个月，Coding Agent（编码智能体）的热度肉眼可见地飙升。从OpenAI的Codex到各种开源或闭源的“编程副驾驶”，它们已经不再是实验室里的玩具，而是开始真正介入我们的日常开发流程。我自己也深度体验了好几款，从自动补全代码到根据注释生成函数，效率提升确实显著。但问题也随之而来：你让Agent去修复一个Bug，它可能顺手“优化”了旁边毫不相干的代码风格；你让它添加一个新功能，它生成的代码可能完全不符合项目的依赖管理规范。更头疼的是，当多个Agent协作，或者Agent与人类开发者混编时，如果没有一套清晰的“交通规则”，代码仓库很快就会变成一团乱麻。

这就是“给Coding Agent写仓库规则”这个议题的核心价值。它不是在限制AI的能力，恰恰相反，是在为AI的高效、安全、可控协作铺平道路。想象一下，你团队里新来了一位天赋异禀但完全不懂公司规矩的实习生，你需要告诉他：哪些红线绝对不能碰（硬约束），哪些是建议遵循的最佳实践（软约束），以及提交代码前需要提供哪些“证据”来证明你确实检查过了（证据门禁）。对Coding Agent的管理，逻辑是相通的。

基于我过去在多个项目中引入和治理AI编码助手的经验，我发现将规则简单地分为“允许”和“禁止”是远远不够的。一个高效的规则体系需要分层，并且必须形成一个可执行、可验证的闭环。因此，我总结出了“硬约束、软约束、证据门禁”这三类拆解方法，并配套一个“6步可执行闭环”的落地流程。这套方法不仅能大幅降低AI引入的“熵增”，还能让AI的输出质量变得可预测、可管理，真正成为团队生产力的倍增器，而非混乱之源。

2. 规则体系的三层拆解：硬约束、软约束与证据门禁

给Coding Agent定规矩，不能一刀切。有些规则是生死线，必须无条件遵守；有些则是“好学生”标准，鼓励但不强制；还有一些规则，其本身无法被机器直接判定，但可以通过要求Agent提供“作业证据”来间接保证。这就是三层规则体系的设计哲学。

2.1 硬约束：不可逾越的“防火墙”

硬约束是规则的底线，是任何Coding Agent在任何操作中都绝对不能违反的条款。这类规则通常与代码安全、核心业务逻辑、法律合规以及项目的基本存续性相关。一旦触发，系统应能自动、即时地阻断本次操作。

硬约束的典型场景与定义：

1. 安全红线：禁止引入已知的高危漏洞模式。例如，禁止使用eval()函数处理不可信的用户输入，禁止SQL查询中直接拼接字符串（必须使用参数化查询或ORM），禁止硬编码密码、密钥等敏感信息。
2. 架构禁区：禁止修改项目的基础架构或核心框架的特定部分。例如，禁止更改数据库连接池的核心配置类，禁止重写或删除项目定义的基类（BaseClass）中的关键方法。
3. 依赖管控：禁止引入未经许可的外部依赖。可以设定一个许可名单（Allow List），Agent只能使用名单内的库，或禁止使用特定版本（如已知有严重Bug的版本）。
4. 法律与许可：禁止生成或引入可能涉及版权、专利问题的代码片段，确保生成的代码符合项目所采用的开源许可证（如GPL、MIT）的要求。

实操要点：

• 规则表述必须绝对明确、无歧义。避免使用“尽量避免”、“最好不要”这类模糊词汇。应使用“禁止”、“必须”、“不允许”等强制性措辞。
• 实现方式上，硬约束应尽可能通过静态代码分析（SAST）工具在提交前即时拦截。例如，集成SonarQube、CodeQL或自定义的ESLint/PMD规则，在Agent尝试提交代码时进行扫描，一旦命中规则即失败并给出明确错误信息。
• 一个常见的误区是把代码风格问题（如缩进是2空格还是4空格）也设为硬约束。这会导致Agent的灵活性严重下降，频繁被琐事阻断。风格问题更适合用软约束或自动化工具（如Prettier）在后台处理。

2.2 软约束：引导最佳实践的“导航仪”

软约束定义了“好代码”应该长什么样。它不强制阻止“不好”的代码被写入，但会对其进行标记、评分或给出改进建议。软约束的目标是引导Agent（以及人类开发者）向更高的代码质量看齐，并保持项目代码风格的一致性。

软约束的典型场景与定义：

1. 代码风格与格式化：命名规范（驼峰、蛇形）、缩进、空格使用、行宽限制、导入语句排序等。这些规则虽然琐碎，但对代码可读性至关重要。
2. 代码复杂度与可维护性：函数长度、圈复杂度、文件行数、重复代码检测等。设定合理的阈值，提醒Agent（和开发者）函数或类可能过于复杂，需要考虑重构。
3. 设计模式与最佳实践：鼓励使用特定的设计模式（如工厂模式、依赖注入），或遵循领域内的最佳实践（如RESTful API设计规范、React Hooks的使用规则）。
4. 文档与注释：要求公共API、复杂函数必须有文档字符串（Docstring），关键算法需有行内注释。可以设定覆盖率要求，但不宜作为硬性阻断条件。

实操要点：

• 软约束的反馈应该是“建议性”而非“惩罚性”的。通常以警告（Warning）、提示（Info）或质量评分（如A-F等级）的形式呈现。
• 强烈建议将软约束的检查与修复自动化。对于代码风格类约束，直接配置Prettier、Black、gofmt等格式化工具，在代码提交前自动格式化，将规则从“需要遵守的建议”变为“自动执行的动作”。对于复杂度等问题，可以在代码评审（Code Review）环节作为重点检查项。
• 软约束的规则库需要与团队现有规范对齐。最好直接复用或导入团队已有的ESLint、StyleCop、Checkstyle等配置文件，确保AI与人的标准一致。

2.3 证据门禁：要求AI“自证清白”的检查点

这是规则体系中最精妙的一层。有些质量要求无法通过简单的模式匹配或静态分析来判定。例如，“代码逻辑是否正确”、“修改是否引入了回归错误”、“性能是否达标”。对于这类规则，我们不强求Agent一次就做到完美，但要求它在提交代码时，必须附带能证明其试图满足这些要求的“证据”。

证据门禁的典型场景与定义：

1. 单元测试证据：要求Agent在修改或新增功能时，必须同时提供或更新对应的单元测试。提交时，需要附带测试用例的代码以及本次运行测试的结果（通过率）。这证明了Agent考虑了功能的正确性。
2. 集成测试/端到端测试证据：对于涉及多个模块的修改，可以要求提供集成测试的运行结果作为证据。
3. 性能基准测试证据：如果修改可能影响性能（如算法优化、数据库查询），要求Agent提供修改前后的性能对比数据（如使用timeit、JMeter的结果）。
4. 影响分析报告：要求Agent自动生成一份简短的报告，说明本次修改影响了哪些文件、哪些函数，以及可能的风险点。这模仿了资深开发者在提交代码前的思考过程。

实操要点：

• 证据门禁的核心是“可验证的产出物”。规则本身不判断代码好坏，而是判断是否提供了合格的“作业”。
• 实现上，这通常需要在CI/CD流水线中设置关卡。例如，配置Git钩子或PR（Pull Request）检查，要求每次提交必须包含测试文件，且所有测试必须通过；或者要求PR描述中必须包含性能测试数据的链接。
• 证据门禁极大地提升了AI工作的透明度和可信度。评审者不再需要盲目信任AI生成的代码，而是可以审查其提供的“证据”是否充分、合理。这相当于让AI学会了“展示你的工作过程”。

3. 六步可执行闭环：从规则定义到持续演进

有了清晰的三层规则，下一步就是如何将它们落地，形成一个能够持续运转的闭环。我将其归纳为六个步骤，这是一个从规划到执行再到优化的完整生命周期。

3.1 第一步：盘点与定义——我们要约束什么？

在动手写任何一条规则之前，必须进行彻底的盘点。盲目照搬别人的规则库（比如搜索“某某规则仓库大全”）往往水土不服。

1. 业务与风险盘点：

   • 核心资产：找出项目中绝对不能出错的核心模块、数据模型、交易流程。这些是硬约束的重点保护对象。
   • 历史事故：回顾项目历史中出现过的生产事故、严重Bug，分析其根本原因。将这些原因转化为预防性的硬约束（例如，因SQL注入出过事故，就加入SQL注入检测的硬约束）。
   • 合规要求：如果项目涉及金融、医疗等行业，有哪些外部合规标准（如等保、GDPR）必须满足？将其具体化为代码层面的约束。

2. 团队规范盘点：

   • 收集并整理团队现有的代码规范文档、CR（Code Review）检查清单、Wiki中的最佳实践。
   • 与团队核心成员访谈，了解他们最常抱怨的代码质量问题是什么？最希望新人（包括AI）遵守哪些约定？

3. 规则分类：将盘点出的所有要求，按照“硬约束”、“软约束”、“证据门禁”三个篮子进行分类。这一步的关键是达成团队共识：哪些是“一票否决”的，哪些是“尽力就好”的。

3.2 第二步：工具化与集成——让规则“活”起来

规则如果只写在文档里，对AI和健忘的人类都无效。必须将它们转化为机器可读、可执行的检查点。

1. 硬约束的工具化：

   • 静态应用安全测试（SAST）：集成SonarQube、Fortify、CodeQL。在CI流水线中配置质量阈（Quality Gate），将关键漏洞和坏味道设为阻断条件。
   • 自定义Linter规则：利用ESLint（JS/TS）、Pylint（Python）、Checkstyle（Java）等工具的插件机制，编写自定义规则。例如，写一个规则检测是否引入了某个被禁止的API。
   • 预提交钩子（Pre-commit Hook）：使用pre-commit框架，在本地提交前运行一系列检查脚本，任何硬约束失败则阻止提交。

2. 软约束的工具化：

   • 代码格式化工具：统一配置Prettier、Black、gofmt，并将其集成到开发者的编辑器和CI流程中，实现自动格式化，消除风格争议。
   • 代码质量分析平台：将SonarQube、Codacy等作为质量看板，设置评分规则。软约束违规会降低评分，但不阻断流程，在CR时作为参考。
   • 内联注释与提示：在IDE插件中，让软约束以警告或提示的形式实时反馈给开发者（和调用Agent的界面），起到即时教育的作用。

3. 证据门禁的流程化：

   • CI流水线关卡：在GitLab CI、GitHub Actions、Jenkins中配置强制性的检查Job。例如：
     • test-evidence: 要求必须存在测试文件，且运行pytest/jest的通过率为100%。
     • build-evidence: 要求编译或构建必须成功。
     • audit-evidence: 要求依赖安全检查（如npm audit、snyk test）没有高危漏洞。
   • PR模板：创建包含证据检查清单的PR模板。要求提交者（无论是人还是Agent的自动化流程）必须勾选或填写相关内容，如“我已更新单元测试”、“性能基准测试结果见附件”。

3.3 第三步：Agent接入与配置——教会AI懂规矩

不同的Coding Agent有不同的接入方式。我们的目标是将定义好的规则“注入”到Agent的决策循环中。

1. 提示词工程（Prompt Engineering）：这是最直接的方式。在给Agent的系统提示词（System Prompt）或上下文（Context）中，清晰、结构化地描述规则。

   • 硬约束：使用明确、强硬的语气。例如：“你绝对禁止做以下事情：1. 使用eval()函数。2. 编写任何形式的SQL字符串拼接...”。
   • 软约束：使用引导性语气。例如：“请遵循以下最佳实践：1. 函数长度建议不超过50行。2. 请使用PascalCase命名类...”。
   • 证据门禁：作为任务的一部分提出。例如：“你的任务是修复X功能。完成后，请同时提供：1. 修复后的代码。2. 针对此修复的单元测试代码。3. 单元测试的运行结果截图。”
   • 技巧：将复杂的规则文档进行摘要和提炼，用Agent能理解的清晰结构（如Markdown列表、JSON Schema）呈现。避免直接粘贴冗长的规范文档。

2. API与插件集成：对于更高级的Agent或自主开发的Agent框架，可以通过API调用来集成规则检查。

   • 前置过滤器：在Agent执行操作前，先调用一个规则检查服务，对当前上下文或计划的操作进行预检，如果违反硬约束则直接返回错误。
   • 后置校验器：Agent生成代码后，自动调用格式化工具、Linter和测试套件，根据结果决定是直接提交、返回修改建议还是失败重试。
   • 框架支持：关注像OpenAI的Codex API、Anthropic的Claude API或开源框架（如LangChain）是否支持在调用时传入“约束”或“护栏”参数。

3. 环境隔离与沙箱：对于高风险操作（如运行未知代码、安装依赖），让Agent在严格的沙箱环境中执行。沙箱本身可以配置网络隔离、文件系统只读、资源限制等硬约束。

3.4 第四步：监控与度量——规则执行得怎么样？

规则上线后，不能放任不管。需要建立监控体系，了解规则的执行情况和效果。

1. 建立核心度量指标：

   • 拦截率：硬约束被触发的频率和原因。这能反映Agent在哪些方面容易“踩雷”，是否需要调整规则或对Agent进行针对性训练。
   • 合规率：提交的代码通过所有硬约束和证据门禁的比例。可以按Agent、按任务类型进行细分统计。
   • 质量趋势：软约束相关的指标，如代码复杂度平均值、测试覆盖率变化、SonarQube评分趋势。观察引入Agent后，整体代码质量是在改善还是恶化。
   • 效率指标：Agent从接受任务到成功提交合规代码的平均耗时。如果规则导致流程过长，可能需要优化检查速度或调整规则粒度。

2. 设置监控看板：使用Grafana、Datadog或CI/CD平台自带的仪表盘，将上述指标可视化。设置告警，例如当硬约束拦截率异常升高时，及时通知负责人排查。

3. 收集定性反馈：定期与开发团队沟通，了解他们对Agent产出代码质量的感受，以及现有规则是否带来了不必要的麻烦。CR（代码评审）环节是收集反馈的黄金时间。

3.5 第五步：分析与调优——规则本身也需要迭代

监控数据会告诉你“发生了什么”，而分析则要回答“为什么”以及“怎么办”。

1. 规则有效性分析：

   • 误报分析：检查硬约束拦截的记录，是否有大量“误伤”？例如，规则禁止了某个模式，但该模式在特定合法场景下是必须的。这需要优化规则逻辑或添加例外。
   • 漏报分析：是否出现了符合规则但质量很差的代码？这可能意味着有新的坏模式出现，需要定义新的规则。
   • 成本收益分析：某些检查非常耗时（如全量安全扫描），但收益很低（极少发现问题）。考虑将其从实时阻断调整为异步报告或抽样检查。

2. 规则库的迭代：

   • 增：根据漏报和团队反馈，添加新的规则。
   • 删：合并重复规则，删除过时或无效的规则。
   • 改：优化规则描述，降低歧义；调整阈值（如圈复杂度从15放宽到20）；将部分硬约束降级为软约束，或反之。
   • 规则版本化：像管理代码一样，对规则集进行版本控制（如使用Git）。任何变更都有记录，便于回滚和审计。

3. Agent提示词优化：根据Agent的违规记录，反推其是否真正理解了规则。可能需要用更清晰的语言、更多的示例来重构提示词。

3.6 第六步：文化融入与推广——让人和AI共同进化

技术措施最终要服务于团队。让规则体系成为团队研发文化的一部分，才能发挥最大价值。

1. 透明化与教育：

   • 将规则库（特别是硬约束和核心软约束）放在团队内部Wiki上，并对每条规则注明原因和示例，让所有成员（包括AI的管理者）都理解“为什么这么定”。
   • 在新成员入职或引入新Agent时，规则文档是必读材料。

2. 将AI规则与人工流程对齐：

   • 确保代码评审（CR）清单与Agent的规则检查项有大量重叠。这样，人类评审者和AI检查器是在用同一把尺子衡量代码。
   • 鼓励开发者在CR时，不仅看代码，也审查Agent提供的“证据”（如测试报告）是否充分。

3. 建立反馈与仲裁机制：

   • 设立一个简单的渠道（如一个特定的Slack频道或GitHub Issue模板），让开发者可以对某条规则提出质疑或建议修改。
   • 定期（如每季度）召开简短的规则评审会，基于数据和反馈，共同决定规则的调整。这能增强团队对规则的认同感。

通过这六步闭环，规则体系就不再是一堆冰冷的条文，而是一个能够伴随项目、团队和AI能力共同成长的有机体。它从定义开始，通过工具落地，在监控中发现问题，在分析中优化自身，最终融入团队文化，形成一个持续改进的正向循环。

4. 实操案例：为一个Python Web API项目配置Agent规则

让我们以一个具体的场景来串联上述所有概念：假设我们有一个用FastAPI编写的Python Web API项目，现在要引入一个Coding Agent（比如基于GPT的助手）来帮助处理功能开发、Bug修复等任务。

4.1 第一步：盘点与定义

业务风险盘点：

• 核心资产：用户身份验证模块、支付回调接口、核心数据库模型。
• 历史事故：曾因ORM使用不当导致N+1查询问题，拖慢接口响应。
• 合规要求：用户密码必须加盐哈希存储，API密钥不能出现在日志中。

团队规范盘点：

• 代码风格：遵循PEP 8，使用Black格式化，行宽88。
• 测试：要求单元测试覆盖核心逻辑，使用pytest，覆盖率不低于80%。
• 依赖：使用poetry管理，新增依赖需团队审核。
• API设计：遵循OpenAPI规范，路径使用复数名词。

规则分类：

• 硬约束：
  1. 禁止明文存储或日志记录密码、API密钥等敏感信息。
  2. 禁止在循环内进行数据库查询（预防N+1问题）。
  3. 禁止直接使用subprocess执行来自外部的字符串命令。
  4. 禁止引入requirements.txt中未声明的第三方库。
• 软约束：
  1. 函数长度建议不超过30行。
  2. 代码必须用Black格式化。
  3. 导入语句应分组（标准库、第三方库、本地模块）并排序。
  4. 异步函数命名应以async_前缀或_async后缀标识。
• 证据门禁：
  1. 修改或新增API接口，必须同时更新openapi.json描述文件。
  2. 修改数据模型或业务逻辑，必须提供更新的单元测试，且测试通过。
  3. 性能优化类修改，需提供简单的基准测试脚本及结果对比。

4.2 第二步：工具化与集成

硬约束工具化：

1. 使用bandit（安全Linter）和semgrep（自定义规则引擎）编写规则，检测硬编码密码和危险的subprocess调用。集成到pre-commit钩子中。
2. 编写一个自定义的pylint插件或使用flake8插件，检查循环内是否有await database.fetch(...)这样的查询语句。
3. 在CI流水线中，增加一个检查步骤，运行poetry check或对比pyproject.toml与导入语句，确保依赖一致。

软约束工具化：

1. 配置pre-commit自动运行black和isort（处理导入排序）。
2. 在CI中配置flake8（PEP 8检查）和pylint（复杂度检查），结果作为报告输出，但不阻断流程（除非设置严重错误为阻断）。

证据门禁流程化：

1. 在GitHub Actions的workflow中定义三个Job：
   • test: 运行pytest，并生成覆盖率报告。要求覆盖率不低于80%（可配置），且必须通过。
   • openapi-validation: 使用spectral或自定义脚本验证openapi.json是否符合规范且已更新。
   • build: 确保poetry install和项目构建成功。
2. 配置分支保护规则，要求PR合并前，上述三个Job必须全部通过。

4.3 第三步：Agent接入与配置

系统提示词示例：

你是一个专业的Python后端开发助手，负责协助开发FastAPI项目。请严格遵守以下规则： 【硬约束 - 绝对禁止】 1. 安全：任何时候都不允许在代码、日志、配置文件中明文写入密码、密钥、令牌。必须使用环境变量或安全配置管理。 2. 数据库：禁止在循环体内部（如for、while）执行`await db.execute()`或`session.query()`等数据库查询操作，以防N+1问题。应使用批量查询或JOIN。 3. 系统命令：禁止使用`os.system`或`subprocess.run`执行由用户输入或外部数据拼接而成的命令字符串。 4. 依赖管理：所有第三方库必须在`pyproject.toml`文件的`[tool.poetry.dependencies]`部分声明。禁止直接使用`pip install`引入新库。 【软约束 - 请尽力遵循】 1. 代码风格：请使用Black格式化代码。函数建议保持在30行以内以提高可读性。 2. 导入规范：导入应分组为：标准库、第三方库、本地模块，每组内按字母排序。 3. 异步标识：对于执行IO操作的异步函数，建议在名称中加入`async_`前缀，如`async_fetch_user`。 【证据要求 - 任务产出必须包含】 1. 代码变更：提供完整的、可运行的代码。 2. 测试证据：如果修改涉及逻辑，请提供对应的pytest单元测试代码。 3. API文档证据：如果新增或修改了API端点，请提供更新后的OpenAPI路径定义（JSON格式片段）。 4. 变更说明：用一段话简述你的修改内容和理由。 现在，请开始处理任务：{用户任务描述}

后置校验流程设计： 当Agent通过API返回代码后，后台自动化流程应：

1. 将代码写入临时工作区。
2. 自动运行black --check和isort --check。如果失败，自动运行格式化工具修正。
3. 运行自定义的pre-commit钩子（包含安全扫描和硬约束检查）。如果任何硬约束失败，则整体任务失败，将错误信息返回给用户和Agent学习。
4. 如果硬约束通过，则尝试运行单元测试（如果Agent提供了）。测试通过后，才视为任务成功完成。

4.4 第四步与第五步：度量和调优

监控看板指标：

• 拦截看板：统计每日被硬约束拦截的任务数，按规则类型（安全、数据库、依赖）分类。发现“循环内查询”规则拦截最多，说明Agent或开发者常犯此错误。
• 质量看板：跟踪pytest通过率、测试覆盖率、pylint平均分。观察引入Agent后，这些指标是上升还是下降。
• 效率看板：记录Agent任务从发起到合规提交的平均耗时。如果发现“依赖检查”环节耗时很长但很少发现问题，可以考虑将其从同步阻断改为异步通知。

规则调优实例：

• 问题：监控发现“禁止循环内查询”规则误报率高。因为有些循环是处理内存中的列表，并非查询数据库。
• 分析：规则过于宽泛。需要更精确地识别真正的数据库查询操作（如使用SQLAlchemy的session.query()或异步的database.fetch_all）。
• 优化：修改自定义pylint插件的检测逻辑，从“检测循环”改为“检测循环内是否包含特定的数据库查询函数调用模式”。同时，在团队Wiki中更新该规则的说明，并添加正反例。

4.5 第六步：文化融入

• 规则文档：在项目的README或docs/目录下创建AGENT_RULES.md文件，详细记录所有三层规则，并附上示例和原因。
• CR对齐：在团队的Code Review清单中，加入“检查是否避免了N+1查询”、“确认敏感信息未泄露”等与硬约束对应的项目。
• 反馈循环：在项目的Slack频道中，当CI流水线因硬约束失败时，自动@提交者和团队负责人，并附上失败详情链接。鼓励大家在频道中讨论失败原因，判断是Agent/开发者错误，还是规则需要调整。

通过这样一个完整的、从理论到实践的闭环，我们就能让Coding Agent从一个可能制造混乱的“黑盒”，转变为一个在清晰规则下高效、可靠协作的“白盒”伙伴。这个过程本身，也是对团队工程规范和开发流程的一次极佳梳理和加固。