architect

Architect

コードベースが構造レベルで適切に整理されているかを評価します。値の発見、広範な調査、詳細分析、評価、そして必要に応じた計画と実行という段階的な分析を行います。

これはコードレビュー（正確性）、コードの簡素化（クリーンアップ）、または/ship（PR 前のパイプライン）の一部ではありません。これらのスキルでは、コードの品質や変更を確認します。 /architectでは、コードベースの構成、つまりモジュール性、結合度、構成、フレームワークとの整合性、構造的な一貫性を確認します。

呼び出し方法

コマンド	動作
/architect	全工程を実行：必要に応じて価値観の確認 > 調査 > 詳細分析 > 評価
/architect --teach	価値観の発見を再実行
/architect --sweep	広範な調査のみを実行し、詳細分析は省略
/architect <target>	サブシステム（例：「ディスパッチシステム」、app/models）に焦点を当てます。必要に応じて価値観の確認を行い、その後、対象領域のみを調査して詳細分析します。メインの評価成果物を更新します。

フェーズ

1. 価値観の確認 — 価値観の発見（プロジェクトごとの初回実行時）。対話形式で行います。
2. 調査 — 7 つのアーキテクチャの観点から、全体をすばやくスキャンします。
3. 詳細分析 — 調査で問題が指摘された観点を並行して分析します。
4. 評価 — 調査結果を提示し、ユーザーと話し合って成果物を生成します。
5. 計画 — 段階的な実装戦略を策定します（必要に応じて実施）。
6. 実行 — 構造変更のための実装計画を呼び出します（必要に応じて実施）。

引数の解析

フラグと対象を $ARGUMENTS から解析します。

• --teach — 設定が存在する場合でも、価値観の発見を強制的に再実行します
• --sweep — 広範な調査のみを実行し、詳細分析は省略します
• それ以外はすべて <target> として扱います — 焦点を当てるサブシステム（パスまたは説明）

複数のフラグを組み合わせることができます。--teach と対象を指定すると、価値観を再確認してから、そのサブシステムに対象を絞ります。

プロジェクトの検出

ARCHITECT="$HOME/.claude/skills/architect/scripts/architect.sh"
PROJECT_INFO=$("$ARCHITECT" detect)
SLUG=$(echo "$PROJECT_INFO" | jq -r '.slug')
ROOT=$(echo "$PROJECT_INFO" | jq -r '.root')
CONFIGURED=$(echo "$PROJECT_INFO" | jq -r '.configured')

SLUG が空の場合は、次のメッセージを表示して停止します："Not in a git repository. /architect needs a git repo to work with."

フェーズ 1：価値観の確認 — 価値観の発見

このフェーズは対話形式で行います。一度に 1 つの質問をします。次に進む前に回答を待ってください。質問を一度にすべて提示しないでください。

スキップ条件： CONFIGURED が true で、--teach が渡されていない場合、このフェーズをスキップします。代わりに既存の設定を読み込みます。

CONFIG=$("$ARCHITECT" config "$SLUG")

その後、フェーズ 2（調査）に進みます。

--teach が渡された場合： 設定が存在していても、このフェーズを実行します。新しい設定で古い設定を上書きします（--force を使用）。

ステップ 1：フレームワークの自動検出

プロジェクトのルートで、フレームワークを示すファイルをスキャンします。

• Gemfile に rails が含まれる — Ruby on Rails
• package.json に nuxt が含まれる — Nuxt.js
• package.json に vue が含まれる — Vue.js
• package.json に next または react が含まれる — Next.js / React
• go.mod — Go
• pyproject.toml または requirements.txt に django が含まれる — Django
• pyproject.toml または requirements.txt に flask または fastapi が含まれる — Flask / FastAPI
• Cargo.toml — Rust
• mix.exs に phoenix が含まれる — Phoenix (Elixir)

検出結果を提示します：「このプロジェクトは [framework] として検出されました。これで合っていますか？それとも、スタックについて補足がありますか？」

続行する前に確認を待ちます。ユーザーが訂正した場合は、その回答を使用します。

ステップ 2：アーキテクチャの考え方を確認する

検出したフレームワークに基づいて、3〜4種類の考え方を提示します。これらは、スキルがアーキテクチャをどう評価するかの枠組みです。「正解」は一つではなく、何を指摘事項とし、何を設計上の選択とするかは、ユーザーの好みによって変わります。

Ruby on Rails の場合：

アーキテクチャに対する考え方を教えてください。Rails で一般的な考え方を挙げます。どれがしっくりきますか？ または、複数を組み合わせていますか？

1. Rails Way（DHH） — 設定より規約。共通の振る舞いには Concern を使います。ファットモデルでも問題ありません。壮大なモノリスを目指します。フレームワークそのものがアーキテクチャです。
2. Sandi Metz の OOP — 小さなオブジェクトと単一責任。継承よりコンポジション。依存性注入。クラスは 100 行未満、メソッドは 5 行未満（目標であり、絶対的なルールではありません）。
3. ヘキサゴナル／クリーンアーキテクチャ — ポートとアダプター。ドメインロジックをフレームワークから独立させます。依存関係逆転。Rails は周辺に置き、中核には純粋な Ruby を使います。
4. 実用的な組み合わせ — それぞれから役立つものを取り入れます。特定の考え方に固執しません。コードベースは思想ではなく、チームのためにあります。

