accelint-onboard-openspec

OpenSpec のオンボーディング

QRSPI 手法に合わせて設定した、プロジェクト固有の完全な openspec/config.yaml を作成できるよう、対話形式でユーザーに質問します。

OpenSpec のオンボーディングで絶対に行わないこと

• サブエージェントを利用できる場合、コードベースの推論を順番に実行しないでください — フェーズ 3 では、異なる調査領域ごとにサブエージェントを並列で起動します。ディレクトリに設定ファイルが多数あるコードベースを順番にスキャンすると、時間を無駄にします。調査エージェント 4 つをすべて同時に起動してください。

関連スキル

このスキルは、エージェント指示スタックのプロジェクト DNA レイヤーを作成します。プロジェクトの構造的な事実を扱います。このスキルは、エージェント指示スタックの振る舞いレイヤー（AGENTS.md / CLAUDE.md）を作成する accelint-onboard-agents スキルと対になるものです。振る舞いレイヤーでは、エージェントの行動、コミュニケーション、意思決定の方法を扱います。

このインタビュー中にユーザーが振る舞いに関する内容（コミット規約、ワークフローの手順、意思決定のヒューリスティック、ツールの好みなど）を自発的に話した場合は、それを受け止めて、次のように案内してください。「それは振る舞いに関する内容なので、AGENTS.md に記載するのが適切です。ここでは参考として記録しますが、内容を反映するには accelint-onboard-agents スキルを使うのが適切です。」 振る舞いに関する内容を config.yaml に書き込まないでください。

AGENTS.md / CLAUDE.md  → accelint-onboard-agents skill  → HOW the agent behaves
openspec/config.yaml   → this skill             → WHAT the project is

---

基本的な考え方

設定には 2 つの役割があります。

1. context: — すべての AI アーティファクトに挿入される、コードベースに関する客観的な事実です。AI の提案をプロジェクトに自然になじませる「DNA」と考えてください。意見ではなく、事実のみを記載します。
2. rules: — 提案／設計／タスク／仕様それぞれのチェックポイントで、チームの品質基準を定めます。

フェーズ

フェーズ 0 — ファイル状態の検出

インタビューの質問を始める前に、openspec/config.yaml が存在するかを確認し、その状態を評価してください。モードを黙って選択してはいけません。検出したモードを必ずユーザーに伝え、続行する前に確認してください。

ステップ 1 — 関連ドキュメントの確認

config.yaml の状態を検出する前に、関連するオンボーディングドキュメントを確認してください。

1. ARCHITECTURE.md を確認する
   • 存在する場合：デプロイとインフラストラクチャを把握するために読みます
   • 2 ターン目（インフラストラクチャ／デプロイに関する質問）の回答候補として利用します
   • 「関連ドキュメント」セクションに記載するため、存在を記録します
   • 次のように伝えます。「ARCHITECTURE.md が見つかりました。すでに記載されているデプロイに関する質問を避けるために活用します。」

注：AGENTS.md と README.md には振る舞いや利用方法の情報が記載されており、プロジェクト DNA ではないため、config.yml の生成に影響させないでください。

ステップ 2 — 設定の状態を検出する

関連ドキュメントを確認した後、設定ファイルの状態を評価してください。

Does openspec/config.yaml exist?
│
├── No → MODE 1: Create
│         Full interview from scratch.
│
└── Yes → Read the file, then assess:
          │
          ├── Empty or near-blank (schema: line only, no context/rules)?
          │     → MODE 1: Create (with overwrite confirmation)
          │       Ask: "config.yaml exists but appears empty — should I
          │       populate it from scratch, or preserve any current content?"
          │
          ├── Contains recognised fields?
          │   (context: block present, rules: block with known artifact keys)
          │     → MODE 3: Refresh
          │       Abbreviated interview covering only detected drift and
          │       unresolved # TODO: fill in markers.
          │
          └── Contains real content in an unrecognised shape?
                → MODE 2: Import
                  Present three options (A / B / C) before proceeding.

認識される形式 = ファイルが有効な YAML であり、値が空でない文字列の context: キー、または既知のアーティファクト ID（proposal、specs、design、tasks）のいずれかを 1 つ以上含む rules: キーがあること。

---

モード 1：作成

