complexity-assessment

複雑さ評価スキル

概要

タスクの説明を分析し、適切なワークフローと検証の深さを選べるよう、実際の複雑さを判断します。速度より正確さを優先してください。複雑さの判断を誤ると、ワークフローも誤り、実装に失敗します。

基本原則： 速度より正確さを優先します。複雑さの判断を誤る ＝ ワークフローの選択を誤る ＝ 実装の失敗です。

使用するタイミング

必ず実施する場合：

• 新しいタスクの計画を立てる前
• 要件は整理できているものの、進め方が明確でない場合
• QA の検証の深さを判断する場合

例外：

• 明らかに単純な修正（誤字、色の変更など）
• 複雑さが明示されているタスク

絶対に守る原則

1. 複雑さを評価せずに計画を始めてはいけません — 複雑さの分類を誤ると、ワークフローも誤り、実装に失敗します。必ず先に評価し、その後で適切なワークフローのフェーズと検証の深さを選んでください。
2. 不確かな場合は必ず慎重に判断し、より高い複雑さに分類してください — 複雑さを過小評価することは、過大評価するより危険です。複雑なタスクを標準と誤分類すると、セキュリティレビュー、アーキテクチャ設計、包括的なテストが省かれてしまいます。
3. 複雑さを分類する前に、影響を受けるファイル数を必ず数えてください — 直感に頼った見積もりは信頼できません。分類する前にコードベースを調べ、変更によって実際に影響を受けるファイル数を数えてください。
4. 不慣れな技術は必ず調査対象として明示してください — 不明な技術には、表面化していない複雑さが潜んでいます。複雑さを見積もる前に、馴染みのないフレームワーク、ライブラリ、サービスをすべて調査が必要なものとして記録してください。
5. ユーザーの気軽な表現を理由に、複雑さの分類を下げてはいけません — 「ちょっとした修正」や「小さな変更」といった表現は、ユーザーの認識を示すものであり、実際の技術的な範囲を示すものではありません。説明のされ方にかかわらず、客観的に評価してください。

ワークフローの種類

依頼された作業の種類を判断してください。

FEATURE

• コードベースに新しい機能を追加する
• 既存の機能に新しい機能を加える
• 新しい UI コンポーネント、API エンドポイント、サービスを構築する
• 例：「スクリーンショットの貼り付けを追加する」、「ユーザーダッシュボードを構築する」、「新しい API エンドポイントを作成する」

REFACTOR

• 既存の機能を新しい実装に置き換える
• あるシステムやパターンから別のものへ移行する
• 動作を維持しながらコード構成を再編成する
• 例：「認証をセッションから JWT に移行する」、「キャッシュ層をリファクタリングする」

INVESTIGATION

• 原因が分からない問題をデバッグする
• バグの根本原因を分析する
• パフォーマンスを調査する
• 例：「ページの読み込みが遅い原因を調べる」、「断続的に発生するクラッシュをデバッグする」

MIGRATION

• システム間でデータを移行する
• データ変換を伴うデータベーススキーマの変更
• インポート／エクスポート操作
• 例：「ユーザーデータを新しいスキーマに移行する」、「レガシーレコードをインポートする」

SIMPLE

• 非常に小さく、範囲が明確な変更
• 1 つのファイルに対する変更
• アーキテクチャ上の判断が不要
• 例：「誤字を修正する」、「ボタンの色を変更する」、「エラーメッセージを変更する」

複雑さの段階

SIMPLE

• 変更するファイルが 1～2 個
• 単一のサービス／領域
• 外部連携なし
• インフラの変更なし
• 新しい依存関係なし
• 例：誤字の修正、色の変更、テキストの更新、単純なバグ修正

STANDARD

• 変更するファイルが 3～10 個
• 1～2 個のサービス／領域
• 外部連携が 0～1 件（十分に文書化され、簡単に利用できるもの）
• インフラの変更は最小限（環境変数の追加など）
• 調査が必要な場合もありますが、基本となるパターンは確立されています
• 例：新しい API エンドポイントの追加、新しいコンポーネントの作成

COMPLEX

• 10 個以上のファイル、または複数領域にまたがる変更
• 複数のサービス／領域
• 外部連携が 2 件以上
• インフラの変更（Docker、データベース、キュー）
• 新しいアーキテクチャパターン
• 調査が必要な、新規に一から構築する機能
• 例：新しい連携（Stripe、Auth0）、データベースの移行、新しいサービス

ワークフロー

フェーズ 1：要件の読み込み

要件ドキュメントを読みます。