Vue／Nuxt の場合：

1. コンポジション優先 — あらゆるものにコンポーザブルを使います。コンポーネントは薄く保ちます。ロジックはコンポーザブルに置き、コンポーネントはテンプレートと接続だけを担います。
2. コンポーネント中心 — コンポーネントがロジックを持ちます。Props は下へ、イベントは上へ流します。ローカル状態を優先します。コンポーザブルは、本当に共有が必要な振る舞いにのみ使います。
3. ストア主導 — Pinia ストアを信頼できる唯一の情報源とします。コンポーネントはストアの状態を描画します。ビジネスロジックはストアとアクションに置きます。
4. 実用的な組み合わせ — 機能に合った方法を使います。特定のパターンに固執しません。

Go の場合：

1. 標準ライブラリ至上主義 — 依存関係は最小限にします。フレームワークより net/http を使います。パッケージ構成はフラットにします。インターフェースは事前に設計せず、必要になったときに見つけます。
2. ドメイン駆動設計 — レイヤーではなくドメインごとにパッケージを分けます。分離には Internal パッケージを使います。依存性注入を明示します。
3. ヘキサゴナル／クリーンアーキテクチャ — ポートとアダプター。フレームワークは周辺に置きます。ドメインの中核には外部依存を持たせません。
4. 実用的な組み合わせ — 役立つものを使います。取り入れたパターンではなく、Go の慣用的な書き方に従います。

その他のフレームワークでは、それに相当する選択肢を提示します。たとえば、フレームワークの慣用的なスタイル、OOP／コンポジション重視、クリーンアーキテクチャ、実用的なスタイルです。同じような対話的な口調を使います。

ユーザーの回答を待ちます。選択内容を保存します。

ステップ 3：重視する価値観を確認する

選ばれた考え方に基づいて、具体的な好みを尋ねる質問を 3〜5 個します。これらの質問で、スキルが構造上の問題をどの程度積極的に指摘するかを調整します。質問は一度に一つずつ行います。

フレームワークと選ばれた考え方に関連するものを、次の中から選びます。

• 結合への許容度：「フレームワークへの結合について、どう考えていますか？ ドメインロジックから ActiveRecord／Pinia などを直接使っても問題ありませんか？ それとも、分離レイヤーを設けたいですか？」

• ファイルサイズの許容範囲：「ファイルサイズはどの程度が許容範囲ですか？ 200〜300 行のクラスやコンポーネントでも問題ありませんか？ それとも、もっと小さく分割したいですか？」

• 抽象化への考え方：「サービスオブジェクト、フォームオブジェクト、インタラクター、コンポーザブルなどの抽象化について、どう考えていますか？ 積極的に使いますか？ それとも、問題が明らかになった場合にのみ使いますか？」

• テストの構成：「テストの整理について、どう考えていますか？ ソースツリーと同じ構成にしますか？ 種類（ユニット／統合）ごとに分けますか？ 振る舞いと実装のどちらをテストしますか？」

• 命名規則：「命名について、強いこだわりはありますか？ サービス、ジョブ、コンポーネントなどに特定の規則を使っていますか？」

質問はフレームワークに合わせて調整してください。Go プロジェクトで ActiveRecord との結合について尋ねてはいけません。回答が明確であれば、質問は 3 つでも構いません。上限は 5 つです。

ステップ 4：アーティファクトの保存場所を尋ねる

評価によって、プロジェクトリポジトリに保存する Markdown アーティファクトが作成されます。保存先を尋ねます。

「このリポジトリのどこにアーキテクチャ評価を保存しますか？一般的な規約では project/architecture-assessment.md ですが、こちらでよろしいですか？それとも別の希望がありますか？」

プロジェクトのルートからの相対パスで保存します。

ステップ 5：スラッグの重複に対処する

保存する前に、検出したスラッグが、異なる project_root を指す設定ですでに使われていないか確認します。

EXISTING_CONFIG=$("$ARCHITECT" config "$SLUG" 2>/dev/null || echo "")

EXISTING_CONFIG が空でない場合は、その project_root を抽出します。

EXISTING_ROOT=$(echo "$EXISTING_CONFIG" | jq -r '.project_root')

EXISTING_ROOT が ROOT と異なる場合は重複です。異なる 2 つのリポジトリが、たまたま同じディレクトリ名を持っています。次のように尋ねます。

「スラッグ [slug] の設定は、すでに [existing_root] を指しています。このプロジェクトの場所は [root] です。このプロジェクトにはどのスラッグを使いますか？」

以降は、ユーザーの回答をスラッグとして使用します。

ステップ 6：設定を保存する

収集した値で JSON 設定オブジェクトを作成し、保存します。

"$ARCHITECT" init "$SLUG" '{
  "project_root": "<ROOT>",
  "project_name": "<project name from user or basename of ROOT>",
  "framework": "<detected framework>",
  "philosophy": "<chosen philosophy>",
  "values": {
    "coupling_tolerance": "<answer>",
    "file_size_comfort": "<answer>",
    "abstraction_appetite": "<answer>",
    "test_architecture": "<answer>",
    "naming_conventions": "<answer>"
  },
  "artifact_path": "<chosen path>",
  "created_at": "<ISO timestamp>"
}' --force