フェーズ 1 → フェーズ 2 → フェーズ 3 → フェーズ 4 のインタビューをすべて実施します。新しいリポジトリでの標準的な手順です。

---

モード 2：インポート

このファイルには、このスキルによって生成されたものではない実際のコンテンツが含まれています。何かに手を加える前に、次の 3 つの選択肢を提示してください。

「この config.yaml には、認識できない構造の既存コンテンツが含まれています。どのように進めますか？

(a) 再構成 — 既存のコンテンツをインポートし、context: / rules: スキーマに割り当てます。AGENTS.md に記載すべき内容（ワークフローの手順、コミット規約、ツールの優先設定など）には印を付け、不足を補うための対象を絞ったヒアリングを行い、現在のファイルと置き換えられる統合済みファイルを作成します。

(b) 追記 — 全項目のヒアリングを実施し、既存のコンテンツを変更せず、その横にスキルの context: セクションと rules: セクションを追加します。

(c) ドライラン — 全項目のヒアリングを実施し、ファイルシステムに変更を加えず、生成される内容を正確に提示します。確定する前に適合性を評価するために使用してください。」

選択肢 (a) が選ばれた場合：

1. ファイル全体を読み込みます。
2. 既存のコンテンツを、可能な範囲で context: のサブセクションと rules: のアーティファクトキーに割り当てます。
3. 関心の分離の境界に反するコンテンツ（例：コミット規約、ワークフローの手順、ツールの優先設定、エージェントの判断ヒューリスティック）に印を付けます。これらは AGENTS.md に記載すべき内容です。違反ごとに、次のように尋ねます：「これは動作に関する内容のようです。AGENTS.md に記載すべきです。そこに移動し、config.yaml から削除しますか？」
4. 不足している箇所のみを対象にしたヒアリングを実施します（既存の記載がない context: のサブセクション、およびルールのないアーティファクトキー）。
5. 書き込む前に、統合後のプレビューを表示します。既存のコンテンツには # from existing file、新しいコンテンツには # new とラベルを付けます。

選択肢 (b) が選ばれた場合： Phase 1 から Phase 4 までの全項目のヒアリングを実施し、生成した context: ブロックと rules: ブロックを既存のコンテンツの横に書き込みます。先頭に次のコメントを追加します： # Sections below added by accelint-onboard-openspec skill

選択肢 (c) が選ばれた場合： Phase 1 から Phase 4 までの全項目のヒアリングを実施し、出力を会話内に提示します。「ファイルは変更されていません。」と明示します。ユーザーが内容に問題がなければ、(a) または (b) として再実行することを提案します。

---

モード 3：更新

ファイルがスキルで想定されているスキーマと一致しています。以前の実行で作成された可能性があります。以下のみを対象に、簡略化したインタビューを実施します。

1. 外部の知見を抽出する — 呼び出し元のプロンプトに findings: リストが含まれているか確認します。

   • プロンプト内の findings: セクション（事実を記述した箇条書きリスト）を解析します。
   • 各知見は、すでに真実であると判明している事柄として記述され、指示の形にはなりません。
   • 例：「config.yaml の Anti-Patterns セクションではポーリングを避けるよう記載されていますが、アーカイブ済みの変更のうち 2 件では、明示された理由によりポーリングが選択されていました」
   • ステップ 4 で統合できるよう、これらの知見を保存します。

2. ドリフトを検出する — ファイルが最後に更新されてからのコードベースの変更をスキャンします。

   シグナル	確認場所
   ランタイム／Node バージョンの変更	.nvmrc、.node-version、Dockerfile
   パッケージ／フレームワークの追加	package.json の依存関係、ワークスペースのルート
   TypeScript 設定の厳格化	tsconfig.json — 新しい strict* フラグ
   モノレポ内の新しいパッケージ	pnpm-workspace.yaml、turbo.json
   ビルドツールの変更	vite.config.*、tsup.config.*
   CI/CD ワークフローの追加	.github/workflows/
   新しいドメイン概念	新しいトップレベルディレクトリ、ソース内の新しいエンティティ型
   非推奨になったアンチパターン	追加された @deprecated タグ、// TODO: replace コメント

3. 未解決の TODO — 前回の実行で残された # TODO: fill in マーカーをすべて見つけ、対象を絞った質問として提示します。