# Read the requirements file
cat .claude/context/requirements/[task-name].md

以下を抽出します。

• task_description：何を構築する必要があるか
• workflow_type：作業の種類（機能追加、リファクタリングなど）
• scope：影響を受ける領域
• requirements：具体的な要件
• acceptance_criteria：成功の判断基準
• constraints：制約

フェーズ 2：タスクの分析

タスクの説明を注意深く読みます。以下を確認します。

複雑さを示す要素（複雑度が高いことを示唆）：

• 「integrate」「integration」— 外部依存関係
• 「optional」「configurable」「toggle」— 機能フラグ、条件分岐
• 「docker」「compose」「container」— インフラストラクチャ
• データベース名（postgres、redis、mongo）— インフラストラクチャと設定
• API／SDK 名（stripe、auth0、openai）— 外部調査が必要
• 「migrate」「migration」— データ／スキーマの変更
• 「across」「all services」「everywhere」— 複数領域にまたがる変更
• 「new service」— 対象範囲が大きい
• 「.env」「environment」「config」— 設定が複雑

単純さを示す要素（複雑度が低いことを示唆）：

• 「fix」「typo」「update」「change」— 修正
• 「single file」「one component」— 対象範囲が限定的
• 「style」「color」「text」「label」— UI の微調整
• 具体的なファイルパスの指定 — 対象範囲が明確

フェーズ 3：各側面の評価

対象範囲の分析

• 変更が必要となるファイル数はどのくらいですか？
• 関係する領域はいくつありますか？
• 変更は局所的ですか、それとも複数領域にまたがりますか？

統合の分析

• 外部サービス／API が関係しますか？
• 新しい依存関係を追加する必要がありますか？
• これらの依存関係について調査が必要ですか？

インフラストラクチャの分析

• Docker／コンテナーの変更が必要ですか？
• データベーススキーマの変更が必要ですか？
• 新しい環境設定が必要ですか？

知識の分析

• コードベースにすでに確立されたパターンがありますか？
• 外部ドキュメントの調査が必要ですか？
• 不慣れな技術が関係しますか？

リスクの分析

• どのような問題が起こる可能性がありますか？
• セキュリティ上の考慮事項はありますか？
• 既存の機能に不具合が生じる可能性はありますか？

フェーズ 4：必要なフェーズの決定

分析に基づいて、必要なフェーズを決定します。

単純なタスクの場合：

discovery → quick_spec → validation

（3 フェーズ、調査なし、最小限の計画）

標準的なタスクの場合：

discovery → requirements → context → spec_writing → planning → validation

（6 フェーズ、コンテキストに基づく仕様書の作成）

外部依存関係を含む標準的なタスクの場合：

discovery → requirements → research → context → spec_writing → planning → validation

（7 フェーズ、不慣れな依存関係の調査を含む）

複雑なタスクの場合：

discovery → requirements → research → context → spec_writing → self_critique → planning → validation

（8 フェーズ、調査と自己批評を含む完全なパイプライン）

フェーズ 5：検証の深さの決定

複雑さとリスクの分析に基づいて、推奨する検証の深さを決定します。

リスクレベル	使用する状況	検証の深さ
TRIVIAL	ドキュメントのみ、コメント、空白	検証を完全に省略
LOW	単一領域、5 ファイル未満、DB／API の変更なし	単体テストのみ
MEDIUM	複数ファイル、1～2 領域、API の変更	単体テスト＋統合テスト
HIGH	データベースの変更、認証／セキュリティ、サービス間	単体テスト＋統合テスト＋E2E＋セキュリティ
CRITICAL	決済、データ削除、セキュリティ上重要な変更	上記すべて＋手動レビュー＋ステージング

検証を省略する基準（TRIVIAL）： 以下のすべてに該当する場合にのみ設定します。

• ドキュメントのみの変更（*.md、コメント、docstring）
• または、純粋に見た目だけの変更（空白、書式、lint の修正）
• 機能コードを変更していない
• 確信度 >= 0.9

以下のいずれかに該当する場合、セキュリティスキャンが必要です。

• 認証／認可コードに変更を加える
• ユーザーデータの取り扱いを変更する
• 決済／金融関連のコードが関係する
• API キー、シークレット、認証情報を取り扱う
• ネットワークアクセスを伴う新しい依存関係を追加する
• ファイルのアップロード／ダウンロード機能が関係する

フェーズ 6：評価結果の出力

以下の構造化された評価を作成します。

# Complexity Assessment: [Task Name]

## Summary

