Claude Code治理指南：Verity.md如何实现质量门禁与成本控制

在 Claude Code 的实际使用中多数问题不是模型能力不够而是项目上下文失焦、费用不可见和 Agent 反复走弯路造成的。Verity.md 这个名字针对的正是这三个痛点quality gates质量门禁、memory记忆管理和 cost control成本控制。如果团队已经在用 Claude Code 写业务代码或维护仓库却没有一套文档规范来约束 Agent 的行为这篇内容会给出可落地的治理思路和参考文档结构。1. 先理解 Claude Code 项目为什么会失控Claude Code 这类 Agent 编码工具的能力边界往往不在模型参数而在使用者如何设计它的工作上下文。很多项目在连续使用 Claude Code 几个小时后会出现同一类现象任务越执行越偏、费用涨得很快、改动过的文件越来越多最后人工 review 的成本甚至超过自己写代码。1.1 长会话带来的上下文失焦Claude Code 在一个会话内会持续累积对话历史。进入第 30 轮、第 50 轮对话后Agent 对“当前任务”的记忆会被早期讨论稀释。表现很典型任务开始时要求“只修改登录模块”执行到后面 Agent 会顺手“优化”相邻模块。同一个接口改了三次第一次改参数名第二次改返回结构第三次改错误码但会话里已经分不清哪次才是最终决定。Agent 在长输出中复述早期错误理解而不是按最新任务描述执行。这不是模型变笨了而是上下文缺乏“门禁”。没有门禁Agent 就不会在动手前回到任务原始约束上确认边界。1.2 记忆缺失造成重复劳动Claude Code 默认不会把上一个项目的经验自动带到下一个任务。即使你在上个任务里已经调研清楚“当前服务不能直接改数据库表结构必须走 API 网关”新会话里的 Agent 依然可能重新踩坑。缺少记忆机制的直接后果同样的技术选型讨论反复发生。Agent 反复生成已经被否定的实现方案。项目里重要约束只存在某个成员的聊天记录里没有沉淀成仓库内文档。1.3 token 成本难以预测Claude Code 按 token 消耗计费而 token 消耗最大的来源不是最终答案而是中间过程。Agent 反复读大文件、反复生成无用的 diff、在长上下文里重复扫描目录都会快速消耗预算。会吃成本的常见动作每轮任务都重新读取整个项目 README 和多个核心文件。对同一个编译错误反复调试但每次都从头读取日志。同时打开多个子任务每个子任务都携带完整项目结构信息。1.4 从“工具好用”到“项目可控”的差距只装一个 Claude Code 并不等于项目可控。真正需要的是给 Agent 一套规则让它知道动手前先看什么、每个任务必须产出什么、不能碰哪些范围、预算用完后如何降级。Verity.md 的定位就是把这类规则沉淀成仓库内可被 Agent 读取、也被人 review 的文档。失控现象直接原因常见后果修改范围越来越大缺少任务边界约束代码 review 成本高回归风险增大同一问题反复出错历史决策未沉淀token 重复消耗交付周期变长费用突增过程 token 不可见月底核算时才暴露成本问题关键约束被忽略项目规范只存在文档或人脑中Agent 产出与项目架构冲突2. Verity.md 的定位不是插件而是 Agent 治理层Verity.md 更像是一组直接放进仓库的规范文档。它通过定义 Agent 在工作开始前必须读取的文件、必须遵守的检查规则以及任务阶段的信息处理方式来约束 Claude Code 的行为。2.1 用“先读文档再动代码”的方式做质量门禁质量门禁不一定只在 CI 里做。对 Agent 而言更有效的门禁发生在任务开始前。可以在仓库根目录放一份 GATE.md里面写好四类门禁范围门禁这个任务允许改动哪些目录禁止改动哪些目录。行为门禁动手前必须确认哪些前置条件比如数据库迁移已执行、API 文档已更新。验收门禁什么情况下任务才算完成例如测试通过、日志无 ERROR、diff 不超过限定范围。回滚门禁改动涉及关键模块时必须先确认回滚方案。Claude Code 在执行任务时如果让它先读取 GATE.md它就会在后续决策中反复引用这些约束。相比只在 prompt 里写一句“你要小心”GATE.md 能提供可反复引用的文本锚点。2.2 用仓库内记忆文件解决跨会话遗忘Claude Code 本身具备一定记忆能力但项目级经验更适合沉淀在版本控制里。可以在仓库内创建一个.claude或.verity目录用于存放三类记忆决策记录记录“为什么不用方案 A而用方案 B”。踩坑记录记录“某个目录下的文件不能直接改必须先看网关层”。命令速查记录“当前项目的测试、构建、静态检查分别用什么命令”。Agent 每次新会话启动时会被要求先读取最近更新的记忆文件。这样即使换了一台电脑、换了一个人操作项目经验也不会丢。2.3 Verity.md 与 Claude Code 自带功能的关系Claude Code 已经有 system prompt、CLAUDE.md、skills 等功能Verity.md 是站在它们之上的组织层。能力Claude Code 自带方式Verity.md 的补充项目指令项目级 CLAUDE.md更细粒度地拆分 GATE、TASK、AGENTS 三套文档技能扩展skills 目录将技能变成仓库内可 review 的标准步骤上下文提示ALWAYS_READ 列表按任务类型选择记忆文件避免一次读太多费用控制预算命令把预算策略写成文档让 Agent 在超预算时自动降级这套设计思路不依赖某个特定版本。只要 Claude Code 还支持项目内文档和文件读取Verity.md 的方式就适用。3. 环境准备先把 Claude Code 装好并确认基础配置在使用 Verity.md 之前先确保 Claude Code 能稳定运行。这个步骤看起来基础却是后面所有门禁和记忆机制的前提。3.1 安装 Claude Code 前的环境检查清单安装前按以下顺序确认环境检查项建议要求检查方式Node.js 版本LTS 版本建议 18 及以上node -vnpm 或原生包管理器可正常执行安装命令npm -v终端权限当前用户有权限写入全局目录安装报 EACCES 时先处理权限网络连通性能正常访问 Claude Code 安装源安装失败时查看错误码安装命令以 Claude Code 官方文档为准常见方式为npm install -g anthropic-ai/claude-code如果安装过程很慢先确认能否解析安装源域名不要急着重复执行。重复执行可能产生半安装状态反而更难排查。3.2 在 VS Code 中使用 Claude Code 的常见配置VS Code 里使用 Claude Code 时需要确认编译器能识别 Claude Code 命令。常见的报错是failed to run claude code: error: could not locate the claude cli on path这表示 VS Code 终端的工作路径没有包含全局 npm 目录。处理思路# 查看 npm 全局路径 npm prefix -g # 将全局路径追加到 PATH export PATH$(npm prefix -g)/bin:$PATH如果是 Windows 系统还需要确认 PATH 里的全局目录与 npm 配置一致。修正后重新打开终端输入claude --version验证。3.3 验证 Claude Code 是否可用的最小步骤安装完成后不要直接进入大项目。先在一个临时目录里做冒烟测试mkdir ~/claude-test cd ~/claude-test claude如果 Claude Code 能正常启动并响应消息再进入正式项目。这个步骤能区分“工具本身有问题”和“项目配置有问题”后面排查时能省很多时间。4. 质量门禁落地用 GATE.md 约束 Agent 的每次改动质量门禁是 Verity.md 最核心的部分。它的目标不是阻止 Agent 工作而是在任务开始前、执行中、结束时分别设置检查点让 Agent 始终处于可被约束的状态。4.1 设计三份基础文档GATE.md、REPO.md、TASK.md建议仓库内先建立三份角色明确的文档GATE.md所有任务都必须遵守的硬性规则。REPO.md当前仓库的结构、模块边界、常用命令。TASK.md本次具体任务的输入、输出和完成条件。目录结构示例project-root/ ├── .verity/ │ ├── GATE.md │ ├── REPO.md │ └── TASK.md ├── src/ └── docs/在 Claude Code 会话开始时用一行指令让 Agent 先读取这三份文件请先阅读 .verity/GATE.md、.verity/REPO.md、.verity/TASK.md 然后复述你的任务边界和禁止修改的目录确认后再开始编码。让 Agent 复述任务边界是一个简单但很有效的门禁动作。复述过约束的 Agent后续执行时偏离程度明显比直接开始编码的情况低。4.2 GATE.md 的内容模板下面模板用于说明思路实际项目需要结合自己的目录和规范修改。# GATE.md ## 一、任务开始前 - [ ] 已确认 TASK.md 中的任务目标 - [ ] 已确认当前分支与目标环境 - [ ] 已确认禁止修改的目录docs/archive、legacy/、vendor/ ## 二、执行中 - [ ] 不修改与当前任务无关的文件 - [ ] 如需修改公共组件先说明影响范围 - [ ] 每个重要步骤均输出执行结果不静默跳过 ## 三、任务完成前 - [ ] 运行测试命令npm test - [ ] 运行静态检查命令npm run lint - [ ] 确认新增或修改的配置有注释 - [ ] 确认没有提交本机绝对路径、密钥、临时文件 ## 四、任务提交后 - [ ] 在 PR 描述中列出修改文件 - [ ] 如果本次改动影响 API 或数据库需更新对应文档这份 GATE.md 的好处是可以被人 review。如果 Agent 某次越界团队能直接指出“GATE.md 第三段要求你没遵守”而不是靠记忆复盘。4.3 用检查清单做门禁而非靠感觉质量门禁要尽量表格化、勾选化。Agent 每完成一个步骤就在输出中标注[x]或[ ]这样人检查时能快速看出哪些环节被跳过。门禁阶段检查内容失败处理范围门禁本次任务涉及的目录是否在白名单内超出范围时停止并请求确认行为门禁是否执行了规定的预检查命令未执行则回到预检查步骤验收门禁测试、lint、构建命令是否通过失败则定位到具体测试用例文档门禁API 或配置变更是否同步文档文档缺失则补充后再提交5. 记忆管理把 Agent 的经验沉淀成仓库资产Claude Code 会话结束后对话历史不是项目资产。真正能复用的是被写入仓库、能被下次会话读取的记忆文件。5.1 设计 VERITY_AGENTS 目录与 ALWAYS_READ记忆文件不要全塞在一个 CLAUDE.md 里。文件太大时Agent 每次读取都会消耗大量 token而且重点会被稀释。建议按主题拆分.verity/ ├── AGENTS/ │ ├── frontend.md # 前端相关决策 │ ├── backend.md # 后端相关决策 │ ├── database.md # 数据库变更经验 │ ├── deploy.md # 发布流程与注意事项 │ └── debugging.md # 项目内常见报错处理 └── GATE.md在 Claude Code 支持 ALWAYS_READ 的项目里可以配置一个最小读取列表。不要让 Agent 一启动就把所有 AGENTS 文件全部读完而是按任务类型选择。ALWAYS_READ: - .verity/README.md # 说明记忆文件的组织方式 - .verity/GATE.md # 通用门禁5.2 用 引用和记忆文件降低重复劳动Claude Code 支持通过引用指定文件作为上下文。在需要让 Agent 记住某个历史决策时直接在 prompt 中引用记忆文件请先阅读 .verity/AGENTS/database.md再回答如何修改订单表的索引。这样比让 Agent 临时搜索整个项目更高效也比把大量内容直接写在 prompt 里更省 token。记忆文件的价值在于它经过了人的筛选是可靠上下文而不是模型自己的猜测。5.3 记忆文件更新流程记忆文件如果没有人维护会在几周后过期。推荐给 Claude Code 一个固定动作当任务中发现新的踩坑点时主动建议更新记忆文件。## 当出现以下场景时建议更新记忆文件 - 解决了 30 分钟以上的疑难问题 - 发现某个目录有隐藏约束 - 从旧方案切换到新方案且新方案值得复用 - 某个命令在特定系统中表现异常给 Agent 的指令示例如果本次调试解决了重要问题请在 .verity/AGENTS/debugging.md 中追加一节 - 问题现象 - 根因 - 解决命令 - 注意事项 不要删除已有内容。6. 成本控制让 token 消耗变得可见、可预、可降级成本控制的本质不是“少用 Claude Code”而是让每一次 token 消耗都服务于当前任务。多数不必要的消耗来自上下文过大、重复读取、无效调试。6.1 设置项目预算和会话预算Claude Code 提供了预算相关的配置能力。具体配置项以当前版本文档为准落地时可以按三个层级设置预算层级设置目标建议额度会话预算单次任务不超过固定 token按任务复杂度设置日预算防止一天内多个会话累计超支个人使用上限项目预算一个迭代周期的总量控制团队共同确认如果当前版本支持对应的配置方式建议直接写进项目配置文件并提交到版本库中让所有人都能看见。6.2 从源头压缩 token 消耗的五个方法每次任务只让 Agent 读取必要文件。不要给它列出整个 src 目录按模块范围给路径。大日志文件不要直接读取。先让 Agent 用grep或tail -n 200定位错误片段再把片段贴给它。明确要求 Agent 不要跳过步骤。跳过步骤会造成返工返工比逐步执行更耗 token。对长期任务设置输出边界。例如只要求输出关键决策和改动文件清单不要输出逐字 diff。记忆文件直接点名经验。让 Agent 知道“这个问题在 debugging.md 里已经记录过”可以避免重新调研。6.3 超过预算后的降级策略成本控制一定要带降级策略否则 Agent 在预算不足时可能偷偷跳过重要步骤。写进 GATE.md 的示例## 预算控制策略 - 当本次会话已消耗 80% 预算时停止所有探索性操作。 - 当达到预算上限时任务暂停输出当前进度与未完成步骤等待人工确认。 - 禁止为节省 token 而跳过测试、lint 或文档更新。给 Agent 的指令示例在执行过程中如果发现当前任务可能超过预算限制 请暂停并输出 1. 已完成内容 2. 剩余工作 3. 预计还需要多少预算 等待我确认后再继续。这样费用不会完全失控Agent 也不会因为预算不足而在“节省”和“质量”之间自行选择。7. 常见问题排查内存崩溃、安装失败和配置不生效Claude Code 使用过程中除了功能问题还会遇到进程崩溃、内存不足、配置不生效等情况。下面按照现象到根因的顺序给出排查路径。7.1 进程退出码 3221225477 与 0xc0000005 的排查思路在 Windows 环境中Claude Code 或相关 Node 进程可能报出process exited with code 3221225477 / 0xc0000005 (memory access violation)0xc0000005 表示内存访问违规常见原因包括本地环境内存不足、进程被系统强制终止、终端或代理程序干扰进程运行。排查顺序步骤操作判断依据1查看系统物理内存占用内存占用超过 90% 时先释放资源2查看 Node 进程数量多个 Claude 子进程残留时先结束残留进程3检查终端是否被杀毒软件或安全策略限制将终端加入白名单后重试4检查是否同时运行了多个重负载程序关闭无关程序后重试5升级 Node 到 LTS 版本旧版 Node 可能出现稳定问题这个崩溃不一定是 Claude Code 自身缺陷也可能是本地资源不足。建议先做最小化验证关掉其他程序重启终端再运行claude。7.2 Java 与构建工具报 OutOfMemoryError 时的处理路径如果 Claude Code 在运行 Java 项目的构建命令时报java: OutOfMemoryError: insufficient memory说明构建进程分配不到足够堆内存。可以分两层处理。第一层调整 Java 构建工具的堆内存参数# Maven 项目提高构建 JVM 内存 export MAVEN_OPTS-Xmx2g # Gradle 项目调整 JVM 参数 export GRADLE_OPTS-Xmx2g第二层把构建命令固化到 REPO.md 中让 Agent 每次按固定命令执行而不是临时猜测。这样人能 review 构建参数Agent 也不会反复尝试不同参数。7.3 安装时提示“could not locate the claude cli on path”这个报错在 VS Code 集成场景中很常见。原因是终端会话的 PATH 不包含 Claude CLI 所在目录。处理方式# 查看全局安装位置 which claude # 如果 which 无输出检查 npm 全局目录 npm prefix -g # Linux / macOS 加入 PATH export PATH$(npm prefix -g)/bin:$PATH # Windows PowerShell 加入 PATH $env:Path ;$(npm prefix -g)修改后重启 VS Code确认claude --version能输出版本号。7.4 配置修改后不生效的原因定位Claude Code 的配置有时由多个层级组成。项目配置、用户配置、环境变量之间如果顺序不对会出现“改了但没生效”的情况。排查顺序现象可能原因检查方式项目配置不生效配置文件路径拼错对比官方路径约定环境变量不生效终端未重启输出 echo 看变量值切换模型后无变化模型名与当前版本不匹配查看支持的模型列表ALWAYS_READ 配置无效格式或目录不对用绝对路径临时测试7.5 跨端内存错误与上下文过大的关系如果 Claude Code 本机运行很不稳定可以观察是否在“会话特别长”的时候崩溃。长会话会累积大量上下文增加内存占用。给长会话设置一个合理的结束时机当任务完成后主动建议开启新会话并使用 .verity/AGENTS 记忆文件继续。这样可以减少单进程内存压力也避免上下文被早期信息污染。8. 生产环境落地与检查清单把 Verity.md 从一个 Git 仓库里的文档规范变成团队真正执行的工程规范还需要在落地上做几个关键决定。8.1 学习环境与生产环境的差异学习环境只需要快速跑通生产环境则要保证可维护、可追溯、可回滚。维度学习环境生产环境配置方式全部写在 prompt 里沉淀到 .verity 目录并纳入 review记忆管理依赖会话内记忆使用 AGENTS 目录持久化费用控制设一个粗略预算分阶段预算加降级策略质量门禁靠自觉遵守用 GATE.md 约束并由团队成员共同 review日志留存随意每个重要任务保留决策记录和关键日志片段8.2 发布前检查清单在一个新项目落地 Verity.md 时可以按下面清单逐项确认检查项状态.verity/目录已加入版本控制是/否GATE.md中的门禁规则与团队实际工作流一致是/否REPO.md记录了项目构建、测试、Lint 的准确命令是/否AGENTS/记忆文件有维护负责人是/否Claude Code 启动指令包含“先读 GATE.md”这一动作是/否预算策略已配置且包含超出预算后的暂停规则是/否所有成员能通过claude --version确认版本一致是/否8.3 给新手的最小起步路径不要一开始就写一整套复杂规范。建议按三步推进。第一步只放一个 GATE.md包含范围门禁和验收门禁。让 Claude Code 每次任务开始前先读取它。第二步添加一个 AGENTS/debugging.md。每次解决疑难问题后让 Agent 追加一条踩坑记录。第三步加入预算设置。把预算数字和暂停策略写进 GATE.md让成本风险可见。这套路径一周内就能跑起来。等团队习惯文档驱动 Agent 的工作方式后再逐步增加 REPO.md、TASK.md 等更细的文档层。9. 扩展方向从个人习惯到团队规范Verity.md 的价值在独立使用时体现为个人效率提升在团队协作中则体现为知识资产沉淀。可以让每个成员负责维护自己熟悉模块的 AGENTS 文件也可以在 CI 脚本中检查“本次 PR 是否更新了对应记忆文件”。还可以进一步构建轻量级的自动检查脚本在 Claude Code 任务执行后用脚本自动扫描 Git 改动文件列表对比 GATE.md 中定义的允许目录一旦越权就打印警告。这不是 CI 门禁但它能给人 review 提供第二道防线。真正值得投入的不是把文档写得越长越好而是让文档成为 Agent 每次任务的固定起点。质量门禁不是限制模型能力而是确保它把能力用在对的地方记忆管理不是增加额外工作而是把已经付过费的经验复用起来成本控制不是少用工具而是每一分 token 都花在解决当前问题上。