4. 質問する前に、見つかった事項をすべて統合して通知する — 次の内容を統合します。

   • 外部の知見（ステップ 1）、ドリフトに関する知見（ステップ 2）、TODO（ステップ 3）
   • 統合したリストをユーザーに提示します。

     「外部の知見が [N] 件、ドリフトしている可能性のあるコンテキストセクションが [M] 件、未解決の TODO が [P] 件見つかりました。 これらについてのみ質問します。それ以外は最新のようです。」

   • 外部の知見がある場合は、その出典を記載します（例：「完了済みの OpenSpec 変更から」）。

5. 対象を絞ったインタビューの後、書き込む前にプレビューには変更されたセクションのみを表示します。変更されていないセクションは再表示しません。

---

Phase 1 — ディスカバリーインタビュー

インタビューは会話形式で進めます。質問を一度にすべて並べないでください。自然な話題ごとに質問をまとめます。ユーザーが技術スタックについて話した場合は、関連するツールを推測して、同じことを聞き直すのではなく確認してください。

Turn 1 — プロジェクトの概要

• プロジェクト名と主な目的は何ですか？
• モノレポ、単一パッケージ、またはその他の構成ですか？モノレポの場合、どのワークスペースがありますか？
• ビルドシステム／タスクオーケストレーションは何ですか？（Turbo、Nx、Make、npm scripts、Makefile…）
• パッケージマネージャーとプライベートレジストリはありますか？（npm、pnpm、yarn、bun…）

Turn 2 — 技術スタック (個別にではなく、まとめて質問してください)

• ランタイムとバージョン（Node.js 20、Bun 1.x、Python 3.12 など）
• 言語と設定（TypeScript strict？ exactOptionalPropertyTypes？ Python の型ヒント？）
• フレームワークとバージョン（React 18、Next.js 14、Express、FastAPI など）
• 主要なドメインライブラリ（Deck.gl、Apache Arrow、Prisma、SQLAlchemy など）
• データレイヤー（Postgres、MongoDB、DynamoDB、ORM／クエリビルダー、データ形式）
• テスト環境（Vitest、Jest、Pytest、testing-library、Playwright など）
• リント／フォーマット（ESLint、Biome、Prettier、Black、Ruff など）
• ビルドツール（Vite、tsup、esbuild、Webpack など）
• CI/CD（GitHub Actions、CircleCI など）
• バージョン管理の方法（Changesets、standard-version、conventional commits など）

Turn 3 — アーキテクチャ

• コードベースはどのように整理されていますか？（機能ベース、レイヤーベース、ドメイン駆動など）
• 共通コード／ユーティリティコードはどこにありますか？
• パスエイリアスはありますか？（@/、~/、src/、#lib/ など）
• よく使われる設計パターンはありますか？（ファクトリー、リポジトリー、オブザーバー、CQRS など）

Turn 4 — ドメインの概念

• 最も重要なドメインエンティティを 3～5 個挙げると何ですか？ 質問の例：「マッピングアプリなら、Layer、Source、Viewport、Feature、Style などが考えられます。」
• AI が知っておくべき、ドメイン固有の用語はありますか？
• コードベース内で、一般的な意味とは異なる専門的な概念はありますか？ 例：「orchestration」は、一般的なワークフローではなく、スタイルとデータを統合するランタイムレイヤーを指す、当チーム固有の用語です。

Turn 5 — パフォーマンス

• 具体的なパフォーマンス目標はありますか？（p95 < 200 ms、60 fps、ヒープ < 50 MB など）
• 既知のホットパスや、パフォーマンスが重要な領域はありますか？
• メモリやバンドルサイズの制約はありますか？

Turn 6 — コードパターン

• エクスポート形式：名前付きエクスポート、デフォルトエクスポート、または混在ですか？
• 命名規則：ファイル、変数、関数、定数はどのように命名しますか？ 例：「ファイルは kebab-case、変数は camelCase、定数は SCREAMING_SNAKE_CASE、型は PascalCase。」
• エラー処理：throw、Result<T,E>、エラーバウンダリー、またはその他の方法ですか？
• テストの構成：describe/it、test/expect、AAA パターンのどれですか？
• テストファイルの場所：ソースと同じ場所、または独立した __tests__/ ツリーですか？
• テストデータには、フィクスチャ／ファクトリーのどのような方法を使いますか？

