workflow-clean-code-angular

确保目标范围内的 Angular 代码达到资深开发者手工编写的水准——整洁、清晰、没有 AI 生成的粗糙代码，架构合理，信号模式正确，并明确分离视图模型。 这不是代码检查工具。代码检查工具会捕获语法问题。这项技能会捕获**设计决策**问题——只有资深工程师在代码审查时才会发现的那类问题。

资深开发者编写的代码与 AI 生成的代码之间，有三点区别：

1. 没有多余内容——不为不可能发生的情况添加防御性检查，不为只有一个调用方的场景创建抽象，不添加重复描述代码的注释
2. 职责各归其位——Store 负责数据转换，组件负责协调 UI，模板只做绑定
3. 模式一致——每个 Store 都遵循相同的结构，每个组件都遵循相同的组织方式，不采用令人意外的约定

<quick_start>

/clean-code-angular feature/budget/          # Standard audit
/clean-code-angular -a --deep feature/       # Deep audit, auto mode
/clean-code-angular --quick core/            # Quick surface scan
/clean-code-angular --slop --vm feature/     # Focus: AI slop + ViewModel
/clean-code-angular diff main                # Audit changes vs main
/clean-code-angular pending                  # Audit uncommitted changes

</quick_start>

标记	描述
-a	自动模式——跳过确认
-e	经济模式——不使用子 Agent，仅直接分析
-s	保存——将报告输出到 .claude/output/clean-code-angular/
-r	恢复——从先前的运行继续
--quick	仅进行表层扫描（grep 模式，不做语义分析）
--deep	完整深度：涵盖所有领域，包括 AI 生成的粗糙代码、视图模型和跨文件分析
--arch	强制进行架构分析
--signals	强制进行信号模式分析
--styling	强制进行样式分析
--testing	强制进行测试分析
--slop	强制检测 AI 生成的粗糙代码
--vm	强制进行视图模型／数据模型分析
--adv	对抗式审查——团队负责人完成工作后，由唱反调的 Agent 逐项质疑发现，检查误报、遗漏问题和严重性夸大
--ultra	最大深度：15 位专家分成 5 个集群，每个集群配一位负责人，另有总技术负责人和对抗式审查。适用于关键代码的终极选项。

默认深度（不带标记）：grep + 对关键文件进行有针对性的语义分析。 --deep 会启用所有专家领域。

``` SCAN ─────────────────► APPLY ─────────────► VERIFY │ │ │ ├─ Parse scope ├─ Load docs/refs ├─ Lint + type-check ├─ Launch specialists ├─ Apply fixes ├─ Run tests │ (up to 10 agents) │ (parallel agents) ├─ Team lead final ├─ Team lead review ├─ Team lead │ craftsman review ├─ Adversarial review │ coherence check ├─ Adversarial final │ (if --adv) └─ Track progress │ challenge (if --adv) └─ Consolidated issues └─ Commit ```

<agent_model>

Agent 架构

此技能会根据标记调整 Agent 数量：

模式	Agent 数量	结构
经济模式（-e）	0	仅使用直接工具，不使用子 Agent
标准	3-10 + 负责人	扁平结构：专家 → 团队负责人
深度（--deep）	14 + 负责人	8 个单项专家 + 3 个信号视角 + 3 个粗糙代码视角 → 达成共识 → 团队负责人
深度 + 对抗式（--deep --adv）	14 + 负责人 + 对抗方	深度模式 + 对抗式审查
超级（--ultra）	15 + 5 位负责人 + 总负责人 + 对抗方 = 22	5 个集群 → 5 位集群负责人 → 总技术负责人 → 对抗式审查

标准／深度模式——扁平架构

最多并行启动 10 位专注于特定领域的专家。数量随范围大小调整：

范围	Agent 数量	覆盖领域
1-4 个文件	3 + 负责人	架构、Angular／信号、TypeScript／样式
5-15 个文件	5 + 负责人	+ Store 模式、组件设计
16-30 个文件	7 + 负责人	+ 模板、AI 生成的粗糙代码
31 个及以上文件	10 + 负责人	全部 10 个领域

10 个领域