実際に尋ねて回答を得た値のみを含めます。--force フラグにより、--teach を再実行した際に設定が確実に上書きされます。

ユーザーに「承知しました。[slug] の設定を保存しました。スイープフェーズに進みます。」と伝えます。

teach が完了したことを記録するよう、状態を更新します。

"$ARCHITECT" update-state "$SLUG" "teach_complete=true" "teach_date=$(date -u +%Y-%m-%dT%H:%M:%SZ)"

---

フェーズ 2：スイープ — 広範なアーキテクチャスキャン

7 つのアーキテクチャの観点から、迅速かつ広範囲にスキャンします。コストと速度を考慮して Sonnet サブエージェントを 1 つだけ使用します。これはトリアージであり、詳細な分析ではありません。

ステップ 1：設定を読み込む

CONFIG=$("$ARCHITECT" config "$SLUG")

サブエージェントのプロンプトに必要な主要フィールドを抽出します。

FRAMEWORK=$(echo "$CONFIG" | jq -r '.framework')
PHILOSOPHY=$(echo "$CONFIG" | jq -r '.philosophy')

ステップ 2：スコープを決定する

<target> が渡された場合、スイープの対象はそのサブシステムのみです。スコープの指示を作成します。

• 対象の指定なし： "ROOT のプロジェクト全体をスキャンしてください。"
• 対象がパスの場合（/、./ で始まる場合、または実在するディレクトリの場合）："ROOT/<target> と、コードベースの他の部分との相互作用を中心にスキャンしてください。"
• 対象が説明の場合（例：「ディスパッチシステム」）："次のように説明されているサブシステムを中心にスキャンしてください：<target>。まず関連するファイルとディレクトリを特定し、その後分析してください。"

ステップ 3：スイープエージェントを起動する

Agent ツールを使用して、サブエージェントを 1 つ起動します。

Agent(model: "sonnet", description: "Sweep: broad architectural scan of {SLUG}")

プロンプトは完全に自己完結している必要があります。サブエージェントには会話のコンテキストがありません。必要な情報をすべて含めます。

You are an architectural reviewer performing a broad sweep of a codebase.
Your job is to triage — identify areas that need deeper analysis, not to
do the deep analysis yourself.

## Project

- **Root:** {ROOT}
- **Framework:** {FRAMEWORK}
- **Philosophy:** {PHILOSOPHY}
- **Full config:** {CONFIG}

## Scope

{scope_instruction}

## Sampling Strategy

Do NOT read every file. Be strategic:

1. **Directory structure first** — run `ls` and `find` (depth-limited) to
   understand the layout
2. **Key entry points** — main config files, route definitions, application
   entry points, schema files
3. **Representative files per layer** — pick 2-3 files from each major
   directory (models, controllers, views, services, composables, etc.)
4. **Boundary files** — files that connect layers or modules (routers,
   registries, factories, dependency injection setup)
5. **Large files** — check file sizes, sample the biggest ones (often
   where coupling and cohesion issues live)

Budget: aim for ~30-50 files sampled total, more for large codebases.

## Architectural Lenses

Evaluate the codebase through each of these 7 lenses:

### 1. Structural Organization
- Directory layout and file grouping — by layer, by feature, or mixed?
- Separation of concerns — is business logic separated from framework plumbing?
- Naming conventions — consistent? Descriptive? Following framework idioms?
- Co-location — are related files near each other or scattered?

### 2. Design Patterns
- GoF patterns in use: adapter, strategy, facade, observer, factory, etc.
- Are patterns applied appropriately or forced where simpler code would do?
- Missing patterns — places where a well-known pattern would reduce complexity
- Over-patterned code — unnecessary abstraction layers, pattern-for-pattern's-sake

### 3. Composition & Inheritance
- Inheritance depth — deep hierarchies are a red flag
- Composable units — are behaviors composed via mixins/modules/composables or
  hardcoded into class hierarchies?
- Mixin/concern sprawl — too many small mixins that fragment understanding

### 4. Coupling & Cohesion
- Module dependencies — who depends on whom? Are there clear layers?
- Boundary clarity — can you change one module without touching three others?
- God objects — classes/modules that know too much or do too much
- Circular dependencies — A depends on B depends on A

### 5. Framework Alignment
- Convention adherence — is the team using the framework the way it was designed?
- Reinvented wheels — building custom solutions for things the framework provides
- Framework-specific anti-patterns (e.g., Rails: SQL in views, callbacks doing
  business logic, skip_before_action sprawl; Vue: mutating props, massive
  computed properties, v-if/v-for on same element)

### 6. API & Interface Design
- Internal API consistency — do similar operations have similar interfaces?
- Method signatures — clear parameter names? Reasonable arity? Options hashes
  vs. keyword args?
- Public surface area — is the public API minimal and intentional, or does
  everything leak?

### 7. Duplication & Reuse
- Copy-paste patterns — similar code in multiple places that should be shared
- Inconsistent approaches — the same problem solved differently in different places
- Missing shared code — utilities or patterns that should be extracted

## Output Format

Return your findings as a JSON object. Be concise in notes — this is triage,
not a full report. Include file_pointers so the deep dive knows where to look.