Note: コミットメッセージの規約はワークフロー手順であり、ここではなく AGENTS.md に記載します。ユーザーがこの時点で話題にした場合は、内容を覚えておき、 accelint-onboard-agents スキルで取り上げてください。config.yaml には追加しないでください。

Turn 7 — アンチパターン

• コードレビューで明示的に禁止されているパターンはありますか？
• コードベース内に、現在も使われているものの、新しいコードでは NOT 模倣すべきでない非推奨パターンはありますか？
• この技術スタック固有の、既知のパフォーマンス上の落とし穴はありますか？

Turn 8 — 提案のルール チームが提案に求める要件は何ですか？質問の例：

• 「データベースのマイグレーションによる影響を、提案に記載する必要がありますか？」
• 「API の破壊的変更を、提案で明示する必要がありますか？」
• 「セキュリティレビューのチェック項目はありますか？」

Turn 9 — 設計のルール プロジェクト固有の設計上の懸念で、ルールに盛り込むべきものはありますか？質問の例：

• 「Docker／Kubernetes のリソース変更について、記録する必要がありますか？」
• 「パフォーマンスへの影響に関するセクションは必要ですか？」
• 「アーキテクチャ図の形式（ASCII、Mermaid）は決まっていますか？」

Turn 10 — タスクのルール

• パッケージやモジュールごとにタスクをどのようにタグ付けしますか？ 例：[PKG:auth]、[MODULE:pipeline]、GitHub ラベルなど
• データベース変更にはロールバック計画が必要ですか？
• デプロイ固有のテストゲート（スモークテスト、カナリアチェックなど）はありますか？

---

フェーズ 2 — スマートなデフォルト

各スタックの回答後に、確認すべき関連規約を提示します。以下の例を参考にし、適宜、ほかのスタックにも拡張してください。

Next.js + TypeScript + Tailwind → 確認を提案する項目：

• App Router と Pages Router のどちらを使うか、および適用されるパターン
• Server Component と Client Component の境界ルール
• "use client" ディレクティブを配置する規約
• API ルートの構成（app/api/ と pages/api/ のどちらを使うか）

React + Vitest + testing-library → 確認を提案する項目：

• fireEvent より userEvent を優先するか
• screen クエリの優先順位（role > label > testid）
• プロバイダー用の render ラッパー

Python + FastAPI → 確認を提案する項目：

• Pydantic v1 と v2 のどちらを使うか（フィールドバリデーターの構文が異なります）
• DB セッションの依存性注入（Depends）
• Alembic のマイグレーションワークフロー
• lifespan と startup／shutdown イベントフックのどちらを使うか

Node.js + Prisma → 確認を提案する項目：

• prisma.$transaction のパターン
• 論理削除と物理削除のどちらを使うか
• マイグレーションの命名規約

---

フェーズ 3 — コードベースの並行推論

インタビューの後、並行して調査サブエージェントを起動し、残りの設定の不足を補います。設定の各セクションはすべて重要です。フィールドが欠けると、その後に生成されるすべての AI 成果物の品質が低下するため、省略するよりも常に推論を優先してください。

調査サブエージェントは並行して起動してください。順番にスキャンしてはいけません。各エージェントは1つの推論領域に集中し、構造化された調査結果を返します。すべてのエージェントが完了するまで待ち、その後、フェーズ 4 の前に結果を統合してください。

次のエージェントを同時に起動してください：

エージェント A — スタックとビルドツール

• ランタイム／Node のバージョン：.nvmrc、.node-version、package.json#engines、Dockerfile
• TypeScript の設定：tsconfig.json（compilerOptions のフラグ、パスエイリアス）
• パッケージマネージャー：package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lockb
• モノレポのワークスペース：package.json#workspaces、pnpm-workspace.yaml、turbo.json、nx.json
• ビルドツール：vite.config.*、webpack.config.*、tsup.config.*、esbuild のスクリプト
• 返す内容：ランタイムのバージョン、TS 設定のフラグ、パッケージマネージャー、ワークスペース一覧、ビルドツール

エージェント B — テストとコード品質

