目次
はじめに
最近、Webアプリの開発にハマっているjin@goldear820です。
今回作ったのは、Flaskで動く燃費管理Webアプリ「GN-AOI(Automotive Optimization Interface)」です。
今回作ったアプリは以下で公開しています。
ただ、この記事で書きたいのはアプリ紹介そのものではありません。
今流行りのCodex CLIを使って実装を進めたのですが、仕様が曖昧なままAIに任せると、次のような状態になりやすいと感じました。
- 修正のたびに実装の方向がぶれる
- 一見動いているが、仕様としては破綻している
- 直せば直すほど別の箇所が崩れる
そこで実装途中から、要件を明確化し、その制約の中で進める流れに切り替えました。
最初は要件を決めずに「あれもやりたい、これもやりたい」とCodexに指示を出していたのですが、気づくと実装の方向が変わってしまうこともありました。
この記事では、Codex CLIを使った開発をどう破綻させずに進めたかという視点で、その流れを整理します。
なぜこのアプリを作ろうと思ったか
燃費記録アプリ自体は世の中にありますが、次のような理由から自分で管理したいと考えました。
- 自分でデータを管理したい
- スマホから気軽に確認したい
- 無駄な広告から解放されたい
最初は軽く作るつもりで、必要な記録をWebで見られれば十分だと思っていました。
ただ、作り始めると機能はすぐ増やせます。(最近のAI凄いです、マジで)
グラフ、分析、エクスポート、見た目の改善と広げられる方向はいくらでもあって、ここで止め方を決めないと終わらないと途中で気づきました。
この問題自体はAIに限った話ではなく、普通の開発でも要件を決めないまま進めると同じように起きます。
今回の開発をどう進めたか
このように現在の状態を整理しておくことで、開発の進捗と課題を常に把握できるようにしています。
そこで一度立ち止まって、「何を作るか」ではなく「どこまで作るか」を先に決める方針に切り替えています。
今回の開発は、結果として次のような流れで進めました。
- 【要件定義】どこまで作るかを決める
- 【仕様設計】その範囲でシンプルな構成を決める
- 【実装】Codex CLIを使って実装を進める
- 【テスト・仕様確定】バグ修正で仕様の曖昧さを潰す
- 【運用設計】公開できる形に構成を整理する
このように、今回の開発では「要件を固定する → その制約の中で設計する → 実装してズレを修正する」という流れを意識しています。
特にCodex CLIのようにAIを使った開発では、仕様が曖昧なままだと修正のたびに出力がぶれやすいため、この順番で進めることが重要だと感じました。
【要件定義】どこまで作るかの決定
最初にやったのは、「何を作るか」ではなく「どこまで作るか」を決めることでした。
作り始めた当初は、思いついた機能をそのままCodexに指示して実装していく形で進めていました。
ただこのやり方だと、機能は簡単に増やせる一方で、スコープがどんどん広がっていきます。
特にAIを使った開発では、実装のハードルが低いため、以下の状態になりやすいと感じました。
- とりあえず作れるから追加する
- 気づいたら機能が増えている
- 終わりどころが分からなくなる
そこで途中から、今回の開発では「ここまでできれば完成とする」という範囲を先に決めることにしています。
実際には、以下のような形でスコープを定義しました。
# release_scope_v1.md ## v1.0 完成条件 - 記録のインポートができる - 記録の登録・表示・削除ができる - 車両情報の登録・表示・削除ができる - 初期化ができる - 各機能でエラーなく一通り操作できる - Android/iPhone/PCでレイアウト崩れや操作不能がない ## 今回やらないこと - グラフ - 高度な分析 - UIの細かい作り込み
このようにスコープを明確にしたことで、以下の効果がありました。
- やらないことを判断できるようになった
- 設計をシンプルに保てるようになった
- Codexへの指示もブレにくくなった
また、このファイルは自分の判断を整理するだけでなく、Codexに対しても「この範囲で実装する」という前提として機能しています。
その結果、不要な機能の提案やスコープ外の実装が減り、全体の一貫性を保ったまま開発を進めることができました。
【仕様設計】CSVベース構成の採用
データ構造については、最初から深く悩んだわけではありません。
もともと使っていた燃費記録アプリがあり、そのアプリがCSVファイルでデータを管理していました。
ただ、このアプリが現在は非公開となってしまい、新しく入手することができなくなっています。
もともと使っていたのは以下のアプリです。
そのため、手元にあるデータをなんとかバックアップして、今回のアプリでもそのCSVをそのまま使えればいい、というのが出発点になりました。
正直なところ、この時点ではデータベースを使うことはほとんど考えていませんでした。
ただ、要件を固定して整理していくと、
- 複雑な検索や集計は不要
- データ量もそこまで多くない
- ファイル単位で完結した方が扱いやすい
という前提が見えてきて、結果的にCSVベースの構成が非常に相性が良いと分かってきました。
また、今回のように既存データをそのまま扱えることも含めて、
- 中身を直接確認できる
- バックアップや移行が簡単
- 環境に依存せず扱える
といったメリットもあり、この構成を採用しています。
【実装】Codex CLIを使った実装
実装自体は、Codex CLIを使って進めています。
ただ、単純に「やりたいこと」をそのまま指示するだけでは、うまくいかないことが多いと感じました。
要件を決めずに実装を進めていた頃は、
- 修正するたびに別の箇所が崩れる
- 同じような実装を何度も繰り返す
- どこまで完成しているのか分からなくなる
という状態になりやすかったです。
そこで、現在の状態を明確にするために、`current_status.md` というファイルを用意しました。
実際のファイルの中身は細かくなりすぎるため省略しますが、構成としては次のような粒度で整理しています。
# current_status.md ## 概要 ## 実装済み ## 実装途中 / 要改善 ## 未実装 ## 気になっている点（UI・使い勝手） ## 備考
- 次に何をやるべきかが明確になる
- Codexへの指示も具体的になる
- 実装の重複や抜け漏れを防げる
という効果がありました。
特にCodex CLIのようにAIを使った開発では、前提となる情報が曖昧なままだと、修正のたびに出力がぶれやすくなります。
そのため、`current_status.md` のように現在の状態を固定することで、開発全体の安定性を保つことができました。
【テスト・仕様確定】曖昧さの解消と仕様の固定
実装を進めていくと、想定通りに動かない箇所や、仕様が曖昧な部分がいくつか見えてきました。
今回の開発では、テスト項目を細かく用意するのではなく、実際に使いながら不整合を潰していきました。
例えば、総走行距離の計算がズレる問題がありました。
原因を追っていくと、初回の走行距離（初期値）の扱いが曖昧になっていたことが分かります。
この時点で、
- 初期値をどのように扱うのか
- どのタイミングで距離を確定するのか
といった仕様が明確に定義されていませんでした。
そこで、この部分を仕様として整理し、「initial_odd_km」という項目を導入しています。
このように、バグを修正するというよりも、
- 曖昧だった仕様を明確にする
- その結果として不具合が解消される
という形で進めていきました。
特にCodex CLIのようにAIを使った開発では、仕様が曖昧なままだと修正のたびに別の挙動を生みやすいため、ここで仕様を固定することが重要だと感じました。
正直なところ、この問題は最初に仕様をしっかり詰めていれば防げた部分でもあります。
ただ、個人開発で最初からすべての仕様を固めてから実装に入るのは現実的には難しく、実際に触ってみて初めて気づく部分も多いと感じました。
今回も、動かしてみて違和感に気づき、その結果として仕様を明確にしていきました。
そのため、最初にすべてを決めきるというよりも、
- ある程度の前提を決めて実装する
- 実際の挙動から仕様を見直す
- その都度仕様として固定していく
という進め方の方が現実的だと感じました。
【運用設計】公開可能な構成への整理
もともとGN-AOIは、自分で使うために作り始めたWebアプリだったので、最初からGitHub公開まで強く意識していたわけではありませんでした。
そのため、開発初期の構成は「とりあえず動けばよい」という寄り方になっていて、実データの置き場所も公開向きとは言えない状態でした。
実際、データをそのままリポジトリ側で扱う構成だと、
- 実データがGit管理に混ざりやすい
- push前に消す手間が発生する
- cloneした人向けの初期状態を作りにくい
といった問題があります。
そこで途中から、実データは `instance/` に分離し、リポジトリ側にはテンプレートとしてのデータ構成だけを残す形に整理しました。
公開を意識した構成への変更（データとコードの分離）
この形にしておくと、自分の環境ではそのまま使い続けられますし、GitHubで公開するときも実データを混ぜずに済みます。
さらに、README側でも初期化手順を書きやすくなるので、cloneした人が再現しやすい構成にできます。
今回の開発では実装そのものだけでなく、最後にこの運用設計を見直したことで、ようやく「公開できる形」になったと感じています。
Codex CLIを使った開発で分かったこと
今回の開発では、Codex CLIを使って実装を進めました。
実際に使ってみて感じたのは、「AIに任せれば勝手に完成する」というものではなく、こちらがどれだけ正確に指示できるかが重要だという点でした。
特に、仕様が曖昧なまま指示を出すと、
- 意図と違う実装が出てくる
- 修正のたびに別の挙動になる
- 全体として一貫性が崩れる
といった問題が起きやすいと感じました。
そのため、「何を作るか」「どういう仕様か」を整理して伝えることが重要になります。
これは、人に実装を依頼するときに仕様を説明するのとほとんど同じ感覚でした。
一方で、仕様さえ明確であれば実装のスピードは非常に速く、試行錯誤のサイクルを短く回せるのは大きなメリットです。
結果として感じたのは、
- 実装は速くなる
- しかし設計や仕様の重要性は変わらない
という点でした。
AIを使った開発でも、最終的に品質を決めるのは実装力ではなく、どれだけ仕様を明確にできるかだと感じています。
今後やりたいこと
今回のGN-AOIは、まずは「公開できる状態に持っていく」ことをゴールにしていたため、機能としてはかなり絞った構成になっています。
今後は、次のような機能を段階的に追加していく予定です。
- グラフ表示
- 簡単な分析機能
- エクスポート機能
- UIの改善
これらの機能についても、今回と同様にCodex CLIを使って実装していく予定です。
実際に使ってみて、仕様さえ明確であれば実装自体はかなり高速に進められると感じているため、今後は「機能追加のスピードを上げる」という意味でもAIの活用を継続していきたいと考えています。
ただし、機能を増やしていく場合も、今回と同様にスコープを意識しながら段階的に追加していくことが重要だと考えています。
まとめ
今回のGN-AOIの開発は、Codex CLIを使ったAI開発の実践という形になりました。
AIによって実装は速くなりますが、「何を作るか」と「どう進めるか」を決める重要性は変わりませんでした。
特に重要だったのは、
- どこまで作るかを先に決める（要件定義）
- シンプルな構成に落とし込む（仕様設計）
- 現在の状態を明確にする（進捗管理）
- 曖昧な部分は仕様として固定する（テスト・仕様確定）
といった基本的な部分でした。
また、機能追加についても一度にまとめて実装するのではなく、単機能ごとに段階的に進めた方が、結果として安定した実装になると感じています。
AIはあくまで実装を補助するツールであり、最終的な品質を決めるのは設計と仕様の明確さでした。
今回の内容が、Codex CLIを使った開発の進め方の一例として参考になれば幸いです。
今回作成したGN-AOIはGitHubで公開しています。
READMEにセットアップ手順も記載しているので、興味があればぜひ試してみてください。
コメント