卒業制作プロジェクトで AI エージェントを積極活用した開発をするためにやっていること
4 月から専門学校の卒業制作で、チーム開発であるシステムを作ることになりました。
まだ本格的な実装には入っておらず、現在は UML 図や ADR を使いながら設計を進めている段階です。その中で強く感じているのは、AI エージェントにいきなりコードを書かせるよりも、先に「AI エージェントがプロジェクトを理解しやすいリポジトリ」を作ることが重要だということです。
この記事では、卒業制作の序盤で実践していて良いと感じている、AI エージェント開発を前提にしたリポジトリづくりの工夫を紹介します。
チームでは Codex を使うことにした
チームで使う AI エージェントサービスとしては、Codex を採用しました。
理由は大きく 3 つです。
- 動作が安定していると感じたこと
- Codex で利用できる GPT-5.5 の性能に期待していること
- Plus / Pro プランでの利用上限面を考えると、チーム開発で使いやすいと感じたこと
2026 年 5 月時点の OpenAI 公式ドキュメントでは、Codex は ChatGPT Free / Go / Plus / Pro / Business / Edu / Enterprise に含まれると説明されています。また、Plus では Codex の Web、CLI、IDE 拡張、iOS 利用などが含まれ、Pro は Plus より高い利用上限を選べるプランとして説明されています。
現在は私が Pro プラン、他のメンバーが Plus プランを使っています。
ただし、利用上限や対象モデルは変わりやすいので、ここは固定の前提にしないほうがよいと思っています。チーム開発で使う場合は、「今のプランで何回使えるか」だけでなく、「誰が重いタスクを投げるか」「軽い確認はどのモデルで行うか」も運用ルールとして考えたほうがよさそうです。
現在の使い分け
まだ設計段階なので、Codex に大量の実装コードを書かせているわけではありません。
現在の主な使い分けは次のような感じです。
| 用途 | 使っているもの | やっていること |
|---|---|---|
| システム構成の相談 | ChatGPT Web Pro | 全体構成、技術スタック、設計方針の相談 |
| プロトタイプ作成 | Codex | 小さな検証用コードや構成案の作成 |
| 設計資料の整理 | Codex | UML、ユースケース、ADR、README などを読みやすく整理 |
| リポジトリ整備 | Codex | AI エージェントが前提情報を読みやすい構成にする |
Codex では主に gpt-5.5 の reasoning effort を high にして使っています。
OpenAI の reasoning モデルの説明では、high は複雑なデバッグ、深い計画、高価値なタスク、エージェント的なコーディングなどに向いているとされています。一方で、gpt-5.5 のデフォルトは medium で、品質・信頼性・性能のバランスが良い開始点とも説明されています。
そのため、私たちの運用としては「設計の整合性確認や複雑なプロトタイプ作成は high、軽い文章整形や単純な確認は medium も候補」という考え方が良さそうです。最初からすべて high に固定するより、タスクの重さに応じて切り替えられるようにしておくと、利用上限や待ち時間の面でも扱いやすくなります。
AI エージェントに理解しやすいリポジトリとは
AI エージェントを使うとき、プロンプトだけを頑張るよりも、リポジトリそのものを「読みやすいプロンプト」にしておくほうが安定すると感じています。
具体的には、次の 3 つを意識しています。
-
AGENTS.mdでプロジェクト固有のルールを伝える - UML 図を画像だけでなくテキストでも管理する
- ADR で意思決定の理由を残す
順番に紹介します。
1. AGENTS.md を置く
Codex では、プロジェクトの指示ファイルとして AGENTS.md を使えます。
注意点として、ファイル名は AGENT.md ではなく、公式ドキュメント上は複数形の AGENTS.md です。
AGENTS.md には、AI エージェントに守ってほしいルールを書きます。たとえば、以下のような内容です。
# AGENTS.md
## Repository rules
- 回答やコメントは日本語で書く。
- 仕様が不明な場合は、推測で実装せず確認する。
- 設計判断を変更する場合は、関連する ADR を確認する。
- `docs/master/` は、ユーザーから明示的に指示されたときだけ参照する。
- ユースケースは `docs/use-cases/UCxxxx.md` を優先して参照する。
ルートの AGENTS.md を巨大にしない
最初は、リポジトリルートの AGENTS.md にすべてのルールを書きたくなります。
しかし、これはあまり良くないと感じています。Codex は AGENTS.md を作業前に読むため、ルートの AGENTS.md が巨大になると、毎回コンテキストを無駄に消費してしまうからです。
公式ドキュメントでは、Codex はグローバルスコープとプロジェクトスコープの AGENTS.md / AGENTS.override.md を読み、プロジェクトルートから現在の作業ディレクトリまでの指示を結合すると説明されています。また、空ファイルは無視され、結合サイズはデフォルトで 32 KiB の上限があります。
そのため、ルートには全体共通のルールだけを書き、機能やディレクトリ固有のルールは近い場所に置くのがよさそうです。
.
├── AGENTS.md # リポジトリ全体のルール
├── docs/
│ ├── adr/
│ │ └── AGENTS.md # ADR の書き方ルール
│ └── use-cases/
│ └── AGENTS.md # ユースケース文書の書き方ルール
└── src/
└── AGENTS.md # 実装時のルール
こうすると、AI エージェントに毎回すべてのルールを読ませるのではなく、「そのディレクトリで必要なルール」を近くに置けます。
2. UML 図は PlantUML や Mermaid で管理する
設計段階では UML 図を多く使っています。
最近の AI は画像も読めますが、少なくとも私たちの試行では、画像の UML 図をそのまま読ませると、ユースケース名は読めても関連線や include / extend の解釈が怪しいことがありました。
そこで、UML 図は画像だけではなく、PlantUML や Mermaid のようなテキストベースの記法で管理するようにしています。
PlantUML は、アクター、ユースケース、関連線などをテキストで書いて図を生成できます。Mermaid も、Markdown に近いテキスト定義から図や可視化を作れるツールです。
テキストで管理するメリットは大きいです。
- Git で差分を見やすい
- AI エージェントが構造を読み取りやすい
- 図の修正を自然言語で依頼しやすい
- 画像の読み間違いを減らせる
たとえば、ユースケース図なら次のように書けます。
画像だけで管理していると、AI に「この関連線は何を表しているのか」を毎回説明する必要があります。テキストで管理しておけば、AI は図の構造そのものを読めます。
厳密な UML を書きたい場合は PlantUML、Markdown 上で軽く図を共有したい場合は Mermaid、という使い分けも良さそうです。
3. ADR で意思決定を残す
ADR は Architecture Decision Record の略で、設計上の意思決定とその背景を残すための軽量なドキュメントです。
最初から ADR を導入していたわけではありません。
Codex にリポジトリを読ませているときに、「チームで話し合って決めたこと」を AI が知らないことに気づきました。これは当然で、AI は会議に参加していません。さらに、自分たち人間側もメモ程度にしか残していなかったので、あとから「なぜこの構成にしたんだっけ？」となる可能性がありました。
そこで、AI エージェントにも人間にも読める意思決定の記録が必要だと考え、ADR を導入しました。
参考にした記事は次の 3 つです。
- 意思決定を記録する Architecture Decision Record (ADR) の話 - NIFTY engineering
- ADR を1年間書いてみた感想 - 一休.com Developers Blog
- ADR（Architecture Decision Record）、始めました。 - Zenn
それぞれの記事から、特に次の点が参考になりました。
NIFTY の記事では、Design Docs には現在の設計や重要なポイントを書き、ADR には「なぜその選択肢を選んだのか」「なぜ他の選択肢を選ばなかったのか」を残す、という考え方が参考になりました。また、1 つの意思決定につき 1 つの ADR を作ること、変更時は古い ADR を直接書き換えず新しい ADR で置き換えることも参考になります。
一休.com の記事では、ADR は「Why」を支えるスナップショットであり、Design Docs は「今どうなっているか」という What を表すもの、という整理がわかりやすかったです。また、タイトルを「〜について」のような名詞止めにせず、「〜は〜とする」のように文にすると論点が明確になる、というコツも実践しやすいです。
Zenn の記事では、ADR を設計フェーズの属人化や議論不足を防ぐために使う流れ、レビュー運用、ステータス管理、MADR 形式などが参考になりました。ADR を単なるメモではなく、チーム内の合意形成プロセスとして扱うのが大事だと感じました。
使っている ADR テンプレート
現在は、だいたい次のようなテンプレートで書いています。
# ADR-xxx: タイトル
<!-- この ADR の現在の状態を書いてください。提案中は Proposed、採用済みは Accepted、非推奨は Deprecated、置き換え済みは Superseded を使います -->
Status: Accepted
<!-- この ADR を提案または判断した日付を書いてください -->
Date: 2026-05-26
<!-- この ADR の優先度を書いてください。後戻りしにくい判断は A、主要機能の判断は B、局所的な機能判断は C を目安にします -->
Priority: B
## Context
<!-- アーキテクチャ上の判断をするに至った背景や経緯を書いてください -->
## Decision
<!-- 採用するアーキテクチャ上の判断を、実装者が迷わない具体さで書いてください -->
## Reason
<!-- なぜその判断を選んだのか、利用体験・セキュリティ・実装コスト・運用・拡張性などの観点で書いてください -->
## Options Considered
<!-- 検討した代替案と、それぞれを採用しなかった理由を書いてください -->
## Consequences
<!-- この判断によって発生する良い影響・悪い影響・制約・追加作業を書いてください -->
## Follow-up
<!-- この ADR だけでは決めきれない未決事項や、後続の設計・実装で確認すべきことを書いてください -->
## References
<!-- 判断の根拠にした資料、関連ユースケース、関連 ADR、外部資料へのリンクを書いてください -->
- 関連ユースケース:
- 関連 ADR:
ポイントは、コメントを入れていることです。
Markdown 表示ではコメントは見えませんが、編集時には「この項目に何を書けばいいか」がわかります。人間にも AI にも優しいテンプレートになります。
ADR は AI に対話ベースで作ってもらう
正直、ADR を毎回きれいに書くのは時間がかかります。
ただ、手間だからといって意思決定を残さないより、少し雑でも残したほうが後から助かると思っています。
そこで、docs/adr/AGENTS.md を用意して、Codex に対話ベースで ADR の下書きを作ってもらうようにしています。
# AGENTS.md
## 基本方針
- `docs/adr/` 配下では ADR（Architecture Decision Record）を管理する。
- ADR は現状説明ではなく、ある時点での設計判断、代替案、トレードオフ、結果を残す文書として扱う。
- 1 ファイルにつき 1 つの設計判断を扱う。
- 関連するユースケースは、分割済みの `docs/use-cases/UCxxxx.md` を参照する。
- `docs/master/` は、ユーザーから明示的に要求されたときのみ参照する。
## ADR の構成
各 ADR は次の構成にする。
- `Status`: `Proposed`, `Accepted`, `Deprecated`, `Superseded` のいずれか
- `Date`: 判断または提案日
- `Priority`: ADR 候補の優先度
- `Context`: 判断が必要になった背景
- `Decision`: 採用する方針
- `Reason`: 判断理由
- `Options Considered`: 検討した代替案
- `Consequences`: 採用後に起きる良い影響・悪い影響・制約
- `Follow-up`: 未決事項や後続設計
- `References`: 関連ユースケースや関連 ADR などの参照
## 更新ルール
- 仕様や実装が変わった場合も、過去 ADR を消さず、新しい ADR で `Superseded` として置き換える。
- 承認前の ADR は `Proposed` とし、チーム合意後に `Accepted` へ変更する。
- 実装・ER 図・画面定義が追加されたら、関連する ADR へのリンクを設計資料側から張る。
このように書いておくと、Codex に「この会話内容から ADR を作って」と依頼したとき、チームの書式に沿った下書きを作ってくれます。
ただし、ADR の最終判断は人間が行います。AI は文章化の補助として使い、Decision や Reason が本当にチームの合意と一致しているかは必ず確認します。
4. Skills で作業手順を再利用する
もう 1 つ導入しているのが Skills です。
Codex の Skills は、特定のタスクに必要な手順や知識をまとめておき、必要になったときに読み込ませる仕組みです。公式ドキュメントでは、Skill は SKILL.md を含むディレクトリで、名前・説明・手順・必要ならスクリプトや参考資料をまとめられると説明されています。
便利なのは、すべての Skill の全文が常にコンテキストに入るわけではなく、最初は名前・説明・パスだけを見て、必要と判断されたときに SKILL.md 全文を読むという点です。これは、AGENTS.md を薄く保つ考え方とも相性が良いです。
現在入れている中で一番使っているのは obra/superpowers です。Superpowers は、コーディングエージェント向けの開発手法と Skills 群をまとめたリポジトリで、ブレインストーミング、計画作成、TDD、コードレビュー、作業ブランチの扱いなどの流れを支援してくれます。
また、Documents / Spreadsheets / Presentations 系の Skill も、ユースケースドキュメントなどを一時的に読み込んだり、ドキュメントの構成を確認したりするのに使っています。
今のところは、実装フェーズというより、設計資料を整理して AI エージェントが読みやすい状態にする用途が多いです。
ここまでやって感じていること
卒業制作のようなチーム開発では、AI エージェントにコードを書かせる前に、次のような情報をリポジトリに置いておくことが大事だと感じています。
- このプロジェクトでは何を作るのか
- どのユースケースを優先するのか
- なぜその技術スタックにしたのか
- なぜその設計方針にしたのか
- どの資料を優先して読めばよいのか
- どの資料は勝手に参照してはいけないのか
AI エージェントは、リポジトリ内に明確なドキュメントがあれば、それを前提に動いてくれます。逆に、会議で話しただけの情報や、人間の頭の中にしかない判断は、AI には伝わりません。
つまり、AI エージェントを活用するには、単に「良いプロンプトを書く」だけではなく、「リポジトリ全体を AI にとって読みやすいコンテキストにする」ことが重要だと思います。
おまけ
実際どれくらいのトークンを使ってるかとcodexbarというのツールで確認したところ過去30日合計で10億トークンでした。
これをAPIで払っていた場合は約1000ドルくらいみたいです。
codexのサブスクに感謝です！ ありがとう！！
まとめ
今回は、卒業制作プロジェクトの序盤で実践している、AI エージェント開発を前提にしたリポジトリづくりについて紹介しました。
特に効果を感じているのは次の 4 つです。
-
AGENTS.mdを使って、AI エージェントに守ってほしいルールを伝える - ルートの
AGENTS.mdを巨大にせず、ディレクトリごとに必要なルールを置く - UML 図は PlantUML や Mermaid でテキスト管理する
- ADR で意思決定の背景と理由を残す
- Skills を使って、繰り返し使う作業手順を再利用する
まだ卒業制作プロジェクトは序盤ですが、設計段階から AI エージェントが理解しやすいリポジトリを作っておくことで、実装フェーズに入ったときの手戻りを減らせるのではないかと感じています。
今後もチェックポイントごとに、AI エージェントを積極活用したチーム開発について記事を書いていこうと思います。
参考リンク
- Custom instructions with AGENTS.md - OpenAI Developers
- Agent Skills - OpenAI Developers
- PlantUML Use Case Diagram
- About Mermaid
- 意思決定を記録する Architecture Decision Record (ADR) の話 - NIFTY engineering
- ADR を1年間書いてみた感想 - 一休.com Developers Blog
- ADR（Architecture Decision Record）、始めました。 - Zenn
- obra/superpowers - GitHub