```json
{
  "timestamp": "<current ISO timestamp>",
  "scope": "<'full' or the target description>",
  "files_sampled": <number of files you read>,
  "lenses": {
    "structural_organization": {
      "health": "green|yellow|red",
      "notes": "Brief summary — what you found, why this rating",
      "file_pointers": ["paths/that/illustrate/the/finding"]
    },
    "design_patterns": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "composition_inheritance": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "coupling_cohesion": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "framework_alignment": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "api_interface_design": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    },
    "duplication_reuse": {
      "health": "green|yellow|red",
      "notes": "...",
      "file_pointers": ["..."]
    }
  }
}
```

**Health ratings:**
- **green** — no significant issues found, aligns with the project's stated philosophy
- **yellow** — some concerns worth investigating, potential improvements
- **red** — clear structural problems that affect maintainability or scalability

Be honest. Green is fine — not every lens will have issues. Don't manufacture
findings. But don't be afraid of red when it's warranted.

Return ONLY the JSON object, no surrounding text.

ステップ 4：スイープ結果を処理する

サブエージェントが返した JSON を解析します。応答が有効な JSON でない場合は、応答から JSON を抽出して（{ から } までのブロックを探して）解析します。

ステップ 5：スイープを記録する

"$ARCHITECT" sweep-log "$SLUG" '<sweep_json>'

ステップ 6：状態を更新する

"$ARCHITECT" update-state "$SLUG" "last_sweep=$(date -u +%Y-%m-%dT%H:%M:%SZ)"

ステップ 7：停止条件を確認する

--sweep が渡された場合は、スイープ結果を読みやすい形式でユーザーに提示し、停止します。

## Architectural Sweep — {project_name}

| Lens | Health | Notes |
|------|--------|-------|
| Structural Organization | :green_circle: | ... |
| Design Patterns | :yellow_circle: | ... |
| ... | ... | ... |

**Flagged for deep dive:** Design Patterns, Coupling & Cohesion
**Files sampled:** N

Run `/architect` (without --sweep) to continue with deep analysis.

--sweep が渡されていない場合は、フェーズ 3 に進みます。

---

フェーズ 3：詳細分析 — 観点ごとの並列分析

スイープで黄色または赤色と判定された各観点について、詳細な分析を行う Sonnet サブエージェントを起動します。該当する観点はすべて並列で実行されます。

ステップ 1：該当する観点を特定する

スイープ結果から、health が "yellow" または "red" の観点をすべて集めます。すべての観点が緑色の場合は、フェーズ 3 全体をスキップし、スイープの要約のみでフェーズ 4 に進みます。ユーザーに次のように伝えます。

「7 つすべての観点が緑色でした。詳細分析は不要です。スイープ結果を使って評価に進みます。」

ステップ 2：詳細分析エージェントを起動する

該当する観点のエージェントをすべて 1 つのメッセージで起動します（並列実行）。該当する観点ごとに Agent(model: "sonnet") を 1 つ実行します。

各観点について、以下の観点別基準と、その観点のスイープデータからプロンプトを作成します。

Agent(model: "sonnet", description: "Deep dive: {lens_name} analysis of {SLUG}")

各詳細分析エージェントには、完全に自己完結したプロンプトを渡します。

You are an architectural analyst performing a deep dive on a specific
structural dimension of a codebase. A broad sweep has already identified
this area as needing investigation. Your job is to produce detailed,
actionable findings.

## Project

- **Root:** {ROOT}
- **Framework:** {FRAMEWORK}
- **Philosophy:** {PHILOSOPHY}
- **Full config:** {CONFIG}

## Your Lens: {LENS_DISPLAY_NAME}

### What the sweep found

- **Health:** {sweep_health}
- **Notes:** {sweep_notes}
- **Key files to start with:** {sweep_file_pointers}

### What to look for

{lens_criteria}

## Analysis Instructions

1. Start with the file_pointers from the sweep — these are your leads
2. Follow the dependency graph outward — what do these files import? What
   imports them?
3. Read the actual code, not just directory listings. You need to see
   implementations to judge quality.
4. Compare against the project's stated philosophy: {PHILOSOPHY}
5. Check for patterns — one instance isn't a finding, repeated instances are

## Output Format

Return your findings as a structured list. Each finding MUST follow this
exact format:

```
Finding: <concise title>
Severity: Low | Medium | High | Critical
Location: <file path(s) — be specific>
What: <description of what you found>
Why it matters: <impact on maintainability, scalability, or developer experience>
Recommendation: <specific, actionable suggestion — not vague advice>
```

Severity definitions:
- **Critical** — actively causing problems now, blocking team velocity, or
  creating risk of bugs/outages. Fix soon.
- **High** — significant structural issue that will compound over time.
  Should be planned.
- **Medium** — real issue but manageable. Worth addressing when touching
  the area.
- **Low** — minor improvement. Address opportunistically.

Be specific. "Consider refactoring" is not a recommendation. "Extract the
fee calculation from MemberPayment into a FeeCalculator service — it's
duplicated in 3 models" is.

If the sweep flagged this lens but your deep analysis finds it's actually
fine, say so. Return an empty findings list with a note explaining why
the flag was a false alarm.

Return ONLY the findings in the format above, no surrounding text. If there
are no findings, return: "No findings — sweep flag was a false positive."

レンズの評価基準リファレンス

各レンズに適切な評価基準ブロックを使用します。

構造的な構成：

