ECC Angular 钩子实战:用 PostToolUse 与 Stop 钩子构建 Angular 代码质量自动化防线

原创2026-09-09 16:44:421,442 阅读
文章标签:人工智能AI 技能AI 插件AI 评测提示工程MCP ClientsAgent 记忆开发工具

ECC Angular 钩子实战:用 PostToolUse 与 Stop 钩子构建 Angular 代码质量自动化防线

本指南围绕 ECC(Everything Claude Code)仓库中面向 Angular 工程的钩子规则展开,系统讲解如何通过 PostToolUse(工具执行后)与 Stop(会话收尾)两类钩子,在 Claude Code / Codex / Opencode / Cursor 等 Agent 编辑 Angular 源码时自动完成格式化、Lint、类型检查与构建校验。读完本文,你将掌握 ECC 钩子规则的配置位置、Angular 专属匹配路径、底层实现原理(格式化器检测、tsconfig 定位、批处理审计),以及如何与仓库内其他 Angular 规则联动落地一套可复用的质量闭环。

一、规则分层:从 common 到 Angular 的扩展机制

ECC 在 rules/ 目录下按技术栈组织规则集(angular、react、vue、golang、rust 等),每套规则又分为 coding-style、patterns、hooks、security、testing 等主题文件。这种分层设计的关键在于:通用规则只写一份,语言/框架专属规则通过"扩展"机制增量补充。

关联文档 docs/ja-JP/rules/angular/hooks.md(英文原版见 rules/angular/hooks.md)开篇即声明:

此文件以 Angular 专属内容扩展 common/hooks.md。

也就是说,Angular 钩子规则是"通用钩子系统 + Angular 增量"的合体。通用部分(钩子类型、自动批准权限、TodoWrite 最佳实践)位于 docs/ja-JP/rules/common/hooks.md,而 Angular 增量部分则聚焦于 PostToolUse 与 Stop 两类钩子的具体检查项。

Angular 文件匹配路径

文档 frontmatter 通过 paths 字段声明规则生效的文件范围,这是钩子 matcher 配对的依据:

paths:
  - "**/*.component.ts"
  - "**/*.component.html"
  - "**/*.service.ts"
  - "**/*.directive.ts"
  - "**/*.pipe.ts"
  - "**/*.spec.ts"

从源码结构看,这份路径清单几乎覆盖了 Angular 应用的典型源文件类型:组件(组件类 + 模板)、服务、指令、管道和单元测试。钩子应主要作用于这些文件——例如编辑 .component.html 后触发模板格式化,编辑 .ts 后触发类型检查,编辑 .spec.ts 后无需触发构建。

二、钩子系统基础:生命周期与触发时机

要理解 Angular 钩子,先要掌握 ECC 钩子系统的整体模型。根据 docs/ja-JP/rules/common/hooks.md 与 hooks/README.md,钩子按生命周期分为五类:

钩子类型 触发时机 典型用途
PreToolUse 工具执行前 参数校验、参数修改,可拦截(exit code 2)或警告
PostToolUse 工具执行后 自动格式化、质量检查,可分析输出但不能阻断
Stop 每次 Agent 响应结束 / 会话收尾 最终验证、批量审计
PreCompact 上下文压缩前 保存状态
SessionStart / SessionEnd 会话开始 / 结束 会话生命周期管理

hooks/README.md 用一条链路描述整体流程:

User request → Claude picks a tool → PreToolUse hook runs → Tool executes → PostToolUse hook runs

仓库中真实的钩子注册清单位于 hooks/hooks.json,它展示了 ECC 如何把大量守护逻辑挂到各个生命周期上:PreToolUse 下有 Bash 前置分发器(pre:bash:dispatcher)、文档文件警告(pre:write:doc-file-warning)、配置保护(pre:config-protection)、MCP 健康检查(pre:mcp-health-check)、GateGuard 事实强制(pre:edit-write:gateguard-fact-force)等;PostToolUse 下则有同步/异步分发器(post:dispatcher:sync / post:dispatcher:async);Stop 下挂载了 stop:format-typecheck、stop:check-console-log、stop:session-end、stop:cost-tracker、stop:desktop-notify 等。Angular 钩子规则正是建议你在自己的工程中按同一套生命周期模型,把 Angular 特有的检查项接入 PostToolUse 与 Stop。

