accelint-onboard-agents

エージェントのオンボーディング

会話形式のインタビューを通じて、AI コーディングエージェントがこのリポジトリでどのように振る舞うべきかを記した、プロジェクト固有の完全な AGENTS.md または CLAUDE.md を作成できるようユーザーを案内します。

関心事の分離

このスキルで作成するのは、エージェント指示スタックの振る舞いレイヤーです。

ここに記載するのは、エージェントが繰り返し行う作業の改善に直接つながる内容だけにしてください。プロジェクトの背景、技術スタックの事実、アーキテクチャの説明、プロセスハンドブックの内容、または近接する参考ドキュメントで説明する方が適切な詳細は、正規の関連ドキュメントを使用し、ここに繰り返し記載するのではなくリンクしてください。これらのレイヤーで同じ内容を重複させてはいけません。

正規の関連ドキュメントには、プロジェクトの特性を記した openspec/config.yml または openspec/config.yaml、システム構造を記した ARCHITECTURE.md、外部から課された境界を記した CONSTRAINTS.md、検証済みの事実と未解決の疑問や前提を記した EPISTEMIC-MAP.md、内部用語を記した JARGON.md などがあります。

以下のルールに従って、このファイルに残す内容と、正規の関連ドキュメントに記載する内容を判断してください。

厳守ルール：ここに記載しない内容

「エージェントはどのように振る舞うべきか」という問いに答えない内容は、AGENTS.md または CLAUDE.md に記載してはいけません。

該当する正規の関連ドキュメントがある場合は、そこに移してください。ない場合は記載しないでください。

AGENTS.md に記載する内容	正規の関連ドキュメントに記載する内容
「コミット前に必ず pnpm check を実行する」	「パッケージマネージャー：pnpm」
「Conventional Commits を使用する」	「TypeScript 5.x、strict モード」
「ファイルを削除する前に確認する」	「モノレポ：Turborepo + PNPM」
「小規模で目的を絞った PR を優先する」	「type を interface より優先する」
「必要に応じてシニア TS エンジニアとして作業する」	「ドメイン：地理空間の可視化」
「main に force-push しない」	「テスト：Vitest + @testing-library」
「デプロイ関連のコードを変更する前に ARCHITECTURE.md を読む」	「サービスのトポロジーとデプロイモデル」
「コンプライアンスに関わるフローを変更する前に CONSTRAINTS.md を確認する」	「実際のコンプライアンス上またはステークホルダー上の制約」

最終的な記載ルール

最終的な AGENTS.md または CLAUDE.md に含めるのは、恒久的に記載する価値がある指針だけです。詳細を記載する価値があるのは、次の条件を満たす場合に限ります。

• エージェントの振る舞いを変える
• 一度限りのタスクではなく、繰り返し行う作業に適用される
• リポジトリ固有のミスや、根拠のない思い込みを防ぐ
• 継続的な指針として十分に長く有効である
• すべてのエージェントセッションで読み込む価値がある

エージェントがすでに知っているかどうか分からないというだけで、詳細を記載してはいけません。エージェントの作業方法に影響する、リポジトリ固有のルールや例外を記述する場合に限って記載してください。それ以外は省略するか、その内容を記載した正規のドキュメントにリンクしてください。

ペルソナやアイデンティティに関する説明は任意です。振る舞いの改善につながる場合にのみ使用してください。役割に関する表現で、実際の作業指針を置き換えないでください。

エージェントのオンボーディングで絶対にしてはいけないこと

• コードベースの調査を絶対に逐次実行しないでください — 調査が必要な場合は、異なる動作領域を担当するサブエージェントを並列で使用してください。ディレクトリに多くの設定ファイルが分散しているコードベースでは、逐次スキャンは時間の無駄になります。
• 質問する前に必要な調査を絶対に省略しないでください — インタビューで不要な質問を追加する前に、コードベースから動作上の規約を推測してください。commitlint.config.ts があるのにコミット形式について質問するのは、ユーザーの時間を無駄にします。範囲を絞った更新の場合は、リクエストに必要な範囲の調査のみ行ってください。
• 生成する AGENTS.md から必須のテンプレートセクションを絶対に省略しないでください — ./assets/template.md の必須セクションについて推測も回答もできない場合は、そのセクションを残し、未解決のフィールドに `` と記載してください。./assets/template.md で明示的に許可されている場合に限り、任意のセクションを省略できます。必須のテンプレートセクションを欠落させると、エージェントの動作が予測できない形で左右されます。
• パッケージレベルのファイルにルートレベルの指示を絶対に重複させないでください — モノレポのルートに AGENTS.md または CLAUDE.md がある場合、パッケージのファイルではそれを参照し、パッケージ固有の内容のみを追加してください。指示を繰り返すと、エージェントを呼び出すたびにコンテキストが膨らみます。
• 両方見つかったという理由だけで、競合する常設ルールを絶対に残さないでください — 情報源の優先順位に従って競合を解決するか、両方を権威ある指針として記載するのではなく、未解決の問題としてプレビューに示してください。
• プレビューを表示せずに最終ファイルを絶対に書き込まないでください — ファイルシステムに書き込む前に、ユーザーが情報源の注釈付きで推測値を確認し、承認する必要があります。

---

競合の解決と情報源の優先順位

インポート、更新、または最終的な統合の際に候補となるルールが競合する場合は、次の順に解決してください。

1. ユーザーが直接確認した回答
2. 確認済みのリポジトリポリシー、または明示的に文書化されたリポジトリの動作
3. リポジトリ内の資料に裏付けられた推測
4. より強い証拠との整合性が保たれている既存の AGENTS.md または CLAUDE.md の内容
5. テンプレートのデフォルト、または汎用的なスキルのデフォルト
6. 競合が未解決の場合は、無理に統合せず `` または明示的な未解決の質問

毎回、次のルールを適用してください。

• 発見したルールが競合している場合、両方見つかったという理由で両方を残さないでください。
• デフォルトを、より強いリポジトリ内の証拠より優先させないでください。
• 現在確認済みの証拠と競合する古いファイルの内容を、変更せずに残さないでください。
• 不確実な点が残る場合は、統一したルールを作り上げず、プレビューに示すか TODO を使用してください。

---

ワークフローの概要

このワークフローを順番に実行してください。先に進まないでください。次のステップに移る前に、各ゲートを完了してください。

Step 0: 進捗管理を開始する

他のワークフローステップに進む前に実施してください。

タスク追跡ツールを使って進捗チェックリストを作成してください。ツールが使用できない場合は、以下のチェックリストを作業状態にコピーするか、返信に記載してください。各ステップの完了後、または分岐を引き継いだ後に更新してください。

