workflow-clean-code-angular

対象範囲の Angular コードが、シニアデベロッパーが手作業で作り上げたコードの水準を満たすようにします。クリーンで明快であり、AI 生成コード特有の粗雑さがなく、適切なアーキテクチャ、正しいシグナルパターン、明確な ViewModel の分離を備えています。 これはリンターではありません。リンターは構文を検出します。このスキルが検出するのは**設計上の判断**です。シニアエンジニアだけがコードレビューで気づくような問題を見つけます。

シニアが作り上げたコードと AI 生成コードを分ける3つのポイント：

1. 不要なものがない — 起こり得ない状況に対する防御的なチェック、利用箇所が1つしかない抽象化、コードの内容を言い換えるだけのコメントがない
2. 適切な責務を適切な場所に置く — ストアはデータ変換を担い、コンポーネントは UI を調整し、テンプレートはバインドだけを行う
3. パターンに一貫性がある — すべてのストアが同じ構造に従い、すべてのコンポーネントが同じ構成に従い、予想外の規約がない

<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	エコノミーモード — サブエージェントを使用せず、直接分析のみを行います
-s	保存 — レポートを .claude/output/clean-code-angular/ に出力します
-r	再開 — 前回の実行から続行します
--quick	表層スキャンのみ（grep パターンを使用し、意味解析は行いません）
--deep	全領域を対象にした詳細分析：AI 生成コード特有の粗雑さ + ViewModel + ファイル間分析を含みます
--arch	アーキテクチャ分析を強制します
--signals	シグナルパターン分析を強制します
--styling	スタイリング分析を強制します
--testing	テスト分析を強制します
--slop	AI 生成コード特有の粗雑さの検出を強制します
--vm	ViewModel/DataModel 分析を強制します
--adv	敵対的レビュー — チームリードのレビュー後、悪魔の代弁者となるエージェントがすべての指摘を検証し、誤検出、見落とし、重大度の過大評価がないかを確認します
--ultra	最大深度：5つのクラスターに15の専門エージェントを配置し、各クラスターにリードを置きます。さらに総括テックリードと敵対的レビューも加わります。重要なコードに対する究極の選択肢です。

デフォルトの深度（フラグなし）：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>

エージェントのアーキテクチャ

このスキルは、フラグに応じてエージェント数を調整します。

モード	エージェント数	構成
エコノミー（-e）	0	直接ツールのみ。サブエージェントなし
標準	リードに加えて3～10	フラット：専門エージェント → チームリード
詳細（--deep）	リードに加えて14	単独エージェント8 + シグナル分析担当3 + AI 生成コードの粗雑さ分析担当3 → 合意形成 → チームリード
詳細 + 敵対的レビュー（--deep --adv）	リードに加えて14 + 敵対的レビュー担当	詳細分析 + 敵対的レビュー
ウルトラ（--ultra）	15 + リード5 + 総括リード + 敵対的レビュー担当 = 22	5つのクラスター → 5人のクラスターリード → 総括テックリード → 敵対的レビュー

標準／詳細モード — フラット構成

最大10の領域特化型専門エージェントを並行して起動します。エージェント数は対象範囲の規模に応じて増減します。

対象範囲	エージェント数	対象領域
1～4ファイル	リードに加えて3	アーキテクチャ、Angular／シグナル、TypeScript／スタイリング
5～15ファイル	リードに加えて5	+ ストアパターン、コンポーネント設計
16～30ファイル	リードに加えて7	+ テンプレート、AI 生成コード特有の粗雑さ
31ファイル以上	リードに加えて10	10領域すべて

### 10 のドメイン

#	ドメイン	焦点
1	アーキテクチャと依存関係	レイヤー違反、機能間のインポート、依存関係の方向
2	シグナルとリアクティビティ	effect() の誤用、computed() の活用機会、linkedSignal()、クリーンアップ
3	ストアのパターン	6 セクションの構成、キャッシュ優先、楽観的更新、リソースの使用
4	コンポーネント設計	OnPush、責務、サイズ、input()/output()、inject()
5	テンプレートの品質	制御フロー、式の複雑さ、ラッパーの肥大化、アクセシビリティ
6	TypeScript の品質	any 型、# フィールド、最新の API、未使用コード
7	スタイリング	::ng-deep、Material M3 トークン、Tailwind v4、!important
8	AI スロップ	過剰な設計、不要なコメント、防御的な見せかけ、冗長な命名
9	ViewModel とデータフロー	DataModel と ViewModel、変換の配置、重複した導出
10	セキュリティ、パフォーマンス、コードの健全性	XSS、回避策／ハック、設計上の問題、@defer、遅延読み込み

--testing、--deep、または --ultra が有効な場合、テストの品質も確認します。テスト専門エージェントは対象範囲の .spec.ts ファイルを読み込み、references/testing-patterns.md に照らして評価します。

Ultra モード — 多層クラスターアーキテクチャ

専任のクラスターリードが付く 5 つのクラスターに、15 の専門エージェントを編成します。各専門エージェントは、必要な参照ファイルだけを正確に読み込み、余計な情報を読み込みません。

クラスター 1：アーキテクチャ → アーキテクチャリード

エージェント	焦点	読み込むファイル
1a	レイヤー違反、機能間のインポート	references/angular-architecture.md
1b	DI パターン、関数型インターセプター、プロバイダー	references/angular-clean-code.md §3
1c	遅延読み込み、ルーティング、@defer の境界	references/angular-anti-patterns.md §19-20

クラスター 2：シグナルと状態 → リアクティビティリード

