团队规范、编码风格与审阅标准沉淀

个人项目靠经验，团队项目靠可共享、可执行、可评审的约定。本节讲团队规范应放在哪里、按什么结构写、如何用只读子代理固化审阅标准，让每位成员（与每位代理实例）得到一致的行为基线。

一、规范的存放分层

内容类型	推荐位置	理由
组织级强制安全/合规标准	托管策略 CLAUDE.md	最高优先级、组织统一下发
项目架构、构建与目录约定、常用工作流	项目 ./CLAUDE.md（入库）	随版本共享给全体成员
按路径/文件类型细分的规则	.claude/rules/*.md 或子目录 CLAUDE.md	按需加载，控制上下文体积
可复用提示模板、审查流程	.claude/commands/、.claude/agents/	显式调用、工具权限受限、可版本管理
本机个人偏好与沙箱数据	./CLAUDE.local.md（gitignore）	不污染团队规则

二、项目 CLAUDE.md 推荐结构

• 项目概述与技术栈：一句话定位、主要语言/框架、运行与构建命令、依赖与前置环境。
• 目录结构与职责：关键目录用途、新增代码应放置的位置。
• 编码与风格约定：命名、缩进/格式、错误处理、注释与文档要求，尽量具体可判定。
• 测试与质量要求：测试组织方式、必须覆盖的关键路径、运行测试与静态检查的命令。
• 工作流约定：分支、提交说明、变更前必须跑的检查、禁止事项（如禁止直接改生产配置）。
• 领域术语与背景：业务专有名词、核心概念，避免代理误解上下文。

原则是"规则少而准、引用不堆砌"：长文档按主题拆到 rules/ 或用 @path 引入；能用现有代码/测试体现的约定不必用文字重复。

三、写法：从模糊口号到可执行条款

模糊写法（效果差）	可执行写法（效果好）
"代码要写得规范、易读"	"遵循仓库现有命名；函数职责单一；新增公开函数补充注释说明参数与返回含义"
"多写测试"	"核心工具函数必须有单测；修复缺陷先补回归用例；改完运行测试命令并保持全绿"
"提交要清晰"	"标题为动作+对象；正文说明动机与影响；关联问题编号；不在一次提交中混合多类改动"

四、用只读子代理固化审阅标准

• 在 .claude/agents/ 定义只读审查代理：tools 只保留 Read/Grep/Glob 等只读能力，不授予写权限，让其专门按团队清单检查差异。
• 在代理提示中写入统一审查维度：正确性与边界条件、并发/竞态、错误处理、与既有模式一致性、测试覆盖、安全敏感点、风格与命名。
• 采用"作者实现、审查者独立复核"的双角色结构：审查者在新鲜上下文看 diff，比作者自查更易发现盲点。
• 把重复的检查命令与流程沉淀为项目自定义命令，减少每次口述约定的成本（命令与子代理的分工见第 7 章）。

五、让约定可被团队维护

• 项目 CLAUDE.md、命令、子代理、规则文件一并入库，变更经代码评审，避免规则只存在于某个人的本机。
• 新成员入职时先读本文件即可获得构建、风格、测试、流程基线；发现规则失效时随对应版本一并更新，而不是口头相传。
• 对"零例外、必须执行"的动作（如每次保存后自动检查），优先用确定性的钩子机制约束，规则文档负责说明目的，二者互补。