このリポジトリは、
AIを「ツール」ではなく「役割を持つチーム」として扱う開発スタイルの
サンプルプロジェクトです。

Claude Code / Kiro / Codex を
明確な役割分担のもとで協働させることを目的としています。

このリポジトリは、以下の記事で解説している内容の
実践用サンプルプロジェクトです。

👉 Kiro × Claude Code × Codex - AIを「チーム」として扱う開発スタイルの実践

記事では、Kiro、Claude Code、Codex CLIを同時に活用する開発スタイルについて、

• なぜこの構成に至ったのか
• どんな失敗があったのか
• どのように役割分担を設計したのか
• 実際の運用フローと使い分け

を詳しく解説しています。

このリポジトリは、記事で紹介した手法を
すぐに試せるサンプルプロジェクトとして提供しています。

• AIを人間チームと同じように 役割分担して使う
• 実装・仕様・デバッグを分離する
• 判断の責任を AI に押し付けない
• 開発の「説明責任」を保つ

完成したアプリケーションよりも、
運用・判断・ログの残し方を重視しています。

このプロジェクトでは、以下の役割分担を採用しています。

• Human

  • 判断・オーケストレーション
  • 最終責任

• Claude Code

  • 実装担当
  • 新規機能・リファクタリング

• Kiro

  • 仕様管理
  • 設計レビュー・受け入れ判断

• Codex

  • デバッグ担当
  • テスト失敗時の原因切り分け
  • 安全な修正判断

.
├── README.md
├── .kiro/
│   ├── specs/
│   │   └── example-calculator/
│   │       ├── requirements.md
│   │       ├── design.md
│   │       └── tasks.md
│   └── steering/
│       └── ai-team-roles.md
├── src/
│   └── example_app.py
├── tests/
│   └── test_example.py
├── reports/
│   └── (検証ログ・判断記録)
├── CLAUDE.md
└── CODEX.md

.kiro/steering/ai-roles.md は
プロジェクト全体の憲法です。

• 各AIの責任範囲
• 判断が必要な場合のルール
• 人間に戻す条件

が定義されています。

すべての AI は、まずこのファイルを前提として動作します。

このプロジェクトでは、
最初から CLAUDE.md / CODEX.md が必要だったわけではありません。

• ai-roles.md のみで運用
• 人間が毎回プロンプトで補足
• 小規模な実験・修正が中心

この段階では、
個別の AI 指示ファイルは不要でした。

• 実装とデバッグの切り替えが頻繁になる
• 同じ注意事項を何度も伝える必要が出てくる
• 判断と作業の境界が曖昧になる

Claude Code には 実装に専念してほしいため、

• 責任範囲
• 参照すべきドキュメント
• やってはいけないこと

を明文化しました。

Codex は デバッグ・検証フェーズで使用しています。

• 修正が広がりすぎない
• 「改善」と「仕様変更」を分離する
• 判断が必要な場面で人に戻す

ために、CODEX.md を作成しました。

• ai-roles.md：プロジェクト全体のルール
• CLAUDE.md：実装フェーズを安定させる
• CODEX.md：デバッグフェーズを安全にする

これらは
運用上の課題に応じて追加したものです。

git clone https://github.com/miyakawa2449/ai-team-dev-sample.git
cd ai-team-dev-sample

実際の開発フローを理解するために、以下のドキュメントを参照してください：

• 初期セットアップ判断ログ
  このプロジェクトの構造と方針を決定した際の判断記録です。なぜこの構成にしたのかが記載されています。

• 日常的な開発フローガイド
  Kiro、Claude Code、Codexの使い分けと、新機能開発・バグ修正・リファクタリングの具体的な手順を解説しています。実践例や判断チャートも含まれています。

• docs/requirements.md
• docs/design.md
• docs/task.md

を先に整えます。

ここでは、

• 何を作るのか
• 何を作らないのか
• 正しい状態とは何か

を 仕様として明文化 します。

• CLAUDE.md を読み込ませる
• docs/ 配下の仕様書を参照させる
• src/ 配下に実装させる

Claude Code は 実装担当 であり、
仕様の判断や拡張は行いません。

• テスト失敗時に Codex を呼び出す
• エラーメッセージ・ログを渡す
• 事実整理と最小限の修正を依頼する

このフェーズでは、

• 実装を広げない
• 「改善」と「修正」を混同しない

ことを重視します。

• 修正理由を確認する
• 判断が必要な場合は仕様に立ち戻る
• reports/ に判断ログを残す
• 仕様通過を確認する

人間は判断と責任を引き受ける役割です。

reports/ には、

• テストログ
• Codex の整理結果
• 修正理由
• 再現手順

を Markdown で残します。

「動いた」ではなく
「なぜその修正をしたのか」 を残すことを重視しています。

• SE / PM / アーキテクト寄りの立場
• AIに実装を任せたいが、判断は手放したくない人
• 開発の説明責任を重視する人

このリポジトリは、

• 高度なアプリケーション
• ベストプラクティス集

ではありません。

AIチーム開発の雛形として、
必要な部分だけを取り入れてください。

AIは万能ではありません。
しかし、役割を与えれば信頼できるチームメンバーになります。

この雛形が、
あなた自身や他の方の開発の助けになれば幸いです。

MIT License - 自由に使用・改変・配布できます

詳細は LICENSE をご覧ください。

Tsuyoshi Miyakawa

• GitHub: @miyakawa2449
• Website: https://miyakawa.codes/
• Repository: https://github.com/miyakawa2449/ai-team-dev-sample