• テストフレームワーク：vitest.config.*、jest.config.*、pytest.ini、pyproject.toml#tool.pytest
• リント／フォーマット：.eslintrc*、biome.json、.prettierrc*、ruff.toml
• テスト構成：テストファイルのサンプル — describe/it のネストの深さ、ソースに対するファイルの相対位置
• テストファイルの型チェック：CI スクリプト、package.json — tsc --noEmit が *.test.ts ファイルに対して実行されるか確認
• プロパティベーステスト：依存関係に fast-check があるか確認
• Vitest のモックのクリーンアップ：vitest.config.ts — clearMocks、mockReset、restoreMocks を確認
• 返す内容：テストフレームワーク、コード品質ツール、テスト構成のパターン、型チェックの設定

エージェント C — アーキテクチャとコードパターン

• アーキテクチャの構成：src/ またはワークスペースルートのディレクトリツリー — 機能ベースかレイヤーベースかを推測
• パスエイリアス：tsconfig.json#compilerOptions.paths、vite.config#resolve.alias
• デザインパターン：ソースファイルのサンプル — ファクトリー関数、リポジトリオブジェクト、オブザーバーフックを確認
• エクスポート形式：ソースファイルを3〜5個サンプルし、名前付きエクスポートとデフォルトエクスポートの数を集計
• 命名規則：ファイル名とエクスポートされた識別子をサンプルし、観察した内容を説明
• エラー処理：throw、Result、Either、tryCatch、エラーバウンダリーコンポーネントを検索
• TypeScript のベースラインパターン：tsconfig.json がある場合は、TS/JS のベースラインパターンを含める必要があることを示す
• 返す内容：アーキテクチャスタイル、パスエイリアス、デザインパターン、エクスポート規約、命名パターン、エラー処理の方針

エージェント D — CI/CD とバージョニング

• CI/CD：.github/workflows/、.circleci/、Jenkinsfile
• バージョニング：.changeset/、CHANGELOG.md、commitlint.config.*、.releaserc*
• アンチパターン：off または warn に設定された eslint ルールの上書き、// TODO: replace や @deprecated などのコメント
• 返す内容：CI/CD プラットフォーム、バージョニングの方針、文書化されたアンチパターン

すべてのエージェントが完了した後： 調査結果を統合推論マップにまとめます。 各フィールドに INFERRED [source] または UNKNOWN のタグを付けます。UNKNOWN のフィールドは、設定プレビューで # TODO: fill in と記載してください。

推論によって解決した各フィールドについて、次のように末尾のコメントでプレビューに出典を記載してください。

- Runtime: Node.js 20 LTS   # inferred from .nvmrc
- Language: TypeScript 5.4, strict, exactOptionalPropertyTypes   # inferred from tsconfig.json

フィールドを推論できない場合（パフォーマンス目標、ドメイン概念、チーム固有のルールなど）は、省略せずに # TODO: fill in と記載してください。ユーザーはプレビューを確認した後に、これらを解決できます。セクションを黙って削除しないでください。明示的な TODO は対応を促しますが、セクションが存在しなければ不足に気づけません。

---

フェーズ 4 — 生成

1. 書き込みを行う前に、設定全体のラベル付きプレビューを表示します。 推測した値にはその根拠となるソースコメントを付け、未解決のフィールドには # TODO: fill in を付けます。これにより、すべてのフィールドについて 確信度の全体像をユーザーに示せます。
2. 次のように尋ねます。「この内容でよさそうですか？ファイルを書き込む前に、修正または追加するセクションはありますか？」
3. 確認後、openspec/config.yaml に書き込みます（必要であればディレクトリを作成します）。推測の根拠となるソースコメントは削除してください。これらは確認用であり、最終ファイルには含めません。**関連ドキュメントのセクションでは、**リポジトリ内に実際に存在するファイルへのリンクのみを含めます。リンクを含める前に、各ファイル（ARCHITECTURE.md、AGENTS.md/CLAUDE.md、README.md）の存在を確認してください。
4. 生成した YAML を検証します。書き込み後にファイルを読み戻し、次の点を確認します。
   • タブがないこと（YAML ではインデントにスペースが必要です）
   • 特殊文字を含む値が適切に引用符で囲まれていること
   • 構文エラーがないこと（対応しない括弧や引用符など）
   • ファイルを有効な YAML として概念的に解析できること 検証で問題が見つかった場合は、すぐに修正してファイルを書き直します。
5. 設定した内容、推測した項目と直接回答された項目の内訳、人による入力がまだ必要な # TODO フィールドを簡潔にまとめて表示します。

---

YAML 生成時の安全ルール

