accelint-architecture-doc

アーキテクチャドキュメント

現在のコードベースを対象に、継続的に更新される ARCHITECTURE.md を生成または更新します。エージェントやエンジニアが、システム構造、技術スタック、デプロイモデルをすばやく、かつ完全に把握できるようにします。

アーキテクチャドキュメント作成時のガードレール

• まず既存の内容を読まずに ARCHITECTURE.md を上書きしてはなりません — 既存のセクションには、デプロイの詳細、セキュリティ上の決定事項、ロードマップに関するメモなど、コードベースのスキャンでは復元できない人間が作成した情報が含まれている可能性があります。ファイルに手を加える前に、必ず内容を読んでください。
• インフラの詳細を捏造してはなりません — コードベースからクラウドプロバイダー、デプロイモデル、データストアを特定できない場合は、推測せずに `` と記載してください。インフラの誤ったドキュメントは、インシデント発生時に深刻な混乱を招きます。
• ディレクトリツリー全体をそのまま貼り付けてはなりません — Project Structure セクションでは、すべてのファイルではなく、意味のあるアーキテクチャレイヤーを示してください。ノイズの多いディレクトリ（node_modules、dist、.git、__pycache__）は折りたたみ、各項目の役割を注記してください。
• 更新モードで変更の検出を省略してはなりません — インタビューを始める前に、コードベースをスキャンして変更の兆候を確認してください。変更のないセクションについて質問すると、ユーザーの時間を無駄にします。
• 11 個すべてのセクションを `` のままにしてはなりません — まず徹底的にスキャンしてください。ほとんどのセクションは、推論によって少なくとも一部を記入できます。TODO ばかりのドキュメントは完成しているように見え、読む人を誤解させます。
• System Diagram（Section 2）に内部実装の詳細を記載してはなりません — このセクションでは、コンポーネントとデータフローを俯瞰できるようにします。データベーススキーマ、関数シグネチャ、モジュール内部の詳細は、別の場所に記載してください。
• サブエージェントを利用できる場合、Stage 2 の調査では並列サブエージェントを必ず使用してください — 調査領域ごとに、同時にサブエージェントを起動してください。順番にスキャンしてはなりません。サブエージェントを利用できない場合は、対象を絞ったインライン調査を行ってください。

作成前に確認すること

作業を始める前に、次の点を確認してください。 順番に実施してください。

リポジトリのルートですか、それともパッケージレベルですか？

• リポジトリのルートにいますか、それともモノレポのパッケージ内にいますか？ pnpm-workspace.yaml、turbo.json、nx.json、lerna.json、または package.json の workspaces フィールドを確認してください。パッケージ内にいる場合は、ルートレベルの ARCHITECTURE.md がすでに存在するかも確認してください。
• ルートレベルのドキュメントは、すべてのサービス、共有インフラ、トップレベルのアーキテクチャなど、システム全体を対象とします。パッケージレベルのドキュメントはそのパッケージに焦点を当て、ルートのドキュメントを参照します。

新規作成、再構成、更新のどれですか？

• ARCHITECTURE.md はすでに存在しますか？ 存在する場合は、スキャンの前に内容を読んで、正確な情報と古くなっている情報を把握してください。
• テンプレートに準拠していますか？ 準拠していない場合は、ファイル構成を変更する前に、再構成を提案してください。

推論できることと、質問が必要なことは何ですか？

• 調査では、サブエージェントを利用できる場合は並列で使用してください。 調査領域ごとに、同時にサブエージェントを起動してください。順番にスキャンしてはなりません。サブエージェントを利用できない場合は、対象を絞ったインライン調査を行ってください。
• 質問は、本当に情報が不足している点に限ってください。 たとえば、コードに記載されていないデプロイの詳細、ロードマップの項目、セキュリティ上の決定事項などです。

ワークフロー

Stage 0: 進捗を記録する

目的：新規作成、更新、再構成の作業中に、ワークフローの状態を確認できるようにします。

Step 0: 進捗の記録を開始する

新規作成、更新、再構成が必要なタスクでは、他のステージの作業を始める前に実施してください。 作業中の状態または返信に、簡潔な進捗チェックリストを作成してください。各ステージの完了後に更新してください。

