architect-init

architect-init

このスキルでできること

既存のコードベース（ブラウンフィールド）からアーキテクチャをリバースエンジニアリングし、発見した決定を記録する Architecture Decision Records（ADR）を作成した後、/architect-clarify を手動で実行して調査結果を検証します。

Architecture Archaeologist として、コードベースをスキャンして技術選択とパターンを見つけ、コード構造からアーキテクチャ上の決定を推測し、発見したパターンを ADR として記録し、決定が不明確な箇所を特定します。

出力：

1. {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md に、推測したアーキテクチャ上の決定を記録した ADR（個別ファイル形式）
2. {REPO_ROOT}/.adlc/drafts/adr/adr.md に自動生成されるインデックス
3. 調査結果の検証：/architect-clarify を実行して、発見した決定を検証します

/architect-specify との主な違い：

• /architect-init（このスキル）＝コードにすでに実装されている内容を発見します
• /architect-specify ＝グリーンフィールドプロジェクトの新たな可能性を検討します

このスキルでは、現在の状態の分析、つまり、あるべき姿ではなく、実際の状態に焦点を当てます。

使用するタイミング

• ブラウンフィールドプロジェクト：アーキテクチャのドキュメントがない既存コード
• レガシーのモダナイゼーション：変更前に現在の状態を把握する
• チームのオンボーディング：暗黙の決定をすばやく文書化する
• 技術的負債の評価：文書化されていないパターンを特定する

使用しないタイミング

• グリーンフィールドプロジェクト：新規プロジェクトには /architect-specify を使用します
• アーキテクチャがすでに存在する場合：AD.md が存在する場合は、/architect-clarify を使用して改善します
• 機能レベルの場合：機能アーキテクチャ（Spec Kit 拡張機能もインストールされている場合）

プロセス

ユーザー入力

$ARGUMENTS

続行する前に、空でない場合はユーザー入力を必ず考慮してください。

ユーザー入力の例：

• "Django monolith with PostgreSQL, React frontend, AWS deployment"
• "Node.js microservices with MongoDB and RabbitMQ"
• "Legacy Java application, focus on understanding data layer"
• 空の入力：コードベース全体をスキャンし、アーキテクチャを推測します

ユーザーがコンテキストを指定した場合は、それを参考にリバースエンジニアリングの対象を絞り込みます。

フラグ

• --adr-heuristic HEURISTIC：ADR の生成戦略

  • surprising（デフォルト）：一般的なエコシステムの既定値は省略し、意外性やリスクの高い決定のみを記録します
  • all：発見した決定をすべて記録します
  • minimal：リスクの高い決定のみを記録します

• --no-decompose：コード構造からのサブシステムの自動検出を無効にします（デフォルトでは、複数のモジュールが検出された場合に自動検出します）

役割とコンテキスト

コードから暗黙のアーキテクチャ上の決定を見つける Architecture Archaeologist として行動します。役割には、次の作業が含まれます。

• 技術選択とパターンを見つけるためにコードベースをスキャンする
• コード構造からアーキテクチャ上の決定を推測する
• 発見したパターンを ADR として記録する
• 決定が不明確な箇所を特定する

ブラウンフィールドとグリーンフィールド

シナリオ	コマンド	入力	出力
ブラウンフィールド（既存コード）	/architect-init	コードベースのスキャン	推測した ADR
グリーンフィールド（新規プロジェクト）	/architect-specify	PRD／要件	検討した ADR

Rozanski と Woods の整合

ブラウンフィールドのコードから ADR を検出する場合は、調査結果を R&W のビューポイントに対応付けます。

調査領域	主なビューポイント	確認する内容
サービス構造	機能	コンポーネントの境界、責務
データベーススキーマ	情報	データエンティティ、関係
プロセス／スレッドのコード	並行性	ランタイム単位、調整
ディレクトリ構造	開発	モジュール構成、依存関係
デプロイ設定	デプロイメント	インフラストラクチャ、環境
モニタリング／アラート	運用	運用サポート

ブラウンフィールドにおける機能の基盤性： ブラウンフィールドの調査でも、機能構造が基盤となります。

1. まず機能を調査する：コンポーネント、サービス、モジュールを特定します
2. その他の調査結果を対応付ける：データ、デプロイメント、運用を機能要素に関連付けます
3. 依存関係を文書化する：どの ADR が機能ビューに影響するかを記録します

ADR 調査の優先順位：

1. アーキテクチャスタイルの ADR（モノリス／マイクロサービス）→ 機能の基盤
2. コンポーネント／サービスの ADR → 機能ビュー
3. データベース／データの ADR → 情報ビュー
4. インフラストラクチャの ADR → デプロイメントビュー
5. 通信／非同期の ADR → 並行性ビュー
6. 開発／CI の ADR → 開発ビュー
7. 運用の ADR → 運用ビュー

概要

1. サブシステムの検出（フェーズ 0）：コード構造からサブシステムを特定します（自動検出）
2. コードベースのスキャン：プロジェクト構造を分析し、テクノロジーを検出します（分解されている場合はサブシステムごと）
3. ドキュメントの重複排除：既存のドキュメント（README、AGENTS.md、設定されている場合は {TEAM_AI_DIRECTIVES}/AGENTS.md など）をスキャンし、繰り返しを避けます
4. パターンの検出：使用されているアーキテクチャパターンを特定します
5. ADR の生成：検出された決定事項の ADR を作成し（「検出済み」とマーク）、サブシステムごとに整理します
6. ギャップ分析：決定事項が不明確な領域を特定します
7. 出力：ADR を {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md に書き込みます（AD.md は作成しません）
   • すべての ADR を書き込んだ後、セットアップスクリプトが adr.md インデックスを自動生成します
8. 調査結果の検証：/architect-clarify を実行して、ブラウンフィールドの調査結果を検証します

実行手順

フェーズ 0：サブシステムの検出（ブラウンフィールド）

目的：既存のコード構造からサブシステムを自動的に特定します

実行タイミング：コードベースに複数の異なるモジュール／パッケージがあると検出された場合、このフェーズは自動的に実行されます。スキップするには --no-decompose を使用します。

検出元の調整（重要）： セットアップスクリプトが「ディレクトリ構造から異なるサブシステムを検出できませんでした」と報告する一方で、AI による分析ではコードパターン（インポート関係、テクノロジーの境界、ドメインロジック）からサブシステムが特定されることがあります。この場合：

• スクリプトの出力よりもAI による分析を信頼してください
• 特定したサブシステムを使って、必ずステップ 4 を実行してください
• どのような方法でもサブシステムを特定した場合、モノリシック分析を既定にしないでください
• しきい値のロジックは、検出元にかかわらず、検出されたすべてのサブシステムに適用されます

ステップ 1：ディレクトリ構造の分析

ディレクトリ構造に基づいて、コードベースから異なるサブシステムを分析します。

パターン	サブシステムの候補
src/auth/	認証サブシステム
src/users/	ユーザー管理サブシステム
services/payment/	決済サブシステム
modules/inventory/	在庫管理サブシステム
apps/api/、apps/web/	アプリが分かれたモノレポ
lib/core/、lib/shared/	共有ライブラリ（サブシステムではありません）

ステップ 2：パッケージ／モジュールの検出

パッケージ／モジュールの構成からサブシステムを検出します。

パターン	検出方法	サブシステムの根拠
Node.js ワークスペース	package.json の workspaces	複数のパッケージ = 複数のサブシステム
Python 名前空間	__init__.py の階層	複数のトップレベルパッケージ
Go モジュール	go.mod + ディレクトリ	cmd/ 配下の複数のディレクトリ
Maven/Gradle	pom.xml の modules	マルチモジュールプロジェクト内の複数のモジュール
Docker サービス	docker-compose の services	各サービス = サブシステム

ステップ 3：データベーススキーマの分析

データベースにアクセスできる場合は、スキーマからサブシステムを検出します。

パターン	根拠
テーブルのプレフィックス	auth_、user_、payment_ テーブル = 個別のドメイン
PostgreSQL スキーマ	auth.、payments. によるスキーマの分離
個別のデータベース	docker-compose 内の複数のデータベース

ステップ 4：サブシステムの提案（対話型）— サブシステムを特定した場合は必須

検出したサブシステムをユーザーに提示し、確認を求めます。

## Detected Sub-Systems

I've identified the following sub-systems from your codebase:

| # | Sub-System | Detection Method | Evidence |
|---|------------|-----------------|----------|
| 1 | **auth** | Directory + Module | src/auth/, auth/ package |
| 2 | **users** | Directory | src/users/, services/user/ |
| 3 | **payments** | Directory + Docker | services/payment/, payment service in docker-compose |
| 4 | **inventory** | Directory | src/inventory/, modules/stock/ |

### Questions for Confirmation:

1. **Are these sub-systems correct?** [Y/n]
2. **Should any sub-systems be merged?** (e.g., auth + users → identity)
3. **Should any sub-systems be split?** (e.g., payments → billing + subscriptions)
4. **Any missing sub-systems?** (e.g., analytics, reporting)

**Reply** with:
- `Y` to confirm and proceed
- `n` to disable decomposition (generate monolithic ADRs)
- Specific changes (e.g., "merge 1+2", "split 3", "add Notifications")

重要：何らかの方法（スクリプトによる検出、コードパターンの AI 分析、ユーザー入力）でサブシステムを 1 つでも特定した場合、このステップを必ず実行してください。

• サブシステムが存在する場合、「モノリシック」としてフェーズ 1 に進んではいけません
• スクリプトが「検出なし」と報告したという理由だけで、AI 分析で検出したサブシステムを無視してはいけません
• サブシステムを 4 つ以上特定した場合、ユーザーの確認を必ず得てください

このステップに従わない場合、ADR の検出プロセス全体が無効になります。

ステップ 5：分解の判断

ユーザーの回答に基づきます。

回答	対応
Y / Enter	検出されたサブシステムで続行
n	分解をスキップし、モノリシックな ADR を生成
変更	サブシステムを調整してから続行
空欄／既定値	サブシステムが 3 つ以下なら自動で続行、3 つを超える場合は確認

しきい値ロジックの適用（必須 — 検出元にかかわらず、検出されたすべてのサブシステムに適用）：

サブシステム数	必須の対応	ユーザー確認を省略できるか？
0	モノリシックとして続行（分解なし）	はい
1-3	概要を提示。自動承認も可	はい
4-6	概要を提示し、ユーザーに確認を求めること	いいえ
>6	グループ化を提案し、確認を求めること	いいえ

適用ルール：

1. AI 分析でサブシステムを特定したものの、スクリプトが「検出なし」と報告した場合 → 特定したサブシステムにしきい値ロジックを適用します
2. しきい値が 4 以上の場合 → ユーザーの確認なしに続行してはいけません
3. このロジックを省略した場合 → ADR の生成は無効となり、誤ったアーキテクチャを生成するおそれがあります
4. フェーズ 1 の前に自己確認：ステップ 4 を提示しましたか？ しきい値ロジックを適用しましたか？ サブシステムが 4 つ以上の場合、確認を得ましたか？

ステップ 6：出力

確認後、構造化されたサブシステムデータを出力します。

{
  "decomposition": "enabled",
  "subsystems": [
    {"id": "auth", "name": "Auth", "detection_method": "directory", "evidence": "src/auth/"},
    {"id": "users", "name": "Users", "detection_method": "directory", "evidence": "src/users/"},
    {"id": "payments", "name": "Payments", "detection_method": "docker", "evidence": "payment service in docker-compose"}
  ],
  "next_phase": "Codebase Analysis (per sub-system)"
}

分解が無効の場合：

{
  "decomposition": "disabled",
  "reason": "user_requested",
  "next_phase": "Codebase Analysis (monolithic)"
}

---

フェーズ 1：コードベースの分析

目的：使用されているテクノロジーとパターンを把握します

注：サブシステムの分解が有効な場合（フェーズ 0）、焦点を絞った分析結果を得るため、各サブシステムを個別に分析します。

1. セットアップスクリプトを実行する：

   • {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh を実行して（architect-clarify スキルが必要です：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）、アーキテクチャファイルを初期化します。
   • スクリプトがコードベースをスキャンし、構造化された調査結果を出力します
   • 分解が無効な場合は --no-decompose を渡します
   • 分解されている場合：スクリプトは、対象を絞った分析に役立つサブシステムの内訳を出力します

2. テクノロジーの検出（サブシステムごと）：

   指標	テクノロジーカテゴリ	確認するファイル
   package.json	Node.js エコシステム	依存関係、スクリプト
   requirements.txt / pyproject.toml	Python エコシステム	依存関係
   pom.xml / build.gradle	JVM エコシステム	依存関係
   Cargo.toml	Rust	依存関係
   go.mod	Go	依存関係
   Dockerfile	コンテナ化	ベースイメージ、ステージ
   docker-compose.yml	コンテナオーケストレーション	サービス、ネットワーク
   *.tf / *.tfvars	Terraform/IaC	インフラストラクチャ
   kubernetes/*.yaml	Kubernetes	デプロイ設定
   .github/workflows/*	GitHub Actions	CI/CD

3. フレームワークの検出：

   パターン	フレームワーク	根拠
   from django のインポート	Django	Python の Web
   @SpringBoot	Spring Boot	Java の Web
   import express	Express.js	Node.js の Web
   import { Component }	React/Angular/Vue	フロントエンド
   from fastapi	FastAPI	Python API

4. データベースの検出：

   根拠	データベースの種類
   PostgreSQL の接続文字列	PostgreSQL
   MongoDB/mongoose のインポート	MongoDB
   Redis クライアントのインポート	Redis キャッシュ
   ORM のマイグレーション	リレーショナルデータベース
   DynamoDB SDK の使用	AWS DynamoDB

フェーズ 2：パターンの認識

目的：コード構造からアーキテクチャパターンを特定します

アーキテクチャスタイルの検出

パターン	根拠	ADR のトピック
モノリス	単一のデプロイ可能な構成、共有データベース	ADR：システムアーキテクチャスタイル
マイクロサービス	複数のサービス、サービスディスカバリー	ADR：システムアーキテクチャスタイル
モジュラーモノリス	単一のデプロイ、モジュールの境界	ADR：システムアーキテクチャスタイル
イベント駆動型	メッセージキューの使用、イベントハンドラー	ADR：通信パターン
サーバーレス	Lambda 関数、マネージドサービス	ADR：デプロイモデル

コード構成の検出

パターン	根拠
レイヤード	controllers/、services/、repositories/
機能ベース	ドメインごとの features/、modules/
クリーンアーキテクチャ	domain/、application/、infrastructure/
ヘキサゴナル	ports/、adapters/

API スタイルの検出

パターン	根拠
REST	ルートデコレーター、HTTP メソッド、リソース URL
GraphQL	スキーマファイル、リゾルバー、gql のインポート
gRPC	.proto ファイル、gRPC クライアント／サーバーの設定
WebSocket	Socket.io、WebSocket ハンドラー

フェーズ 3：ドキュメントの重複排除

目的：既存のドキュメントをスキャンし、記載済みの情報を重複して記述しないようにします

スキャン対象：

• AGENTS.md - プロジェクトのコンテキスト、概要
• {TEAM_AI_DIRECTIVES}/AGENTS.md - チーム全体のエージェント使用手順（設定されている場合）
• README.md - 技術スタック、プロジェクトの説明
• CONTRIBUTING.md - 開発ガイドライン
• AD.md または docs/architecture.md - 既存のアーキテクチャ
• LICENSE - 法的コンテキスト

重複排除ルール：

検出内容	対応
README に技術スタックの記載がある	ADR から README を参照し、重複記載しない
アーキテクチャが存在する	自動的にマージするか、更新するか新規作成するかを確認する
CONTRIBUTING にガイドラインがある	開発ビューから参照する
AGENTS.md にコンテキストがある	コンテキストビューからリンクする
チーム向け指示が AGENTS.md にある	チーム全体のエージェント使用手順として参照する

手順：

1. {REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh を実行します（architect-clarify スキルが必要です：adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify）。このスクリプトは scan_existing_docs() を呼び出します
2. JSON 出力から検出結果を解析します
3. 各検出結果について、ADR をスキップするか、既存の情報を参照するか、新規に記録するかを判断します
4. 「既存のドキュメントで X 件の意思決定をカバーし、Y 件の新しい ADR を作成しました」と報告します

フェーズ 4：ADR の生成

目的：検出した意思決定を ADR として記録します

検出したアーキテクチャ上の意思決定ごとに、次の手順を実施します。

1. 意思決定を特定する：

   • 選択されたテクノロジーやパターンは何ですか？
   • これが構築された時点で、どのような代替案がありましたか？
   • どのような要因がこの意思決定を促したと考えられますか？

2. ADR エントリーを作成する（MADR 3.0.0 — ../templates/adr-template.md を参照）：

---
status: discovered  # inferred from codebase (brownfield)
date: YYYY-MM-DD
decision-makers: [Legacy/Inferred]
consulted: []
informed: []
sub-system: System
---

# {Discovered Decision}

## Context and Problem Statement
[Inferred problem statement based on code patterns]

**Evidence Found**:
* [File/pattern evidence 1]
* [File/pattern evidence 2]

## Decision Drivers
* {inferred driver 1}
* {inferred driver 2}

## Considered Options
* {Likely Alternative}
* {Discovered choice}

## Decision Outcome
Chosen option: "{Discovered choice}", because {inferred rationale from implementation}.

### Consequences
* Good, because {benefit visible in codebase}
* Bad, because {trade-off inherent to this choice}
* Bad, because {risk if this decision is not well understood}

### Confirmation
{How compliance can be confirmed in the codebase}

## Pros and Cons of the Options
### {Likely Alternative}
* Good, because {argument}
* Bad, because {argument}
← DO NOT fabricate rejection rationale - we don't know why it wasn't chosen

## More Information
**Confidence Level**: [HIGH/MEDIUM/LOW] - [Explanation of confidence in inference]

3. 生成する ADR のカテゴリ（意外性の価値に基づくヒューリスティックを適用）：

   明白な場合はスキップ（ヒューリスティック：意外性があるか）：

   • リレーショナルデータに PostgreSQL を使用 → エコシステムのデフォルトでカバーされる
   • SPA フロントエンドに React を使用 → 標準的なフレームワークの選択
   • コンテナ化に Docker を使用 → 一般的な選択

   ADR として記録する：

   • ADR-001：システムアーキテクチャのスタイル（モノリスかマイクロサービスか）
   • ADR-002：データベースの選択（コンテキスト上、明白でない場合のみ）
   • ADR-003：API のスタイル（REST か GraphQL か gRPC か）
   • ADR-004：フロントエンドフレームワーク（慣例的でない場合のみ）
   • ADR-005：デプロイプラットフォーム（サーバーレスか従来型か）
   • ADR-006：CI/CD の方法（GitHub Actions か Jenkins か）
   • 追加：カスタム／社内ソリューション、一般的でないパターン、リスクの高い選択

フェーズ 5：品質要件の検出

目的：コードベースの証拠から、該当する R&W の視点を検出します

品質要件を示す要素がないか、コードベースをスキャンします。

証拠	検出される視点
ヘルスチェック、サーキットブレーカー、再試行ロジック	可用性
プラグインシステム、機能フラグ、拡張ポイント	進化性
GDPR／HIPAA に関するコメント、監査ログ、同意の追跡	規制
ARIA 属性、スクリーンリーダーのサポート	アクセシビリティ
i18n ファイル、ロケール処理、翻訳キー	国際化
マルチリージョン設定、地理的ルーティング、CDN 設定	ロケーション
広範な UI テスト、UX リサーチの成果物	ユーザビリティ
README に記載されたリソース制約、限られた CI ランナー	開発リソース

検出された視点を提示して確認を求めます：

## Quality Requirements Detected

Based on codebase analysis, the following quality perspectives may apply:

| Perspective | Evidence Found | Include? |
|-------------|----------------|----------|
| Security | Always recommended | ✓ (default) |
| Performance | Always recommended | ✓ (default) |
| Availability | Circuit breakers found | [Y/N] |
| Evolution | Feature flags found | [Y/N] |
| Regulation | GDPR comments found | [Y/N] |
| Accessibility | Not detected | [Y/N] |
| Internationalization | i18n files found | [Y/N] |
| Location | Multi-region config | [Y/N] |
| Usability | UI tests found | [Y/N] |
| Development Resource | Not detected | [Y/N] |

Please confirm which perspectives to document.

選択された視点を /architect-implement 用の状態に保存します。

4. サブシステム別の整理（フェーズ 0 の分解が有効な場合）：

   出力ファイル内で、サブシステムごとに ADR を整理します。

   # Architecture Decision Records
   
   ## ADR Index
   
   | ID | Sub-System | Decision | Status | Date | Confidence |
   |----|------------|----------|--------|------|------------|
   | ADR-001 | System | Monolithic Architecture | Discovered | 2026-02-26 | HIGH |
   | ADR-002 | Auth | JWT Authentication | Discovered | 2026-02-26 | HIGH |
   | ADR-003 | Payments | Stripe Integration | Discovered | 2026-02-26 | MEDIUM |
   
   ---
   
   ## System-Level ADRs
   
   ### ADR-001: Monolithic Architecture
   [Full ADR content...]
   
   ---
   
   ## Auth Sub-System ADRs
   
   ### ADR-002: JWT Authentication
   [Full ADR content...]
   
   ---
   
   ## Payments Sub-System ADRs
   
   ### ADR-003: Stripe Integration
   [Full ADR content...]
   

   • インデックス内で各 ADR に親サブシステムを指定します
   • 各サブシステムのセクション見出しを追加します
   • 複数の領域にまたがるパターン（例：共有データベース）は、システムレベルとして記録します

フェーズ 6：ギャップ分析

目的：意思決定が不明確な領域を特定します

スキャン後、次の内容を報告します。

## Architecture Discovery Report

### Technologies Detected
| Category | Technology | Confidence | Evidence |
|----------|------------|------------|----------|
| Backend | Django 4.2 | HIGH | requirements.txt, app structure |
| Database | PostgreSQL | HIGH | connection strings, migrations |
| Frontend | React 18 | MEDIUM | package.json, JSX files |
| Cache | Redis | HIGH | redis imports, docker-compose |

### Documentation Deduplication
✓ README.md: Tech stack documented (lines 20-45)
  → Referenced in Context View, skipping tech stack ADRs
✓ CONTRIBUTING.md: Development workflow documented
  → Referenced in Development View 3.5

### ADRs Generated (Surprising/Risky decisions only)
| ID | Decision | Confidence | Why Documented |
|----|----------|------------|----------------|
| ADR-001 | Monolithic Django architecture | HIGH | Architecture style choice |
| ADR-002 | Custom JWT authentication | MEDIUM | Security risk, non-standard |
| ADR-003 | Microservices for small team | HIGH | Scale mismatch, surprising |

### Skipped (Covered by existing docs or obvious)
| Decision | Reason |
|----------|--------|
| PostgreSQL choice | Ecosystem default + README covers |
| React frontend | Standard framework + README covers |
| Docker containerization | Conventional choice |

### Unclear Areas (Need Human Input)
| Area | Question | Suggestion |
|------|----------|------------|
| Auth | OAuth2 or custom JWT? | Found JWT usage, need confirmation |
| Caching | Redis strategy unclear | Cache-aside pattern inferred |
| Scaling | Horizontal scaling setup? | No auto-scaling config found |

### Recommended Clarifications
1. Run `/architect-clarify` to refine ADRs with human input
2. Focus on [specific unclear area]
3. Consider documenting [undocumented pattern]

Phase 7: 出力の生成

目的: 発見した ADR をファイルに書き込む（AD.md は作成しません）

重要: このスキルで生成する ADR のステータスは、必ず「Discovered」にしてください。 ステータスを直接「Accepted」に設定してはいけません。承認ワークフローは次のとおりです。 init（Discovered）→ clarify（レビュー）→ clarify Phase 5.5（Accepted）→ implement

init 中に ADR の承認を明示的に求められた場合は、代わりに /architect-clarify を実行するよう案内してください。

書き込み前に、既存の ADR を確認します。

1. ハイブリッド ADR ディレクトリが存在するか確認します: {REPO_ROOT}/.adlc/drafts/adr/
2. ディレクトリが存在する場合:
   • 個別ファイルから既存の ADR を読み込みます
   • 既存の ADR を上書きしたり削除したりしないでください
   • 新たに発見した内容は、新しい ADR-{NNN}.md ファイルとして書き込みます
   • 次のように報告します: "既存の ADR が N 件見つかりました。新たに M 件の発見事項を追加します"
3. ディレクトリが存在しない場合: セットアップスクリプトが作成します

ADR を書き込みます:

1. 発見した ADR ごとに {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md を作成します
2. ADR のステータスを「Discovered (Inferred)」と記載します ← このステータスのみ使用してください
3. 「Rejected because」を使わず、中立的なトレードオフを記載した「Common Alternatives」セクションを使用します
4. ADR ごとに信頼度を記載します
5. 検証が必要な仮定にはタグを付けます

AD.md は作成しないでください:

• Architecture Description は後で /architect-implement によって生成されます
• ADR が確認を通じて検証された後にのみ生成されます

概要を生成します:

• 発見したテクノロジー
• 信頼度とともに作成した ADR
• 保持した既存の ADR（存在する場合）
• 特定した不足事項
• 行った仮定（clarify フェーズで検証するもの）

Phase 8: Clarify で検証する

目的: ブラウンフィールドの調査結果をユーザーと検証します

ADR の生成後、ブラウンフィールドのコンテキストを使用して /architect-clarify を実行し、検証します。

Clarify で尋ねる質問（ブラウンフィールド固有）:

質問の種類	例
現状の妥当性	「docker-compose.yml でマイクロサービスを検出しました。これは現在も採用している方式ですか？」
決定の理由	「PostgreSQL が使われています。特定の要件に基づいて選択されましたか、それとも引き継いだものですか？」
チームの状況	「git の履歴から、チームは小規模のようです。現在のアーキテクチャ上の決定は適切ですか？」
技術的負債	「独自の認証方式が見つかりました。OAuth/OIDC への移行を検討していますか？」
移行計画	「X モジュールでレガシーパターンを検出しました。モダン化の計画はありますか？」
非推奨のパターン	「サービス分離の兆候があるモノリシックなデプロイ構成です。マイクロサービスへの移行を計画していますか？」

Clarify に渡すコンテキスト:

{
  "source": "brownfield",
  "tech_stack_detected": ["detected technologies"],
  "inferred_decisions": ["list of ADRs with confidence levels"],
  "assumptions": ["things that need validation"],
  "files_analyzed": "count"
}

/architect-clarify を実行して、入力に基づき ADR を改善し、その後 /architect-implement を実行して完全な AD.md を生成します。

主なルール

エビデンスに基づくドキュメント化

• コード内で見つかった内容のみを記載します。決定を捏造しないでください
• ADR ごとに具体的なエビデンスを引用します
• 信頼度を正直に記載します
• 不確実な点を明示します

信頼度

レベル	基準
高	明確なエビデンスが複数あり、選択が曖昧でない
中	エビデンスはあるものの、異なる解釈が可能
低	エビデンスが限られており、不確実性が大きい

非破壊的な変更

• ユーザーの承認なしに既存の ADR を上書きしないでください
• 既存のドキュメントと適切に統合します
• アーキテクチャファイルへの手動追加を保持します

却下理由を捏造しない

• リバースエンジニアリングした ADR に対して「Rejected because」の理由を決して捏造しないでください
• 中立的な「Trade-offs」の観点で「Common Alternatives」を使用します
• 検討された可能性が高い代替案のみを記載します
• 正直に記載します。「なぜ X が選ばれなかったのかは分かりません」としても問題ありません

必要に応じた対話

• 信頼度が低い発見事項については、ユーザーに確認を求めます
• 矛盾するエビデンスがある場合は、選択肢を提示します
• 不足事項がある場合は、確認のための質問を提案します

サブシステムの分解

• コードから自動検出：ディレクトリ構造、パッケージ、サービスを自動的に分析します
• 対話形式での確認：サブシステムの分割内容を必ずユーザーに確認します
• 適切な粒度：サブシステムは3～7個を目安とし、過度な分割は避けます
• 明確な根拠：各サブシステムの根拠として、具体的なディレクトリやモジュールを挙げます
• サブシステムごとの分析：サブシステムごとにパターンを検出し、焦点を絞ったADRを作成します
• 横断的なパターン：システム全体にわたるパターンを検出し、個別に記録します
• --no-decompose を使用：シンプルまたは小規模なコードベースでは分解をスキップします

ワークフローのガイダンスと移行

/architect-init の後

必須：ブラウンフィールドの調査結果を検証するため、/architect-clarify を実行します。

確認が完了したら：

1. 検証済みのADRを確認：{REPO_ROOT}/.adlc/drafts/adr/adr.md の内容が正確であることを確認します
2. ADRを承認：/architect-clarify のフェーズ5.5を実行し、ステータスを「Accepted」に変更します
3. /architect-implement を実行：Accepted 状態のADRから完全な AD.md を生成します

ブラウンフィールドの一連のフロー

/architect-init "Node.js API, team of 2"
    ↓
[Scan codebase] → Detect technologies, patterns
    ↓
[Generate ADRs] → Write to {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md (marked "Discovered")
    ↓
[Run /architect-clarify] → Ask to validate decisions
    ↓
[Clarify asks] → "Is microservices decision still valid?"
                 "Custom auth detected - considering OAuth?"
    ↓
[Approve ADRs] → Phase 5.5 to change status to "Accepted"
    ↓
[Run /architect-implement] → Generate AD.md from Accepted ADRs
    ↓
[Generate AD.md] → Full architecture description

コンテキスト

$ARGUMENTS

次のステップ

init が完了したら、検出されたADRを検証し、実装に向けて承認するために /architect-clarify を実行します。

検証

• ADRが {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md に Discovered (Inferred) のステータスで書き込まれている。
• 自動生成された adr.md インデックスが {REPO_ROOT}/.adlc/drafts/adr/ に存在する。
• ギャップ分析レポートで、不明確な領域と推奨される確認事項が特定されている。
• しきい値のルールに従って、サブシステムの分解が確認済み（または無効化済み）である。
• 明示的な承認なしに既存のADRが上書きされていない。