• Step 1: モノレポのルートにある指示ファイルを確認する
• Step 2: 関連ドキュメントを確認する
• Step 3: ローカルファイルの状態を検出する
• Step 4: Mode 2 または Mode 3 が検出された場合、既存ファイルの使い方を確認する
• Step 5: 必要に応じて Mode 2 または Mode 3 内の分岐を選択する
• Step 6: 選択したモードのプレイブックを実行する
• Step 7: 必要に応じて、並行して調査し、残りの動作上の不明点を解消する
• Step 8: 最終的な編集チェックを行う
• Step 9: ラベル付きのプレビュー全体を提示し、レビューのフィードバックを集める
• Step 10: この手順で出力する場合は、確認済みのファイルを書き込む
• Step 11: ファイルを書き込んだ場合は、書き込み後の品質チェックを行う
• Step 12: 完了の概要を出力する

重要な順序ルール：

• Step 1、Step 2、Step 3 でローカルファイルの状態を確認し、モードを検出します。
• Step 4、Step 5 でユーザーの意図を確認し、検出されたモード内の分岐を選択します。
• Step 6 では、モードのプレイブックを1つだけ実行します。
• Step 7 は、必須のテンプレート項目に動作上の不明点が残っている場合にのみ実行します。
• Step 8 から Step 12 で、プレビュー、書き込み、レビューの手順を完了します。

後続のステップを省略するよう明示されている分岐がある場合は、その指示に従ってください。それ以外の場合は、この順序を守ってください。

---

Stage 1 — 開始状態を検出する

インタビューの質問をしたり、モード固有の手順に進んだりする前に、Stage 1 を完了してください。

• モードを黙って選択してはいけません。
• 検出したモードを必ずユーザーに伝えてください。
• 続行する前に確認を取ってください。

Step 1: モノレポのルートにある指示ファイルを確認する

ローカルファイルを評価する前に、現在の作業ディレクトリがモノレポ内のパッケージかどうかを確認してください。

現在のディレクトリより上の階層にあるルートに AGENTS.md または CLAUDE.md がある場合：

1. ルートファイルを最後まで読みます。

2. 次のように伝えます："ルートレベルの AGENTS.md または CLAUDE.md が [path] にあります。すべてのパッケージに適用される指示を重複させないよう、これをコンテキストとして使用します。ここで生成するファイルでは、必要に応じてルートを参照し、内容を繰り返さないようにします。"

3. 生成するファイルにヘッダー参照を追加します：

4. インタビュー中は、各ターンの冒頭で、質問する前に、そのセクションについてルートファイルで既に定められている内容を伝えます：

   "ルートの AGENTS.md または CLAUDE.md では、このセクションの内容として [summary] が定められています。

   生成するファイルでは、内容を繰り返さずに参照を記載してください。ユーザーが追加や上書きを希望した場合は、不足している点や異なる点に絞って、通常のターンで質問してください。

ステップ 2：関連ドキュメントを確認する

ステップ 1 の完了後、ローカルのファイル状態を検出する前に、次のいずれかに該当する正式な関連ドキュメントを確認します。

• 行動レイヤーの境界を適切に保つのに役立つ、または
• 最終的な ## Related Documentation セクションに含めるべきドキュメントである。

次の順番で関連ドキュメントを確認します。

1. openspec/config.yml または openspec/config.yaml があるか確認します。
   • どちらかのファイルがある場合は読み、プロジェクトの技術スタックとパターンを把握します。
   • ## Related Documentation セクションに記載するため、ファイルの存在を記録します。
   • 次のように知らせます。「openspec/config.yml または openspec/config.yaml が見つかりました — 行動とプロジェクト固有の DNA の境界を保つために活用します。」
2. ARCHITECTURE.md があるか確認します。
   • ファイルがある場合は読み、システム構造を把握します。
   • ## Related Documentation セクションに記載するため、ファイルの存在を記録します。
   • 次のように知らせます。「ARCHITECTURE.md が見つかりました — 行動のガイダンスがシステム構造に依存する場合に活用します。」
3. CONSTRAINTS.md、EPISTEMIC-MAP.md、JARGON.md を特に重視し、その他の正式な関連ドキュメントがあるか確認します。
   • ファイルがある場合は、行動のガイダンス、承認の境界、エージェント向けの用語に実質的な影響を与える可能性がある場合に限り読みます。
   • 最終的な ## Related Documentation セクションに記載するため、存在するファイルを記録します。

この確認では、次の制限を適用します。

• このステップを広範なハンドブックの調査にしないでください。
• 正式な関連ドキュメントを特定します。その内容全体を AGENTS.md に取り込まないでください。
• 行動に関するファイルの正確性と適切な範囲、関連リンクを保つために必要な部分だけを読みます。

ステップ 3：ローカルのファイル状態を検出する

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

ローカルの AGENTS.md または CLAUDE.md の状態を検出します。

次の順番で確認します。

1. 現在のディレクトリにローカルの AGENTS.md または CLAUDE.md があるか確認します。
2. どちらのファイルもない場合は、モード 1：作成を選択します。
3. ローカルファイルがある場合は、モードを分類する前に読みます。
4. ファイルを読んだ後、モードを一度だけ分類します。
   • 空またはほぼ空で、意味のある行が約 10 行未満の場合は、上書きの確認を伴うモード 1：作成を選択します。 次のように質問します。「AGENTS.md はありますが、ほぼ空のようです。最初から内容を作成しますか、それとも現在の内容を保持しますか？」
   • ./assets/template.md の正式なテンプレート構成に基づく形で、正式なセクション見出しが 2 つ以上認識できる場合は、モード 3：更新を選択します。
   • 認識できる形式ではないものの、実際の内容が記載されている場合は、モード 2：取り込みを選択します。

認識、更新、監査の動作では、正式な構成の参照先として ./assets/template.md を使用します。すべての必須セクションでは、見出しをテンプレートで定義されたとおりにし、正式な順序を維持します。## Optional review-specific rules や ## Maintenance guidance などの任意の見出しは、テンプレートで許可されている場合に限り残します。

次の図は、分類の参考として使用してください。優先されるのは、上記の順序付きリストです。

Local `AGENTS.md` or `CLAUDE.md` in current directory?
│
├── No
│   └── MODE 1: Create
│       Full interview from scratch.
│
└── Yes
    ├── Read the file first
    └── Then classify:
        ├── Empty or near-blank (< about 10 meaningful lines)
        │   └── MODE 1: Create
        │       Ask: "AGENTS.md exists but appears empty — should I populate it from scratch, or preserve any current content?"
        ├── Canonical template shape from `./assets/template.md`
        │   └── MODE 3: Refresh
        │       Two or more canonical section headings in recognizably template-based form.
        └── Real content in an unrecognized shape
            └── MODE 2: Import

