はじめに
CursorやClaudeでコードを書くとき「コードを一気に生成させて、後からレビューする」というやり方が結構辛い
出力されたものが多いと把握するのに時間がかかるし、出力されてから方針を変えようと思っても修正コストが高くなってしまう
また、少しの修正でも、全部書き直すような動きをしがちでやりとりが散らかる
それを避けるために、最近はAIにはまず自前の作業手順ドキュメントを書かせ、それを段階的にレビューしながら進めている
そうして作業をしていると、最も時間がかかるのは「自分が理解すること」になっていると実感する
この記事では理解へのアプローチをまとめておく
理解しやすい構造
最も手軽に意識しやすいのは「説明の順序」だと感じていて、実際自分もこれを気にするようにしてから言語化がスムーズになった
上の記事が自分の考えにかなり近い
この記事はプレゼンに関するものだけど、理解しやすい順序として普遍的なものだと思う
ポイントは以下の3つ
KU接合 既知（known）から未知（unknown）へ
CA接合 具体的（Concrete）なものから抽象的（Abstract）なものへ
BN接合 大きい概念（Broad）から小さい概念（Narrow）へ
文章を作る時だけでなく、自分が何かを学ぶ際にもこのポイントを大事にしている
具体例
KU接合 既知（known）から未知（unknown）へ
Railsではコントローラーに処理を書きすぎるとFat controllerになる。(既知)
条件分離や例外処理をServiceとして責務を切り出すことで見通しがよくなる。(未知)
既知であるかは人や状況によって常に変化する
必要であれば既知の範囲を広げていき、最終的に説明したい未知のものへ誘導することが重要
CA接合 具体的（Concrete）なものから抽象的（Abstract）なものへ
Railsはその機能が巨大なために、
ActiveRecordやActionMailerとして、別のGemに実装が分離されている。(具体的)
1つの大きなコードの塊だと、保守性が低く危険である。
なので、機能ごとにGemを分割して、管理のしやすい形にしている。
これは「関心の分離」という思想に従っていると言える。(抽象的)
具体と抽象の差が大きすぎると理解が追いつかない
相手が理解していないと感じたら、その差を埋めるような説明が必要
BN接合 大きい概念（Broad）から小さい概念（Narrow）へ
RailsはMVCアーキテクチャを採用しており、
アプリケーション全体は「Model」「View」「Controller」の3つの役割によって大きく形作られている。(大きい概念)
中でもViewは、レスポンスデータをJSONやHTMLなどの形式へ変換する部分を担っている。(小さい概念)
基本的に小さい概念が肥大化する
小さい概念をさらに分割していくことを初めから考えておく
これらをAIとの対話に落とし込む
1. DOCS_GUIDEを書く
自分はCursorが出してくるPlanの形式を指定するために、DOCS_GUIDEというドキュメントを事前に書いている
プロジェクトやそのときの気分によって変えているけど、大体は以下のような感じにしている
# DOCS_GUIDEについて
このガイドは、作業内容を記載したドキュメントを作成する一連のフローについて説明しています
以下の3ステップに沿って、ドキュメントを作成してください
ただし、１ステップごとにユーザーへレビューを依頼してください
勝手に次のステップへ進まないでください
1. ユーザーに指示された内容から、どのようなものを実装する必要があるかを列挙してください
2. 変更が必要なファイルと、その変更内容の概要について記載してください
3. 各変更内容の概要に、具体的なコードで修正内容を追記してください
~~~~(ファイルの命名規則やドキュメントの書き方など)~~~~
2. やりたいことを伝える
ここでは割とふんわり伝える。
例) booksテーブルとCRUD APIを作って。DOCS_GUIDE.mdに従って。
3. ステップ1のレビュー
大雑把な方向性をレビューする
認証が必要ではないか、関連テーブルの修正は必要ではないかなどを考える
- booksテーブルのスキーマ定義
- マイグレーション作成
- Bookモデル定義
- CRUD APIのエンドポイント追加
4. ステップ2のレビュー
具体的なファイルに思いを馳せるフェーズ
基底クラスへの修正や参照元となるファイルへの変更が必要ではないかを考える
- db/migrate/..._create_books.rb
booksテーブルを作成するマイグレーション
- app/models/book.rb
モデル定義とバリデーション追加
- app/controllers/books_controller.rb
CRUDアクションの追加
- spec/requests/books_spec.rb
リクエストスペック追加
5. ステップ3のレビュー
具体的なコードをファイルごとに見る
ここまでの道のりで、自分の中でもある程度実装内容が想像できているのですんなり読める
(はず)
- db/migrate/..._create_books.rb
~~~
create_table :books do |t|
t.string :title, null: false
t.string :author, null: false
t.date :published_at
t.text :description
t.integer :stock, null: false, default: 0
t.timestamps
end
~~~
6. 実際のコードへ反映する
実際に反映すると当然エラーやテストの失敗が発生するので、ここから先は都度AIに修正させる
終わりに
AIの進化が目覚ましいため、これから先のボトルネックは人間のレビューになってくるだろうと思う
いかにレビューの速度と質を高められるかを今後は課題にしていきたい