project-brain

Project Brain

gh を使用して、プロジェクト専用の Git ベースのナレッジベースを読み取ります。brain は証拠として扱い、リポジトリ内のパスと調査したコミットを引用し、文書化された事実と推論を区別して、リポジトリで質問に答えられない場合はその旨を伝えます。

必須の事前確認

Git ワークツリーで計画、回答、レビュー、診断、文書作成、またはファイル変更を行う前に、次の手順を実行します。

1. git rev-parse --show-toplevel で現在のワークツリーのルートを確認します。
2. そのルートに .project-brain.json があるか確認します。
3. ファイルが存在する場合は、このワークフローを実行して、実質的な推論や作業を行う前に brain を参照します。このマーカーは無条件の指示です。ユーザーが Project Brain に言及するまで待ったり、参照が不要だと判断したりしないでください。
4. タスクの根拠を得るのに十分な関連資料を読みます。最低限、agent-guide.md が存在する場合は読み、その後、依頼に関連する情報源を特定して読みます。
5. brain にアクセスできない場合は、具体的な障害を報告します。根拠のない推測で作業を続けてはいけません。

Project Brain はマーカーで指定される別のリポジトリです。アクティブなプロジェクト内にあると想定したり、子ディレクトリとして追加したり、アクティブなワークツリーにクローンしたりしないでください。

brain の特定

1. アクティブなワークツリーのルートにある .project-brain.json を読み取ります。次の形式を受け入れます。

   {
     "repository": "owner/project-brain-repo",
     "defaultBranch": "main"
   }
   

2. repository が必須です。明示的にワークフローを実行したのにマーカーがない場合、またはフィールドが欠落している場合は、推測せず Project Brain のリポジトリを尋ねます。マーカーが存在するものの無効な場合は、設定エラーを報告して停止します。

3. gh auth status を実行します。認証されていない場合は、ユーザーに gh auth login の実行を依頼して停止します。

4. defaultBranch が指定されている場合はそれを使用します。指定されていない場合は、gh repo view OWNER/REPO --json defaultBranchRef --jq '.defaultBranchRef.name' で特定します。

5. gh api repos/OWNER/REPO/commits/BRANCH --jq '.sha' で現在のコミットを特定し、回答に短縮 SHA を含めます。

トークンや認証情報を表示してはいけません。

コンテキストの読み取り

特定の既知のパスを取得する場合は、クローンせずに次のコマンドを使用します。

gh api --method GET "repos/OWNER/REPO/contents/PATH" -f "ref=BRANCH" -H "Accept: application/vnd.github.raw+json"

情報の探索や複数ファイルに関する質問では、設定されたブランチをアクティブなプロジェクトのワークツリー外に新しく作成した一時ディレクトリへクローンします。

gh repo clone OWNER/REPO TEMP_DIR -- --depth 1 --branch BRANCH

クローンをローカルで検索します。次の順序で、ファイルが存在する場合は読み取ります。

1. agent-guide.md
2. graphify-out/wiki/index.md
3. インデックスからリンクされている関連 Wiki ページ
4. Wiki がない場合、または情報が不十分な場合は graphify-out/GRAPH_REPORT.md
5. 参照されているソースファイル。特に context/ 内の人間が作成した資料
6. 補足情報として、raw/code/{owner}/{repo}/… 内のソースコードのミラーを含む、機械取り込みされた raw/ 内の記録

意見が食い違う場合は、生成された要約よりも、人間が作成した決定事項や要件を優先します。矛盾や鮮度に関する懸念は明示します。graphify-out/ の要約を、元のソースより強い証拠として扱ってはいけません。

raw/code/ のミラーは、最後の同期時点でのソースリポジトリのデフォルトブランチの HEAD をスナップショットしたものです。実際のソースリポジトリ内で作業している場合は、コードの正確性についてはそのワーキングツリーを優先し、リポジトリ間の情報やアーキテクチャのコンテキストには raw/code/ とコード関連の Wiki 記事を使用します。

回答と作業

• 重要な主張にはすべて、context/decisions/auth.md のように brain を基準としたパスを付けて引用します。
• コンテキストに基づく回答の末尾には、Project Brain: OWNER/REPO@SHORT_SHA を記載します。
• 文書化された事実、妥当な推論、不足している情報を区別します。
• デフォルトでは読み取り専用でアクセスします。
• 現在のコードが brain と異なるという理由だけで、brain を編集してはいけません。
• ユーザーが明示的にナレッジの更新を依頼した場合は、デフォルトブランチにプッシュしないでください。クローンを作成し、ブランチを作成して、関連する人間管理のファイルのみを編集し、レビュー用に gh pr create でプルリクエストを開きます。機械管理の raw/ コンテンツは編集しないでください。