• Step 1: 対象範囲と関連ファイルを特定する
• Step 2: モードを特定し、適切なゲートを適用する
• Step 3: 調査を実行し、調査結果を統合する
• Step 4: 対象を絞ったインタビューの質問をする
• Step 5: プレビューを提示し、確認を待つ
• Step 6: 承認されたファイルを書き込み、未解決の TODO をまとめる

完了条件：チェックリストが存在し、各ステージの後に更新されること。

ステージ 1：スコープとモードの検出

目的：スコープを判断し、関連ファイルを検出し、探索やインタビューを始める前に適切なモードのゲートを有効にします。

ステップ 1：スコープと関連ファイルの検出

現在の作業ディレクトリがモノレポのルートか、モノレポ内のパッケージかを判断します。 モードを検出する前に実行してください。

確認するモノレポの兆候：

兆候	ファイル
PNPM ワークスペース	pnpm-workspace.yaml
npm/Yarn ワークスペース	package.json → workspaces フィールド
Turborepo	turbo.json
Nx	nx.json
Lerna	lerna.json
モノレポ内のパッケージ	親ディレクトリに上記のいずれかがある

モノレポのルートにいる場合：

• システム全体（すべてのサービス、共有インフラ、パッケージ間の関係）を網羅するルートレベルの ARCHITECTURE.md を生成します。
• セクション 3（コアコンポーネント）では、リポジトリを単一のアプリとして扱わず、重要なパッケージごとにサブセクションを作成します。
• セクション 1（プロジェクト構造）では、各パッケージの役割を注記したワークスペースのレイアウトを示します。

モノレポ内のパッケージにいる場合：

1. 現在のディレクトリより上に、ルートレベルの ARCHITECTURE.md があるか確認します。
2. ルートレベルのドキュメントがある場合は、それを読み、次のように伝えます。

   「[path] にルートレベルの ARCHITECTURE.md が見つかりました。これをコンテキストとして使用し、共有インフラの重複を避けて、ここにパッケージ固有のドキュメントを生成します。」 パッケージレベルのドキュメントには、次のヘッダー参照を含めます。

3. ルートレベルのドキュメントがない場合は、先に生成するか、パッケージレベルのドキュメントを単独で生成するかを提案します。
4. パッケージレベルのドキュメントでは、このパッケージの目的、内部構造、他のパッケージへの依存関係、パッケージ固有のデプロイまたは設定の詳細に焦点を当てます。

モノレポではない場合： 通常どおり進めます。ARCHITECTURE.md はプロジェクト全体を対象とします。

デフォルトのスコープルール： パッケージディレクトリ内から呼び出された場合、ユーザーがリポジトリ全体のドキュメントを明確に求めていない限り、パッケージレベルの ARCHITECTURE.md が必要だと判断します。ルートとパッケージの両方のドキュメントがない場合は、独断で対象を広げず、デフォルトでローカルパッケージのスコープを維持します。

ステップ 1.1：関連ドキュメントの確認

要件：ステップ 1 のスコープ検出が完了していること。

ARCHITECTURE.md の状態を検出する前に実行してください。

1. openspec/config.yml または openspec/config.yaml を確認します。
   • ファイルがある場合は読み込み、ランタイム、フレームワーク、ライブラリ、パターンなどのスタック情報を抽出します。
   • これらの情報を使用して技術スタックのセクションをあらかじめ埋め、重複したスキャンを減らします。
   • 生成するドキュメントで相互参照するファイルとして記録します。
   • 次のように伝えます。「openspec/config.yml が見つかりました。スタック情報とコーディングパターンの信頼できる情報源として使用します。」

このステップによりスキャン作業が減り、ドキュメントをプロジェクトで定義されているスタックと一貫させやすくなります。

完了条件：openspec/config.yml または openspec/config.yaml があるかどうかを把握し、存在する場合は読み込んでいること。

ステップ 2：モードを判定し、適切なゲートを適用する

前提：ステップ 1 とステップ 1.1 が完了していること。

次の順序でタスクを分類します。

