.clinerules と instructions.md の作成ガイド

AIエージェント（Antigravity等）にGitHub連携を自律的かつ安全に行わせるための、コンテキスト提供ファイル（「エージェントのOS」）の書き方ガイド。

目的

AIがリポジトリのルールを理解し、勝手なIssue操作や認証エラーを防ぎ、自律的にタスクを遂行できるようにする。

1. .clinerules の役割と書き方

役割: そのリポジトリ専用の「AIへの強制ルール」。作業開始時に必ず読み込まれる。

推奨記述例

# GitHub連携ルール
- GitHubの操作には必ず `gh` コマンドを使用すること。
- Issueを読み取る際は `gh issue view [number] --json title,body,comments` を使用して、コンテキストを正確に把握すること。
- 実装計画（Implementation Plan）を生成した後は、必ず対象のGitHub Issueの本文を更新、またはコメントとして投稿して永続化すること。
- プロジェクトボード（Projects v2）のステータス変更が必要な場合は、`gh project item-edit` コマンドを使用すること。

# コミットメッセージのルール
- コミット時は必ず関連するIssue番号を含めること（例: "feat: add user auth (fixes #12)"）。

2. instructions.md の役割と書き方

役割: プロジェクトの「設計思想や技術スタック」を伝えるドキュメント。

GitHub連携向け記述例

# プロジェクト管理フロー
- **Single Source of Truth:** GitHub Issues が常に正解である。
- **タスク管理:** 
    - 全ての機能開発はIssueから始まる。
    - 実装中にタスクが追加された場合、ローカルのメモだけでなくGitHub Issueのチェックリストを更新する。
- **GitHub Projects:** 
    - プロジェクトIDは "12" である。
    - 作業開始時にStatusを "In Progress"、完了時に "Done" へ移行させること。

3. コンテキスト提供の3つのコツ

① gh コマンドの結果を食わせる

作業開始時にAIにリポジトリの状態を把握させる。

gh repo view --json name,description,urlgh issue list --limit 5

② ディレクトリ構造の要約 (architecture.md)

AIがファイルを探す手間を省くため、主要ディレクトリの役割を記述しておく。

③ ステータスマッピングの定義

GitHub Projectsのカラム名（Status）の意味を教える。

• "Backlog" = 実現したいこと、将来のタスク（AIにまだ触らせない）,
• "Ready" = 仕様が確定し、AIに渡せる状態のタスク
• "In Progress" = 現在実行中のタスク
• "Done" = 完了したタスク

4. ワークフロー指示のテンプレート

最初の指示プロンプト例：

「.clinerules を確認して。その後、GitHub Issue #12を読み取って、現在のリポジトリ構造と照らし合わせ、不足している実装ファイルを特定して。計画ができたら、Issue #12の本文をその計画で更新して。」

まとめ

• 迷いの解消: AIが正しいコマンドと情報の場所を理解する。
• 一貫性: 誰が作業しても同じルールが適用される。
• 自動化: 自律的な更新サイクルが生まれる。