团队引入AI编程助手之后，最先遇到的往往不是能力不够 ，而是风格不对 。模型写出来的代码能跑、逻辑也对，但变量命名用的是教科书式的data、temp，异常处理方式和公司内部约定的错误码体系完全不搭，测试覆盖率随缘发挥。说到底，大模型学的是全世界的代码习惯的平均值，而每个公司的规范都是带着自己历史包袱的特殊方言 。想让AI Agent说这门方言，不能指望一句请遵守公司规范的提示词就搞定，得从提示层、工具层、流程层多管齐下。
下面以Pi Agent（earendil-works开源的provider-agnostic编程代理框架，由Mario Zechner主导开发） 为例，拆解一套可落地的规范约束体系，并给出每一层的具体配置示例。
为什么单靠System Prompt不够用
很多团队第一反应是在系统提示词里堆一大段请使用4空格缩进、请用驼峰命名、请写单元测试，这招短期有效，但有三个硬伤。
- 规范文档一旦超过几百行，塞进上下文会稀释模型注意力，后面提示词反而被遗忘
- 规范是活的，今天改了ESLint规则，提示词得同步手动改，容易漏更
- 提示词只能建议 ，无法强制，模型心情不好照样会违反
真正可靠的做法是把规范拆成可执行的检查点 ，分布在Agent工作流程的不同环节，形成一张层层拦截的网。Reddit上一个关于AI辅助开发团队代码规范的讨论里，有工程师总结得很直白------有用的规则大多很无聊，生成的测试要人复核，新依赖要多一道审查，安全敏感代码要二次把关，这其实就是分层防护思路的朴素版本。
下面这张图展示了一套完整的规范约束链路。
这张图里每一个节点，Pi Agent都有对应的实现机制，接下来逐一拆开讲。
第一层 规则文件------给Agent立规矩的底本
Pi Agent作为一个provider-agnostic的编码代理框架，意思是它不绑定某一家模型厂商，可以自由切换Claude、GPT、Gemini等后端，这也决定了它的规范约束不能依赖某个模型特有的调教技巧，而要靠结构化配置来统一行为。
实践上通常会在项目根目录放一份类似AGENTS.md的规则文件，Pi Agent启动时会把它读入上下文，作为每次对话的开场白。一份比较实用的规则文件大致是这样的结构（示例）
markdown
# 项目编码规范（Pi Agent 规则文件）
## 命名约定
- 变量与函数使用小驼峰，类名使用大驼峰
- 禁止使用 data、temp、obj 这类无意义命名
- 数据库字段名统一使用蛇形命名
## 错误处理
- 所有外部调用必须捕获异常，并转换为公司统一的 AppError 类型
- 禁止使用裸露的 try/catch 吞掉异常不记录日志
## 依赖管理
- 新增第三方依赖前，必须在 PR 描述中说明用途和替代方案
- 禁止引入 lodash 的全量包，必须按需引入子模块
## 测试要求
- 新增函数必须附带单元测试，覆盖率不低于 80%
- 涉及金额计算的逻辑必须有边界值测试这份文件相当于给Agent的宪法，但它只是起点。真正能把这些条文变成硬约束的，是接下来的钩子机制。
第二层 Hooks钩子------执行前拦截，执行后审计
Pi Agent内置了工具调用层面的钩子体系，社区里已经有人用它来给编辑类操作做审计日志，比如有开发者提到自己搭了一个小扩展，通过hooks追踪文件操作，包括读、写、改，记录Agent在会话期间具体做了什么 。这正是实现规范约束最关键的技术抓手------因为钩子可以在Agent真正写文件之前 介入检查，也可以在写完之后介入复核。
一个贴合公司规范场景的Hook实现大致是这样的思路（基于Pi Agent的扩展/钩子接口，TypeScript伪代码示意）
typescript
// pre-tool-use hook：代码落地前拦截
export const preEditHook = async (ctx: ToolContext) => {
const { filePath, newContent } = ctx.payload;
// 规则1：禁止直接修改生成的类型文件
if (filePath.endsWith(".generated.ts")) {
return { allow: false, reason: "生成文件禁止手动修改，请改源 schema" };
}
// 规则2：调用公司内部 lint 服务做静态检查
const lintResult = await runCompanyLinter(newContent);
if (!lintResult.pass) {
return {
allow: false,
reason: `未通过公司代码规范检查：${lintResult.errors.join("; ")}`
};
}
return { allow: true };
};
// post-tool-use hook：落地后记录审计日志
export const postEditHook = async (ctx: ToolContext) => {
await auditLog.record({
tool: ctx.toolName,
file: ctx.payload.filePath,
diff: ctx.result.diff,
timestamp: Date.now()
});
};这套机制的妙处在于，规范检查不再依赖模型自觉 ，而是变成了代码执行链路上物理意义上绕不过去的卡口。模型想写不合规的代码，Hook直接拒绝执行，并把原因回传给Agent让它自己改。社区里也有讨论指出当前Edit工具的Hook在diff信息传递上还有改进空间，这说明钩子机制仍在快速演进，但方向已经很明确。
Pi Agent的工具执行组件本身是作为@earendil-works/pi-agent-core暴露出来的，这意味着企业完全可以基于这个核心包做深度定制，把公司自己的CI/Lint服务无缝接进工具执行流程里。
第三层 Skills与Subagents------把规范封装成专家
单纯靠Hook做否决式 拦截，用户体验不算好，更聪明的做法是让Agent一开始就知道怎么做对，而不是写错了再被打回去。这就是Skills（技能）和Subagent（子代理）机制存在的意义。
社区里有一个专门维护个人Pi Agent配置的项目，内容就包括安全扩展、子代理定义、技能和提示模板，用于更强力的AI辅助开发。这种模式下，公司可以把特定领域的规范------比如数据库迁移、支付接口调用、权限校验------封装成一个个专职子代理，每个子代理只被允许使用预设好的工具集和代码模板。
举个例子，公司内部如果有一套统一的数据库迁移规范（比如所有migration必须可回滚、必须加索引评审），可以这样定义一个Subagent
yaml
# subagents/db-migration-expert.yaml
name: db-migration-expert
description: 专门处理数据库 schema 变更，严格遵循公司迁移规范
allowed_tools:
- run_migration_dry_run
- check_index_impact
- generate_rollback_script
system_prompt: |
你是公司数据库规范专家子代理。所有迁移脚本必须：
1. 包含对应的 rollback 脚本
2. 新增索引前先运行 check_index_impact 评估影响
3. 禁止在迁移脚本中直接写业务逻辑主Agent遇到数据库变更类任务时，会自动把任务路由给这个专职子代理处理，相当于把资深DBA的经验打包成了一个随时在线的专家角色，比在主Agent身上堆砌所有规则要清爽得多。
第四层 MCP集成------把公司已有的质量工具链接进来
Pi Agent在1.0版本里加入了通过Codemode实现的内置MCP（Model Context Protocol）支持，这一步其实解决了一个很现实的问题------公司通常早就有自己的静态分析平台、安全扫描工具、依赖审查系统，没必要让Agent重新发明一套，而是直接把这些现有服务通过MCP协议暴露成Agent可调用的工具。
比如公司内部有一套Sonar质量门禁服务，可以把它包装成一个MCP Server，Pi Agent在生成代码后自动调用
json
{
"mcpServers": {
"company-quality-gate": {
"command": "node",
"args": ["./mcp-servers/sonar-gate.js"],
"description": "对接公司内部 SonarQube 质量门禁，返回代码异味与安全漏洞列表"
}
}
}这样一来，Agent每次提交代码变更前都会被要求先过一遍公司真实的质量门禁，而不是只依赖模型自身的代码审美 。Pi Agent同时支持把自己作为SDK嵌入到长期运行的服务里，这意味着企业甚至可以把整条生成-检查-修正的流程常驻化，变成CI流水线里的一个标准环节，而不只是开发者本地偶尔用一下的交互式工具 。
四层机制一览
| 层级 | 解决的问题 | Pi Agent对应机制 | 强制力 |
|---|---|---|---|
| 规则文件 | 让Agent知道规范是什么 | AGENTS.md类上下文注入 | 弱（建议性） |
| Hooks钩子 | 执行前拦截违规操作 | pre/post-tool-use hook | 强（物理阻断） |
| Skills/Subagent | 把专业规范封装为专家角色 | 子代理定义与技能模板 | 中（引导性） |
| MCP工具集成 | 复用公司现有质量工具链 | Codemode暴露的MCP Server | 强（真实工具校验） |
如果要量化整套体系的效果，一个简单直观的指标是规范遵循率
规范遵循率=Agent生成代码的总次数通过检查的生成代码次数×100%
很多团队的经验是，光靠提示词这个指标大概在六七成，加上Hook强制拦截和MCP质量门禁之后能冲到九成以上，但最后那一道人工Code Review永远不能省------毕竟规范能写进代码里的只是显性 部分，还有大量这段逻辑是不是真的符合业务意图这种只有人能判断的东西。
写在最后
让AI Agent遵守公司代码规范，本质上不是一个提示词工程 问题，而是一个系统设计 问题。Pi Agent的价值恰恰在于它不是一个封闭的黑盒助手，而是一套可以被公司按自己需求插拔、扩展的编码代理框架------规则文件管知道 ，Hook管拦截 ，Subagent管专业 ，MCP管接驳现有工具链 ，四层叠在一起才真正把公司方言教给了AI。工具会一直迭代，但这套分层治理的思路，大概会是未来很长一段时间里团队落地AI编程助手的标准打法。
参考资料
Pi Coding Agent CHANGELOG, earendil-works/pi, GitHub, github.com/earendil-wo...
s1lver091/pi-agent-config, Personal Pi coding agent configuration (safety extensions, subagents, skills, prompt templates), GitHub, github.com/s1lver091/p...
What coding standards are your teams using for AI-assisted development, Reddit r/webdev, www.reddit.com/r/webdev/co...
Pi 1.0 Release Guide: MCP, Codemode and Pi Durable, Developers Digest, www.developersdigest.tech/blog/pi-1-0...
Edit tool hook missing diff information, earendil-works/pi Discussions, GitHub, github.com/earendil-wo...
tool-execution.ts, earendil-works/pi, GitHub, github.com/earendil-wo...
Extension loader loads jiti and the full TUI graph at import, earendil-works/pi Issues, GitHub, github.com/earendil-wo...
Pi non-interactive mode cannot see piped input, earendil-works/pi Issues, GitHub, github.com/earendil-wo...
feat: support pi (pi.dev) as an Agent Runtime backend, CherryHQ/cherry-studio Issues, GitHub, github.com/CherryHQ/ch...
How I installed the Pi coding agent (earendil-works/pi) on a Raspberry Pi 2 / ARMv7, Reddit r/raspberry_pi, www.reddit.com/r/raspberry...