三、PostToolUse 钩子:编辑后的即时质量守护

原文档明确指出,PostToolUse 钩子在 ~/.claude/settings.json 中配置(关于仓库推荐的安装方式差异,详见第五节)。针对 Angular 工程,文档列出四项核心检查。

3.1 Prettier:编辑后自动格式化 .ts 与 .html

规则要求:编辑完成后对 .ts 与 .html 文件自动格式化,保证代码风格统一,避免 Agent 产出与团队 prettier 配置不一致的代码。

ECC 仓库本身就有可对照的参考实现——scripts/hooks/post-edit-format.js。该脚本的核心逻辑如下:

  1. 文件匹配:仅对 \.(ts|tsx|js|jsx)$ 文件生效(Angular 场景即 .ts;.html 模板通常由 prettier 的 angular 插件或项目自身的 HTML formatter 处理);
  2. 项目根发现:调用 scripts/lib/resolve-formatter.js 的 findProjectRoot(),自被编辑文件所在目录向上逐级查找 package.json、biome.json、.prettierrc* 等标记文件(见 PROJECT_ROOT_MARKERS);
  3. 格式化器检测:detectFormatter() 按优先级返回 biome 或 prettier——先查 biome.json / biome.jsonc,再查 package.json 中的 prettier 键,最后遍历十种 prettier 配置文件(.prettierrc、.prettierrc.json、.prettierrc.js/.cjs/.mjs/.yml/.yaml/.toml、prettier.config.js/.cjs/.mjs);
  4. 二进制解析:resolveFormatterBin() 优先使用项目本地 node_modules/.bin 下的可执行文件(省去 npx 每次约 200~500ms 的解析开销),缺失时才回退到包管理器执行命令(npx/pnpm/yarn/bunx,Windows 下映射为 .cmd shim);
  5. 非阻塞失败:格式化器未安装或执行失败时静默跳过,绝不影响 Agent 正常流程。

值得注意的工程细节:Biome 场景下该脚本使用 check --write(格式化 + Lint 一步完成),避免与 quality-gate 钩子重复执行;Windows 场景下对含 shell 元字符的路径做注入防护(UNSAFE_PATH_CHARS 检查)。

3.2 ESLint / ng lint:Angular 源码的语义与风格检查

规则要求:编辑 Angular 源文件后运行 ng lint,以捕获**装饰器误用(decorator misuse)、模板错误(template errors)、样式违规(style violations)**三类问题。

这三类问题正是 Angular Lint 相对通用 Lint 最有价值的增量:

  • 装饰器误用:如 @Input / @Output / @HostListener 使用不当、@Component 元数据配置错误;
  • 模板错误:模板语法、绑定表达式、指令使用错误(*ngIf / ngSwitch / [property] 绑定等);
  • 样式违规:组件样式作用域、命名约定等团队规范问题。

在实际工程中,ng lint 的执行依赖 angular.json 中配置的 lint target(Angular 现代版本基于 ESLint)。该命令应在编辑 component.ts、directive.ts、service.ts 等文件后触发,属于"即时反馈"型检查,应在 PostToolUse 阶段完成,而不是拖到会话结束。

3.3 TypeScript 检查:tsc --noEmit

