ツールを入れればとかスキルを使えば等々、言われているのだけど、結局のところ従来の開発フローにうまくハメてあげるのが近道なのじゃないかと思っており、備忘録として残しておく。
プロンプト一発は無理
作り直しする際、最初のプロンプトを修正してやり直すとか、段階を踏むとかあるが、どちらも再現性が低く、成果物が安定しない。結局、従来の開発フローみたいなものを実施するようになった。
- 作るものの外部要件をdraft.mdに書き出す。
全体のアーキテクチャ、必須の機能や、実行環境、データのフローの概要、参考にする文献や先行実装といったものを書き出す。AIモデルと壁打ちして出力させることもある。 - draft.mdをベースに実装プランを検討させる。
プランは複数のフェーズに分割して、受け入れ条件を明確にする。例えば、参考文献の調査がフェーズ0にあるなら、フェーズ0の受け入れ条件は調査結果のドキュメントになるはず、といった具合。プランは、plan.mdとして保存するけれど、エージェントとやり取りして過不足を調整する。「このパターンが抜けてるように思えるから、フェーズ1に追加するタスクを検討して」とか。 - plan.mdをベースに各フェーズをタスクに分割させる。
タスクはそれぞれチケットに対応するので、フェーズとタスクの進捗状況（planned/in-progress/doneぐらいで良い）と入力・出力（成果物）を含めて、tickets.jsonとして保存する。例えば「phase 1のtask 1のinputsは、phase 0のtask 5のoutputsとtask 6のoutputsが必要」みたいなフェーズ・タスク間の関係が明確になるようにする。draftとplanはMarkdownでも良いけれど、タスク管理は頻繁に更新されるので、ticketsは壊れにくいJSONにしておいた方が良い。 - チケットに着手させる。
あとは「phase 0から着手して」って依頼するだけなんだけど、実際のタスクの進行にはいくつか安定させる仕組みが要る。 - 安定させる作業もエージェントにやらせる。
自分の場合は、Zedの.rulesでやらせてる。
それぞれのタスクでドキュメントやコードといった成果物があるので、それらに対する検証フローは必須。Pythonならpytestとか、linterの類いを使う。
タスク内のアクション、例えばコード生成などは全てgit addさせ、タスクの最後にgit commitさせる。これで「phase 1のtask 5はキャンセル、元に戻して」という指示ができるようになる。
コンテキストの引き継ぎが出来るように、journal / checkpoint / snapshotをMCPサーバに依頼させる（次項）。
コンテキストウインドウを引き継がせる
コンテキストウインドウを跨いだ場合、エージェントは旧セッションの内容をぼんやりとしか把握していない。メモリは圧縮されているから。
利用しているモデルやAIエージェントを動かしている環境が各々で違うので、ポイントだけ。自動的にCompletion（ユーザの入力と、それに対するエージェントの出力）を記録する仕組みを利用すると、セッション間、あるいはタスク間の引き継ぎ精度が上がる。
自分の場合、これに対する暫定的な解はagentops_mcp_serverで、Zedの.rulesと組み合わせることで、ほぼ問題は解消した。journal / checkpoint / snapshotという用語で分かる通り、これはPostgreSQL等を参考にした記録用のMCPサーバで、作業途中で落ちても、どこまで作業完了しているかはjournalを見れば分かる。仕掛かり中のタスクを先頭からやり直す場合はcheckpointからロールフォワードする。journalが重くなったらsnapshotだけ読めば再開できるような仕組みにしてある。かなり巨大なファイルになってしまうので、journalはローテートするけれど、snapshotがあれば数行だけで再開できるので、こういう実装を選択した。
「続きを」
現在、自分が主に使っているのは、gpt-5.2-codexなので、これを読んで「使ってるエージェントの頭が悪すぎ」とか「こういうSKILLを使えば良いのに」という意見はもちろんあると思う。
ただ、gpt-5.2-codexを含むAIモデルの学習データは、上に説明したような従来からある開発フローで書かれてきたコードやドキュメントの方がまだまだ多く、しばらくはこの方法でイケる気がしている。
途中で判断を求められることはあるけれど、envrcctlはひたすら「続きを」と回答するだけでほぼ実装できたことを記しておく。