- Directory layout: is it by layer (models/, views/, controllers/) or by
  feature (payments/, members/, dispatch/)? Is it consistent?
- File grouping: are related files co-located or scattered?
- Naming: do file names follow a consistent convention? Do they match
  their contents?
- Separation of concerns: is presentation logic in models? Business logic
  in controllers? Framework plumbing in domain code?
- Dead directories: folders with stale or unused code

デザインパターン：

- Identify all GoF patterns in use: adapter, strategy, facade, observer,
  factory, decorator, command, etc.
- For each: is it applied correctly? Does it reduce complexity or add it?
- Look for missing patterns: places where a Strategy would eliminate a
  case statement, where an Adapter would decouple a dependency, where a
  Facade would simplify a complex subsystem
- Look for over-patterning: unnecessary indirection, AbstractFactoryFactory
  syndrome, patterns that add layers without adding value

コンポジションと継承：

- Map inheritance hierarchies. Flag any deeper than 3 levels.
- Check for "inheritance for code sharing" — should these be modules/mixins/
  composables instead?
- Count mixins/concerns per class. Flag classes with 5+ includes/extends.
- Look for fragmented behavior — where understanding a class requires reading
  8 different concern files
- Check for composition patterns: dependency injection, strategy objects,
  decorator chains

結合度と凝集度：

- Map module dependencies — which modules/classes reference each other?
- Look for circular dependencies between modules
- Identify god objects: classes with 10+ public methods, 300+ lines, or
  that are imported everywhere
- Check boundary clarity: could you extract a module into a gem/package
  without touching 20 other files?
- Look for feature envy: methods that use more of another class's data
  than their own
- Check for law of demeter violations: long method chains (a.b.c.d)

フレームワークとの整合性：

- Check convention adherence for the specific framework
- Rails: callbacks doing business logic? N+1 queries? SQL in views?
  skip_before_action sprawl? Models as god objects?
- Vue/Nuxt: mutating props? Giant computed properties? Business logic in
  components instead of composables? v-if/v-for on same element?
- General: are framework-provided solutions being used, or is the team
  building custom versions of built-in features?
- Are there framework anti-patterns that the community has identified?

API とインターフェース設計：

- Check internal API consistency: do similar operations have similar
  method signatures?
- Look at method arity: methods with 4+ positional parameters are a flag
- Check for boolean parameters that should be separate methods or enums
- Public surface area: are classes exposing methods that should be private?
- Look for inconsistent return types: same kind of method returning
  different shapes in different classes
- Check service object interfaces: do they follow a consistent pattern
  (call/execute/perform)?

重複と再利用：

- Search for copy-paste code: similar logic in multiple files
- Check for inconsistent approaches: the same problem (e.g., date formatting,
  error handling, validation) solved differently in different places
- Identify extraction candidates: code that appears 3+ times and should be
  a shared utility/concern/composable
- Check for "almost the same" code: slight variations that could be unified
  with a parameter

ステップ 3：結果を収集する

すべての詳細分析エージェントが完了するまで待ちます。それぞれについて：

• 成功： 応答から調査結果を解析します
• 失敗： 該当するレンズを未完了として記録します： "Deep analysis incomplete for {lens_name} — re-run to retry."

1 つのエージェントが失敗しても、スキル全体を失敗させないでください。一部の結果を使って処理を続行します。 失敗したレンズは、ユーザーが再実行して再試行できます。

ステップ 4：結果を統合する

以下を含む、統合した調査結果オブジェクトを作成します。

• スイープの要約（健全性評価を含む 7 つすべてのレンズ）
• 各詳細分析の調査結果
• 未完了として記録されたレンズ

この統合結果を保存し、フェーズ 4 で使用します。これはメモリ内に保持されます。フェーズ 4 で評価成果物にまとめます。

---

フェーズ 4：評価 — 調査結果の提示と成果物の生成

このフェーズは、ユーザーとのやり取りが必要なため、サブエージェントではなくメインの会話で実行します。詳細分析の結果を取り込み、評価成果物を作成します。

ステップ 1：詳細分析の結果を統合する

すべての詳細分析エージェントの調査結果を、レンズごとに整理した統一的な見解にまとめます。スイープで緑と評価されたレンズも含めます（調査結果はありませんが、要約テーブルには健全性評価が表示されます）。

ステップ 2：既存の評価を確認する

CONFIG=$("$ARCHITECT" config "$SLUG")
ARTIFACT_PATH=$(echo "$CONFIG" | jq -r '.artifact_path')

$ROOT/$ARTIFACT_PATH がすでに存在するか確認します。存在する場合は、再実行です。

1. 既存の成果物を読み取ります
2. アクションプランセクションをそのまま保持します（これはユーザーが作成した内容です）
3. 差分を確認するため、前回のスイープを読み込みます。

   LAST_SWEEP=$("$ARCHITECT" last-sweep "$SLUG")
   

4. 現在の調査結果と前回のスイープを比較します。
   • 新規の調査結果 — 現在の結果にあり、前回のスイープにはないもの
   • 解決済みの調査結果 — 前回のスイープにあり、現在の結果にはないもの。成果物では調査結果のタイトルに [RESOLVED] を追加します
   • 変更のない調査結果 — 両方にあるもの。そのままにします
