create-second-brain-prd

セカンドブレイン PRD ジェネレーター

ユーザーが記入した要件テンプレートを基に、AI セカンドブレインを構築するための、パーソナライズされたプロダクト要件定義書を生成します。

このスキルには、空のテンプレートが ${CLAUDE_SKILL_DIR}/my-second-brain-requirements.md に同梱されています。 このスキルを実行する前に、テンプレートをワークスペースにコピーして記入してください。

パラメーター

• $0（必須）— 記入済みの要件ファイルのパス（例：./my-second-brain-requirements.md）
• $1（任意）— PRD の出力先パス。デフォルトは .agent/plans/second-brain-prd.md です

ワークフロー

1. 要件を読む — $0 にある記入済みの要件ファイルを読みます。引数が指定されていない場合は、ユーザーにパスを尋ねてください。まだ記入していない場合は、${CLAUDE_SKILL_DIR}/my-second-brain-requirements.md に空のテンプレートがあることを伝え、ワークスペースにコピーしてから記入するよう案内してください。

2. アーキテクチャの参考資料を読み込む — 設計図として ${CLAUDE_SKILL_DIR}/references/architecture-reference.md を読みます。

3. すべてのツールと API を調査する — どのプラットフォームやライブラリにも精通していると決めつけないでください。Gmail や Slack のような一般的な API にも、実装に影響する細かな仕様、レート制限、SDK 固有のパターンがあります。ユーザーの技術スタックに含まれるツールはすべてウェブで調査し、PRD に正確で具体的な指針を盛り込んでください。

   次のコア依存関係は必ず調査してください：

   • Claude Agent SDK — 会話の作成方法、system_prompt プリセット、setting_sources、allowed_tools、ストリーミング応答、認証情報の取り扱い
   • FastEmbed — ONNX モデルの読み込み、バッチ埋め込み API、モデルキャッシュの設定、対応モデル
   • フックシステム — Claude Code のフックタイプ（PreToolUse、PostToolUse など）、コールバックのシグネチャ、settings.json の設定

   ユーザーが選択したすべてのプラットフォーム（Gmail、Slack、Linear、HubSpot など）について、以下を調査してください：

   • 認証方式（OAuth2 フロー、API トークン、ボットトークンなど）
   • 使用する主要な SDK／ライブラリ（例：google-api-python-client、slack_sdk など）
   • ユーザーの主要タスクに必要な具体的な API エンドポイント
   • プラットフォーム固有のセットアップ要件（例：Slack の Socket Mode には App Token と Bot Token が必要です。カスタムドメインで Gmail を利用する場合は、OAuth 同意画面を本番環境用に公開する必要があります）
   • レート制限、ページネーションのパターン、よくある注意点

   目標： PRD の各フェーズに、コーディングエージェントが推測なしで実装できるだけの技術的な具体性を盛り込んでください。調査結果をそのまま大量に記載するのではなく、各フェーズで実行できる実装メモに要約してください。

4. PRD を生成する — 出力先パス（$1、指定がない場合は .agent/plans/second-brain-prd.md）に、段階的な構築計画を次のセクションで作成してください。

PRD の構成

出力する PRD には、以下を含めてください：

ヘッダー：

