incu-way-arch-assessment

アーキテクチャ評価プロセス

アーキテクチャ全体、モジュール、または現在のブランチにおける変更を、明示的な品質属性と設計原則に照らして評価し、チームが行動に移せる追跡可能で優先順位付けされた評価にまとめる、ゲート駆動型のワークフローです。出力は docs/assessments/arch/{slug}/ASSESSMENT.md に保存されます。

呼び出し方法は2つあります。

• 単独（システムまたは設計の監査）： 専用ブランチ assess/arch-{slug} → develop へのPR。
• 別のフローに組み込む場合： 呼び出し元の現在のブランチ／ワークツリーに書き込み、評価はそのフローのPRに含めます。専用のブランチやPRは作成しません。例： incu-way-development がゲート2で計画中の設計を評価する、incu-way-docs がドキュメント作成中に構造上のリスクを指摘する、incu-way-init が既存のコードベースを調査する。

これは評価フローです。incu-way-docs と同様に、.ways/state.json は管理しません（このモデルは feature／bug／security の作業向けです）。評価して推奨事項を提示しますが、修正は実装しません。推奨事項への対応は、別の incu-way-development または incu-way-bugs の作業項目です。

---

リポジトリの適格性チェック（最初に実施）

Phase 0 の前に、現在のリポジトリが ~/.ways/config.yaml の blacklist（形式は incu-base の global-config ルール。常時有効としてインストールされます）に該当するか確認してください。該当する場合は、このリポジトリが incu-way の対象外であることをユーザーに伝え、このまま進める（一度限りの例外）か、中止するかを尋ねます。回答があるまで、どのフェーズも実行しないでください。ファイルがない場合、または該当しない場合は、通常どおり進めてください。

---

Phase 0 — 範囲と調査

目標： 何を、どの観点から評価するのかを把握してから判断します。読み取り専用です。

受け入れ時の確認

1. 利用可能なコンテキストをもとに、対象を確認します。
   • リポジトリ全体、特定のモジュール／サービス／境界づけられたコンテキスト、または現在のブランチの差分 （提案された変更または新しいコード — git diff develop...HEAD）
   • 既存コードを対象とする実装済みの状態の監査か、まだ実装されていない計画／PRD／提案を対象とする設計段階のレビューか
2. 評価の土台とし、すでに記述されている内容を再導出しないよう、まず既存のアーキテクチャドキュメントを読みます（docs/architecture/、README.md、PRD.md、各種ADR）。ドキュメントがない、または古くなっている場合は記録します。それ自体が指摘事項です。

対象の調査

調査を行い、まだ評価はしません。

• 分解構造 — 実際のトップレベル構造（レイヤー、ヘキサゴナルアーキテクチャのポート／アダプター、機能別フォルダー、マイクロサービス）と、コードが文書化された意図に合致しているか。
• 依存関係 — モジュール／パッケージの依存方向、循環、結合が集中する箇所、依存元と依存先。
• 境界 — ドメインロジックとインフラストラクチャ／フレームワークのコードが存在する場所、および境界を越えた漏出。
• 横断的関心事 — 認証、設定、ロギング／可観測性、エラー処理、トランザクション。それぞれの配置と一貫性。
• データと統合 — ストア、外部システム、およびコードからそれらにアクセスする方法。
• テスト — カバーされているレイヤー、テストの構成、テスト不能なもの。

Phase 0 の終了基準

Gate 1 の前に、Claude が次の事項を説明できる状態にします。

• 対象と、それが実装済みの状態か設計段階か
• 主なコンポーネントと、実際の依存関係
• 使用した既存ドキュメント、および不足している／古くなっているドキュメント
• このシステムで重要となる候補の品質属性
• 不明確な領域。推測せず、未解決の質問として記録します

名前だけから設計上の特性を推測してはいけません。コードから構造上の事実が明確に読み取れない場合は、確信を持った主張ではなく、未解決の質問として扱います。

---

ゲート 1 — 評価の範囲と基準

何を評価するのか、およびどの基準で評価するのかを提案し、対象の規模に合わせて調整します（単一モジュールの場合は、複数サービスのプラットフォームよりも軽い観点が必要です）。次の形式で提示します。

