ECC Angular 钩子实战:用 PostToolUse 与 Stop 钩子构建 Angular 代码质量自动化防线
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。该脚本的核心逻辑如下:
- 文件匹配:仅对
\.(ts|tsx|js|jsx)$文件生效(Angular 场景即.ts;.html模板通常由 prettier 的angular插件或项目自身的 HTML formatter 处理); - 项目根发现:调用 scripts/lib/resolve-formatter.js 的
findProjectRoot(),自被编辑文件所在目录向上逐级查找package.json、biome.json、.prettierrc*等标记文件(见PROJECT_ROOT_MARKERS); - 格式化器检测:
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); - 二进制解析:
resolveFormatterBin()优先使用项目本地node_modules/.bin下的可执行文件(省去 npx 每次约 200~500ms 的解析开销),缺失时才回退到包管理器执行命令(npx/pnpm/yarn/bunx,Windows 下映射为.cmdshim); - 非阻塞失败:格式化器未安装或执行失败时静默跳过,绝不影响 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 工程借鉴:
- 累积器(accumulator):每次编辑时,scripts/hooks/post-edit-accumulator.js 把被编辑文件路径写入临时文件(
ecc-edited-<sessionId>.txt,位于系统临时目录);Stop 钩子读取后去重解析并立即删除该文件,保证重复触发不会重复处理; - 按项目根分组格式化:同一项目根下的所有 JS/TS 文件合并为一次 formatter 调用(Biome 用
check --write,Prettier 用--write),避免每个文件单独启动进程; - 按 tsconfig 目录分组类型检查:
.ts/.tsx文件按最近的tsconfig.json目录分组,每个目录只跑一次tsc --noEmit,错误行按文件过滤输出; - 预算管理:总预算 270 秒按批次数量均分(
TOTAL_BUDGET_MS / totalBatches),确保在 Stop 钩子 300 秒墙钟时限内完成,即使面对大型 monorepo 也不会超时; - 插件克隆保护:
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/ 中的现成实现(格式化、类型检查、控制台日志检测、成本跟踪等)快速搭建属于自己的质量防线。