完了条件：ファイルの状態と検出したモードが明示されていること。

---

ステージ 2 — 作業の進め方を確認する

検出、逸脱のスキャン、またはいずれかのモード固有のヒアリングを開始する前に、ステージ 2 を完了してください。

ステップ 4：既存ファイルの使用方法を確認する

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

ステップ 3 で モード 2 が検出された場合は、まず次の質問をします。

「始める前に、このファイルには標準テンプレートに従っていない内容があります。 新規作成して、既存ファイルを参考資料としてのみ扱いますか (インポートの場合に推奨)、それとも既存ファイルを使用しますか？」

ステップ 3 で モード 3 が検出された場合は、まず次の質問をします。

「始める前に、このファイルはすでに標準テンプレートに従っています。 既存ファイルを使用しますか (更新の場合に推奨)、それとも 新規作成して、参考資料としてのみ扱いますか？」

ユーザーが新規作成を選択した場合は、ただちにモード 1：作成に切り替えます。

• 既存ファイルは読み取り専用の参考資料として扱います。
• 既存ファイルのうち、現在も正確な内容は引き継ぎます。
• 既存ファイルの内容を黙って破棄してはいけません。
• テンプレートは、新しいファイルのトップレベルの構造を決めるために使用し、既存のガイダンスを残してよいかどうかの判断には使用しません。
• 既存のガイダンスが「最終採用ルール」を満たしているものの、専用のテンプレート見出しがない場合は、その動作を規定する標準セクションに配置します。
• テンプレートに記載がないことだけを理由に、トップレベルのセクションを追加したり、そのガイダンスを破棄したりしてはいけません。
• 構造を一から再生成します。
• その後、ステップ 6aに進みます。

ユーザーが既存ファイルを使用を選択した場合：

• ステップ 3 で モード 2 が検出された場合は、ステップ 5aに進みます
• ステップ 3 で モード 3 が検出された場合は、ステップ 5bに進みます

ステップ 3 ですでにモード 1が選択されている場合は、ステップ 4 とステップ 5 を省略し、直接ステップ 6aに進みます。

完了条件：モード 2 またはモード 3 が検出された場合、新規作成と既存ファイルを使用のどちらにするかが明示されていること。

ステップ 5a：モード 2 の分岐を選択する

前提：ステップ 4 からモード 2としてここに進んでいること。

変更や統合を始める前に、次の 3 つの選択肢を提示します。

「この AGENTS.md には、認識できない構造の既存コンテンツがあります。 どのように進めますか？

(a) 再構成 — 既存コンテンツを取り込み、このスキルのテンプレートの各セクションに割り当てます。代わりに標準の関連ドキュメントに含めるべき内容にはフラグを付け、ギャップを埋めるための的を絞ったヒアリングを行い、現在のファイルと置き換えられる統合済みファイルを作成します。

(b) 追記 — 完全なヒアリングを行い、既存の内容を変更せずに、その下にテンプレートに沿った AGENTS.md ブロックを追記します。

(c) ドライラン — 完全なヒアリングを行い、ファイルシステムを変更せずに、生成する内容を正確に表示します。確定する前に適合性を評価する場合に使用してください。」

分岐先：

• ユーザーが (a) を選択した場合は、ステップ 6bに進みます。
• ユーザーが (b) を選択した場合は、ステップ 6cに進みます。
• ユーザーが (c) を選択した場合は、ステップ 6dに進みます。
• ユーザーが選択するまで、いずれの分岐も開始してはいけません。

完了条件：モード 2 の分岐が明示されていること。

ステップ 5b：モード 3 の更新方法を選択する

前提：ステップ 4 からモード 3としてここに進んでいること。

モード 3 の意図確認ゲートが満たされた後に限り、更新方法を 1 つだけ選択します。

• 部分更新 — 依頼がすでにこのスキルの範囲内にあり、次のように対象が明確に限定されている場合に使用します。
  • 既知の矛盾を 1 つ修正する
  • 新たに確認された根拠に基づき、1 つのセクションを更新する
  • 古くなったルールを 1 つ削除または緩和する
  • 既存のセクションに属する限定的な追加を 1 つ行う
  • 周囲の構造を変更せずに、ラッパーまたは変換を更新する
• 全体更新 — 依頼の範囲が広い場合、ファイルの複数箇所にずれが生じている可能性がある場合、または限定的な更新によって、より広範な見直しが必要となる矛盾、セクション間の依存関係、不整合が明らかになった場合に使用します。

分岐先：

• 依頼が部分更新の条件を満たす場合は、ステップ 6eに進みます。
• それ以外の場合は、ステップ 6fに進みます。

完了条件：更新の分析を始める前に、モード 3 の更新方法が明示されていること。

---

ステージ 3 — 選択したモードのプレイブックを実行する

ステップ 6 の分岐を 1 つだけ実行します。

ヒアリングを行う経路で共通のヒアリングブロック

インタビューはステージ 1 と 2 の完了後にのみ行ってください。会話形式で進めてください。質問を一度にすべて提示しないでください。質問は、./assets/template.md の標準テンプレートに直接対応する自然なトピックごとのやり取りにまとめてください。このテンプレートを、セクション名、セクションの順序、必須セクションと任意セクションの区別、プレースホルダーの扱い、デフォルトのひな型に関する唯一の基準とします。ユーザーがワークフローについて説明した場合は、関連する行動上の制約を推測し、同じ内容を再度質問するのではなく確認してください。質問の数や詳しさは、依頼の規模に応じたものにしてください。リポジトリ内の確かな証拠からすでにわかる情報は質問しないでください。

テンプレートに含まれる内容だけを質問してください。テンプレートで定義されていない回答を記載するために、追加の AGENTS.md セクションを独自に作成しないでください。テンプレート上で任意のトピックについては、テンプレートで許容される範囲で、維持、調整、省略のいずれとするか確認してください。複数のやり取りから回答をまとめる際は、./assets/template.md で定義された正確な標準セクションに対応付けてください。

ターン 1 — 優先すること

• このリポジトリで、エージェントが重視すべき、長期的に有効な優先事項は何ですか？ (例：推測せずリポジトリのワークフローに従う、範囲を絞った小さな変更を優先する、作業を追跡可能にする、既存のパターンに沿う。)
• エージェントの行動に大きく影響する、リポジトリ固有の優先事項はありますか？
• エージェントが継続的に重視すべきなのは、シンプルさ、スピード、安全性、レビューのしやすさ、あるいは別の事項ですか？