规则要求:编辑 .ts 文件后运行 tsc --noEmit,在类型层面第一时间拦截错误。这条规则的仓库级参考实现是 scripts/hooks/post-edit-typecheck.js,其实现要点非常契合 Angular 场景:

  • tsconfig 定位:从被编辑文件所在目录向上逐级查找 tsconfig.json(最多 20 层防止死循环),在找到的目录下执行 npx tsc --noEmit --pretty false(Windows 使用 npx.cmd 以避免 shell: true 带来的命令注入风险),超时 30 秒;
  • 错误过滤:tsc 输出的是整个项目的错误,脚本只筛选与当前编辑文件相关的行——它同时比对原始路径、绝对路径、相对路径三种形式,并刻意避免使用裸 basename 匹配,防止 src/utils.ts 与 tests/utils.ts 同名文件互相误报;
  • 仅报告不阻断:将相关错误行写入 stderr 提示,最多截取 10 行,然后原样透传输入。

3.4 构建检查:ng build

规则要求:在生成或大幅修改 Angular 代码后运行 ng build,尽早捕获模板与类型错误。ng build 是三者中代价最高的检查(涉及 AOT 编译与打包),因此规则明确限定触发条件为"生成新代码或大规模变更",而非每次小编辑——这与 3.3 的 tsc --noEmit 形成互补:高频小步用 tsc --noEmit,低频大幅变更用 ng build 做整包验证。

四、Stop 钩子:会话收尾的批量审计

4.1 Lint 审计

原文档规定:会话结束前,对本次会话修改过的文件整体运行 ng lint,捕获尚未解决的违规。这弥补了 PostToolUse 只检查"当前编辑文件"的盲区——当一个功能涉及多文件联动修改时,跨文件的 lint 问题(如未使用的导入、组件间引用关系)只有在会话收尾的全局审计中才能完整暴露。

4.2 批处理机制的仓库级实现

"对修改过的文件整体执行检查"这一思想,在 ECC 中有成熟的批处理实现——scripts/hooks/stop-format-typecheck.js。该 Stop 钩子的设计非常值得 Angular 工程借鉴:

  1. 累积器(accumulator):每次编辑时,scripts/hooks/post-edit-accumulator.js 把被编辑文件路径写入临时文件(ecc-edited-<sessionId>.txt,位于系统临时目录);Stop 钩子读取后去重解析并立即删除该文件,保证重复触发不会重复处理;
  2. 按项目根分组格式化:同一项目根下的所有 JS/TS 文件合并为一次 formatter 调用(Biome 用 check --write,Prettier 用 --write),避免每个文件单独启动进程;
  3. 按 tsconfig 目录分组类型检查:.ts/.tsx 文件按最近的 tsconfig.json 目录分组,每个目录只跑一次 tsc --noEmit,错误行按文件过滤输出;
  4. 预算管理:总预算 270 秒按批次数量均分(TOTAL_BUDGET_MS / totalBatches),确保在 Stop 钩子 300 秒墙钟时限内完成,即使面对大型 monorepo 也不会超时;
  5. 插件克隆保护:isPluginClonePath() 跳过 ~/.claude/plugins 等第三方检出目录——这些代码不属于用户,不应被批量重写。

该实现的正确性由测试 tests/hooks/stop-format-typecheck.test.js 保障,测试覆盖了"原样透传输入""无效 JSON 透传""无 file_path 透传""累积器文件创建/去重/清理"等边界行为。

五、配置与安装方式

5.1 规则文档给出的配置位置

Angular 钩子规则文档(docs/ja-JP/rules/angular/hooks.md)指出 PostToolUse 钩子在 ~/.claude/settings.json 中配置。结合文档的四项检查,可得到如下示意配置(需按项目实际命令路径调整):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "**/*.{ts,html}",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      },
      {
        "matcher": "**/*.ts",
        "hooks": [
          {
            "type": "command",
            "command": "npx ng lint"
          },
          {
            "type": "command",
            "command": "npx tsc --noEmit"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "npx ng lint"
          }
        ]
      }
    ]
  }
}

