Claude Code × GitHub運用：AIエージェントと協働する開発ワークフロー

Claude Codeは強力だが、そのまま使うと危険な理由

Claude Codeは非常に強力なAIエージェントです。ただし、ルールを決めずに使うと、プロジェクトは簡単にカオスになります。

• ファイル構成がいつの間にか変わっている
• 既存の設計を無視して実装が進む
• セッションを切り替えると前提条件を忘れる

これはAIの性能の問題ではありません。人間側が「どう使うか」を設計していないことが原因です。

重要なのは、AIエージェントにどうやってプロジェクトのルールを伝えるか、という点です。

AI前提で設計した開発ワークフローの全体像

まずは全体の流れから整理します。

ワークフローの基本構成

すべてを1セッションで完結させようとしない、というのが最大のポイントです。

/plan：機能を決め切るフェーズ

機能計画は docs/plans/ にMarkdownで作成します。別セッション・別エージェントでも実装できるレベルまで具体化し、実装時に迷わない状態を作ります。

/design：UIが必要な場合のみ

UI設計が必要な場合のみ実行します。Google Stitch MCP経由でデザインを生成し、その結果をplanファイルに反映します。

※Google Stitch2026/02/27現在は無料

/tdd：実装フェーズ

GitHub Issueを起点に、Issue作成 → ブランチ作成 → テスト → 実装 → PR、という流れで進めます。Claude Codeは必ずテスト駆動で使います。

セッション引き継ぎの考え方

Claude Codeはセッションを跨ぐと普通にコンテキストを忘れます。そのため、ドキュメントを必ず中継点として挟みます。

AIは忘れる前提で作る進捗管理の設計

進捗管理は「AIが忘れる」ことを前提に設計します。

docs/progress.md：進捗のハブ

プロジェクト全体の進捗を1ファイルで管理します。新しいセッションを開始したら、必ず最初に読みます。

docs/plans/feature-xxx.md：機能単位の設計書

機能ごとに1ファイル作成し、このファイルだけ読めばコードを見ずに実装できる状態を目指します。仕様、制約、影響範囲、テスト方針まで記載します。

/CODEMAPS 配下の構造マップ

ディレクトリ構成と責務を文章で説明します。AIが「どこを触るべきか」を判断しやすくするための資料です。

完了したplanの整理

完了したplanは docs/plans/finished/ に移動し、progress.mdは1行で簡潔にまとめます。情報を溜め込みすぎないことも重要です。

AIでも事故らないGit・GitHubブランチ戦略

ブランチ構成はシンプルかつ事故りにくい形にします。

ブランチ構成

• main：本番
• develop：統合
• feat/issue-{番号}-{機能名}：作業用

Closes #issue の注意点

GitHubの Closes #issue番号 は、デフォルトブランチにマージされたときのみ有効です。そのため、feature → develop、develop → main の両方のPRに記載します。

複数AIエージェントを安全に並列実行する方法

Claude Codeを本格運用すると、複数セッションの並列実行が前提になります。

競合防止ルール

• progress.mdにエージェント名、Issue、変更予定ファイルを記載
• ファイルの重複があれば作業を停止
• 必ずユーザーに報告

これだけで、同じファイルを知らない間に触る事故はかなり防げます。

曖昧さを減らすための言語ルールと制約

解釈のブレを減らすため、ルールは極力シンプルにします。

言語はすべて日本語

thinking、コメント、コミットメッセージ、ドキュメントまで、すべて日本語で統一します。

スコープの限定

プロジェクトフォルダ外の変更は禁止し、触ってよい範囲を明確にします。AIの善意の暴走を防ぐためです。

CLAUDE.mdをオンボーディング資料として扱う

CLAUDE.mdは、AIエージェントに渡すオンボーディング資料です。

人間の新メンバーに渡すドキュメントと同じ発想で、ルールや前提条件、暗黙知を言語化します。

これを整備することで、Claude Codeは単なるツールではなく、一緒に開発できるメンバーとして機能します。

サンプルリポジトリの案内

Anthropicハッカソン優勝者による「Everything Claude Code」設定集

https://github.com/affaan-m/everything-claude-code

この記事で紹介した構成やルールを含むサンプルリポジトリを公開しています。

https://github.com/kanekenl/claude-code-template/

CLAUDE.mdやdocs構成の参考になれば幸いです。