ns-harness-architecture-rules

アーキテクチャルールの生成

コーディングエージェント向けにホットメモリを作成します。リポジトリの構成と、エージェントが決して違反してはならない制約を記した、常時読み込まれる単一の {harness_root}/rules/architecture-rules.md です。

これはビジネス仕様（ns-harness-codebase-reverse-spec）でも、SDD 計画アーティファクト（ns-harness-bootstrap-brownfield）でもありません。これは憲章です。毎回のセッションで読み込まれ、簡潔に保たれ、明示的なパスとすべきこと・してはいけないことのルールを用いて、機械が読み取ることを目的に記述されます。

設計原則

1. エージェント優先 — ファイルパス、エントリーポイント、禁止領域、テストコマンドを記載します。電文調の表や箇条書きを使い、文章を流し読みする開発者は対象読者ではありません。
2. 簡潔さを標準に — 80～200 行を目標とします（上限は約 250 行）。詳細はスコープを限定したレイヤールールや docs/ に記載し、このファイルから参照します。
3. 根拠に基づく — すべてのルールは、リポジトリ内で確認した内容に裏付けられている必要があります。inferred の項目には印を付け、スタックやパターンを捏造しないでください。
4. 基盤となる情報 — エージェントはこの内容を絶対的に信頼します。古いルールは気付かれない失敗を招くため、推測するより記載を省くことを優先してください。
5. 分離 — 普遍的なアーキテクチャ情報はここに記載し、ファイル形式やドメインの詳細は兄弟ルール（backend-rules.md、frontend-rules.md など）に記載します。

保存する前に毎回 ../ns-harness/references/agent-artifact-compress.md を確認し、それでも草案が行数上限を超える場合は references/compression-guide.md を確認してください。

ハーネスの検出

../ns-harness/references/harness-discovery.md と ../ns-harness/references/rules-sync.md を確認してください。

出力先	使用する場合
{harness_root}/rules/architecture-rules.md	デフォルト — 正式な憲章
{product_root}/.nextstage-harness/rules/architecture-rules.md	モノレポの製品フォルダーがハーネスの基点の場合