重要： YAML の構文では特殊文字の扱いが厳密です。config.yaml の生成時に構文エラーを避けるため、次のルールに従ってください。

引用符で囲む場合

ルール： YAML の特殊文字で始まる値は、引用符で囲む必要があります。

特殊文字：|、>、"、'、(、)、[、]、{、}、*、&、!、%、@、`

例：

# Parentheses at start of value
❌ description: (internal) auth module     # Syntax error
✅ description: "(internal) auth module"   # Quoted

# Square brackets (looks like YAML list syntax)
❌ tag: [PKG:auth]                         # YAML thinks it's a list
✅ tag: "[PKG:auth]"                       # Quoted string

# Pipe character (YAML thinks it's block scalar)
❌ pattern: some|other                     # Syntax error
✅ pattern: "some|other"                   # Quoted

# Colon in value (YAML thinks it's a nested key)
❌ note: Time: 5pm                         # Syntax error
✅ note: "Time: 5pm"                       # Quoted

# Value containing quotes - escape with opposite quote type
✅ command: 'npm run "test:unit"'          # Single quotes protect doubles
✅ command: "npm run 'test:unit'"          # Double quotes protect singles

複数行文字列の扱い

複数行の内容にはブロックスカラーインジケーターを使用します。

# Literal block (preserves newlines) - preferred for context field
context: |
  Line 1
  Line 2
  Line 3

# Folded block (folds newlines into spaces) - rarely needed
description: >
  This is a long
  description that
  flows together.

インデントのルール

• スペースのみを使用します — タブは使いません
• インデントを統一します — 通常は階層ごとに 2 スペースです
• ブロックスカラー — | または > の中の内容は、キーに対してインデントを下げます

リスト値のルール

# Simple list items - no quotes needed for plain text
rules:
  proposal:
    - Keep proposals under 100 lines
    - Include scope boundaries

# List items with special chars - quote them
rules:
  tasks:
    - "Tag with [PKG:name] format"        # Quotes protect [ and ]
    - 'Use "Test:" prefix for validation' # Single quotes protect inner "

検証チェックリスト

設定を生成した後、次の点を頭の中で確認します。

1. コロンの直後に、引用符で囲まれていない (、)、|、"、' がないこと（複数行に | または > を使用する場合を除く）
2. ファイル内にタブ文字がないこと
3. 全体を通して 2 スペースのインデントが統一されていること
4. すべてのリスト項目（-）が、親要素内で同じインデント位置に揃っていること
5. 引用符で囲んだ文字列で、開始と終了に同じ種類の引用符を使っていること

これらのルールに違反すると、YAML の解析に失敗します。

---

設定テンプレート

次の構造をそのまま使用します。すべての [placeholder] を、インタビューまたはコードベースからの推測で得た内容に置き換えます。どちらの方法でも解決できないフィールドは、プレースホルダーを # TODO: fill in に置き換えます。フィールドを省略してはいけません。すべてのセクションが、後続の AI アーティファクトの品質を左右します。

schema: spec-driven

# Project Context
# Injected into every AI-generated artifact (proposal, design, spec, tasks).
# QRSPI principle: objective research layer — facts only, no opinions.