ターン 2 — コミュニケーション方法

• エージェントにはどのようなコミュニケーションを望みますか？ (例：簡潔、詳しい説明を含む、会話的、状況に応じて調整する。)
• エージェントには推論を説明してほしいですか、それとも作業のみを進めてほしいですか？
• 変更を加える際、テンプレートに記載されている内容以外に、報告についての必須事項はありますか？ (例：差分を表示する、ファイル全体を表示する、インラインコメントを付ける、説明を別のブロックにまとめる。)
• 情報が不足している場合や不確かな場合、エージェントにはどのように対応してほしいですか？ (例：前提を明示して範囲を絞って進める、進める前に必ず確認する、範囲が変わる可能性のある不確実性についてのみ質問する。)

ターン 3 — 作業の進め方

• 変更を加える前に、エージェントは何を読み、確認し、または伝える必要がありますか？
• 変更作業中に、テンプレートのデフォルト以外で継続的に守るべきワークフロー上の要件はありますか？
• タスクを完了する前に、必ず実施すべき検証、作業範囲の確認、安全性の確認はありますか？
• リポジトリで OpenSpec などの仕様駆動型ワークフローを使っている場合は、ここには長期的に有効なエージェントのワークフロー指針のみを記載し、詳しい手順については標準ドキュメントへのリンクを示してください。

ターン 4 — リポジトリ固有のコマンドとエントリーポイント

• セットアップ、ビルド、テスト、Lint／フォーマット、タスク実行では、どのコマンドを優先すべきですか？
• 間違えやすいパスの規則、パッケージマネージャーのルール、コマンドの実行パターンはありますか？
• 特定のリポジトリのエントリーポイントを使うために、エージェントが避けるべきコマンドはありますか？

ターン 5 — 判断の指針

• エージェントはどのような場合に質問し、どのような場合に自律的に進めるべきですか？ 例として適切な内容：「ファイルの削除」「公開 API の変更」「マイグレーションの変更」「新しい依存関係の追加」。
• 作業の途中で範囲が広がった場合、デフォルトではどのように対応すべきですか？
• 根拠が不十分な場合や、複数の実装方法が妥当な場合、エージェントは選択、質問、トレードオフの提示のどれを行うべきですか？

ターン 6 — 承認と安全性の境界

• リスクが高い、コストがかかる、元に戻しにくい、または共有システムに影響するため、実行前に承認を必要とする操作は何ですか？
• 常に守るべき、譲れない安全上の境界は何ですか？ 例：シークレットを絶対にコミットしない、スキーマやマイグレーションの変更前に確認する、承認なしに本番環境で操作しない。
• サンドボックス、リモート環境、公開、または外部から信頼されている情報に関して、文書化すべき境界はありますか？

ターン 7 — 完了時の品質基準

• 作業完了と見なす前に、どのチェックを実施する必要がありますか？
• エージェントはどのような証拠を報告すべきですか？
• このリポジトリ固有のレビューや引き継ぎに関する要件はありますか？ ターン 8 — 任意のレビュー固有ルール、関連ドキュメント、メンテナンスガイダンス
• このリポジトリでは、コードレビューの動作を導くために AGENTS.md を十分に活用していますか。## Optional review-specific rules を残すべきでしょうか。それとも、この任意のセクションは省略すべきでしょうか。
• 実際に存在する場合、## Related Documentation にどの正規ドキュメントを記載すべきでしょうか。
• ## Maintenance guidance に追加すべきリポジトリ固有のメンテナンスガイダンスはありますか。それとも、テンプレートの既定の内容をそのままにすべきでしょうか。

インタビュー形式のパスで共通するスマートデフォルトのブロック

より強い根拠をすでに確認した後で、避けられるインタビューの負担を減らす場合にのみ、スマートデフォルトを使用してください。

スマートデフォルトは確認のための質問であり、恒久的なポリシーではありません。次の条件を満たす場合にのみ使用してください。

• 該当するテンプレートのフィールドに、まだ回答が必要である
• ユーザーからの直接の入力で、すでに回答が示されていない
• リポジトリの根拠から、すでに回答が得られていない
• 一から尋ねるよりも、既定値を提示するほうが、ユーザーが可能性の高い慣例をすばやく確認できる

新たなポリシーを導入したり、対象範囲を広げたり、エコシステムに関する想定を生成ファイルに持ち込んだりするために、スマートデフォルトを使わないでください。

次のルールを適用してください。

1. まず、より強い根拠を優先します。 ユーザーからの直接の入力、リポジトリの根拠、正規テンプレート、または現在も一貫性のある既存のガイダンスによってフィールドの回答がすでに得られている場合、そのフィールドに既定値を提示しないでください。
2. 既定値は結論ではなく、確認のための質問として提示します。 既定値は、確認、却下、または修正できるものとして表現してください。採用済みのポリシーとして示さないでください。
3. 既定値の範囲を根拠に見合うものにします。 一度に一つの可能性の高い慣例を確かめる、限定的な質問を優先してください。リポジトリから得られた一つの兆候を、広範なワークフローの一式に拡大しないでください。
4. 例はあくまで参考として扱います。 以下の質問例は、よくあるパターンを示しています。網羅的なチェックリストではなく、毎回必ず使う必要もありません。
5. ユーザーまたはリポジトリによって否定された既定値を残さないでください。 より強い根拠に基づく回答に置き換えるか、フィールドを確認できない場合は `` のままにしてください。

質問の例

収集済みのリポジトリの根拠に当てはまる場合にのみ、次のようなパターンを使用してください。

リポジトリで PNPM モノレポを使っているように見える場合：

• 「PNPM ワークスペースの兆候が見つかりました。生成するガイダンスでは、ワークスペースルートに関わる依存関係の変更とパッケージ単位の依存関係の変更を、異なるものとして扱うべきでしょうか。」
• 「パッケージの選択が重要な場合、エージェントにはワークスペースを考慮したタスクコマンドを優先させますか。」

リポジトリで CI に GitHub Actions を使っているように見える場合：

• 「GitHub Actions のワークフローが見つかりました。作業完了と判断する前に、エージェントに特定の CI チェックの結果を報告させる、またはその完了を待たせるべきでしょうか。」
• 「ファイルに記載すべき必須ステータスチェックや PR ゲートはありますか。」

リポジトリで Conventional Commits を使っているように見える場合：

• 「コミット規約に関する兆候が見つかりました。ファイルでエージェントに Conventional Commits を使うよう指示すべきでしょうか。また、記載すべきリポジトリ固有のタイプや破壊的変更のルールはありますか。」
• 「スコープの使用方法やフッターの規約は、明記するほど重要ですか。」