スキャンする前に AGENTS.md と既存の {harness_root}/rules/*.md を読み、既存の情報を再利用して参照してください。兄弟ルールと重複させないでください。レガシー形式の .cursor/rules/*.mdc は、{harness_root} が存在しない場合に限り使用します。

使用するタイミング

トリガー	アクション
新しいリポジトリ／エージェントの初回セットアップ	初期憲章を生成する
スタックまたはレイアウトの大幅な変更	その場で更新する
architecture-rules.md がないが、他のルールは存在する	兄弟ルールを相互参照して生成する
ユーザーからルールが古い、またはエージェントが同じミスを繰り返すと報告された	対象セクションを更新する

ワークフロー

ステップ 1 — 基点とベースライン

1. {harness_root} と {product_root} を特定します。
2. AGENTS.md、既存の architecture-rules.md を読み、{harness_root}/rules/*.md を一覧表示します。
3. ユーザーが指摘した不足点（あれば）と、今回が新規作成か更新かを記録します。

ユーザーがスコープを指定していない場合は、リポジトリ全体と {product_root} のサブツリーのどちらを対象にするか、一度だけ確認します。

ステップ 2 — 調査

references/reconnaissance-checklist.md と references/stack-signals.md に従ってください。読み取り専用です。アプリケーションコードは変更しないでください。

最低限のスキャン項目：

1. ルートのマニフェスト（package.json、composer.json、pyproject.toml、go.mod、Cargo.toml、docker-compose.yml など）。
2. ディレクトリツリー（{product_root} の下、約 2 階層）。
3. エントリポイント（HTTP ルーター、index.php、main.ts、CLI コマンド、ワーカー）。
4. モジュール／ドメインのフォルダーと、生成済みまたはビルドディレクトリ（編集禁止ゾーン）。
5. テストの構成とテストの実行方法（スクリプト、Docker、CI のスニペット）。
6. docs/、README.md 内の既存ドキュメント。

チェックポイント（推奨）： スタック、レイアウト、モジュール、生成済みゾーン、テストコマンドを含む簡単な調査マップを提示し、下書きの作成前にユーザーに確認または修正を求めてください。明示的な自律実行の場合のみ省略してください。

ステップ 3 — アーキテクチャの事実を抽出

証拠を、エージェントが行動に移せるルールにまとめます。

カテゴリー	把握する内容
範囲	プロダクトルート、モノレポか単独プロジェクトか、仕様とエージェント用アセットの保存場所
スタック	言語、フレームワーク、DB、キャッシュ、キュー、判明している場合はローカル URL／ポート
レイアウト	フォルダーツリー（簡略版）、モジュールの境界
パターン	API スタイル、マルチテナント対応、認証、モジュールの慣習、統合境界
禁止事項	生成済みディレクトリ、マイグレーションの制約、シークレットの保存場所
開発とテスト	Docker サービス、テストコンテナー名、コピーして実行できるテストコマンド（動作に関するルールは AGENTS.md に記載）
規律	コード／ドキュメントとユーザーとのチャットで使用する言語、最小限の差分、完了時の形式 — リポジトリのルールまたは AGENTS.md に記載されている場合のみ

大規模なサブシステムについては、内容をインラインで記載しないでください。専用のレイヤールールを指す行を 1 つ追加し、後続の作業でその兄弟ファイルを生成することを提案してください。兄弟ファイルの作成方法：npx @nextstage-brasil/harness add-rule <name> --description "…"（デフォルトは alwaysApply: false）。.cursor/rules/*.mdc を手書きしたり、manifest.json の cursor.description または適用モードを省略したりしないでください。../ns-harness/references/rules-sync.md を参照してください。

ステップ 4 — 規約を下書きする

ひな型として references/architecture-rules.template.md を使用してください。

正規ファイルに YAML フロントマターを付けないでください。アダプターのメタデータは .nextstage-harness/manifest.json に格納します。

執筆ルール：

• 段落より表や箇条書きを優先してください。
• 実際の破損を防ぐ制約に限り MUST / MUST NOT を使い、理由が自明でない場合は数語で説明してください。
• 最後に 主要な参照先 を設け、トピックとファイルパス（仕様、兄弟ルール、AGENTS.md）を対応付ける表を記載してください。
• 出力ファイルは英語のみとします。

保存前（必須）： ../ns-harness/references/agent-artifact-compress.md（caveman ultra）を適用し、それでも予算を超える場合は references/compression-guide.md を適用してください。圧縮した下書きのみを書き込んでください。

ステップ 5 — 作成、同期、報告

1. {harness_root}/rules/architecture-rules.md（または {product_root}/.nextstage-harness/rules/...）を作成します。圧縮したエージェント向けのホットメモリのみを記載してください。
2. .nextstage-harness/manifest.json に architecture-rules があり、cursor.alwaysApply: true と claude.paths: null が設定されていることを確認します。
3. npx @nextstage-brasil/harness sync を実行するか、ユーザーに実行を案内して、アダプターを再生成します。
4. ユーザーが明示的に依頼していない限り、アプリケーションのソースは変更しないでください。
5. 簡潔に（箇条書き 3～6 項目）報告します。検出した内容、行数、新規セクションと更新したセクション、依然として不足している関連ルールを提案してください。

以前の architecture-rules.md が存在した場合は、削除、統合、または別ファイルに保留した内容を明記してください。

更新モード

既存ファイルを更新する場合：

1. ユーザーが手動で編集した可能性のある安定したセクション（コミュニケーションのロケール、GitLab MCP サーバー名、保護対象ブランチ）は、調査によって誤りと判明しない限り保持します。
2. スタック、レイアウト、モジュールは、現在の証拠に基づいて置き換えます。
3. コードベースに合わなくなったルールは削除します。ユーザーが監査証跡を求めた場合に限り、末尾に ## Changelog コメントブロックを追加します。それ以外の場合は追加しません。

品質基準（保存前のセルフチェック）

• agent-artifact-compress.md を適用（caveman ultra。エッセイ調の文章は禁止）
• 正規ファイルに YAML フロントマターがない
• manifest.json に architecture-rules があり、alwaysApply: true が設定されている
• 行数が 250 行以下（できれば 200 行以下）
• すべてのスタック項目をマニフェストまたは設定で検証済み
• 存在する場合、生成されるパス／禁止されているパスを記載
• Docker／CI が検出された場合、テストコマンドはコピーしてそのまま実行可能
• 別のテスト用コンテナー／サービスが存在する場合、開発用コンテナーやホストではなく、テストサービス名とコマンドを文書化
• 関連ルールの内容を丸ごと重複させず、リンクのみを記載
• ビジネスドメインのルールを含めない（それらは docs/specs/ に記載）
• harness sync を実行するか、ユーザーに実行を案内

関連スキル

• ns-harness-bootstrap-brownfield — SDD 計画用の brownfield-map.md（より広範で、計画を重視）
• ns-harness-codebase-reverse-spec — 技術に依存しないビジネス動作
• ns-harness — アーティファクトのパスとゲートの規約