## Proposed assessment

- **Target:** {repo | module X | current branch diff}
- **Mode:** as-built audit | as-designed review
- **Quality attributes (rated):**
  - [ ] Maintainability / modularity
  - [ ] Coupling & cohesion
  - [ ] Layering / boundary integrity (hexagonal, SoC)
  - [ ] Scalability & performance posture
  - [ ] Testability
  - [ ] Security posture (structural — defer deep checks to incu-way-security-validation)
  - [ ] Observability & operability
  - [ ] Consistency with documented architecture
- **Out of scope:** {what this pass will not cover}
- **Open questions:** {anything ambiguous about the target or intent}

• 対象に適さない属性は削除し、対象に固有の属性があれば追加します。
• 次のように確認します。「これが {target} の評価範囲と基準です。評価を開始する前に確認してください。」
• 停止します。ユーザーが範囲と基準を確認するまで、評価を作成しないでください。

---

分離環境の設定（スタンドアロンモードのみ）

別のフローに組み込まれている場合は、これをスキップし、既存のブランチ／worktree に書き込みます。

スタンドアロンで実行する場合は、書き込みを始める前に、作業をどのように分離するかをユーザーに尋ねます。

現在のチェックアウトに新しいブランチを作成して作業しますか。それとも、別の git worktree を作成しますか。

ユーザーの回答をそのまま使用します。 質問した後は停止し、ユーザーが選択するまでブランチや worktree を作成しないでください。

現在のチェックアウトに未コミットの変更がある場合は、ブランチの切り替えや worktree の作成を行う前に停止して確認します。

オプション A — 現在のチェックアウトにブランチを作成

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c assess/arch-{slug}

オプション B — 別の worktree

worktree は .worktrees/ の下にのみ作成します。ユーザーにパスを尋ねないでください。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/assess-arch-{slug} -b assess/arch-{slug} origin/develop

{slug} は {kebab-target} です（例：payments-core、checkout-redesign）。すべての出力は、選択した作業場所内に書き込み、コミットします。

---

フェーズ 2 — 評価を作成する

目標： 実際のコード／設計に基づいて ASSESSMENT.md を作成します。

評価のルール（必須）

• 追跡可能であること。 すべての指摘に、その根拠（path/to/file.ext:line、モジュール、依存関係のエッジ、設定キーなど）を示します。読者が検証できなければなりません。
• 創作しないこと。 存在するものを評価し、「あるべき」姿を評価しないでください。特性が不明確な場合は、推測して評価せず、未解決の質問／要確認事項に記載します。
• 評価を付けること。 各品質属性には評価とその根拠を示し、曖昧な形容詞だけで済ませないでください。
• 重大度は好みではなくリスクを反映すること。 指摘の重大度は、それが伴うアーキテクチャ上のリスク（影響範囲、不具合を引き起こす可能性、後から変更するコスト）を表すものであり、個人的なスタイルの好みではありません。
• 推奨するが、実装しないこと。 推奨事項は具体的かつ優先順位付きにします。このフローではコードを変更しません。
• 矛盾を記録すること。 コードが文書化されたアーキテクチャと矛盾する場合は、どちらかを黙って選ばず、矛盾を明示します。

ASSESSMENT.md の構成

# Architectural Assessment — {target}

## Scope
- Target: {repo | module | branch diff}
- Mode: as-built | as-designed
- Date: {YYYY-MM-DD}
- Criteria: {the attributes confirmed at Gate 1}

## Executive summary
3–5 sentences: overall health, the one or two things that matter most, the headline risks.

## Quality attribute ratings
| Attribute | Rating | Evidence | Notes |
|-----------|--------|----------|-------|
| Maintainability | Strong / Adequate / At risk / Poor | `path:line`, module | … |
| Coupling & cohesion | … | … | … |
| Layering / boundaries | … | … | … |
| Scalability | … | … | … |
| Testability | … | … | … |

## Strengths
What is genuinely well-structured and should be preserved (each with evidence).

## Findings
| # | Area | Severity | Finding | Evidence | Recommendation |
|---|------|----------|---------|----------|----------------|
| 1 | Coupling | High | Domain layer imports the HTTP framework directly | `src/domain/order.ts:12` | Introduce a port; move the dependency to the adapter |
| 2 | … | … | … | … | … |

