knowledge-workspace

ナレッジワークスペース（Secondbrain）

一元管理されたナレッジリポジトリは marcioaltoe/secondbrain です。プロジェクトごとのミラー、編集メモ、共有標準、そして LLM が管理するナレッジ wiki（第二の脳）が含まれます。コードリポジトリは通常のファイルとしてドキュメントを管理し、Secondbrain がそれを自動的に集約します。

契約

ドキュメント（CONTEXT.md、docs/ — 仕様、ADR、タスクファイル、レビュー成果物）は、コードリポジトリ内の通常のファイルです。コミットフローは 1 つだけです。

• ドキュメントとコードを一緒に編集し、同じブランチと PR で一緒にコミットします。task_NN.md のステータス変更と ## Result セクションは通常のリポジトリへのコミットです。2 つ目のリポジトリは不要で、ドキュメントを別途プッシュすることもありません。
• main へのプッシュ後（マージの種類や直接プッシュを問わず。フィーチャーブランチは対象外）、GitHub Actions が .secondbrain-export に記載されたパスを secondbrain/projects/<project>/mirror/ にミラーします。これは自動で行われます。手動で同期しないでください。
• ミラーは読み取り専用です。secondbrain の projects/<project>/mirror/ は編集しないでください。次回の同期で上書きされます。編集する価値のあるコンテンツは、コードリポジトリ（プロジェクトドキュメント）または secondbrain の編集エリアに配置してください。
• 編集エリアは secondbrain で直接編集し、その main にプッシュします。projects/<project>/notes/（リポジトリに属さないプロジェクトメモ — 会議メモ、時代ごとのアーカイブ、クライアントからのフィードバック）と shared/（プロジェクト横断の標準）が該当します。registry/projects.json では、どのリポジトリがどのプロジェクトに公開できるかを許可リストで管理します。
• 取り込みは一方向です。secondbrain の内容がコードリポジトリに書き戻されることはありません。リポジトリから shared/ の内容を参照する場合は、リンクしてください。コピーしてはいけません。

エクスポートの契約

コードリポジトリ内のファイル	目的
.secondbrain-project	プロジェクト名のみ。projects/ 配下のキーであり、secondbrain のレジストリ内のキーでもあります
.secondbrain-export	リポジトリが公開する内容。1 行につき 1 パスを記載し、ディレクトリは再帰的に対象となります。!pattern の行は除外対象（rsync/gitignore と同様）で、# はコメントです
.github/workflows/secondbrain-sync.yml	単独の同期ワークフロー。secondbrain の templates/repo/secondbrain-sync.yml からコピーします。プライベートな個人リポジトリでは再利用可能なワークフローを公開できないため、すべてのリポジトリと所有者で同じファイルを使用します

コミット済みのファイルのみエクスポートできます（同期ではマージ済みコミットのチェックアウトを読み込みます）。また、シンボリックリンクは拒否されます。新しい成果物（OpenAPI ファイルなど）をエクスポート対象に追加する場合は、同じ PR で .secondbrain-export を更新してください。

新しいプロジェクトの追加

templates/repo/ と secondbrain の README に従ってください。registry/projects.json に登録し（active: true）、projects/<name>/notes/ を作成し、上記の 3 つのファイルをリポジトリに追加して、SECONDBRAIN_APP_CLIENT_ID 変数と SECONDBRAIN_APP_PRIVATE_KEY シークレットへのアクセス権を付与します（組織リポジトリには組織レベル、個人アカウントのリポジトリにはリポジトリレベルで付与）。その後、main にマージします。

第2の脳（wiki）

記録に加えて、secondbrain は Karpathy 方式の LLM wiki をホストしています。正式な契約は secondbrain 独自の AGENTS.md（~/dev/secondbrain のセッションで自動読み込みされます）です。このセクションでは、ほかのセッションで必要となる内容を扱います。secondbrain の brain/skills/ にある secondbrain スキルをインストールすると、参照、取り込み、メッセージ送信の詳細な運用ガイドとして利用できます。このスキルがドキュメントとミラーの契約を管理します。

• 参照（実装や計画のための調査。どのリポジトリからでも可）：~/dev/secondbrain/wiki/index.md から始めるか、qmd を使って wiki、取り込み済みソース、共有標準、すべてのプロジェクトミラーを含む全体を検索します：

  qmd query "pergunta em linguagem natural"          # hybrid + rerank, best
  qmd search "keywords" -c wiki                      # scoped: wiki|raw|shared|projects|areas|fiscal
  qmd query "..." --all --files --min-score 0.3      # agent-friendly output
  qmd query "..." -c leis                            # statutory text; opt-in, never in unscoped searches
  

• ビジネス知識の提供：ai-memory-messaging を読み込み、memory_message_send を使って調査内容を default/marcioaltoe-secondbrain に送信します。ソースの出所、日付、調査結果、制限事項を記載してください。ファイルシステムの受信箱は Marcio が 2026-10-25 に廃止しました。外部セッションから Secondbrain に書き込まないでください。調査内容はそこでアーカイブされ、Ingest を通じてまとめられます。送信前に qmd で重複を確認すると便利です。

• プロジェクト間の連携と継続性：既存プロジェクト間の依頼と回答には memory_message_* を使い、依頼に応じて同一プロジェクト内の継続性を保つには ai-memory-handoff を使います。静的クライアントでは送信者と受信者のスコープを指定します。メールボックスがない場合は Marcio に伝えてください。ファイルシステムによる代替手段を作成しないでください。古くなったローカルルールや自動化を更新し、Roundfix Baseline に古いワークフローがまだ記載されている場合は確認してください。

• 管理領域：wiki/、raw/、編集メモ、共有資料、エリアは Secondbrain のセッションが管理します。ミラーは引き続き読み取り専用です。外部セッションから書き込める例外はありません。

アンチパターン

• CONTEXT.md/docs のシンボリックリンクを作成する、.knowledge/ のチェックアウトをマウントする、またはブートストラップスクリプトを実行する。このフローは全面的に廃止されています。
• secondbrain の projects/<project>/mirror/ 以下を編集またはコミットする。
• 「同期を早める」ために、変更のきっかけとなった PR からドキュメントの変更を切り離す。ミラーはマージ時に更新されます。作業中の状態がブランチにのみ存在するのは正しい状態です。
• shared/ の内容をコードリポジトリにコピーする。代わりにリンクしてください。コピーは次第に実態と乖離します。
• .secondbrain-project の参照先を別のプロジェクトのフォルダーにする。