リポジトリで OpenSpec または別の仕様駆動ワークフローを使っているように見える場合：

• 「仕様駆動ワークフローの兆候が見つかりました。そのワークフローのうち、AGENTS.md に記載するべき、エージェントが恒常的に従う動作はどの部分で、正規のプロジェクトドキュメントに残すべき部分はどれでしょうか。」
• 「重要な変更では、実装を始める前に、エージェントが文書化された仕様ワークフローに従うべきでしょうか。」

完了条件：可能性の高い慣例が確認、却下、またはより強い根拠に基づく内容に置き換えられ、未確認の既定値が恒久的なガイダンスに持ち込まれていないこと。

ステップ 6a：モード 1 を実行 — 新規作成

新しいリポジトリ、ユーザーが内容を追加したい空またはほぼ空のファイル、あるいは明示的に新規作成を選択した場合は、このブランチを使用します。

このブランチは次の順に実行します。

1. インタビュー形式のパスに共通するインタビューブロックを実行します。
2. インタビュー形式のパスに共通するスマートデフォルトブロックを実行します。
3. 必須テンプレートフィールドに未解決の項目が残っている場合は、ステップ 7に進みます。
4. それ以外の場合は、ステップ 8に進みます。

完了条件：インタビューの回答と確認済みのスマートデフォルトがギャップを埋めるための調査に利用できる状態、またはドラフトが最終的な編集レビューに進める状態です。

ステップ 6b：モード 2 を実行 — 再構成

このスキルで生成されていない実質的な内容がファイルにあり、ユーザーが**（a）再構成**を選択した場合に限り、このブランチを使用します。

このブランチは次の順に実行します。

1. ファイル全体を読みます。
2. 既存の各セクションを、./assets/template.md の標準テンプレートセクションに対応付けます。
3. テンプレートのセクション順序を維持し、## Optional review-specific rules のように、テンプレートで明示的に許可されている任意のセクションのみを残します。
4. 関心の分離の境界に反する内容（スタックの事実、技術バージョン、ドメインの説明、制約、前提、内部用語など）にフラグを立てます。その内容は適切な標準の関連ドキュメントに移します。
   • 違反項目ごとに、次のように尋ねます。「これは［X］について説明しています。AGENTS.md や CLAUDE.md ではなく、標準の関連ドキュメントに記載する内容です。適切なドキュメントに移して、ここには参照を残しますか？」
5. 既存の記述がないために不足している箇所、つまり標準テンプレートのセクション、または ./assets/template.md の必須テンプレートフィールドに限って、インタビュー形式のパスに共通するインタビューブロックを実行します。
6. プレビューの前に、情報源の優先順位ルールを適用し、重複する内容、矛盾する内容、隣接ドキュメントに属する内容を削除します。
7. ステップ 6 の後も必須テンプレートフィールドの回答が不足している場合は、ステップ 7に進みます。
8. それ以外の場合は、ステップ 8に進みます。
9. ステップ 9では、書き込み前に統合プレビューを表示します。引き継いだ内容には # from existing file、新しい内容には # new のラベルを付けます。

完了条件：統合ドラフトが最終的な編集レビューに進める状態、または残りの不足項目がステップ 7 に回されている状態です。

ステップ 6c：モード 2 を実行 — 追記

このスキルで生成されていない実質的な内容がファイルにあり、ユーザーが**（b）追記**を選択した場合に限り、このブランチを使用します。

このブランチは次の順に実行します。

1. インタビュー形式のパスに共通するインタビューブロックを実行します。
2. インタビュー形式のパスに共通するスマートデフォルトブロックを実行します。
3. 必須テンプレートフィールドに未解決の項目が残っている場合は、ステップ 7に進みます。
4. それ以外の場合は、ステップ 8に進みます。
5. ステップ 10では、生成したテンプレートに沿ったブロックを --- 区切りの下に追記し、コメントを付けます：``。

追記モードでも、矛盾する恒久的なガイダンスを追加する場合は、プレビューでその矛盾を提示してください。

完了条件：追記したドラフトが最終的な編集レビューに進める状態、または残りの不足項目がステップ 7 に回されている状態です。

ステップ 6d：モード 2 を実行 — ドライラン

このスキルで生成されていない実質的な内容がファイルにあり、ユーザーが**（c）ドライラン**を選択した場合に限り、このブランチを使用します。

このブランチは次の順に実行します。

1. インタビュー形式のパスに共通するインタビューブロックを実行します。
2. インタビュー形式のパスに共通するスマートデフォルトブロックを実行します。
3. 必須テンプレートフィールドに未解決の項目が残っている場合は、ステップ 7に進みます。
4. それ以外の場合は、ステップ 8に進みます。
5. ステップ 9では、ラベル付きプレビューの表示後に停止します。
6. 出力を会話内に提示し、「ファイルは変更されていません」と明示します。
7. ユーザーが内容に問題がなければ、（a）再構成または**（b）追記**として再実行することを提案します。
8. ステップ 10とステップ 11はスキップします。ステップ 9 の後は、直接ステップ 12に進みます。

完了条件：ドライランのドラフトが最終的な編集レビューに進める状態、または残りの不足項目がステップ 7 に回されている状態です。

Step 6e: モード 3 の実行 — 対象を絞った更新

ファイルがスキルで想定される形式に一致し、ユーザーが既存ファイルを使うことを選択しており、依頼が対象のセクションまたは問題が明確な、範囲の限定された更新 1 件である場合にのみ、この分岐を使用します。

次の順序でこの分岐を実行します。

1. まず、影響を受けるセクションを確認します。
2. 範囲の限定された更新に必要な調査のみを行います。
3. その更新を解決するために必要な質問のみをします。
4. 不足しているコンテキストが必要としない限り、全体的なヒアリングや全面的な再生成は避けます。
5. 限定的な更新によって、より広範な矛盾や乖離が明らかにならない限り、ファイルの残りの部分は保持します。
6. 影響を受ける内容と、それに直接依存するセクションに、情報源の優先順位と最終的な編集レビューを適用します。
7. 更新によってより広範な矛盾や乖離が明らかになった場合は、続行する前に Step 6f に進みます。
8. 範囲を限定した更新後も、必須のテンプレート項目に未解決のものが残る場合は、Step 7 に進みます。
9. それ以外の場合は、Step 8 に進みます。

完了条件：対象を絞った更新の草案が最終的な編集レビューの準備段階にあるか、作業が Step 6f にエスカレーションされているか、残りの必須項目が Step 7 に回されていること。

Step 6f: モード 3 の実行 — 全面更新