1. 対象の場所に ARCHITECTURE.md があるか確認します。
   • ない場合は、MODE 1: Create に進み、ステージ 2 → ステージ 3 → ステージ 4 を最後まで実行します。
2. ある場合は、分類する前にファイルをすべて読みます。
3. 既存ファイルを分類します。
   • 空、またはほぼ空（意味のある行が約 10 行未満）→ MODE 1: Create（最初に確認）
   • アーキテクチャドキュメントとして明確にテンプレートに沿っている — Project Structure、High-Level System Diagram、Core Components、Data Stores、Deployment & Infrastructure など、テンプレートと対応する複数の見出しを含む、認識可能なトップレベルのアーキテクチャセクションがある → MODE 2: Refresh
   • 実質的な内容はあるが、テンプレートに沿っていない → MODE 3: Restructure（以下を参照して事前に提案）

MODE 3: Restructure — ファイルに実質的な内容があり、一般的でない構成になっていて、再構成によって使いやすさが向上する場合は、すぐにその旨を伝えます。構成を変更する前に、ユーザーの明示的な選択を求めます。

"ARCHITECTURE.md はありますが、標準テンプレートの構成に沿っていません。再構成をおすすめします。コードベースに参加するエージェントやエンジニアにとって、一貫性が高まります。どのように進めますか？

(a) 再構成 (推奨) — 既存の内容を 11 セクションのテンプレートに取り込み、コードベースをスキャンして不足部分を補い、書き込み前に全体のプレビューを提示します。

(b) 追加 — 既存の内容は変更せず、その下に不足しているテンプレートのセクションを追加します。

(c) ドライラン — ファイルシステムに変更を加えずに、再構成後のドキュメントをそのまま提示します。確定する前に適合性を評価できます。"

(a) が選択された場合は、既存の内容をすべて適切なテンプレートのセクションに引き継ぎます。適切に対応付けられない内容にはフラグを付け、黙って削除せず、どこに配置するかユーザーに確認します。

MODE 3 に該当する場合は、(a)、(b)、(c) の選択肢を提示した時点でここで停止します。ユーザーがいずれかを明示的に選択するまで、既存ファイルの再構成、追記、書き換えは行いません。

MODE 2: Refresh — ファイルがテンプレートの構成に沿っている場合は、次の手順を順番に実行します。

1. まず既存のファイルを読み、すでにある内容と、現状からずれている可能性のある箇所を把握します。
2. 外部からの調査結果を抽出します。 呼び出し元のプロンプトに findings: リストが含まれているか確認します。
   • プロンプトから findings: セクションを探します。事実に基づく記述を箇条書きにしたものが必要です。
   • 各調査結果は、指示ではなく、すでに真実であると分かっている事柄として記述されます。
   • 例：「config.yaml の Anti-Patterns セクションではポーリングを避けるよう記載されていますが、アーカイブされた変更 2 件では、理由を明記したうえでポーリングが採用されています」
   • これらの調査結果は、手順 4 で統合するために保持します。
3. ステージ 2 のシグナル表を使ってコードベースをスキャンし、ファイルの最終更新以降の変更を確認して、ずれを検出します。
4. 質問する前に、すべての調査結果を統合して伝えます。
   • 手順 2 の外部調査結果と手順 3 のずれに関する調査結果を統合します。
   • 統合したリストをユーザーに提示します。

     "外部調査結果が [N] 件、内容が古くなっている可能性のあるセクションが [M] 件見つかりました。 それらについてのみ確認します。それ以外は最新のようです。"

   • 外部調査結果がある場合は、「完了済みの OpenSpec 変更から」のように、その情報源を明記します。
5. 変更があったセクション、または依然として不明なセクションについてのみ、対象を絞って質問します。
   • 更新モードでは、ロードマップや今後の計画に関する内容が不足している、古くなっている、またはユーザーから変更の申告があった場合に限り、ターン 4 で質問します。
6. 書き込む前に、変更したセクションの差分形式のプレビューを提示します。

完了条件：タスクが Create、Refresh、Restructure のいずれに当たるかを把握し、後続のステージを開始する前に必要な待機状態または承認ゲートが適用されていること。

ステージ 2：調査

目的：不足している事実についてユーザーに尋ねる前に、統合された調査マップを作成します。