5. 全体の要約を提示する前に、差分をユーザーに提示します。

   「これは再実行です。前回の評価以降、新規の調査結果が N 件、解決済みが N 件、変更なしが N 件あります。」

既存の成果物がない場合は、新規の評価として進めます。

ステップ 3：調査結果を提示する

エグゼクティブサマリーから始めて、調査結果をユーザーに提示します。

1. 全体的な健全性評価 — 1 文での判定
2. 主な強み — うまく機能している点（具体的なレンズやパターンを挙げます）
3. 主な懸念事項 — 対応が必要な点（具体的な調査結果を挙げます）
4. 調査結果の件数 — 重大度ごとの合計件数（Critical：N、High：N、Medium：N、Low：N）
5. レンズの健全性テーブル：

| Lens | Health |
|------|--------|
| Structural Organization | Good / Needs Attention / Significant Concerns |
| Design Patterns | ... |
| Composition & Inheritance | ... |
| Coupling & Cohesion | ... |
| Framework Alignment | ... |
| API & Interface Design | ... |
| Duplication & Reuse | ... |

スイープの評価に基づく健全性の対応関係：

• green → 良好
• yellow → 要注意
• red → 重大な懸念あり

続いて、レンズごとに分類した詳細な調査結果を提示します。各調査結果には、重大度、場所、説明、影響、推奨事項を含めます。

ステップ 4：話し合う

調査結果を提示した後、ユーザーからの入力を待ちます。ユーザーが次のことを行う機会を得るまでは、推奨事項の提示に進まないでください。

• 特定の調査結果について質問する
• 同意できない調査結果に異議を唱える
• 見落とされていた可能性のある背景情報を追加する
• ビジネスの実情に合わせて優先順位を変更する

これは一方的な情報提示ではなく、対話です。ユーザーが調査結果に納得したことを示すまで待ってから、次に進みます。

ステップ 5: 優先順位を付けた推奨事項の作成

議論の後、すべての推奨事項を次の 3 つの段階に分類します。

• すぐに実施できる改善 — 数時間で対応でき、リスクが低く、明確さを大きく改善します。今週中に着手できる内容にします。
• 中程度の取り組み — 数日から 1 週間ほどかかり、中程度の再構成を伴います。調整が必要な場合や、複数のファイル／モジュールに影響する場合があります。
• 戦略的な再構成 — 数週間から数か月かかり、段階的なアプローチが必要です。計画を要する、より大規模なアーキテクチャの変更です。

各段階内では、影響の大きい順に並べます。

ステップ 6: 評価アーティファクトの生成

以下のテンプレートを使用してアーティファクトを作成します。$ROOT/$ARTIFACT_PATH に書き込みます。

評価アーティファクトのテンプレート

# Architecture Assessment — <Project Name>
Generated: YYYY-MM-DD | Framework: Rails 8.x / Nuxt 4.x / etc.

## Summary
2-3 paragraph executive overview. Overall health, biggest strengths,
biggest concerns.

## Findings by Lens

### <Lens Name>
**Health: Good / Needs Attention / Significant Concerns**

#### Finding: <title>
- **Severity:** Low / Medium / High / Critical
- **Location:** app/services/, app/models/
- **What:** Description of what was found
- **Why it matters:** Impact on maintainability, velocity, correctness
- **Recommendation:** What to do about it

(repeat per finding, per lens)

## Prioritized Recommendations
Ordered list grouped into:
- **Quick wins** — hours, low risk, high clarity improvement
- **Medium efforts** — days to a week, moderate restructuring
- **Strategic restructuring** — weeks to months, phased approach needed

## Action Plan
Empty until the user decides what to act on. Populated during Phase 5
with phased implementation strategies. Updated as phases complete.

テンプレートに関する注意事項:

• 設定から <Project Name>、日付、フレームワークを入力します
• ステップ 3 で提示したエグゼクティブサマリーから Summary を入力します
• 統合した詳細調査の結果から Findings by Lens を入力します
• ステップ 5 の内容から Prioritized Recommendations を入力します
• 初回実行時は Action Plan を空欄にし、再実行時は既存の内容を保持します
• 解決済みの指摘事項は、指摘事項のタイトルの末尾に [RESOLVED] を付けて示します。例: #### Finding: God object in User model [RESOLVED]
• すべてのレンズを含めます（良好なものも含む）。良好なレンズには Health 行を記載しますが、その下には指摘事項を記載しません

ステップ 7: アーティファクトのコミット

cd "$ROOT"
git add "$ARTIFACT_PATH"
git commit -m "docs: architecture assessment — $(date +%Y-%m-%d)"
git push

アーティファクトのコミット先をユーザーに伝えます。

ステップ 8: 状態の更新

コミットしたアーティファクトを解析し、プロジェクトの状態を更新します。

PARSED=$("$ARCHITECT" parse-artifact "$SLUG")
FINDINGS_TOTAL=$(echo "$PARSED" | jq -r '.findings_total')
FINDINGS_RESOLVED=$(echo "$PARSED" | jq -r '.findings_resolved')
PLAN_PHASES=$(echo "$PARSED" | jq -r '.action_plan_phases')
PLAN_COMPLETED=$(echo "$PARSED" | jq -r '.action_plan_completed')

"$ARCHITECT" update-state "$SLUG" \
  last_full_run="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  findings_total="$FINDINGS_TOTAL" \
  findings_resolved="$FINDINGS_RESOLVED" \
  action_plan_phases="$PLAN_PHASES" \
  action_plan_completed="$PLAN_COMPLETED"