context: |
  # ═══════════════════════════════════════════════════════════════════════════
  # STACK FACTS
  # ═══════════════════════════════════════════════════════════════════════════

  ## Project Identity
  [project name and one-sentence purpose]
  [repo structure: monorepo / single-package / workspaces list]
  [build system and task orchestration]
  [package manager + registries]

  ## Tech Stack
  - Runtime:            [e.g., Node.js 20 LTS]
  - Language:           [e.g., TypeScript 5.4, strict mode, exactOptionalPropertyTypes]
  - Framework:          [e.g., Next.js 14 App Router]
  - Key Libraries:      [domain-specific dependencies with versions]
  - Data Layer:         [databases, ORMs, data formats, query builders]
  - Testing:            [framework, utilities, coverage tooling]
  - Linting/Formatting: [tools and config files in use]
  - Build Tools:        [bundlers, compilers, transpilers]
  - CI/CD:              [platform and key workflow names]
  - Versioning:         [release strategy and changelog tooling]

  ## Architecture Patterns
  - Organisation: [feature-based / layer-based / domain-driven / other]
  - Shared code:  [path to shared utilities / packages]
  - Path aliases: [list of aliases and their resolved paths]
  - Key patterns: [design patterns in common use]

  ## Domain Concepts
  - [Entity or concept]: [one-line definition]
  - [Entity or concept]: [one-line definition]
  - [Entity or concept]: [one-line definition]

  ## Performance Targets
  - [metric]: [target value and context]

  ### TypeScript/JavaScript Performance (if applicable)
  - Hot paths:    [functions executed >1000 times per interaction or >100 times/sec]
  - Frame budget: [for real-time systems: 60fps = 16.67ms, 120fps = 8.33ms]
  - Constraints:  Bounded iteration (explicit limits on loops/queues), O(n) or better algorithmic complexity

  # ═══════════════════════════════════════════════════════════════════════════
  # PATTERNS TO FOLLOW
  # ═══════════════════════════════════════════════════════════════════════════

  ## Code Patterns
  - Exports:         [named / default / mixed — and when each applies]
  - Naming:          [files, variables, functions, constants, types]
  - Error handling:  [throw / Result<T,E> / boundaries / other]
  - Validation:      [approach and library]
  - Constants:       Use `as const` objects, never `enum`
  - Classes:         Prefer functions over classes unless state management required or extending existing class
  - Return values:   Return zero values (empty array, empty string, 0, false) instead of null/undefined
  - Leaf functions:  Leaf functions (bottom of call stack) should be pure — same inputs produce same outputs, no side effects. Centralize state manipulation in parent/orchestrator functions.
  - Type safety:     Avoid `any` (use `unknown` or generics); avoid `enum` (use `as const` objects); use `type` over `interface`
  - Immutability:    Prefer `const`, immutable data structures, pure functions
  - Documentation:   Comprehensive JSDoc for all exported code (@param, @returns, @template, @example)
  - Order:           Internal functions, variables and types should be defined before they are used (internal/export types -> internal/export constants -> internal/export functions)
  - Parameter order: Data-last ordering — place the data being operated on as the final parameter. Enables partial application and composition.
  - Composition:     Use curried functions when the same first parameter(s) recur across call sites.

  ## Architecture Patterns
  - [pattern name]: [brief description of how it's used here]

  ## Testing Patterns
  - Pattern:        AAA (Arrange, Act, Assert) with clear boundaries
  - Property-based: (If available) Use `fast-check` for encode/decode pairs, validators, normalizers, pure functions
  - Test scope:     Never test library internals; never export internals to test them; never mock own pure functions
  - Structure:      [describe/it nesting convention]
  - File location:  [co-located / __tests__ / other]
  - Test doubles:   Hierarchy: real implementation > fakes > stubs > spies > mocks
  - Fixtures:       [factory functions / fixture files / inline data]
  - Assertions:     [preferred assertion style]
  - Nesting:        Max 2 levels of describe blocks — use descriptive test names instead
  - Verification:   MUST run `tsc --noEmit` on test files before marking complete
  - Benchmarks:     [approach if any]

  # NOTE: Commit message convention, PR workflow, and tool preferences
  # are behavioral — they belong in AGENTS.md, not here.

  # ═══════════════════════════════════════════════════════════════════════════
  # PATTERNS TO AVOID
  # ═══════════════════════════════════════════════════════════════════════════

  ## Code Anti-Patterns
  - Using `any` instead of `unknown` or generics
  - Using `enum` instead of `as const` objects
  - Using `interface` when `type` works (prefer type)
  - Returning `null`/`undefined` instead of zero values (empty arrays, empty strings, 0, false)
  - Not validating external data with schemas
  - Deep nesting instead of early returns

  - [anti-pattern]: [why it's banned or deprecated]

  ## Performance Anti-Patterns
  - Chaining array methods (`.filter().map().reduce()`) — use single reduce pass
  - Using `Array.includes()` for repeated lookups (use `Set.has()` for O(1) lookups)
  - Recomputing constants inside loops (hoist invariants outside)
  - Unbounded loops or queues (set explicit limits to prevent runaway resource consumption)
  - Placing `try/catch` in hot paths (V8 cannot inline, 3-5x slowdown)

  - [anti-pattern]: [why it's banned or deprecated]

  ## Testing Anti-Patterns
  - Testing library internals (e.g., verifying Array.prototype.map works)
  - Exporting internal functions just to test them
  - Loose assertions in tests (toBeTruthy, toBeDefined)
  - Nested describe blocks >2 levels deep
  - Testing implementation details instead of behavior

  - [anti-pattern]: [why it's banned or deprecated]

  ## Documentation Anti-Patterns
  - Missing JSDoc on exported functions/types
  - Documenting HOW instead of WHAT/WHY in JSDoc
  - Vague comment markers (`// TODO: fix this` instead of `// TODO: Replace with binary search for O(log n)`)

# ═══════════════════════════════════════════════════════════════════════════
# PER-ARTIFACT RULES
# ═══════════════════════════════════════════════════════════════════════════

rules:
  proposal:
    # QRSPI: Scope definition, not a plan.
    - State the requirement or ticket driving this change
    - Define scope boundaries — explicitly list what is OUT of scope
    - Keep under 100 lines (tight and focused)
    [user-specific proposal rules]

  design:
    # QRSPI: The "brain surgery" checkpoint — reviewed before any code is written.
    # Target ~200 lines capturing current state, desired state, open questions.

    # Required sections (in this order):
    - Start with "Current State": what the code does today, key files, entry
      points, relevant data flows
    - "Desired End State": what changes after this work, what stays the same
    - "Patterns to Follow": ONLY if specific files/functions to reference exist
      for this change's domain
    - "Patterns to Avoid": ONLY if specific anti-patterns apply to this change
    - "Open Questions": genuine uncertainties requiring human input. If none,
      state explicitly "No unresolved questions."
    - "Resolved Decisions": numbered (Decision 1, Decision 2…) with Choice,
      Rationale, Alternatives Considered

    # Technical depth:
    - Use ASCII diagrams for data flows, state machines, architecture
    - Call out performance implications where relevant
    [user-specific design rules]

    # Constraints:
    - Keep under 250 lines total

  tasks:
    # QRSPI: Vertical slicing for early failure detection.

    # Vertical slicing (strong preference):
    - Order as vertical slices — each task delivers a testable end-to-end path
    - Do NOT group by architectural layer unless explicitly justified
    - Horizontal (layer-by-layer) only for pure infrastructure; include
      justification in the task description when used
    - Each task MUST include an explicit "Test:" line describing what to verify
      before proceeding to the next task
    - Prefer 3–5 major slices; more than 5 suggests scope is too large

    # Granularity:
    - Max 2 hours per task; break larger work into subtasks
    [user-specific task tagging, e.g., [PKG:name] or [MODULE:name]]
    - Call out inter-task dependencies explicitly
    [user-specific rollback requirements]
    [user-specific deployment test gates]

  spec:
    - Use Given/When/Then for behaviour specifications
    - Include concrete example data relevant to the domain
    - Document edge cases explicitly
    [user-specific spec rules]

# ═══════════════════════════════════════════════════════════════════════════
# RELATED DOCUMENTATION
# ═══════════════════════════════════════════════════════════════════════════
# Include only files that actually exist in the repository:
# - ARCHITECTURE.md: System overview, deployment, component interactions, data flows
# - AGENTS.md: Agent behavior rules, workflow procedures, communication style
# - README.md: Installation, quick start, usage guide

---

対話の原則

• 尋問調ではなく、会話形式で。 関連する質問はまとめて一度に尋ねます。箇条書きだけを並べた形式ではなく、自然な言葉を使います。
• 推測して確認します。 「Vitest を使うとおっしゃっていたので、コンポーネントテストには @testing-library/react を使うものと想定します。合っていますか？」のように尋ねるほうが、最初から質問し直すより適切です。
• 例で曖昧さを減らします。 命名規則について尋ねる際は、ユーザーがパターンを把握できるよう、まず例を示します。
• 反復的に進めます。 ユーザーが回答を修正できるようにします。最初の回答に固定してはいけません。
• 書き込み前にプレビューします。 生成した設定全体を必ず表示し、ファイルシステムに変更を加える前に明示的な確認を得ます。
• 尋ねる前に推測し、省略する前に尋ねます。 未回答のフィールドについては、必ずコードベースからの推測を試みます。推測できない場合は、そのセクションを削除せず # TODO を提示します。TODO が明示された設定なら次の作業に活用できますが、セクションが欠けた設定では、それに依存するすべてのアーティファクトの品質が気付かないうちに低下します。