ステージのルール：

• サブエージェントを利用できる場合は、並行して使用します。
• 調査領域をまたいで、同時に起動します。順番に調査しないでください。
• サブエージェントを利用できない場合は、対象を絞って直接調査します。
• ステージ 3 の前に、調査結果を統合します。

ステップ 3：調査を実施し、結果を統合する

前提条件：ステップ 2 が完了しており、MODE 3 の待機状態があれば解消されていること。

以下の調査領域について、構造化された調査結果を収集します。 調査結果を統合するまで、ステージ 3 を開始しないでください。

サブエージェントを利用できる場合、同時に調査する領域：

エージェント A — プロジェクトの識別情報と構成

• README.md、package.json / pyproject.toml / go.mod / Cargo.toml を読み、プロジェクト名と説明を確認する
• ディレクトリツリーの上位 2～3 階層を一覧表示する（node_modules、dist、.git、__pycache__、.next、build は除外）
• モノレポのワークスペースパッケージとその役割を特定する
• AGENTS.md または CLAUDE.md があるか確認する（見つかった場合はパスを記録する — ステージ 4 で使用）
• 返す内容：プロジェクト名、目的を一文で示したもの、注釈付きディレクトリ構成、エージェント向けドキュメントのパス（または該当なし）

エージェント B — 技術スタックとコンポーネント

• package.json（フロントエンドとバックエンドの依存関係）、requirements.txt / pyproject.toml、go.mod、Cargo.toml、build.gradle
• フレームワーク設定ファイル：next.config.*、vite.config.*、nuxt.config.*、angular.json、svelte.config.*
• バックエンドのエントリーファイル：server.ts、app.py、main.go、Application.java、config/application.rb
• docker-compose.yml — サービス、ポート、環境変数、サービス間の依存関係
• 返す内容：フロントエンド技術、バックエンド技術、主要ライブラリ、ポート付きのサービス一覧

エージェント C — インフラ、CI/CD、デプロイ

• IaC：terraform/、pulumi/、cdk/、serverless.yml、k8s/ または kubernetes/
• コンテナ設定：サービスごとの Dockerfile*、デプロイ設定としての docker-compose.yml
• CI/CD：.github/workflows/、.circleci/、Jenkinsfile、.gitlab-ci.yml、Procfile
• クラウド関連の手がかり：*.aws.json、.aws/、gcp/、azure/、Dockerfile のベースイメージ
• モニタリング：Datadog、Sentry、Prometheus、Grafana、CloudWatch の設定または依存関係
• 返す内容：クラウドプロバイダー（推定または不明）、主要なマネージドサービス、CI/CD プラットフォーム、モニタリングスタック

エージェント D — データ、セキュリティ、外部 API

• データストア：prisma/schema.prisma、alembic/、migrations/、ORM 設定、.env.example の DATABASE_URL、Redis/Kafka/RabbitMQ の依存関係
• 認証／セキュリティ：認証ミドルウェアファイル、JWT/OAuth/SAML/OIDC の依存関係、シークレットマネージャー（Vault、AWS Secrets Manager、Doppler）、HTTPS 設定、WAF 設定
• 外部連携：.env.example のキー接頭辞（STRIPE_、SENDGRID_、TWILIO_、OPENAI_ など）、依存関係に含まれる SDK パッケージ
• 返す内容：データストアの一覧（名前、種類、目的）、認証方式、外部サービス一覧

エージェント E — テストとコード品質 (他のエージェントと並行して実行できます)

• テスト設定：jest.config.*、vitest.config.*、pytest.ini、pyproject.toml [tool.pytest]、Playwright 設定、Cypress 設定
• コード品質：.eslintrc*、biome.json、.prettierrc*、mypy.ini、ruff.toml、sonar-project.properties
• ローカル環境のセットアップ：Makefile、CONTRIBUTING.md、docker-compose.yml の開発用ターゲット
• 返す内容：テストフレームワーク、コード品質ツール、ローカル環境のセットアップコマンド

すべてのエージェントが完了したら、調査結果を統合して、統一された調査マップを作成します。各項目には INFERRED [source] または UNKNOWN のタグを付けます。UNKNOWN の項目はステージ 3 の質問になります。 この統合マップができるまでは、インタビューの質問をしてはいけません。