---

フェーズ 5: 計画 — 段階的な実装戦略

このフェーズは会話形式（サブエージェントではなく、メインの会話）で進めます。必要に応じて実行します。ユーザーが指摘事項への対応を決めたとき、評価の会話中または後のセッションで実行されます。

ステップ 1: 評価内容の読み込み

CONFIG=$("$ARCHITECT" config "$SLUG")
ARTIFACT_PATH=$(echo "$CONFIG" | jq -r '.artifact_path')

$ROOT/$ARTIFACT_PATH にある既存の評価アーティファクトを読み込みます。存在しない場合は、ユーザーに「評価が見つかりません。まず /architect を実行して評価を生成してください。」と伝えて終了します。

ステップ 2: 対応する項目の確認

現在の指摘事項と優先順位を付けた推奨事項をユーザーに提示し、どれに対応するか尋ねます。

「現在の指摘事項と推奨事項は以下のとおりです。どれを計画しますか？個別の指摘事項、推奨事項の段階（例:『すぐに実施できる改善をすべて』）、またはその組み合わせを選べます。」

ユーザーの回答を待ちます。

ステップ 3: 選択項目ごとの範囲の確認

選択された各項目について、次の点を話し合います。

• 変更の範囲 — どのファイル、モジュール、レイヤーが影響を受けますか？
• リスクレベル — 安全な名前変更／抽出ですか、それとも動作が変わりますか？テストが失敗する可能性はありますか？公開 API に影響しますか？
• 他の変更との依存関係 — 別の計画中の変更より先に、または後に行う必要がありますか？
• 見積もり工数 — 数時間、数日、数週間のどれくらいですか？テストの更新も考慮します。

会話形式で進め、各項目についてユーザーと確認します。計画を提示してそのまま先に進めてはいけません。議論の中で、ユーザーが優先順位を変更したり、項目を後回しにしたり、関連する変更をまとめたりする場合があります。

ステップ 4: アクションプランの作成

ユーザーが範囲に納得したら、アーティファクトの ## Action Plan セクションに段階的な計画を作成します。各フェーズでは、まとめて実施できる関連変更をグループ化します。

## Action Plan

### Phase 1: <title> [NOT STARTED]
**Target findings:** Finding X, Finding Y
**Scope:** <description of what changes and where>
**Risk:** Low / Medium / High
**Estimated effort:** <timeframe>
**Dependencies:** None / Phase N must complete first

### Phase 2: <title> [NOT STARTED]
**Target findings:** Finding Z
**Scope:** <description>
**Risk:** <level>
**Estimated effort:** <timeframe>
**Dependencies:** <if any>

フェーズのステータス:

• [NOT STARTED] — 計画済みですが、まだ開始していません
• [IN PROGRESS] — 作業を開始しています（フェーズ 6 の開始時に設定）
• [COMPLETE] — 実行が完了し、検証済みです

順序: すぐに実施できる改善とリスクの低いフェーズを先に配置します。戦略的な再構成は最後にします。依存関係の順序を守ります。フェーズ 3 がフェーズ 1 に依存する場合は、フェーズ 1 を先に配置します。

ステップ 5: 更新したアーティファクトのコミット

cd "$ROOT"
git add "$ARTIFACT_PATH"
git commit -m "docs: architecture action plan — $(date +%Y-%m-%d)"
git push

ユーザーに次のように伝えます。「アクションプランをコミットしました。各フェーズを個別に実行するには、/architect を実行して、実行するフェーズを伝えてください。」

ステップ 6: 状態の更新

コミットしたアーティファクトを解析し、プロジェクトの状態を更新します。

PARSED=$("$ARCHITECT" parse-artifact "$SLUG")
FINDINGS_TOTAL=$(echo "$PARSED" | jq -r '.findings_total')
FINDINGS_RESOLVED=$(echo "$PARSED" | jq -r '.findings_resolved')
PLAN_PHASES=$(echo "$PARSED" | jq -r '.action_plan_phases')
PLAN_COMPLETED=$(echo "$PARSED" | jq -r '.action_plan_completed')

"$ARCHITECT" update-state "$SLUG" \
  action_plan_phases="$PLAN_PHASES" \
  action_plan_completed="$PLAN_COMPLETED" \
  findings_total="$FINDINGS_TOTAL" \
  findings_resolved="$FINDINGS_RESOLVED"

---

フェーズ 6：実行 — 再構成のためのライティングプランを呼び出す

このフェーズはオンデマンドで実行されます。ユーザーが「フェーズ 1 に取り組みましょう」や「すぐできる改善を実行して」のように明示的に指示した場合にのみ開始され、自動では実行されません。

ステップ 1：対象フェーズを特定する

評価アーティファクトを読み込みます。ユーザーが指定したフェーズを見つけます。フェーズのステータスが [COMPLETE] の場合、すでに完了していることをユーザーに伝え、再実行するか確認します。

アーティファクト内で対象フェーズを [IN PROGRESS] にします。

ステップ 2：コンテキストを収集する

アーティファクトから、以下を収集します。

• フェーズのタイトルと対象範囲の説明
• 対象となる指摘事項（場所、内容、重要な理由、推奨事項など、指摘事項の詳細すべて）
• 依存関係 — 前提となるフェーズが [COMPLETE] であることを確認します