Severity: Critical / High / Medium / Low — architectural risk, not style.

## Tech debt register
Debt items worth tracking, each with rough cost-to-fix and cost-of-delay.

## Open questions / to verify
- …

文章は簡潔にします。短く直接的な文を使い、段落よりも表のほうが読みやすい場合は表を使います。

---

フェーズ 3 — 図と優先順位付け

• 図（理解の助けになる場合）： 問題箇所を強調した対象のMermaidコンポーネント図／依存関係図と、構成変更を推奨する場合は目標状態の図を作成します。終了前に、すべての図が Mermaid パーサーで検証されていることを確認してください。 正しく描画されない図は、図がないよりも悪い結果になります。
• 優先順位付きの推奨事項： 指摘の推奨事項を、短い今すぐ／次に／検討のリストに並べ、各項目に指摘番号を付けます。これは実行可能な引き継ぎです。「今すぐ」の項目は通常、後続の incu-way-development または incu-way-bugs の作業項目になります。

---

ゲート 2 — レビュー

評価、図、優先順位付けを作成した後：

• パス、エグゼクティブサマリー、重大度別の主要な指摘、および未解決の質問／要確認事項を提示します。
• 次のように伝えます。「アーキテクチャ評価の準備ができました。docs/assessments/arch/{slug}/ASSESSMENT.md にあります。未解決の質問を入力用に記載しています。レビューしてください。」
• 停止します。ユーザーのレビューを待ってから先に進んでください。

組み込みで実行している場合は、制御を呼び出し元のフローのレビューゲートに戻します。評価はそこでレビューされ、そのフローの PR に含まれます。以下のスタンドアロン PR 手順はスキップします。

---

フェーズ 4 — PR（スタンドアロンモードのみ）

assess/arch-{slug} をプッシュして PR を作成するため、incu-way-prepare-pr の実行を提案してください。自分でプッシュしたり、gh pr create を実行したりしないでください。

incu-way-prepare-pr で使用する PR のタイトル／本文案：

Title: assess(arch): {target}

PR 本文には次の内容を含めてください：

• 対象範囲： 対象、モード、評価した基準。
• 概要： エグゼクティブサマリーと、重大度別の主な調査結果。
• 推奨事項： 今すぐ実施／次に実施／検討する項目の一覧。
• 未解決の質問： チームからの意見が必要な未解決事項。

作成したら、PR の URL を共有してください。停止してください。ユーザーの承認を得るまでマージしないでください。

---

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	ブロックする条件
1	対象範囲と基準の提案	「{target} の評価対象範囲と基準は以上です。評価を開始する前に確認してください。」	ユーザーの確認
2	評価書の作成完了	「アーキテクチャ評価書を docs/assessments/arch/{slug}/ASSESSMENT.md に用意しました。ご確認ください。」	ユーザーのレビュー
3	（スタンドアロン）レビュー済み	PR assess/arch-{slug} → develop 用に incu-way-prepare-pr の使用を提案し、ユーザーが実行したら URL を共有する	ユーザーの PR 承認

---

作成されるもの

docs/assessments/arch/{slug}/
  ASSESSMENT.md   # ratings, findings, tech debt, prioritized recommendations, diagrams

---

してはいけないこと

• ゲート 1 で対象範囲と基準が確認される前に、評価書を作成しないでください。
• 構造、意図、評価を作り上げないでください。検証できない内容は 「未解決の質問／要確認」に記載してください。
• 追跡できない調査結果を記載しないでください。各調査結果はファイル／モジュール／エッジ／キーを示してください。
• スタイル上の好みで重大度を決めないでください。重大度はアーキテクチャ上のリスクです。
• ここで修正を実装しないでください。推奨事項を提示し、変更は後続の incu-way-development / incu-way-bugs の項目に任せてください。
• Mermaid パーサーでレンダリングに失敗する図を確定しないでください。
• 別のフローに組み込まれている場合、独立した PR を作成しないでください。評価は呼び出し元の PR に含めてください。
• スタンドアロンモードでは、develop または main に直接書き込まないでください。assess/arch-{slug} を使用してください。