完了条件：統合された調査マップがあり、インタビューで質問が必要な項目を把握していること。

ステージ 3：的を絞ったインタビュー

目的：調査では特定できなかった不足情報のみを解決します。

ステージのルール：

• 不足している情報のみを尋ねます。すべての質問を一度に尋ねてはいけません。

ステップ 4：対象を絞った質問をする

前提条件：ステップ 3 が完了していること。

関連する質問を、自然な会話の流れでまとめてください。 残っている不明点に該当する質問だけをします。

ターン 1 — コンポーネントの不明点 (サービスやコンポーネントが不明確な場合)

• ディレクトリ構造からは把握しにくいサービスやコンポーネントはありますか？
• スキャンで見つからなかった外部サービス（サードパーティの SaaS、社内共通プラットフォームなど）はありますか？

ターン 2 — インフラストラクチャとデプロイ (クラウドプロバイダーまたはデプロイモデルが UNKNOWN の場合のみ)

• 使用しているクラウドプロバイダーと主要なマネージドサービスは何ですか？
• サービスはどのようにデプロイされていますか？（VM、コンテナ、サーバーレス、PaaS など）
• 監視とログ記録のスタックは何ですか？

ターン 3 — セキュリティ (認証方式が UNKNOWN の場合のみ)

• 認証方式は何ですか？（OAuth2、JWT、セッション Cookie、API キー、SSO など）
• 認可モデルは何ですか？（RBAC、ACL、ポリシーベースなど）
• 特筆すべきセキュリティツールや監査慣行はありますか？

ターン 4 — ロードマップと今後の計画 (必ず質問すること — 推測では把握できません)

• 文書化しておくべき、予定されているアーキテクチャの変更や移行はありますか？
• アーキテクチャに影響する、既知の技術的負債はありますか？

ターン 5 — 識別情報と用語集 (README または package.json に記載がない場合)

• 主な連絡先またはチーム名は何ですか？
• 定義が必要な、プロジェクト固有の用語や略語はありますか？

完了条件：残っている不明点すべてに回答があるか、未解決の不明点がプレビュー内で `` として示されていること。

ステージ 4：プレビューと書き込み

目的：書き込み前にプレビューの確認を必須とし、承認されたファイルを書き込んで、未解決の TODO を要約します。

ステージのルール：

• プレビューは単なる配慮ではなく、必須の確認段階として扱ってください。

ステップ 5：プレビューを表示して確認を待つ

前提条件：ステップ 4 が完了しているか、ステップ 3 ですでにすべての不明点が解消されていること。

1. 書き込み前に、ARCHITECTURE.md の全内容を、ラベル付きのプレビューとして表示します。
   • 自動検出された値には # inferred from [file] を付けます。
   • 未解決の項目には `` を付けます。
2. 次のように尋ねます："この内容でよろしいですか？書き込む前に修正すべきセクションはありますか？"
3. 明示的な確認を待ちます。

選択したモードのプレビューを表示し、続行の確認を受け取るまでは、ARCHITECTURE.md、AGENTS.md、または CLAUDE.md を書き込んだり編集したりしないでください。 沈黙、部分的なフィードバック、または暗黙の承認を、確認として扱わないでください。

完了条件：ユーザーがプレビューを確認し、書き込みを許可することを明示的に確認していること。

ステップ 6：承認されたファイルを書き込み、未解決の TODO を要約する

前提条件：ステップ 5 が完了していること。

1. 対象の場所（ルートまたはパッケージディレクトリ）に ARCHITECTURE.md を書き込みます。
   • 推測の根拠を示すコメントを削除します。これらは確認用であり、最終ファイルには含めません。
   • openspec/config.yml の参照について： ステップ 1.1 で確認したとおり、ファイルが実際に存在する場合に限り含めます。存在しないファイルへの参照は追加しないでください。