#	领域	重点
1	架构与依赖	分层违规、跨功能导入、依赖方向
2	Signals 与响应性	滥用 effect()、computed() 的使用机会、linkedSignal()、清理
3	Store 模式	6 个部分的结构、缓存优先、乐观更新、资源用法
4	组件设计	OnPush、职责、规模、input()/output()、inject()
5	模板质量	控制流、表达式复杂度、包装器臃肿、无障碍性
6	TypeScript 质量	any 类型、# 字段、现代 API、死代码
7	样式	::ng-deep、Material M3 令牌、Tailwind v4、!important
8	AI Slop	过度工程化、不必要的注释、防御性表演、冗长命名
9	ViewModel 与数据流	DataModel 与 ViewModel、转换位置、重复派生
10	安全、性能与代码健康	XSS、变通方案/黑客式修复、设计异味、@defer、延迟加载

启用 --testing、--deep 或 --ultra 时，会检查测试质量。测试专家会读取范围内的 .spec.ts 文件，并依据 references/testing-patterns.md 进行评估。

Ultra 模式 — 多层集群架构

15 位专家分为 5 个集群，每个集群都配有专属集群负责人。每位专家只加载所需的参考文件，不会臃肿。

集群 1：架构 → 架构负责人

Agent	重点	加载内容
1a	分层违规、跨功能导入	references/angular-architecture.md
1b	DI 模式、函数式拦截器、提供者	references/angular-clean-code.md §3
1c	延迟加载、路由、@defer 边界	references/angular-anti-patterns.md §19-20

集群 2：Signals 与状态 → 响应性负责人

Agent	重点	加载内容
2a	Signal 模式、computed、effect、afterRenderEffect	references/angular-clean-code.md §2
2b	Store 结构、变更、resource API	references/angular-clean-code.md §2 + §13
2c	RxJS 的合理用法与反模式、Observable/Signal 桥接	references/angular-anti-patterns.md §2 + Valid RxJS table

集群 3：代码质量 → 质量负责人

Agent	重点	加载内容
3a	TypeScript、类型、现代 API（toSorted、structuredClone）	references/angular-anti-patterns.md §6
3b	AI Slop 检测（全部 9 类）	references/ai-slop-detection.md
3c	错误处理、catch 类型、资源错误状态	references/angular-clean-code.md §13

集群 4：UI 与模板 → 前端负责人

Agent	重点	加载内容
4a	控制流、@defer、模板表达式	references/angular-clean-code.md §4
4b	样式、无障碍性、NgOptimizedImage	references/angular-anti-patterns.md §7 + §20-21
4c	管道、ViewModel 分离、格式化	references/viewmodel-patterns.md + references/angular-clean-code.md §15

集群 5：测试与安全 → 安全负责人

Agent	重点	加载内容
5a	测试质量、harness、覆盖率	references/testing-patterns.md
5b	安全、变通方案、无 Zone 违规	references/angular-anti-patterns.md §8 + §15-16
5c	Signal Forms、API 验证、表单模式	references/angular-clean-code.md §14 + §9

流程：

15 specialists (parallel) → 5 cluster leads (parallel) → Grand Tech Lead → Adversarial

团队负责人（Standard/Deep）

在专家完成工作后启动。由一位资深 Angular 架构师担任，负责：

• 将所有专家报告合并为一份去重后的清单
• 通过阅读实际代码排除误报
• 解决专家之间的矛盾
• 补充没有任何单个专家发现的跨领域问题
• 确定最终问题清单的优先级
• 在 step-02 验证修复的一致性
• 在 step-03 进行最终的匠心审查

集群负责人（Ultra）

每位集群负责人只会收到 3 位专业人员的报告。他们会：

• 在自己的领域内去重
• 解决专业人员之间的矛盾
• 补充领域特有的跨领域观察
• 输出聚焦于该领域的报告（每个集群最多 10 个问题）

技术总负责人（Ultra）

接收全部 5 份集群负责人报告。他是一位资深 Angular 架构师，会：