| Dimension     | Assessment                                        |
| ------------- | ------------------------------------------------- |
| Complexity    | [simple/standard/complex]                         |
| Workflow Type | [feature/refactor/investigation/migration/simple] |
| Confidence    | [0.0-1.0]                                         |

## Reasoning

[2-3 sentence explanation]

## Analysis

### Scope

- Estimated files: [number]
- Estimated areas: [number]
- Cross-cutting: [yes/no]
- Notes: [brief explanation]

### Integrations

- External services: [list]
- New dependencies: [list]
- Research needed: [yes/no]
- Notes: [brief explanation]

### Infrastructure

- Docker changes: [yes/no]
- Database changes: [yes/no]
- Config changes: [yes/no]
- Notes: [brief explanation]

### Knowledge

- Patterns exist: [yes/no]
- Research required: [yes/no]
- Unfamiliar tech: [list]
- Notes: [brief explanation]

### Risk

- Level: [low/medium/high]
- Concerns: [list]
- Notes: [brief explanation]

## Recommended Phases

1. [phase1]
2. [phase2]
3. ...

## Validation Recommendations

| Setting          | Value                              |
| ---------------- | ---------------------------------- |
| Risk Level       | [trivial/low/medium/high/critical] |
| Skip Validation  | [yes/no]                           |
| Minimal Mode     | [yes/no]                           |
| Test Types       | [unit, integration, e2e]           |
| Security Scan    | [yes/no]                           |
| Staging Required | [yes/no]                           |

**Reasoning**: [1-2 sentences explaining validation depth]

## Flags

- Needs research: [yes/no]
- Needs self-critique: [yes/no]
- Needs infrastructure setup: [yes/no]

判断フローチャート

START
  |
  +--> Are there 2+ external integrations OR unfamiliar technologies?
  |     YES -> COMPLEX (needs research + critique)
  |     NO
  |      |
  +--> Are there infrastructure changes (Docker, DB, new services)?
  |     YES -> COMPLEX (needs research + critique)
  |     NO
  |      |
  +--> Is there 1 external integration that needs research?
  |     YES -> STANDARD + research phase
  |     NO
  |      |
  +--> Will this touch 3+ files across 1-2 areas?
  |     YES -> STANDARD
  |     NO
  |      |
  +--> SIMPLE (1-2 files, single area, no integrations)

検証チェックリスト

評価を完了する前に：

• 要件ドキュメントを最後まで読む
• 複雑さを示す指標をすべて特定する
• 単純さを示す指標をすべて特定する
• スコープを分析する（ファイル、領域、横断的な影響）
• 統合を分析する（外部サービス、依存関係）
• インフラストラクチャの要件を評価する
• 不足している知識を特定する
• リスクレベルを判断する
• フェーズを決定する
• 推奨する検証の深さを示す

よくある間違い

統合を過小評価する

なぜ問題なのか： 1つの統合でも、多数のファイルに影響することがあります。

代わりに行うこと： 不慣れなテクノロジーについては、調査が必要な項目として挙げます。

インフラストラクチャを無視する

なぜ問題なのか： Docker／DB の変更は複雑さを大きく増します。

代わりに行うこと： インフラストラクチャの要件を早い段階で確認します。

過度に自信を持つ

なぜ問題なのか： 信頼度が 0.9 を超えることは、ほとんどありません。

代わりに行うこと： 慎重に評価します。迷った場合は、より高い複雑さを選びます。

他のスキルとの連携

このスキルは、次のスキルと相性よく連携します。

• spec-gathering：評価に必要な要件を提供します
• spec-writing：評価を使って仕様の詳細度を決定します
• qa-workflow：検証に関する推奨事項を活用します

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
ファイルを調査せずに SIMPLE と判定する	実際に影響を受けるファイル数を過小評価します	階層を割り当てる前に、影響を受けるファイル数を数えます
「簡単な修正」という表現で階層を下げる	ユーザーの認識 ≠ 技術的なスコープです	客観的に評価し、ユーザーの気軽な表現は考慮しません
統合と外部 API を無視する	外部依存関係はリスクと複雑さを増します	評価にすべての外部サービス／API を列挙します
不明なテクノロジーの調査フラグを省略する	不慣れなテクノロジーには見えない複雑さがあります	不慣れなテクノロジーはすべて調査対象として挙げます
ロールバックの複雑さを考慮しない	COMPLEX／EPIC では復旧計画が必要です	複雑さの評価にロールバックの難易度を含めます

メモリープロトコル

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 発見した問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断されることを前提にしてください。メモリーに記録されていなければ、実行されていないものとします。