エージェント	焦点	読み込むファイル
2a	シグナルのパターン、computed、effect、afterRenderEffect	references/angular-clean-code.md §2
2b	ストアの構成、ミューテーション、リソース API	references/angular-clean-code.md §2 + §13
2c	RxJS の適切な使い方とアンチパターン、Observable と Signal のブリッジ	references/angular-anti-patterns.md §2 + Valid RxJS table

クラスター 3：コード品質 → 品質リード

エージェント	焦点	読み込むファイル
3a	TypeScript、型、最新の API（toSorted、structuredClone）	references/angular-anti-patterns.md §6
3b	AI スロップの検出（9 カテゴリーすべて）	references/ai-slop-detection.md
3c	エラー処理、catch の型指定、リソースのエラー状態	references/angular-clean-code.md §13

クラスター 4：UI とテンプレート → フロントエンドリード

エージェント	焦点	読み込むファイル
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：テストとセキュリティ → セキュリティリード

エージェント	焦点	読み込むファイル
5a	テストの品質、ハーネス、カバレッジ	references/testing-patterns.md
5b	セキュリティ、回避策、ゾーンレスの違反	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 アーキテクトが次の作業を行います。

• すべての専門エージェントのレポートを、重複を排除した 1 つのリストに統合します
• 実際のコードを読み、誤検知を取り除きます
• 専門エージェント間の矛盾を解決します
• どの専門エージェントも気づかなかった横断的な所見を追加します
• 最終的な問題リストに優先順位を付けます
• step-02 で修正の整合性を確認します
• step-03 で職人の視点から最終レビューを行います

クラスターリード（Ultra）

各クラスターリードが受け取るのは、3人のスペシャリストの報告のみです。以下を行います。

• 担当領域内の重複を排除します
• スペシャリスト間の矛盾を解決します
• 担当領域に固有の、複数の領域にまたがる所見を追加します
• 担当領域に焦点を絞ったレポートを出力します（クラスターあたり最大10件の問題）

グランドテックリード（Ultra）

5人のクラスターリードのレポートをすべて受け取ります。以下の役割を担う、Angular のプリンシパルアーキテクトです。

• すべてのクラスターのレポートを、1つの統合されたリストにまとめます
• クラスター間の矛盾を解決します（例：「コアに移す」とするアーキテクチャと、「インライン化する」とする品質の見解）
• クラスター間に共通するシステム的なパターンを特定します（例：「すべてのファイルで DI の問題が同じ」）
• 技術的な深刻度だけでなく、ビジネスへの影響に基づいて優先順位を付けます
• 問題を最大30件に制限し、それを超える場合は総数を記載します
• 「システム全体の診断」セクションを追加します。問題のパターンの根本原因は何でしょうか？

敵対的レビュアー（--adv または --ultra）

チームリード／グランドリードの後に起動します。懐疑的なシニアエンジニアとして、以下を行います。

• 各所見に異議を唱えます：「これは本当に誤りでしょうか？妥当なアーキテクチャ上の理由があるのではないでしょうか？」
• 誤検出を探します：指摘された問題ごとに実際のコードを読み、見落とされたコンテキストがないか確認します
• 見落とされた問題を探します：対象範囲内のすべてのファイルを読み、すべてのスペシャリストとリードが見落とした問題を探します
• 深刻度を問い直します：「これは本当に重大でしょうか、それとも重要なだけでしょうか？本番環境のユーザーが気づくでしょうか？」
• RxJS の誤検出を確認します：有効な RxJS パターンがシグナルのアンチパターンとして指摘されていないか確認します
• Angular のバージョンに関する前提を確認します：推奨事項が Angular 21 以降に合っているか確認します
• プロジェクトプロファイルとの整合性を確認します：所見が {project_profile} に記載されたプロジェクトの規約に反していないか確認します

出力：リードの所見に対する格上げ、格下げ、削除、追加をまとめた修正表。

</agent_model>

<state_variables>

変数	型	説明
{task_description}	string	分析対象の範囲
{task_id}	string	ケバブケースの識別子
{auto_mode}	boolean	確認を省略します
{economy_mode}	boolean	サブエージェントを使用しません
{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エージェントによる多層アーキテクチャ全体を使用します
{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	Deep モード、--slop
references/viewmodel-patterns.md	Deep モード、--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} に照らして判断します — 文書化されたプロジェクトの規約に沿うパターンを指摘してはいけません
• 一度に 1 ステップずつ読み込みます
• スコープの規模に応じてエージェント数を調整します（エコノミーモード = エージェント 0、直接ツールのみ）
• パターン検出には Grep ツールを使用します（bash grep は使用しません）
• スコープを意識します：指定されたスコープ内のファイルのみを変更します
• すべての指摘に file:line の参照が必要です
• すべての修正に出典の引用が必要です
• チームリードはスキャン後と適用後にレビューします </execution_rules>

<success_criteria> このワークフローの完了後、スコープ内のコードはシニア Angular 開発者が手作業で書いたかのような状態になります：

• アーキテクチャ違反がゼロ
• 全体を通して最新のシグナルパターンを採用
• ストアは適切な ViewModel セレクターを備えた 6 セクション構成に従う
• AI らしい粗雑さがない — 不要なコメント、抽象化、防御的なコードがない
• 明確に分離された ViewModel — ストアは変換を担い、コンポーネントはバインドし、テンプレートはシンプルなまま
• スコープ内のすべてのファイルでパターンが一貫
• 品質チェックに合格（lint + type-check + format）
• テストに合格
• --adv の場合：敵対的レビューで見落としや誤検出が見つからない </success_criteria>