用规则文件和钩子约束Claude Code

Claude Code 总是忘记团队约定，问题未必出在提示词写得不够长。作者在 .NET 和 Angular 项目里，把反复交代的要求沉淀为规则文件，再用 kit 插件拦截部分操作，让约定跨会话保留。

这套方案值得看的，是它划清了三类事情：哪些交给模型理解，哪些用程序检查，哪些仍需人工核验。规则负责表达意图，hooks 负责执行部分约束，但作者没有给出效率提升或缺陷下降的对照数据。

规则怎样才能跟着项目走

claude-config 是规则模板，kit 是配套插件。原文在 2026-11-09 更新：插件从 kit-config 改名为 kit，版本为 1.10.0，原来的 copia-regole.bat 复制脚本由 skills 替代，安全规则拆成三个文件。规则用意大利语编写，代码、标识符和提交信息保持英文。

它没有把所有要求塞进一个文件，而是按生效时机拆分：

• .claude/rules/ 存放自动加载的模块；.claude/rules-optional/ 存放功能工作流、邮件和基础设施等可选模块，移入 rules/ 才加载。
• core.md、git.md、security.md 在启动时加载，覆盖通用协作、Git 流程和安全原则。
• 其余模块通过文件头的 paths: 匹配文件，处理前端、后端和 Docker 的具体要求。

例如，frontend.md 和 security-frontend.md 匹配 *.ts、*.html、*.css、*.scss，要求使用 Angular、PrimeNG，不使用旧式 NgModule 和 any，同时约束 CSP 等前端安全事项。

后端模块匹配 *.cs、*.csproj、*.props，涉及 .NET 10、EF Core、vertical slice 与 clean architecture 的选择，以及认证授权、上传、限流和日志。docker.md 匹配 Dockerfile、compose 文件和 docker/**，要求多阶段构建、每个环境一个 compose 文件，并禁止在 compose 中放数据库。

CLAUDE.md 则记录项目事实：架构、数据库、ORM、多租户、ASVS 级别等必须询问后填写。作者想解决的是模型擅自补全技术决策的问题，同一个选择确认一次，后续会话读取记录。

哪些约定能从提醒变成拦截

作者最在意两条规则：不明确时一次只问一个问题；非简单任务先写计划。

计划保存在项目根目录的 PIANO.md，列出步骤和状态框。只有构建与测试通过，步骤才能勾选；完成后删除计划，历史保留在 changelog。core.md 还规定前后端使用 ProblemDetails、以翻译键代替文本、统一 UTC 日期，并要求 xUnit、Vitest、Playwright，以及新增代码 80% 的覆盖率。

这些约定里，有些能被 hooks 检查。kit 的问题数量检查限制 AskUserQuestion 每次调用只能包含一个问题；写入后检查则核对计划是否先记录构建、测试结果，再勾选步骤，同时检查代码质量和 C# 实践。

命令守卫会阻止 git init、git push --force、删除远程分支、git reset --hard、git clean -f、--no-verify 和 rm -rf。普通 push 和 tag 始终允许；git status、git log、gh pr view 等只读命令也始终允许。gh pr create/merge 和 gh release 只有在 CLAUDE.md 声明安装 GitHub CLI 后才放行。

这与 git.md 中「本地提交必须先确认」是不同层面的约束。原文没有说每条文字规则都有对应的强制检查。

写入守卫还会拦截 appsettings*.json、compose 文件及其他写入内容中的真实密钥和不安全模式。会话相关 hooks 提醒单问题规则、报告上次会话后变更的规则，并在结束时提醒未完成计划。配置位于 plugins/kit/hooks/hooks.json，主要通过四个事件脚本运行，每项检查在 plugins/kit/tests/ 下有测试。

有测试的拦截器，也不等于完整的代码审查。

装好插件后，规则仍要按项目选择

以下两条命令用于在每台机器安装一次插件：

claude plugin marketplace add AngeloDotNet/claude-config
claude plugin install kit@claude-config

要留意第二行现在安装的是 kit。使用旧名 kit-config 的用户需要安装 kit、移除 kit-config，并重启 Claude Code，因为 hooks 在会话启动时加载。

项目接入分三种情况：新项目复制规则和 CLAUDE.md 模板，再用 /kit:avvia-progetto 完成询问与记录；已有项目用 /kit:copia-regole 逐文件选择规则；已有规则则用 /kit:aggiorna-regole 更新，每个文件分别确认。只需要 Git 约定的项目，可以仅保留 core.md 和 git.md。

插件另有 16 个按需调用的命令，下面的导图保留了完整名称。它们不会因为安装插件就自动运行。

维护记录也属于方案的一部分：CHANGELOG.md 按日期记录原因、文件和验证情况，_template/ 提供项目启动指南及处理 kit-allow 例外的 CI 辅助工具。哪些细节没有对照来源核验，changelog 会标注。

我的判断

我认可「项目事实写入文件、可检查约束交给程序」这个方向。相比只维护一份长提示词，按文件类型加载规则更容易控制适用范围，hooks 也能在模型执行操作时提供额外检查。

但这是一份带有作者偏好的模板。强制 develop、进入 develop 的 PR 使用 squash、涉及 main 使用 merge commit，以及禁止 MediatR、禁止 compose 承载数据库，都不能直接当成普遍最佳实践。采用 trunk-based development 或依赖 compose 启动本地数据库的团队，需要先改规则。

权限边界也要逐条读。这个插件会拦截部分危险命令，却始终允许普通 push 和 tag。安装它并不能替代团队对远程操作的授权约定。

作者明确承认，hooks 逐行读取代码，跨多行的 public 成员或复杂 attribute 可能漏检。PostgreSQL 行级安全和 ASP.NET Core Identity 的 passkey 支持，也尚未针对 .NET 10 正式版核验，只标记为首次使用时检查。

因此，这套实践证明了规则可以被组织、分发和部分执行；它是否减少返工、是否优于其他配置方式，仍是经验之谈，原文没有对照数据。

能拿来做什么

• 给日常 AI 编程项目整理一份最小约定，先记录提交授权、构建命令和技术栈选择；采用作者模板前，删除与项目冲突的要求。
• 前端团队可以优先统一接口错误结构、翻译键和 UTC 日期，再按实际文件类型加载规则，让跨会话协作有固定依据。
• 为非简单修改保留临时计划，明确完成条件；若采用自动勾选检查，应核对它是否真的读取了构建与测试结果。
• 将安全规则区分为可自动检查和待人工核验两类，尤其保留作者标注的未验证事项，避免把模板文字当成验证结论。