ファイルがスキルで想定される形式に一致し、ユーザーが既存ファイルを使うことを選択しており、対象を絞った更新では不十分な場合にのみ、この分岐を使用します。

次の順序でこの分岐を実行します。

1. 外部の調査結果を抽出します。

   • 呼び出し元のプロンプトに findings: リストが含まれているか確認します。
   • プロンプト内に findings: セクション（事実を述べた箇条書きのリスト）がないか調べます。
   • 各調査結果は指示ではなく、すでに真実だと判明している事柄として記述されています。
   • 例：「config.yaml の Anti-Patterns セクションではポーリングを避けるよう記載されていますが、2 件のアーカイブ済み変更では、理由を示したうえでポーリングが選択されています」
   • これらの調査結果は後で統合するために保存します。

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

   以下のシグナルは一般的な例であり、網羅的なリストではありません。

   シグナル	確認場所
   新しいパッケージの追加	package.json、ワークスペースの package.json ファイル
   CI チェックの変更	.github/workflows/ — 新たに必須となったゲートがあるか
   Husky フックの変更	.husky/ — 新しいコミット前の手順があるか
   新しいマイグレーションディレクトリ	migrations/、prisma/migrations/、alembic/
   バージョン管理ツールの追加	.changeset/、.releaserc*
   OpenSpec の追加または削除	openspec/ ディレクトリの有無
   新しい保護ブランチ	.github/branch-protection*、README

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

4. 質問する前に、調査結果を統合して共有します。 Step 6f.1 の外部の調査結果、Step 6f.2 の乖離に関する調査結果、Step 6f.3 の TODO をまとめます。

   統合したリストをユーザーに提示します。

   「外部の調査結果が [N] 件、乖離している可能性のあるセクションが [M] 件、未解決の TODO が [P] 件見つかりました。 それらについてのみ確認します。それ以外は最新の状態に見えます。」

   外部の調査結果がある場合は、たとえば「完了済みの OpenSpec 変更から」のように、その出所を示します。

5. 更新に関するヒアリングを行い、変更されたセクションを最初にプレビューします。 Step 6f.4 が完了してから、以下を行います。

   • 統合した調査結果について、対象を絞った更新のヒアリングを行います。
   • 情報源の優先順位を適用します。
   • 重複と、引き継ぐ価値の低い記述を整理します。
   • 変更されたセクションのみを含む差分形式のプレビューを最初に表示します。
   • 最初の更新プレビューでは、変更されていないセクションを再出力しません。
   • 書き込みの前には、Step 9 で必要となる、ラベル付きの完全なプレビューも必ず作成します。

6. 更新後も必須のテンプレート項目に未解決のものが残る場合は、Step 7 に進みます。

7. それ以外の場合は、Step 8 に進みます。

完了条件：変更されたセクションの草案が最終的な編集レビューの準備段階にあり、残りの必須項目がある場合は Step 7 に回され、Step 9 で必要となる完全なラベル付きプレビューがまだ保留されていること。

---

Stage 4 — 並行調査で残りの動作上の不足を補う

ステップ 7：並行調査で残る動作上のギャップを埋める

ステップ 7 は、ステップ 6 のブランチを 1 つ完了した後にのみ実行し、動作上のギャップが未解決のまま残っている標準テンプレートのセクションまたは必須テンプレート項目に限って実行します。選択したステップ 6 のブランチですでに十分な情報が確認できている場合は、ステップ 7 を省略して ステップ 8 に進みます。

./assets/template.md にある、まだ回答がないすべての標準テンプレートのセクションと必須テンプレート項目を監査します。該当する場合は、## Quality bar for finished work、## Related Documentation、## Maintenance guidance も含めます。各ギャップについて、再度質問したり `` を残したりする前に、並行サブエージェントを使ってコードベースから動作上の意図を直接推定します。明示的な TODO がある動作に関わるファイルは、調査対象として有効です。必須のテンプレートセクションが欠けているファイルは、エージェントの動作に予測不能な形で影響します。

調査の目的は、動作上のギャップを埋めることです。出力範囲を最大化することではありません。必要に応じて幅広く情報を集めますが、最終的な採用ルールを満たす調査結果のみを引き継ぎます。

調査サブエージェントは並行して起動してください。順番に調査してはいけません。各エージェントは 1 つの動作領域に集中し、構造化された調査結果を返します。すべてのエージェントの完了を待ちます。その後、ステップ 8 の前に結果を統合します。

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

エージェント A — バージョン管理とコミット規約

• コミット規約：commitlint.config.*、最近の git log --oneline、.gitmessage、.releaserc*
• バージョン管理ワークフロー：.changeset/、CHANGELOG.md、standard-version、conventional-changelog
• 強制プッシュの保護：.github/branch-protection*、ブランチポリシーに関する README の記述
• 返す内容：タイプと例を含むコミットメッセージ形式、バージョン管理コマンド、ブランチ保護ルール

エージェント B — CI/CD とコミット前ワークフロー

• PR ワークフロー：.github/PULL_REQUEST_TEMPLATE.md、.github/workflows/（CI ゲート名、必須チェック）
• コミット前チェック：.husky/、.lefthook.yml、package.json#scripts（lint、typecheck、test）
• 返す内容：PR の規約（規模、ラベル、テンプレート）、コマンドを含むコミット前チェックリスト、CI の必須チェック

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

• テストランナー：vitest.config.*、jest.config.*、pytest.ini、pyproject.toml [tool.pytest]、Playwright、Cypress
• パッケージマネージャー：package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lockb
• TypeScript プロジェクト：tsconfig.json の有無、tsconfig.json#paths または vite.config のパスエイリアス
• Vitest の設定：vitest.config.ts — clearMocks、mockReset、restoreMocks フラグを確認
• テストファイルの型チェック：CI ワークフロー、package.json のスクリプト — tsc --noEmit がテストファイルを対象に実行されるか確認
• 返す内容：該当する場合は、テストフレームワーク、パッケージマネージャー、TypeScript 固有のガードレール、Vitest のクリーンアップ設定

エージェント D — セキュリティとマイグレーション

• マイグレーションファイル：migrations/、prisma/migrations/、alembic/ の有無
• シークレットの取り扱い：.env.example、.gitignore のパターン、dotenv またはボールトツールの有無
• 返す内容：マイグレーションが存在する場合のガードレール、シークレットの取り扱い方針

エージェント E — OpenSpec と仕様駆動ワークフロー