• プロジェクト名（パーソナライズ形式：「[User's Name] のセカンドブレイン」）
• 生成日
• 概要：主要タスクに基づく 1〜2 文 フェーズ 1：基盤（メモリレイヤー）
• 「Memory vault folder name」で指定された名前を使って、メモリ保管庫のフォルダーを設定します（例：MyVault/Memory/）。「Dynamous」をハードコードしないでください。必ずユーザーが選んだ名前を使います。
• Obsidian を使用している場合は、ビューアーとして紹介します。使用していない場合は、保管庫はどのエディターでも使える Markdown ファイルのフォルダーにすぎないことを説明します。
• SOUL.md、USER.md、MEMORY.md、BOOTSTRAP.md、daily/ の構成を作成します。
• BOOTSTRAP.md は初回起動時のオンボーディングスクリプトです。ユーザーが Claude Code を初めて使うセッションで、対話を通じて USER.md、SOUL.md、HEARTBEAT.md を個人に合わせて設定します（名前、タイムゾーン、役割、コミュニケーションスタイル、インテグレーション、積極性の希望について、一度に 1 つずつ質問します）。オンボーディングが完了すると、自身を削除します。オンボーディングの途中でセッションが終了した場合は、ファイルが保持され、次回に続きから再開します。SessionStart フックは BOOTSTRAP.md を検出し、コンテキストに挿入する必要があります。
• リポジトリのルートに CLAUDE.md を作成します。これは Claude Code のプロジェクト指示ファイルで、すべての会話に読み込まれます。プロジェクトの説明、主要なパス（保管庫、スクリプト、フック、スキル、データディレクトリ）、プロジェクトの規約（タイムゾーン、アドバイザーモード、保管庫にシークレットを保存しない、チェックボックスの構文、YAML フロントマター）、および各フェーズ後に更新する「Completed Phases」セクションを記載して初期化します。また、「Build Commands」セクションも追加します。最初はプレースホルダーを記入し、各フェーズで実際のコマンドが導入されたら入力します。このファイルは、エージェントがプロジェクトとやり取りする方法を確認するためのリファレンスです。
• 「About You」と「Memory Categories」の回答に基づいて各ファイルをカスタマイズします。
• 作成する主要ファイル、推定複雑度：低

フェーズ 2：フック（コンテキストの永続化）

• SessionStart フック（すべての会話にメモリを挿入します。初回オンボーディング用の BOOTSTRAP.md も検出して挿入します）
• PreCompact フック（会話のコンテキストを抽出し、バックグラウンドで memory_flush.py を起動します）
• SessionEnd フック（同じパターンで、コンテキストを抽出してバックグラウンドでフラッシュを実行します）
• memory_flush.py：PreCompact／SessionEnd から起動される、バックグラウンドの Agent SDK スクリプトです。allowed_tools=[]（推論のみで、ツールは使用しません）で Claude を使い、会話から保存する価値のある決定事項、教訓、事実をインテリジェントに判断します。箇条書きの要約を日次ログに書き込みます。重複排除とファイルロック機能を備えています。これは非常に重要です。これがないと、日次ログには、日次の振り返りで実際に MEMORY.md に反映できるインテリジェントな要約ではなく、機械的に抜き出された会話記録が含まれてしまいます。
• フックの再帰防止：Agent SDK のすべてのセッション（heartbeat、reflection、chat、memory flush）で、os.environ["CLAUDE_INVOKED_BY"] = "<name>" を設定する必要があります。SessionEnd フックと PreCompact フックはこの環境変数を確認し、設定されている場合はスキップします。これにより、Agent SDK の終了によって追加のフラッシュが実行され、ログエントリーの重複や無限再帰が発生するのを防ぎます。
• 共有ユーティリティ（shared.py）：同時書き込みを安全に行うためのクロスプラットフォームのファイルロック（Windows では msvcrt、Unix では fcntl を使う file_lock()）、外部 API 呼び出しのリトライ（指数バックオフを使う with_retry()）、およびアトミックな状態書き込みを提供します。複数のプロセス（heartbeat、reflection、chat、flush）が日次ログや状態ファイルに同時に書き込みます。ファイルロックがないと、互いの書き込み内容を破損させます。
• 主要ファイル、推定複雑度：中

フェーズ 3：メモリ検索（ハイブリッド RAG）

• チャンク化と埋め込みのパイプラインを設定します。
• SQLite + sqlite-vec + FTS5（ローカル）または Postgres + pgvector（VPS）
• ハイブリッド検索：0.7 ベクトル + 0.3 キーワード
• 主要ファイル、推定複雑度：中

フェーズ 4：インテグレーション（優先度上位 3 件から）

• 「Integration Priority」のランキングを使用します。
• インテグレーションごとに、認証の設定、API モジュール、レジストリエントリー、query.py のサブコマンドを実装します。
• integration_template.py のパターンを参照します。
• インテグレーションごとの主要ファイル、推定複雑度：中 フェーズ 5：スキル（スターターパック）
• Vault の構造に関するスキル（ファイルの整理方法をエージェントに教えます）
• 「Top Tasks」に基づくカスタムスキルを少なくとも 1 つ
• スキルの構成：SKILL.md + scripts/ + references/
• 主なファイル、推定複雑度：低〜中

フェーズ 6：プロアクティブなシステム（ハートビート + 振り返り）

• ハートビートのフローは、次の順序で段階的に実行する必要があります：（1）Python がインテグレーションからデータを収集 → （2）状態の差分を計算 → （3）事前チェック用ガードレールエージェント（フェーズ 8 を参照。ツールを使わない独立した Claude 呼び出しで、サニタイズ済みの外部データを評価し、メインのハートビートエージェントがデータを見る前に {verdict: "pass"|"fail"|"suspicious"} を返します。fail の場合は実行を中止し、suspicious の場合は警告付きで続行します）→ （4）ツールを使用するメインの Claude Agent SDK 推論呼び出し → （5）通知。この事前チェック用ガードレールのステップは必須です。これはセキュリティスタックにおける唯一のセマンティックインジェクションチェックであり、別フェーズとして後付けするのではなく、ハートビートパイプラインに直接組み込む必要があります。
• 状態の差分計算（ハートビートフローのステージ 2）：build_snapshot(gmail_data, asana_data, slack_data, calendar_data, ...) および diff_snapshot(current, previous) 関数を実装し、各インテグレーションの現在の状態をハッシュ可能なスナップショットとして生成し、前回の実行との差分を計算します。状態は .claude/data/state/heartbeat-state.json に永続化します（shared.py を介したアトミック書き込み）。メインの Claude 推論呼び出しに渡すのは差分のみです。つまり、新着メール、新たに期限超過となったタスク、新たに未読になった Slack メッセージのみを渡します。これが通知疲れへの対策です。状態の差分計算がないと、30 分ごとの実行で同じ未読メールが何度も表示され、ユーザーに延々と通知されます。この仕組みがなければ、ハートビートは本番環境では使い物になりません。生成された PRD で学生がパターンをたどれるよう、これらの正確な関数名を使った明示的な成果物として指定する必要があります。
• 選択したプロアクティブ度に応じてスケジュールを設定します
• 毎日の振り返り：日次ログの重要な項目を MEMORY.md に昇格させます。SOUL.md の書き込み保護を必ず含めます。PreToolUse フックによって、振り返りエージェントが SOUL.md を編集できないようにします。エージェントのアイデンティティやルールの変更を提案したい場合は、代わりに日次ログへ記録します。これにより、ユーザーの承認なしにエージェントが徐々に自らの性格を書き換える「魂のドリフト」を防ぎます。
• 選択したプロアクティブ度を、具体的なハートビートの動作に対応付けます
• 下書き管理（アドバイザー／アシスタント／パートナーのプロアクティブ度では必須）：ハートビートには、下書きのライフサイクル管理システムを完全に実装する必要があります。具体的には、（1）返信が必要なメール、DM、コミュニティの投稿をインテグレーションデータからスキャンする、（2）drafts/sent/ を対象に RAG を使ってユーザーの文体を再現し、返信の下書きを生成する（文体の照合には memory_search.py --path-prefix drafts/sent を使用）、（3）YAML フロントマター（type、source_id、recipient、subject、context、created、status）と「Original Message」および「Draft Reply」セクションを含む Markdown ファイルとして、drafts/active/ に下書きを書き込む、（4）24 時間を超えて未対応の下書きを drafts/expired/ に移動して期限切れにする、（5）ユーザーが実際にプラットフォーム上で返信したことを検知し、本人の実際の返信文を記録してファイルを drafts/sent/ に移動する。下書きファイルを作成するには、ハートビートの Agent SDK セッションに Write/Edit ツールが必要です。読み取り専用ツールでは不十分です。下書きの作成基準（何を下書きし、何をスキップするか）は USER.md で定義する必要があります。
• 習慣の追跡：カスタマイズ可能な柱、自動達成検出ルール、ハートビートによる毎日のリセット、未チェックの柱に対する一日の遅い時間帯のリマインダーを含む HABITS.md
• 主なファイル、推定複雑度：高

フェーズ 7：チャットインターフェース（任意）

• プラットフォームの選択で Chat/Messaging を選んだ場合にのみ含めます
• 会話を保持する Slack/Discord ボット
• 拡張性を考慮したプラットフォームアダプターパターン
• 主なファイル、推定複雑度：高 フェーズ 8：セキュリティ強化
• 認証情報保護フック（block-secrets.py）：すべてのファイルアクセスツール（Read、Bash、Grep、Edit、Write、Glob）を傍受し、.env ファイル、API トークン、OAuth 認証情報、SSH キー、その他の秘密情報へのアクセスをブロックする PreToolUse フックです。環境変数を漏えいさせる Bash コマンドもブロックし、標準出力に秘密情報を流出させるスクリプトの書き込みもブロックします。これは最も重要なセキュリティコンポーネントです。これがなければ、LLM が誤ってすべての API キーを読み取り、漏えいさせる可能性があります。個別の専用フックとして実装する必要があります（汎用コマンドガードと統合しないでください）。
• すべての外部データをサニタイズします（3 層防御：パターン検出 → Markdown エスケープ → XML 信頼境界）。XML によるラップには、システムプロンプト内の TRUST_BOUNDARY_INSTRUCTION を組み合わせ、<external_data> タグ内の内容は指示ではなくデータとして扱うよう Claude に明示する必要があります。この指示を伴わないラップは、防御の半分にすぎません。
• 事前チェックのガードレールエージェント：メインのハートビートエージェントが外部からの入力データを処理する前に、allowed_tools=[] を指定した別の Claude Agent SDK 呼び出しを実行します。サニタイズ済みのコンテキストを渡し、{"verdict": "pass"|"fail"|"suspicious"} を返すようにします。fail の場合 → ハートビートの実行を中止し、ブロックした内容をログに記録します。suspicious の場合 → 日次ログに警告を記録して続行します。pass の場合 → メインの推論呼び出しに進みます。これはセキュリティスタック内で唯一のセマンティックチェックです（他のレイヤーはすべてパターンベースです）。決定論的な正規表現をすり抜けたインジェクションの試みを検出します。Phase 6 のハートビートフローでは、状態の差分確認とメインエージェント呼び出しの間に組み込んでください。独立したユーティリティとして実装しないでください。
• セキュリティ境界に関する回答に基づくコマンドガードレール。実装には、破壊的な操作（rm -rf、dd、mkfs）、認証情報の持ち出しを回避する手法（不明なホストへの curl、シェルにパイプで渡す wget）、パッケージのインストール（pip install、npm install、brew install）、権限昇格（sudo、chmod 777）、許可リストにないドメインへの外向きネットワーク呼び出しを網羅する、30 個以上のパターンを含む名前付きリスト DANGEROUS_BASH_PATTERNS を shared.py に用意する必要があります。チェックではサブシェルの $(...) とバッククォート `...` の構文を再帰的に抽出し、その内容も再チェックする必要があります（単純な文字列照合は $(echo rm\ -rf\ /) で回避できます）。照合前に、一般的なバイナリパスのプレフィックス（/usr/bin/、/bin/）を削除します。これは block-secrets.py（認証情報ファイルを保護するもの）とは別の機能です。DANGEROUS_BASH_PATTERNS は破壊的なコマンドやデータ流出コマンドを防ぎ、両方のフックがすべての PreToolUse Bash 呼び出しで実行されます。
• API キーの分離（Python CLI ラッパーパターン）
• 主要ファイル、推定複雑度：中〜高

フェーズ 9：デプロイ

• インフラストラクチャに関する回答に基づきます
• ローカル：OS のスケジューラー設定（Windows Task Scheduler / cron / launchd）
• VPS の場合：サーバーのセットアップ、Vault の同期、SSH トンネル
• concat-both マージドライバーを使った Vault 同期（「Local + VPS」を選択した場合は必須）：両方のマシンで 2 分間隔のタイマーを使い、git-sync（simonthum/git-sync など）で Git 経由で Vault を同期します。日次ログ（Memory/daily/*.md）は追記専用で、両方のマシン上でハートビート、振り返り、チャット、フラッシュの各プロセスが同時に書き込みます。単純な Git マージでは同期のたびに競合が発生します。解決策として、.gitattributes にカスタムの concat-both マージドライバーを登録し、Memory/daily/*.md に、競合を起こす代わりに両方の側から追加された内容を連結するスクリプトを適用します。ドライバースクリプト（git-merge-concat）は、ancestor/local/remote の各バージョンを受け取り、remote をベースにして、local が追加した行のうち、まだ含まれていないものを末尾に追加します。このドライバーがないと、実際の利用を始めて最初の日のうちに Vault 同期が破綻し、ユーザーはシステムを使わなくなります。スクリプトのパス、.gitattributes のエントリ、各マシンで実行する git config merge.concat-both.driver の登録コマンドを含む、名前付きの成果物として必ず提示してください。
• 選択内容に基づくコスト見積もり 各フェーズには以下を含めます：
• 作成する内容（1～2文）
• 作成する主なファイル（パスを含む）
• 依存関係（先に完了しておく必要があるフェーズ）
• 想定される複雑さ（低／中／高）
• パーソナライズに関するメモ（個別の回答がこのフェーズにどう反映されるか）
• CLAUDE.md の更新リマインダー：各フェーズの最後に、新たに追加したパス、ビルドコマンド、規約を CLAUDE.md に追記してください。これにより、エージェントが参照するプロジェクト情報を最新に保てます。コマンドがあっても CLAUDE.md に記載されていなければ、エージェントはその存在を把握できません。

フッター：

• 推奨されるビルド順（フェーズはおおむね順番に進めますが、一部は並行して進められます）
• 「この PRD は要件に基づいて生成されました。システムの進化に合わせて、見直し、更新してください。」

5. 出力を確認する — PRD の保存先（出力パス）をユーザーに伝え、フェーズ 1 から始めるよう提案します。

パーソナライズのルール

• ファイルパスでは、必ずユーザーが指定した保管庫フォルダー名を使用してください（「Dynamous」ではなく、「Memory vault folder name」に記載された名前を使用します）。たとえば、「SecondBrain」と記載されている場合、すべてのパスを SecondBrain/Memory/、SecondBrain/Memory/daily/ などにします。
• Obsidian を使用していない場合は、PRD で Obsidian に言及しないでください。保管庫を「メモリ保管庫」または「Markdown フォルダー」と呼びます。Obsidian を使用している場合は、閲覧・編集用ツールとして記載します。
• すべての箇所で、ユーザーが選んだプラットフォーム名を使用してください（一般的な「メール」ではなく、ユーザーが選んだものが「Gmail」であれば「Gmail」を使用します）。
• 積極性のレベルを具体的な動作に対応づけます。
  • Observer → ハートビート通知のみ。下書きの作成や習慣の追跡は行いません。
  • Advisor → ハートビート通知と、確認用のメール／メッセージの下書き作成を行います。提案付きで習慣を追跡しますが、自動チェックは行いません。
  • Assistant → ハートビート通知、下書き作成、ファイルの自動整理、自動記録を行います。客観的な柱について、習慣を自動検出します。
  • Partner → 上記すべてに加えて、リスクの低いメッセージの送信、定型タスクの自動完了、習慣の完全な自動検出を行います。
• セキュリティ境界を、フェーズ 8 のガードレールルールに直接反映させます。
• メモリのカテゴリを使って、フェーズ 1 で保管庫のフォルダー構成を作成します。
• 連携の優先順位を、フェーズ 4 の順序に反映させます。