2. エージェントの動作に関するドキュメントがあれば更新します。 Agent A が AGENTS.md または CLAUDE.md を見つけた場合、ARCHITECTURE.md への参照があるか確認します。参照がない場合は、エージェントがシステム構造を理解しやすくするための参照ブロックを追加します。以下で説明するとおり、アーキテクチャドキュメント自体が完成した後に行う、二次的なフォローアップ編集として扱ってください。
3. 推測した内容、直接回答を得た内容、および人による入力が引き続き必要な `` セクションを簡潔に要約して出力します。

完了条件：承認されたファイルが書き込まれ、残りの TODO が要約されていること。

対話の原則

• 並行して調査する。 サブエージェントを利用できる場合は、ステージ 2 で同時に起動します。その場合、設定ファイルを一つずつ確認しないでください。
• まず調査し、次に質問する。 サブエージェントでは埋められない実際の不足情報についてのみ、ヒアリングの質問をします。
• デフォルトで再構成する。 ファイルがテンプレートに従っていない場合は、再構成を推奨し、選択肢 (c) を末尾に埋もれさせるのではなく、選びやすい選択肢にします。
• モノレポを考慮する。 ルートのドキュメントとパッケージのドキュメントは、対象読者が異なります。それぞれの対象範囲を適切に保ち、相互に参照します。
• 見つかった内容を知らせる。 更新モードでは、質問する前に何が乖離していたかをユーザーに伝えます。
• 書き込む前にプレビューする。 生成したドキュメント全体を必ず表示し、ファイルシステムに変更を加える前に承認を得ます。
• 質問する前に推測し、省略する前に質問する。 明示的な `` マーカーがあるドキュメントは対応可能です。セクションが欠けたドキュメントは、気づかれないまま誤解を招きます。
• 人が作成した内容を保持する。 更新モードでは、内容を黙って削除しないでください。その内容を提示し、引き続き正確かどうかを確認します。
• 書き込みのたびに日付を設定する。 書き込みのたびに、セクション 10 の「最終更新日」を今日の日付に設定します。

出力テンプレート

完全な 11 セクションの ARCHITECTURE.md の骨組みについては、references/template.md を読み込みます。

モノレポのパッケージドキュメント： 冒頭の見出しの直後に、以下を記載します。

相対パスを調整し、実際のルート ARCHITECTURE.md を指すようにします。

エージェント動作ドキュメントの更新

ARCHITECTURE.md はシステム構造に関する技術ドキュメントです。エージェント動作ファイルから参照しないでください。AGENTS.md や CLAUDE.md などのエージェント動作ファイルから ARCHITECTURE.md を参照してください。システム構造がエージェントの動作に関係する場合があるためです。

ARCHITECTURE.md の書き込み後、エージェント A が AGENTS.md または CLAUDE.md を見つけていた場合は、次の順に実行します。

1. エージェント動作ファイルを読み、 すでに ARCHITECTURE.md に言及しているか確認します。
2. CLAUDE.md を使用していて、 たとえば @AGENTS.md のように、単に AGENTS.md を指している場合は、代わりに AGENTS.md を更新します。ポインターファイルは変更しないでください。ポインターファイルはルーティング用のスタブであり、アーキテクチャのガイダンスを追加する場所ではありません。
3. ARCHITECTURE.md への参照がない場合は、 ファイル末尾にある accelint-onboard-agents と同じ構造の ## Related Documentation セクションを追加または更新します。

## Related Documentation

- **ARCHITECTURE.md** — System architecture, deployment overview, component interactions
  _(Reference this when behavioral decisions depend on understanding system structure)_

4. セクションの形式を正確に保ちます。 タイトルには ## Related Documentation を使用します。各項目は次の形式にします。

- **<filename>** — description
  _(Condition or scenario by which this file is used)_

5. ## Related Documentation セクションがすでにある場合は、 セクションを重複して作成せず、そのリストに ARCHITECTURE.md の項目を追加します。既存のリスト形式を維持します。用途を説明する注記は、インデントされた独立した行に記載します。
6. 実際のエージェント動作ファイルがない場合は、 このスキルの一環として新たに作成しないでください。承認済みのアーキテクチャドキュメントだけを書き込み対象にします。

完了条件：アーキテクチャのガイダンスが実際のエージェント動作ファイルに記載され、## Related Documentation 構造を使用し、ポインタースタブは変更されていません。