• OpenSpec の兆候：openspec/ ディレクトリ、openspec/config.yml、openspec/config.yaml、および opsx:* または openspec-* スキルへの参照
• 関連するワークフローの根拠：仕様駆動の作業に関係する、永続的なエージェントワークフローの期待事項を定義している場合に限り、関連ドキュメントを確認
• 返す内容：仕様駆動ワークフローが使われているか、どの部分を永続的なエージェント動作ガイダンスに含めるべきか、エージェントがそのワークフローをいつ実行すべきか

すべてのエージェントの完了後： 調査結果を統合し、1 つの調査マップにまとめます。 各テンプレート項目に # inferred from [source] のタグを付けます。不明な場合は空欄のままにします。調査後も空欄の項目は、生成ファイル内で明示的な `` マーカーになります。テンプレートで削除が明示的に許可されている場合に限り、任意のテンプレートセクションを省略します。

ソース注釈付きのプレビュー： 検出結果を統合したら、推定値に末尾コメントを付けてプレビューを表示します。

- Always run `pnpm check` before committing   # inferred from .husky/pre-commit
- Use Conventional Commits (`feat:`, `fix:`)  # inferred from commitlint.config.ts

フィールドを推定できない場合 — たとえば、意思決定のヒューリスティック、コミュニケーションスタイル、役割の定義など — セクションを省略せず、`` を付けます。

完了条件：残っている行動上の不足点が、リポジトリの根拠に基づいて解決されているか、ステップ 8 の前に明示的な TODO として残されています。

---

ステージ 5 — プレビュー、書き込み、品質チェック

選択したパスに必要なすべての先行ステップが完了するまで、ステージ 5 に進まないでください。

ステップ 8：プレビューの前に必須の最終編集パスを実施する

ユーザーが確認する前に、組み立てたドラフトを整理します。

• セクション間で重複するガイダンスを削除します。
• 情報源の優先順位ルールを使って矛盾を解消します。
• エージェントの行動を直接規定しない、関連ドキュメントやハンドブック形式の内容を削除します。
• 根拠があり、行動に影響し、長期的に有効な場合を除き、壊れやすい詳細情報の優先度を下げます。
• 裏付けの弱い詳細情報は、信頼性の高いルール、正式なリンク、または確信度が低すぎる場合は `` に置き換えます。
• 範囲が広くノイズの多いドラフトよりも、短く明確で、行動に焦点を当てた最終ドラフトを優先します。

完了条件：ドラフトが整理され、プレビューの準備ができています。

ステップ 9：ラベル付きのプレビューを表示し、レビューのフィードバックを集める

何かを書き込む前に、整理済みの AGENTS.md または CLAUDE.md のラベル付きプレビュー全体を表示します。

• 推定値には、その情報源を示すコメントを付けます。
• ステップ 6b では、引き継いだ内容に # from existing file、新しい内容に # new のラベルを付けます。
• 未解決のテンプレートフィールドには `` を付けます。
• ./assets/template.md の必須テンプレートセクションを、テンプレートの順序のまま残します。
• 任意のセクションは、リポジトリに引き続き役立ち、かつ ./assets/template.md で許可されている場合にのみ残します。
• 更新フローでは、変更されたセクションを先に表示してもかまいませんが、書き込みの前にプレビュー全体を表示する必要があります。

これにより、ユーザーは信頼度を完全に把握できます。

ゲート — 書き込む前にレビューのフィードバックを集める

「この内容でよさそうですか？ファイルを書き込む前に、修正または補足したいセクションはありますか？」と尋ねます。

非対話型またはヘッドレス環境でも、プレビュー全体を表示し、セッション中に人間の確認を得られなかったことを明示してください。実際に確認されていないのに、人間による確認済みだと主張してはいけません。

このゲートを満たすか、コンテキストが明示的に非対話型である場合を除き、ファイルを書き込まないでください。

完了条件：レビューゲートが満たされているか、コンテキストが明示的に非対話型です。

ステップ 10：確認済みのファイルを書き込む

出力を書き込むブランチでのみ、このステップを実行します。ステップ 6d ではスキップします。

レビューゲートを満たした後に限り、オンボーディング対象のディレクトリにある AGENTS.md または CLAUDE.md に書き込み、推定元コメントを削除します。

これらのコメントはレビュー用であり、最終ファイルに含めてはいけません。

## 関連ドキュメント セクションには、リポジトリ内に存在し、エージェントの行動に実質的に役立つファイルへのリンクのみを含めます。リンクを含める前に、候補となる各ファイルを確認してください。テンプレートの例示的な箇条書き（ARCHITECTURE.md、CONSTRAINTS.md、openspec/config.yaml、JARGON.md、その他の正式なドキュメントのプレースホルダー）は、実際のリポジトリ内のファイルに応じて調整または削除します。openspec/config.yml または openspec/config.yaml が存在しない場合は、どちらのパスも含めないでください。

完了条件：レビュー専用コメントを含めずに、確認済みのファイルが書き込まれています。

Step 11: AGENTS.md または CLAUDE.md の品質チェックを実行する

ファイルを書き込む Step 10 の後にのみ、このステップを実行します。Step 6d ではスキップしてください。

書き込みの完了後、生成されたファイルを ./references/rubric.md に照らして評価します。

ルーブリックは形式的に言及するだけでなく、書き込み後の構造化レビューとして使用してください。生成された AGENTS.md または CLAUDE.md をレビューします。生成されたファイルが CLAUDE.md の場合は、リポジトリのエージェント指示ファイルとして同じルーブリックを適用してください。スコープや参照先の確認に必要な場合に限り、同じディレクトリまたはルートレベルにあるエージェント指示のラッパーと、直接リンクされた関連ドキュメントを参照してください。

レビューは次の順に実施します。

1. レビュー対象の成果物を確認します。
2. 公平に採点するために必要な証拠だけを集めます。
3. ルーブリックのすべてのカテゴリを 0〜5 のスケールで採点します。
4. 次の式を使用してカテゴリの重みを適用します：（素点 / 5）× カテゴリの重み。
5. レビューメモと、採点対象外の有効性チェックを追加します。

ユーザーには、次の内容を含む簡潔なレビュー結果を提示します。

• レビューしたファイルのパス
• 100 点満点の加重合計スコア
• 次の基準に基づく対応する評価：
  • A = 90〜100
  • B = 75〜89
  • C = 60〜74
  • D = 40〜59
  • F = 0〜39
• 強みを 2〜4 点
• 最も弱いルーブリックカテゴリとその素点
• 該当する場合、最もリスクの高い弱点
• ファイルが実際にエージェントの動作を変える可能性について、採点対象外の短い有効性メモ

結果に基づいて、ユーザー向けの完了時の対応を決めます。