说明:上例为基于规则文档要点整理的示意结构,实际使用时 matcher 应结合第二节的 Angular 文件路径清单细化,命令建议使用项目本地 node_modules/.bin 中的可执行文件(性能更优),并参考 scripts/hooks/post-edit-format.js 的做法为钩子设置合理的 timeout。

5.2 ECC 仓库推荐的安装方式

需要特别说明的是,hooks/README.md 明确指出:不要把仓库自带的 hooks/hooks.json 直接粘贴到 ~/.claude/settings.json——该文件是面向插件/仓库形态的,其中的命令路径会被 ECC 安装器改写为实际 Claude 根目录。正确方式是使用 ECC 安装器:

bash ./install.sh --target claude --modules hooks-runtime --enable-hooks
pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks

安装后钩子会被解析写入 ~/.claude/hooks/hooks.json(Windows 为 %USERPROFILE%\.claude)。这一区分对 Angular 开发者同样成立:如果你只是在自己的 Angular 工程中配置少量钩子,直接编辑 ~/.claude/settings.json 即可;如果需要完整启用 ECC 的钩子运行时,则应走安装器。

六、配套最佳实践:自动批准权限与 TodoWrite

Angular 钩子规则继承自 docs/ja-JP/rules/common/hooks.md 的通用约束,其中两条对钩子工作流至关重要:

自动批准权限(Auto-Accept Permissions)需谨慎使用:

  • 仅在可信、定义清晰的计划上启用;
  • 在探索性工作中禁用;
  • 绝不使用 dangerously-skip-permissions 标志;
  • 应改在 ~/.claude.json 中通过 allowedTools 配置允许的工具白名单。

这条约束与钩子体系天然互补:钩子负责"事后把关"(格式化、Lint、类型检查),权限控制负责"事前约束"(哪些工具可以免确认执行),二者共同构成质量防线,而不是用一刀切的跳过权限来换取速度。

TodoWrite 工具最佳实践:对于多步骤任务,使用 TodoWrite 跟踪进度、验证对指令的理解、支持实时调整,并展示细粒度实现步骤。Todo 列表的价值在于暴露:顺序错误的步骤、缺失的条目、多余的无谓条目、粒度错误的需求理解。在 Angular 功能开发(组件 → 服务 → 模板 → 测试)这类典型多步任务中,配合钩子的即时检查,可以形成"计划可见、执行可查、质量可控"的闭环。

七、与 Angular 规则集联动:完整的质量闭环

钩子只是 Angular 质量体系的一环。在 rules/angular/ 下,ECC 还提供了与之配套的规则文件,推荐组合使用:

  • rules/angular/testing.md:Angular 测试规范——ng test --no-watch 的 CI 模式、standalone 组件 TestBed 配置、signal input 通过 fixture.componentRef.setInput() 注入、优先使用 Angular CDK component harness 而非直接 DOM 查询、fakeAsync + tick 与 waitForAsync + whenStable 的异步策略、provideHttpClientTesting 的 HTTP 测试,以及服务、管道、守卫的覆盖目标;
  • rules/angular/patterns.md 与 rules/angular/coding-style.md:架构模式与编码风格基线;
  • rules/angular/security.md:Angular 安全实践(如模板注入、XSS 防护相关约束)。

将本文的钩子配置与上述规则组合后,一个典型的 Angular Agent 开发闭环是:编辑组件/服务 → Prettier 自动格式化 + ng lint + tsc --noEmit 即时反馈(PostToolUse)→ 生成新模块后 ng build 整包验证 → 会话结束前全局 ng lint 批量审计(Stop),全程辅以 allowedTools 白名单与 TodoWrite 计划跟踪。这套模式既适合在个人 Angular 工程中手工配置(~/.claude/settings.json),也适合通过 ECC 安装器启用完整的钩子运行时后,参照 hooks/hooks.json 与 scripts/hooks/ 中的现成实现(格式化、类型检查、控制台日志检测、成本跟踪等)快速搭建属于自己的质量防线。

登录后查看全文
ECC