• 将所有集群报告合并为一个统一的问题列表
• 解决跨集群矛盾（例如，架构建议“移至 core”，而质量建议“内联”）
• 识别跨集群的系统性模式（例如，“每个文件都有相同的 DI 问题”）
• 按业务影响而非仅按技术严重程度排序
• 最多列出 30 个问题；如果问题更多，则注明总数
• 添加“系统性诊断”部分：这些问题模式背后的根本原因是什么？

对抗性审查员（--adv 或 --ultra）

在团队负责人／技术总负责人之后启动。这位资深工程师持怀疑态度，会：

• 质疑每项发现：“这真的有问题吗？是否存在合理的架构原因？”
• 排查误报：读取每个标记问题对应的实际代码，并检查是否遗漏了上下文
• 排查遗漏问题：读取范围内的所有文件，查找所有专业人员和负责人都遗漏的问题
• 质疑严重程度：“这真的严重吗，还是只是重要？生产环境中的用户会注意到吗？”
• 检查 RxJS 误报：确认有效的 RxJS 模式不会被标记为信号反模式
• 检查 Angular 版本假设：确认建议符合 Angular 21+
• 对照项目配置检查：确认没有任何发现与项目在 {project_profile} 中记录的规范相矛盾

输出：一张更正表，列出对负责人发现的问题的升级、降级、移除和新增项。

</agent_model>

<state_variables>

变量	类型	描述
{task_description}	string	要分析的范围
{task_id}	string	kebab-case 标识符
{auto_mode}	boolean	跳过确认
{economy_mode}	boolean	不使用子 Agent
{save_mode}	boolean	保存报告
{depth}	quick / standard / deep	分析深度
{force_*}	boolean	各领域的强制标志
{scoped_files}	string[]	范围内的文件
{issues}	array	汇总的问题列表
{workspace_path}	string	angular.json 的路径
{agent_count}	number	要启动的专业人员数量
{adversarial_mode}	boolean	在团队负责人之后运行对抗性审查
{ultra_mode}	boolean	完整的 22 Agent 多层架构
{project_profile}	object	检测到的项目规范、库和架构决策——用于过滤误报

</state_variables>

<reference_files>

文件	加载时机
references/angular-anti-patterns.md	始终加载（扫描清单）
references/angular-clean-code.md	始终加载（正确模式）
references/angular-style-guide.md	始终加载（Angular 官方规范）
references/angular-architecture.md	存在架构问题或使用 --arch 时
references/ai-slop-detection.md	深度模式或使用 --slop 时
references/viewmodel-patterns.md	深度模式或使用 --vm 时
references/testing-patterns.md	存在测试问题或使用 --testing 时

</reference_files>

<entry_point>

加载 steps/step-01-scan.md

</entry_point>

<step_files>

步骤	文件	用途
01	step-01-scan.md	解析范围、启动专业人员、由团队负责人汇总
02	step-02-apply.md	加载文档、应用修复、由团队负责人检查一致性
03	step-03-verify.md	质量门禁、工匠审查、提交

</step_files> <execution_rules>

• 扫描前先了解项目上下文——读取 CLAUDE.md、package.json、angular.json 和 eslint 配置，构建 {project_profile}
• 使用 {project_profile} 过滤所有发现——绝不标记符合已记录项目惯例的模式
• 一次加载一个步骤
• 根据范围大小调整 Agent 数量（经济模式 = 0 个 Agent，仅使用直接工具）
• 使用 Grep 工具检测模式（不要使用 bash grep）
• 按范围操作：只修改指定范围内的文件
• 每项发现都必须附上 file:line 引用
• 每项修复都必须附上来源引用
• 团队负责人在扫描后和应用修复后都要进行审查 </execution_rules>

<success_criteria> 完成此工作流后，指定范围内的代码应读起来像是由资深 Angular 开发者亲手编写的：

• 零架构违规
• 全面采用现代 signal 模式
• Store 遵循包含 6 个部分的结构，并配有恰当的 ViewModel 选择器
• 不含 AI 腔调——没有不必要的注释、抽象或防御性代码
• ViewModel 分层清晰——Store 负责转换，组件负责绑定，模板保持简洁
• 范围内所有文件的模式保持一致
• 质量检查通过（lint + 类型检查 + 格式检查）
• 测试通过
• 若使用 --adv：对抗式审查未发现遗漏问题或误报 </success_criteria>