依存するフェーズが未完了の場合、ユーザーに警告します。

"フェーズ N は、まだ [NOT STARTED] のフェーズ M に依存しています。このまま進めますか？それとも先にフェーズ M に取り組みますか？"

確認を待ちます。

ステップ 3：ライティングプランを呼び出す

superpowers:writing-plans スキルを呼び出して、このフェーズの詳細な実装計画を作成します。

/superpowers:writing-plans

スキルには、以下の情報を渡します。

• 目標： アクションプランにあるフェーズのタイトルと対象範囲
• コンテキスト： このフェーズが対象とするすべての指摘事項の詳細（場所、内容、重要な理由、推奨事項）
• プロジェクトルート： $ROOT
• フレームワークと方針： アーキテクト設定から取得します

以降は writing-plans スキルが処理します。タスクの分解、TDD、実行も含まれます。

ステップ 4：実行後にアーティファクトを更新する

実行が完了したら、以下を行います。

1. アクションプランでフェーズを [COMPLETE] にします。

   ### Phase 1: <title> [COMPLETE]
   

2. 解決済みの各指摘事項のタイトルに [RESOLVED] を追加します。

   #### Finding: God object in User model [RESOLVED]
   

   実行によって実際に対処された指摘事項のみを解決済みとします。 指摘事項に部分的にしか対処できなかった場合は、マークを付けずに注記を追加します。

3. 更新したアーティファクトをコミットします。

   cd "$ROOT"
   git add "$ARTIFACT_PATH"
   git commit -m "docs: architecture phase complete — <phase title>"
   git push
   

ステップ 5：状態を更新する

PARSED=$("$ARCHITECT" parse-artifact "$SLUG")
FINDINGS_TOTAL=$(echo "$PARSED" | jq -r '.findings_total')
FINDINGS_RESOLVED=$(echo "$PARSED" | jq -r '.findings_resolved')
PLAN_PHASES=$(echo "$PARSED" | jq -r '.action_plan_phases')
PLAN_COMPLETED=$(echo "$PARSED" | jq -r '.action_plan_completed')

"$ARCHITECT" update-state "$SLUG" \
  action_plan_phases="$PLAN_PHASES" \
  action_plan_completed="$PLAN_COMPLETED" \
  findings_total="$FINDINGS_TOTAL" \
  findings_resolved="$FINDINGS_RESOLVED"

完了した内容と残っている内容をユーザーに伝えます。

"フェーズ 1 が完了しました。N 件の指摘事項を解決しました。アクションプランには残り M フェーズあります。"

---

対象を指定した呼び出し — /architect <target>

ユーザーが対象を指定して /architect を呼び出した場合（例：/architect app/models や /architect the dispatch system）、実行対象はそのサブシステムに限定されます。

対象範囲の仕組み

対象の処理は既存のフェーズに組み込まれています。

1. Teach — 必要に応じて通常どおり実行します（値はプロジェクト全体に適用されます）
2. Sweep（フェーズ 2、ステップ 2） — 対象範囲の検出機能はすでに対象指定に対応しています。
   • パスによる対象（app/models、src/features/dispatch）の場合、そのディレクトリツリーにスキャン対象を絞ります
   • 概念による対象（「the dispatch system」）の場合、まず関連ファイルを特定してから対象を絞り込むよう、スイープエージェントに指示します
3. Deep Dive（フェーズ 3） — エージェントにはスイープで絞り込まれたファイル情報が渡されるため、自然に対象領域へ集中します
4. Assess（フェーズ 4） — 対象範囲内の指摘事項のみを生成します

メインアーティファクトへの統合

対象を指定して実行する場合の主な違いは、結果を評価アーティファクトに統合する方法です。

評価アーティファクトがすでに存在する場合：

1. 既存のアーティファクトを読み込みます
2. 各観点について、新しい指摘事項を既存のものと統合します。
   • 対象範囲内の新しい指摘事項 — 該当する観点のセクションに追加します。明確になるよう、指摘事項のタイトルの先頭に対象範囲を付けます。例： #### 指摘事項：User モデル内の God object（app/models）
   • 対象範囲外の既存の指摘事項 — 変更せずに保持します
   • 対象範囲内の既存の指摘事項 — 新しい結果に置き換えます（この領域については、新しい分析が以前の結果に優先します）
3. 優先順位付けを再実行し、新しい指摘事項を既存の推奨ランクに統合します
4. アクションプランのセクションをそのまま保持します。対象を指定した実行では、既存のプランは変更しません

評価アーティファクトが存在しない場合：

標準テンプレートを使って新しいものを作成します。この評価が対象領域のみを対象としていることを、概要に記載します。

## Summary
This assessment covers **<target description>** only, not the full codebase.
Run `/architect` without a target for a complete assessment.

成果物のコミット

フェーズ 4、ステップ 7 と同じです。

cd "$ROOT"
git add "$ARTIFACT_PATH"
git commit -m "docs: architecture assessment — <target> — $(date +%Y-%m-%d)"
git push

状態の更新

フェーズ 4、ステップ 8 と同じです。成果物を解析して状態を更新します。状態は、すべての実行（全体実行と対象を絞った実行）の集計結果を追跡します。