ARCHITECTURE.md

このファイルはシステムの最上位マップです。簡潔に保ち、必要に応じてより詳細な文書を指すようにしてください。

システム構成

プロダクト: [製品名に置き換え]
プライマリユーザーワークフロー: [メインワークフローに置き換え]
ランタイムサーフェス: [desktop / web / cli / services / workers]
プロダクト動作の信頼できる情報源: docs/product-specs/

ドメインマップ

ドメイン	目的	プライマリエントリーポイント	関連仕様
`[domain-a]`	`[所有する機能]`	`[modules / routes / commands]`	`[spec path]`
`[domain-b]`	`[所有する機能]`	`[modules / routes / commands]`	`[spec path]`

レイヤーモデル

エージェントが場当たり的なアーキテクチャを発明しないよう、固定方向モデルを使用する：

Types -> Config -> Repo -> Service -> Runtime -> UI

横断的な関心事は、レイヤーを直接またぐのではなく、明示的なプロバイダーまたはアダプターの境界を通じて参加させるべきである。

厳格な依存ルール

下位レイヤーは上位レイヤーに依存してはならない。
UIはランタイムまたはサービスの契約をバイパスしてはならない。
データアクセスはリポジトリまたは同等のアダプターを通じて行わなければならない。
共有ユーティリティは汎用的であり続け、ドメインロジックを蓄積してはならない。
新しい依存関係は、対応するプランまたは設計文書で正当化されるべきである。

横断的インターフェース

関心事	承認された境界	備考
ロギングとトレーシング	`[provider / utility path]`	`[構造化のみ、場当たり的なコンソール使用は不可]`
認証	`[provider path]`	`[トークン/セッションルール]`
外部 API	`[client or provider path]`	`[レート制限 / リトライガイダンス]`
フィーチャーフラグ	`[flag boundary]`	`[所有権]`

現在のホットスポット

[エージェントが安全に変更するのが最も難しい領域]
[境界が弱いかテストが脆弱な領域]

変更チェックリスト

アーキテクチャ関連のコードに触れる場合：

ドメインマップまたは許可された境界が変更された場合、このファイルを更新する。
理由が変更された場合、docs/design-docs/ の関連設計文書を更新する。
ルールを機械的に強制すべき場合、実行可能チェックを追加または更新する。