1. 从“代码生成”到“代码治理”为什么你的Coding Agent需要规则最近和几个团队聊发现大家用上Coding Agent比如GitHub Copilot、Cursor、Codeium或者基于GPT-4、Claude 3的自建Agent之后都经历了一个相似的“蜜月-阵痛”周期。一开始惊叹于它“一句话生成一个函数”的效率紧接着就开始头疼它生成的代码风格五花八门、安全漏洞暗藏、甚至把过时的API和库给搬了出来。这让我想起一个老段子给你一把锋利的斧头不代表你就能成为好木匠更可能的是把家具砍得乱七八糟。Coding Agent就是这把“锋利的斧头”。它的本质是一个基于海量代码和自然语言训练的概率模型擅长“模仿”和“关联”但并不真正理解你项目的独特上下文、业务约束和团队规范。让它自由发挥就像让一个博览群书但毫无工程经验的新人直接提交代码产出可能很“炫”但大概率不可用、不可靠、不可维护。因此问题的核心从“如何让Agent写更多代码”转向了“如何让Agent写出对的代码”。答案就是为它制定一套“游戏规则”——仓库规则Repository Rules。这不是简单的代码风格检查那是Linter的事而是一套贯穿代码生成、审查、集成全流程的治理框架。今天我就结合自己给多个团队落地Agent治理的经验拆解一套可落地的规则设计方法论硬约束、软约束、证据门禁并提供一个从设计到落地的6步闭环。2. 规则的三重境界硬、软、证据门禁为Coding Agent设计规则不能一刀切。有些规则是红线碰了就得出局有些是建议最好遵守有些则需要它自己证明“清白”。对应到工程实践就是硬约束、软约束和证据门禁。2.1 硬约束不可逾越的“高压线”硬约束是底线是那些一旦违反就会直接导致代码被拒绝、任务失败的规则。它们通常与安全性、正确性、法律合规性强相关。安全漏洞模式禁止这是最核心的硬约束。你必须明确告诉Agent哪些代码模式是绝对禁止的。例如SQL注入禁止出现字符串拼接的SQL查询。必须使用参数化查询或ORM的安全方法。命令注入禁止使用来自用户输入未经清洗的字符串拼接系统命令如os.system(user_input)。硬编码密钥禁止在代码中明文出现API密钥、数据库密码、私钥等。必须通过环境变量或密钥管理服务获取。不安全的反序列化禁止反序列化不可信的来源。使用已弃用且有已知CVE的库版本在生成requirements.txt或package.json时必须避开特定版本。如何实现这不仅仅是靠提示词说“不要写不安全的代码”。你需要提供一个负面模式清单并在Agent的产出上运行静态应用安全测试SAST工具如BanditPython、ESLint配合安全插件JavaScript、SpotBugs/FindSecBugsJava。将SAST工具的检查作为CI/CD流水线中的一个阻塞性关卡任何中高危问题直接导致构建失败。架构边界守护对于微服务或模块化架构硬约束可以防止Agent“越界”。例如禁止服务A的代码直接连接服务B的数据库。禁止在展示层Controller直接编写复杂的业务逻辑或数据访问代码。禁止引入未经架构委员会评审的新技术栈或中间件。这通常需要结合自定义的代码架构分析工具如ArchUnitfor Java,Dependency-Cruiserfor JavaScript来实现在代码提交或合并请求MR时进行校验。许可证合规性禁止引入具有传染性许可证如GPL的第三方库除非经过法务明确许可。可以在依赖安装阶段如npm install,pip install或使用像FOSSA、WhiteSource这样的软件成分分析SCA工具进行扫描和拦截。实操心得硬约束的清单一开始不必求全可以从OWASP Top 10和团队历史上最痛的安全事件开始。关键是要自动化把规则变成CI/CD中的自动化检查点而不是靠人脑记忆和人工审查。2.2 软约束强烈推荐的“最佳实践”软约束关乎代码的可读性、可维护性、一致性和性能。违反软约束不会直接导致失败但会产生警告、建议修改或者在代码评审Code Review中作为重点讨论项。这是提升代码整体质量的关键。代码风格与格式化虽然基础但至关重要。统一使用Prettier、Black、gofmt等工具进行自动化格式化。规则是Agent生成的代码必须能够通过这些工具的检查且不改变代码逻辑。这可以通过在提交前自动运行格式化工具如pre-commithook来实现。命名约定要求变量、函数、类名遵循项目约定如Python的snake_caseJava的CamelCase。这可以通过配置ESLint、Pylint、SonarQube等工具的规则来实现并设置为警告级别。复杂度控制禁止生成圈复杂度Cyclomatic Complexity过高的函数例如超过15。禁止生成超过100行的函数具体数值可按团队调整。这同样是SonarQube或各类Linter的强项设置为警告提醒开发者或要求Agent进行重构。注释与文档要求对于公共API、复杂算法、核心业务逻辑要求Agent生成函数/方法的docstring或注释。可以将其作为代码覆盖率检查的一部分但更推荐作为一种文化倡导在评审中确认。性能反模式提醒例如在循环中执行数据库查询N1问题、使用低效的字符串拼接在循环中使用等。这可以通过代码扫描工具如PMD、Checkstyle的扩展规则来检测并发出警告。踩坑实录我们曾把“函数不超过50行”设为硬约束结果Agent为了达标把逻辑拆得支离破碎反而降低了可读性。后来改为软约束警告并配合“函数内聚性”的评审要求效果更好。软约束的目标是引导而非扼杀。2.3 证据门禁需要自证清白的“挑战”这是最灵活、也最体现智能的一层规则。它不直接禁止或建议某种模式而是要求Coding Agent为其生成的特定类型代码提供“证据”证明其合理性或正确性。如果无法提供则代码不予接受。“为什么用这个库”门禁当Agent引入一个新的、非项目标准清单内的第三方库时必须同时生成一个简短的“采用理由”例如“引入lodash的groupBy函数因为原生的Array.reduce实现相同逻辑代码量多且易错且lodash已是项目现有依赖。”“未引入新的HTTP客户端库而是使用已有的axios以保持技术栈统一。” 这个“理由”可以作为代码注释的一部分在评审时供人判断。“算法选择依据”门禁当实现一个非平凡non-trivial的算法或逻辑时要求Agent在注释中简要说明选择此算法而非另一种的原因特别是涉及性能考量时。例如“此处使用哈希表字典实现O(1)查找而非数组遍历的O(n)因为该函数在热点路径上会被频繁调用。”“测试覆盖”承诺门禁对于Agent生成的核心业务逻辑代码可以要求它同时生成相应的单元测试用例。这不是要求100%覆盖而是要求它证明自己理解逻辑分支。例如生成一个函数后附带生成2-3个针对典型、边界场景的测试用例。这可以通过在Agent的Prompt中明确要求来实现如“请为上述函数编写一个pytest单元测试覆盖正常输入和空输入的情况。”“变更影响分析”门禁当Agent建议修改一个被多处引用的公共函数或配置时可以要求它列出或通过工具分析出可能受影响的调用方作为变更上下文的一部分。这能有效防止“改一处崩一片”的情况。经验之谈证据门禁将部分“评审”工作前移到了“生成”阶段迫使Agent进行更深入的“思考”。它生成的“证据”本身也是极好的文档降低了后续人工评审的成本。实施的关键是将这些“证据”输出标准化、结构化如固定的注释标记## Rationale:便于工具提取和评审人查看。3. 六步构建可执行的规则闭环设计好了规则如何让它们真正运转起来而不是躺在文档里睡大觉下面这个六步闭环是我们经过多次迭代验证的有效路径。3.1 第一步审计与定义——从“痛点”中提炼规则不要凭空想象规则。召集一次小组会议复盘最近一个月由Agent引入或协助开发所导致的线上问题、Bug、评审争议和返工。收集案例每个人列出2-3个具体例子。分类归因每个问题是安全、性能、风格、还是架构问题定义规则针对每一类问题讨论它应该是硬约束、软约束还是证据门禁。例如“Agent引入了有安全漏洞的库版本” - 硬约束CI中集成SCA扫描并阻塞。“Agent写的函数太长太难读” - 软约束设置圈复杂度和函数行数警告。形成初始清单得到一个优先级排序的规则列表P0必须立即实施P1本月内实施P2后续优化。3.2 第二步工具链匹配——为规则寻找“执法者”每一条规则都需要一个或多个工具来自动化执行。硬约束执法者SAST工具Bandit, Semgrep、SCA工具Dependabot, Snyk、架构守护工具ArchUnit。软约束倡导者LinterESLint, Pylint、格式化工具Prettier, Black、代码质量平台SonarQube。证据门禁记录员这部分最灵活可以依靠Prompt工程在给Agent的指令中模板化要求如“请为引入的新依赖说明理由...”。自定义脚本/插件开发一个简单的Git钩子或IDE插件在检测到新依赖或特定代码模式时提示开发者补充理由。评审模板在MR描述模板中增加章节如“本次变更引入的新依赖及理由”、“核心算法选择说明”。制作一个映射表规则类型规则描述对应工具集成阶段处置方式硬约束禁止引入有已知高危CVE的库Dependabot / SnykCI (依赖安装后)失败阻塞合并硬约束禁止出现SQL注入代码模式Semgrep (自定义规则)CI / 预提交钩子失败阻塞合并软约束函数圈复杂度不得超过15SonarQube ScannerCI警告质量门禁可设为警告软约束代码必须符合Black格式化Black预提交钩子自动格式化不通过则阻塞提交证据门禁新依赖需说明理由MR描述模板 / 自定义检查代码评审时无理由则要求补充否则不予通过3.3 第三步分层集成——把规则嵌入开发流规则和工具不能游离在流程之外必须无缝嵌入开发流水线。本地预守Pre-commit将代码格式化、基础Lint、简单的安全模式扫描如用trivy扫描容器镜像集成到Git的pre-commit钩子中。这是第一道防线能让开发者在提交前就修正大部分软约束和部分硬约束问题。可以使用pre-commit框架统一管理。持续集成CI强检在CI流水线如GitHub Actions, GitLab CI中顺序执行代码扫描SAST 架构守护。依赖扫描SCA。代码质量分析SonarQube。所有硬约束检查必须在此阶段并且设置为阻塞性failure状态。只有全部通过才能进入后续环节。合并请求MR门禁将CI状态设置为MR合并的必要条件。同时利用MR的描述模板、评论机器人如danger.js来强化证据门禁例如机器人可以自动检测MR中是否新增了依赖项并作者要求补充理由。3.4 第四步提示词工程——从源头引导Agent这是直接与Coding Agent对话的层面。你需要将规则“翻译”成它理解的指令写入你的系统提示词System Prompt或常用指令模板中。硬约束声明“你生成的代码必须避免任何安全漏洞。绝对禁止1. 使用字符串拼接生成SQL查询必须使用参数化查询2. 将未经验证的用户输入传递给系统命令...”软约束引导“请遵循项目的代码风格使用4个空格缩进函数名使用snake_case导入语句分组并排序... 对于复杂函数请考虑拆分为更小的函数。”证据门禁要求“当你决定引入一个新的第三方库时请在代码注释中以## Rationale:开头简要说明采用它的理由并与现有技术栈进行比较。”“请为你实现的核心算法函数编写简要的docstring并附带1-2个使用示例。”一个精心设计的系统提示词能大幅减少后续工具链的“纠错”工作量实现源头治理。3.5 第五步度量与反馈——让规则越用越聪明规则不是一成不变的。你需要建立度量机制看它们是否有效是否带来了不必要的负担。定义核心指标拦截率硬约束在CI阶段拦截了多少次有问题的提交警告量软约束产生了多少警告趋势是上升还是下降评审效率引入证据门禁后MR的平均评审时长、评论次数是否有变化问题回溯由Agent参与编写的代码其引发的线上事故或Bug数量是否减少定期复盘每两周或每月查看上述指标。召开一个简短的复盘会哪些规则频繁触发是规则太严还是Agent/开发者需要培训是否有新的“坑”出现需要补充为新规则哪些规则几乎从未触发可以考虑降级如硬约束降为软约束或移除迭代规则根据复盘结果调整规则列表、工具配置或提示词。这是一个持续的优化过程。3.6 第六步文化培育——规则是辅助不是枷锁最后也是最容易忽略的一步。规则治理的目的不是限制创造力而是提升整体协作效率和代码可靠性。需要向团队明确传达“为什么”比“是什么”更重要在引入每一条新规则时都要向团队解释其背后的原因安全事件、维护成本等获取大家的理解和支持。规则是共同财产鼓励团队成员主动提出规则建议特别是从踩坑经验中提炼。工具是帮手当工具误报False Positive或带来不便时应有快速通道反馈和调整避免让工具成为开发流程的敌人。最终责任在人Coding Agent是强大的助手但代码的最终责任仍在开发者。规则和工具只是提供了更强大的安全网和校验器不能替代人的思考和评审。4. 实战案例为一个Python后端项目配置规则闭环假设我们有一个基于FastAPI的Python后端项目团队开始广泛使用Cursor基于GPT-4的Agent。我们如何应用上述框架第一步审计与定义通过复盘我们确定P0级问题1Agent有时会使用subprocess拼接用户输入命令注入风险2生成的函数过于冗长3会引入不熟悉的库而不说明。第二步工具链匹配硬约束安全选用Bandit进行SAST扫描重点配置subprocess相关规则。硬约束依赖启用Dependabot或Snyk扫描requirements.txt。软约束代码质量使用Black格式化Pylint进行代码检查设置圈复杂度、行数警告。证据门禁新库暂无完美工具决定通过MR模板和人工评审实现。第三步分层集成本地配置.pre-commit-config.yaml包含black、isort、flake8和bandit仅扫描高危的检查。repos: - repo: https://github.com/psf/black rev: 23.1.0 hooks: - id: black - repo: https://github.com/PyCQA/bandit rev: 1.7.5 hooks: - id: bandit args: [-ll, -iii, --skip, B101,B404,B603] # 跳过一些低危/误报高的检查CIGitHub Actionsjobs: security-scan: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Run Bandit SAST run: | pip install bandit bandit -r . -ll -iii # 全量扫描更严格 - name: SCA Scan with Snyk uses: snyk/actions/pythonmaster env: SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }} with: args: --severity-thresholdhigh quality-check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Lint with Pylint run: | pip install pylint pylint --fail-under8.0 --rcfile.pylintrc your_project/将security-scan的结果设置为合并的必需检查。第四步提示词工程在Cursor的全局设置或项目级提示词中写入你是一个专业的Python后端开发者正在开发一个FastAPI项目。请严格遵守以下规则 【硬约束-安全】 1. 绝对禁止使用 subprocess.run(shellTrue) 或拼接用户输入来执行命令。 2. 数据库操作必须使用SQLAlchemy ORM或异步驱动禁止字符串拼接SQL。 【软约束-质量】 1. 函数长度尽量控制在50行以内圈复杂度低于10。 2. 使用类型注解Type Hints。 3. 公共API必须包含详细的Google风格的docstring。 【证据门禁】 1. 如果引入一个 requirements.txt 中不存在的第三方库请在代码上方以注释说明理由格式为# Lib Adoption: 理由。 2. 对于复杂的业务逻辑请简要说明算法思路。第五步度量与反馈在GitHub仓库中观察Dependabot和Bandit的告警数量。在月度技术会议上分享被拦截的典型案例讨论规则是否需要调整。通过这六步我们为一个具体的项目搭建起了一个从意识、到工具、到流程的完整Coding Agent治理闭环。这套方法的核心思想是分层治理和持续演进它不是要捆住Agent的手脚而是为它戴上精准的导航仪让它在正确的轨道上释放更大的生产力。 Coding Agent规则治理：硬约束、软约束与证据门禁的工程实践
1. 从“代码生成”到“代码治理”为什么你的Coding Agent需要规则最近和几个团队聊发现大家用上Coding Agent比如GitHub Copilot、Cursor、Codeium或者基于GPT-4、Claude 3的自建Agent之后都经历了一个相似的“蜜月-阵痛”周期。一开始惊叹于它“一句话生成一个函数”的效率紧接着就开始头疼它生成的代码风格五花八门、安全漏洞暗藏、甚至把过时的API和库给搬了出来。这让我想起一个老段子给你一把锋利的斧头不代表你就能成为好木匠更可能的是把家具砍得乱七八糟。Coding Agent就是这把“锋利的斧头”。它的本质是一个基于海量代码和自然语言训练的概率模型擅长“模仿”和“关联”但并不真正理解你项目的独特上下文、业务约束和团队规范。让它自由发挥就像让一个博览群书但毫无工程经验的新人直接提交代码产出可能很“炫”但大概率不可用、不可靠、不可维护。因此问题的核心从“如何让Agent写更多代码”转向了“如何让Agent写出对的代码”。答案就是为它制定一套“游戏规则”——仓库规则Repository Rules。这不是简单的代码风格检查那是Linter的事而是一套贯穿代码生成、审查、集成全流程的治理框架。今天我就结合自己给多个团队落地Agent治理的经验拆解一套可落地的规则设计方法论硬约束、软约束、证据门禁并提供一个从设计到落地的6步闭环。2. 规则的三重境界硬、软、证据门禁为Coding Agent设计规则不能一刀切。有些规则是红线碰了就得出局有些是建议最好遵守有些则需要它自己证明“清白”。对应到工程实践就是硬约束、软约束和证据门禁。2.1 硬约束不可逾越的“高压线”硬约束是底线是那些一旦违反就会直接导致代码被拒绝、任务失败的规则。它们通常与安全性、正确性、法律合规性强相关。安全漏洞模式禁止这是最核心的硬约束。你必须明确告诉Agent哪些代码模式是绝对禁止的。例如SQL注入禁止出现字符串拼接的SQL查询。必须使用参数化查询或ORM的安全方法。命令注入禁止使用来自用户输入未经清洗的字符串拼接系统命令如os.system(user_input)。硬编码密钥禁止在代码中明文出现API密钥、数据库密码、私钥等。必须通过环境变量或密钥管理服务获取。不安全的反序列化禁止反序列化不可信的来源。使用已弃用且有已知CVE的库版本在生成requirements.txt或package.json时必须避开特定版本。如何实现这不仅仅是靠提示词说“不要写不安全的代码”。你需要提供一个负面模式清单并在Agent的产出上运行静态应用安全测试SAST工具如BanditPython、ESLint配合安全插件JavaScript、SpotBugs/FindSecBugsJava。将SAST工具的检查作为CI/CD流水线中的一个阻塞性关卡任何中高危问题直接导致构建失败。架构边界守护对于微服务或模块化架构硬约束可以防止Agent“越界”。例如禁止服务A的代码直接连接服务B的数据库。禁止在展示层Controller直接编写复杂的业务逻辑或数据访问代码。禁止引入未经架构委员会评审的新技术栈或中间件。这通常需要结合自定义的代码架构分析工具如ArchUnitfor Java,Dependency-Cruiserfor JavaScript来实现在代码提交或合并请求MR时进行校验。许可证合规性禁止引入具有传染性许可证如GPL的第三方库除非经过法务明确许可。可以在依赖安装阶段如npm install,pip install或使用像FOSSA、WhiteSource这样的软件成分分析SCA工具进行扫描和拦截。实操心得硬约束的清单一开始不必求全可以从OWASP Top 10和团队历史上最痛的安全事件开始。关键是要自动化把规则变成CI/CD中的自动化检查点而不是靠人脑记忆和人工审查。2.2 软约束强烈推荐的“最佳实践”软约束关乎代码的可读性、可维护性、一致性和性能。违反软约束不会直接导致失败但会产生警告、建议修改或者在代码评审Code Review中作为重点讨论项。这是提升代码整体质量的关键。代码风格与格式化虽然基础但至关重要。统一使用Prettier、Black、gofmt等工具进行自动化格式化。规则是Agent生成的代码必须能够通过这些工具的检查且不改变代码逻辑。这可以通过在提交前自动运行格式化工具如pre-commithook来实现。命名约定要求变量、函数、类名遵循项目约定如Python的snake_caseJava的CamelCase。这可以通过配置ESLint、Pylint、SonarQube等工具的规则来实现并设置为警告级别。复杂度控制禁止生成圈复杂度Cyclomatic Complexity过高的函数例如超过15。禁止生成超过100行的函数具体数值可按团队调整。这同样是SonarQube或各类Linter的强项设置为警告提醒开发者或要求Agent进行重构。注释与文档要求对于公共API、复杂算法、核心业务逻辑要求Agent生成函数/方法的docstring或注释。可以将其作为代码覆盖率检查的一部分但更推荐作为一种文化倡导在评审中确认。性能反模式提醒例如在循环中执行数据库查询N1问题、使用低效的字符串拼接在循环中使用等。这可以通过代码扫描工具如PMD、Checkstyle的扩展规则来检测并发出警告。踩坑实录我们曾把“函数不超过50行”设为硬约束结果Agent为了达标把逻辑拆得支离破碎反而降低了可读性。后来改为软约束警告并配合“函数内聚性”的评审要求效果更好。软约束的目标是引导而非扼杀。2.3 证据门禁需要自证清白的“挑战”这是最灵活、也最体现智能的一层规则。它不直接禁止或建议某种模式而是要求Coding Agent为其生成的特定类型代码提供“证据”证明其合理性或正确性。如果无法提供则代码不予接受。“为什么用这个库”门禁当Agent引入一个新的、非项目标准清单内的第三方库时必须同时生成一个简短的“采用理由”例如“引入lodash的groupBy函数因为原生的Array.reduce实现相同逻辑代码量多且易错且lodash已是项目现有依赖。”“未引入新的HTTP客户端库而是使用已有的axios以保持技术栈统一。” 这个“理由”可以作为代码注释的一部分在评审时供人判断。“算法选择依据”门禁当实现一个非平凡non-trivial的算法或逻辑时要求Agent在注释中简要说明选择此算法而非另一种的原因特别是涉及性能考量时。例如“此处使用哈希表字典实现O(1)查找而非数组遍历的O(n)因为该函数在热点路径上会被频繁调用。”“测试覆盖”承诺门禁对于Agent生成的核心业务逻辑代码可以要求它同时生成相应的单元测试用例。这不是要求100%覆盖而是要求它证明自己理解逻辑分支。例如生成一个函数后附带生成2-3个针对典型、边界场景的测试用例。这可以通过在Agent的Prompt中明确要求来实现如“请为上述函数编写一个pytest单元测试覆盖正常输入和空输入的情况。”“变更影响分析”门禁当Agent建议修改一个被多处引用的公共函数或配置时可以要求它列出或通过工具分析出可能受影响的调用方作为变更上下文的一部分。这能有效防止“改一处崩一片”的情况。经验之谈证据门禁将部分“评审”工作前移到了“生成”阶段迫使Agent进行更深入的“思考”。它生成的“证据”本身也是极好的文档降低了后续人工评审的成本。实施的关键是将这些“证据”输出标准化、结构化如固定的注释标记## Rationale:便于工具提取和评审人查看。3. 六步构建可执行的规则闭环设计好了规则如何让它们真正运转起来而不是躺在文档里睡大觉下面这个六步闭环是我们经过多次迭代验证的有效路径。3.1 第一步审计与定义——从“痛点”中提炼规则不要凭空想象规则。召集一次小组会议复盘最近一个月由Agent引入或协助开发所导致的线上问题、Bug、评审争议和返工。收集案例每个人列出2-3个具体例子。分类归因每个问题是安全、性能、风格、还是架构问题定义规则针对每一类问题讨论它应该是硬约束、软约束还是证据门禁。例如“Agent引入了有安全漏洞的库版本” - 硬约束CI中集成SCA扫描并阻塞。“Agent写的函数太长太难读” - 软约束设置圈复杂度和函数行数警告。形成初始清单得到一个优先级排序的规则列表P0必须立即实施P1本月内实施P2后续优化。3.2 第二步工具链匹配——为规则寻找“执法者”每一条规则都需要一个或多个工具来自动化执行。硬约束执法者SAST工具Bandit, Semgrep、SCA工具Dependabot, Snyk、架构守护工具ArchUnit。软约束倡导者LinterESLint, Pylint、格式化工具Prettier, Black、代码质量平台SonarQube。证据门禁记录员这部分最灵活可以依靠Prompt工程在给Agent的指令中模板化要求如“请为引入的新依赖说明理由...”。自定义脚本/插件开发一个简单的Git钩子或IDE插件在检测到新依赖或特定代码模式时提示开发者补充理由。评审模板在MR描述模板中增加章节如“本次变更引入的新依赖及理由”、“核心算法选择说明”。制作一个映射表规则类型规则描述对应工具集成阶段处置方式硬约束禁止引入有已知高危CVE的库Dependabot / SnykCI (依赖安装后)失败阻塞合并硬约束禁止出现SQL注入代码模式Semgrep (自定义规则)CI / 预提交钩子失败阻塞合并软约束函数圈复杂度不得超过15SonarQube ScannerCI警告质量门禁可设为警告软约束代码必须符合Black格式化Black预提交钩子自动格式化不通过则阻塞提交证据门禁新依赖需说明理由MR描述模板 / 自定义检查代码评审时无理由则要求补充否则不予通过3.3 第三步分层集成——把规则嵌入开发流规则和工具不能游离在流程之外必须无缝嵌入开发流水线。本地预守Pre-commit将代码格式化、基础Lint、简单的安全模式扫描如用trivy扫描容器镜像集成到Git的pre-commit钩子中。这是第一道防线能让开发者在提交前就修正大部分软约束和部分硬约束问题。可以使用pre-commit框架统一管理。持续集成CI强检在CI流水线如GitHub Actions, GitLab CI中顺序执行代码扫描SAST 架构守护。依赖扫描SCA。代码质量分析SonarQube。所有硬约束检查必须在此阶段并且设置为阻塞性failure状态。只有全部通过才能进入后续环节。合并请求MR门禁将CI状态设置为MR合并的必要条件。同时利用MR的描述模板、评论机器人如danger.js来强化证据门禁例如机器人可以自动检测MR中是否新增了依赖项并作者要求补充理由。3.4 第四步提示词工程——从源头引导Agent这是直接与Coding Agent对话的层面。你需要将规则“翻译”成它理解的指令写入你的系统提示词System Prompt或常用指令模板中。硬约束声明“你生成的代码必须避免任何安全漏洞。绝对禁止1. 使用字符串拼接生成SQL查询必须使用参数化查询2. 将未经验证的用户输入传递给系统命令...”软约束引导“请遵循项目的代码风格使用4个空格缩进函数名使用snake_case导入语句分组并排序... 对于复杂函数请考虑拆分为更小的函数。”证据门禁要求“当你决定引入一个新的第三方库时请在代码注释中以## Rationale:开头简要说明采用它的理由并与现有技术栈进行比较。”“请为你实现的核心算法函数编写简要的docstring并附带1-2个使用示例。”一个精心设计的系统提示词能大幅减少后续工具链的“纠错”工作量实现源头治理。3.5 第五步度量与反馈——让规则越用越聪明规则不是一成不变的。你需要建立度量机制看它们是否有效是否带来了不必要的负担。定义核心指标拦截率硬约束在CI阶段拦截了多少次有问题的提交警告量软约束产生了多少警告趋势是上升还是下降评审效率引入证据门禁后MR的平均评审时长、评论次数是否有变化问题回溯由Agent参与编写的代码其引发的线上事故或Bug数量是否减少定期复盘每两周或每月查看上述指标。召开一个简短的复盘会哪些规则频繁触发是规则太严还是Agent/开发者需要培训是否有新的“坑”出现需要补充为新规则哪些规则几乎从未触发可以考虑降级如硬约束降为软约束或移除迭代规则根据复盘结果调整规则列表、工具配置或提示词。这是一个持续的优化过程。3.6 第六步文化培育——规则是辅助不是枷锁最后也是最容易忽略的一步。规则治理的目的不是限制创造力而是提升整体协作效率和代码可靠性。需要向团队明确传达“为什么”比“是什么”更重要在引入每一条新规则时都要向团队解释其背后的原因安全事件、维护成本等获取大家的理解和支持。规则是共同财产鼓励团队成员主动提出规则建议特别是从踩坑经验中提炼。工具是帮手当工具误报False Positive或带来不便时应有快速通道反馈和调整避免让工具成为开发流程的敌人。最终责任在人Coding Agent是强大的助手但代码的最终责任仍在开发者。规则和工具只是提供了更强大的安全网和校验器不能替代人的思考和评审。4. 实战案例为一个Python后端项目配置规则闭环假设我们有一个基于FastAPI的Python后端项目团队开始广泛使用Cursor基于GPT-4的Agent。我们如何应用上述框架第一步审计与定义通过复盘我们确定P0级问题1Agent有时会使用subprocess拼接用户输入命令注入风险2生成的函数过于冗长3会引入不熟悉的库而不说明。第二步工具链匹配硬约束安全选用Bandit进行SAST扫描重点配置subprocess相关规则。硬约束依赖启用Dependabot或Snyk扫描requirements.txt。软约束代码质量使用Black格式化Pylint进行代码检查设置圈复杂度、行数警告。证据门禁新库暂无完美工具决定通过MR模板和人工评审实现。第三步分层集成本地配置.pre-commit-config.yaml包含black、isort、flake8和bandit仅扫描高危的检查。repos: - repo: https://github.com/psf/black rev: 23.1.0 hooks: - id: black - repo: https://github.com/PyCQA/bandit rev: 1.7.5 hooks: - id: bandit args: [-ll, -iii, --skip, B101,B404,B603] # 跳过一些低危/误报高的检查CIGitHub Actionsjobs: security-scan: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Run Bandit SAST run: | pip install bandit bandit -r . -ll -iii # 全量扫描更严格 - name: SCA Scan with Snyk uses: snyk/actions/pythonmaster env: SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }} with: args: --severity-thresholdhigh quality-check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Lint with Pylint run: | pip install pylint pylint --fail-under8.0 --rcfile.pylintrc your_project/将security-scan的结果设置为合并的必需检查。第四步提示词工程在Cursor的全局设置或项目级提示词中写入你是一个专业的Python后端开发者正在开发一个FastAPI项目。请严格遵守以下规则 【硬约束-安全】 1. 绝对禁止使用 subprocess.run(shellTrue) 或拼接用户输入来执行命令。 2. 数据库操作必须使用SQLAlchemy ORM或异步驱动禁止字符串拼接SQL。 【软约束-质量】 1. 函数长度尽量控制在50行以内圈复杂度低于10。 2. 使用类型注解Type Hints。 3. 公共API必须包含详细的Google风格的docstring。 【证据门禁】 1. 如果引入一个 requirements.txt 中不存在的第三方库请在代码上方以注释说明理由格式为# Lib Adoption: 理由。 2. 对于复杂的业务逻辑请简要说明算法思路。第五步度量与反馈在GitHub仓库中观察Dependabot和Bandit的告警数量。在月度技术会议上分享被拦截的典型案例讨论规则是否需要调整。通过这六步我们为一个具体的项目搭建起了一个从意识、到工具、到流程的完整Coding Agent治理闭环。这套方法的核心思想是分层治理和持续演进它不是要捆住Agent的手脚而是为它戴上精准的导航仪让它在正确的轨道上释放更大的生产力。