• 評価が A の場合、生成された AGENTS.md または CLAUDE.md を採点し、品質が高いと判断したことをユーザーに伝えます。
• 評価が B の場合、生成された AGENTS.md または CLAUDE.md を採点し、品質は十分と判断したことを簡潔に伝えます。
• 評価が B 未満の場合、ファイルが期待する品質基準に達していないことをユーザーに警告し、最も弱いカテゴリに結び付けた具体的な改善案を提示します。改善案は、実行可能で簡潔なものとし、優先順位を付けてください。また、最も影響の大きい問題に対処するため、ファイルを修正することも提案してください。

スコアの一部が不完全なリポジトリの証拠に依存する場合は、その旨を簡潔に伝え、確実性を誇張しないでください。

完了条件：ユーザーが生成されたファイルと、書き込み後の品質評価の両方を受け取っていること。

Step 12: 完了サマリーを出力する

適用される前のステップが完了した後にのみ、このステップを実行します。

書き込みと品質チェックが完了したら、生成した内容、直接回答された内容と推測された内容、人による入力がまだ必要な `` セクション、品質チェックの結果を簡潔にまとめて出力します。

Step 6d では、書き込みと品質チェックの結果を除いた同じ簡潔なサマリーを出力し、書き込みを行っていないことを明示します。

完了条件：ユーザーに最終サマリーが提示されていること。

---

AGENTS.md テンプレート

正式なテンプレート ./assets/template.md を読み、使用してください。

AGENTS.md の構造に関しては、セクション名、セクション順、必須セクションと任意セクションの区別、プレースホルダーの扱い、既定の枠組みを含め、このファイルを唯一の参照元としてください。AGENTS.md の生成、取り込み、再構成、追記、監査、更新を行う際は、構造に関わるすべての処理を、このスキル内の例、チェックリスト、埋め込まれたセクション一覧ではなく、このテンプレートに基づいてください。

AGENTS.md を生成または更新するときは、テンプレートに厳密に従い、確認済みの回答またはリポジトリの証拠を使ってプレースホルダーを埋め、未解決のプレースホルダーは `` に置き換え、必須のテンプレートセクションを維持してください。任意のセクションを省略できるのは、テンプレートで明示的に許可されている場合に限ります。確認済みまたは強く推測できる場合を除き、例示的な文章をそのまま転記せず、最終ファイルは簡潔で、エージェントの動作に焦点を当てたものにしてください。

---

品質チェックリスト

オンボーディングが完了したと判断する前に、生成されたファイルが次の要件を満たしていることを確認してください。

• 振る舞いとプロジェクト DNA の分離を維持し、振る舞いに関係しない内容を、openspec/config.yml、openspec/config.yaml、ARCHITECTURE.md、CONSTRAINTS.md、EPISTEMIC-MAP.md、JARGON.md などの適切な正本となる関連ドキュメントに誘導している
• ./assets/template.md の必須セクションを、テンプレートの順序どおりにすべて含め、事実が不明な箇所には `` を使用している
• モノレポのパッケージファイルに重複して記載せず、ルートレベルのエージェント向けガイダンスを参照している
• リポジトリ内に存在する関連ドキュメントへのリンクのみを含めている
• 競合する恒常的なルールをそのまま残さず、情報源の優先順位に基づいて矛盾を解消している
• セクション間で重複するガイダンスを統合している
• エージェントの振る舞いを実質的に導かない、価値の低い、不安定な、ハンドブック形式の、または関連ドキュメント向けの内容を削除している
• 表面的な網羅性のために内容を水増しせず、各セクションを簡潔に保ち、振る舞いのレイヤーに焦点を当てている
• テンプレートの例やデフォルト値を、自動的に適用されるポリシーではなく、説明用のひな型として扱っている
• リポジトリに適合し、テンプレートで許可されている場合に限り、任意のテンプレートセクションを残している
• ファイルシステムに書き込む前に完全なプレビューを提示し、最終ファイルから推論に関するコメントを削除している
• 書き込み後に ./references/rubric.md に照らしてレビューし、その結果として得られた品質メモまたは改善ガイダンスをユーザーに提示している

---

対話の原則

• 並行して調査する。 調査が必要な場合は、サブエージェントを同時に起動してください。設定ファイルを一つずつ確認してはいけません。
• 尋問ではなく、会話をする。 関連する質問をまとめて一度に尋ねてください。箇条書きで質問を羅列せず、平易な英語で説明するように伝えてください。
• 推測して確認する。 「Husky についてお聞きしました。pre-commit フックでは pnpm check が実行されると想定していますが、確認いただけますか？」のほうが、何もないところから尋ねるより適切です。
• 曖昧さを減らす例を示す。 判断のヒューリスティクスについて尋ねる際は、ユーザーがパターンを見つけやすいよう、具体的なシナリオを提示してください。
• 反復して進める。 最終的な書き込みの前に、ユーザーが回答を修正できるようにしてください。
• 書き込み前にプレビューする。 ファイルシステムに触れる前に、生成した AGENTS.md または CLAUDE.md の全文を必ず提示し、明示的な確認を得てください。
• 尋ねる前に推測し、省略する前に尋ねる。 TODO が明記されたファイルは対応可能です。セクションが黙って抜けているファイルは、予測できない形でエージェントの振る舞いを左右します。
• 適切な分量を保つ。 信頼できる結果を得られる範囲で、最も軽量なワークフローを使用してください。範囲の狭い更新は、より広いずれが見つからない限り、狭い範囲に保ってください。
• レイヤーの境界を越えない。 この聞き取りの中でユーザーが振る舞いに関係しない内容を提示した場合は、それを認識したうえで、AGENTS.md や CLAUDE.md ではなく適切な正本となる関連ドキュメントに記載すべきだと伝えてください。プロジェクト DNA は accelint-onboard-openspec を使って openspec/config.yml または openspec/config.yaml に、システム構造は accelint-architecture-doc を使って ARCHITECTURE.md に、内部用語は jargon-extractor を使って JARGON.md に、前提とリスクは epistemic-mapper を使って EPISTEMIC-MAP.md に、外部との境界は constraints-extractor を使って CONSTRAINTS.md に振り分けてください。
• モノレポでは重複せず、参照する。 ルートレベルの AGENTS.md または CLAUDE.md が存在する場合、パッケージレベルのファイルではそれを参照し、そのパッケージ固有の内容だけを追加してください。ルートとパッケージのファイルに同じ指示を繰り返すと、エージェントの呼び出しごとにコンテキストが増えるため、パッケージのファイルは冗長ではなく、補足的な内容にしてください。
• 情報をまとめてからプレビューする。 ユーザーが確認するのは、組み立てたメモそのものではなく、整理済みの最終案です。