CONTENTS
三行で
- コード生成のためのドキュメントをまず生成する
- ドキュメントをまず「完璧に」仕上げる
- ドキュメントに沿って「完璧な」コードを生成させる
何より重要なこと
何よりも重要なのは、「完璧」を目指すことだ。 気に入らないコードは徹底的に排除する必要がある。 「ドキュメントだし、実装するときに修正させればいいか」という考えはプロジェクトの破綻をもたらす。 些細な違和感も逃さずに修正しなければならない。
AI エージェントによるコード生成は、コードベースのコードを参考にして生成される雰囲気が強い。 よくないコードが混入すると、そのコードを正しいものとしてコードの生成が行われることになる。
まず、ドキュメントの時点で徹底的にレビューして、完璧な実装計画を作成すること。 そして、そのドキュメントをもとに完璧なコード生成を目指すことが重要となる。
目指すべきこと
AI エージェントでコードを生成する目的は、素早くドメイン知識を構築することだ。 素早いコードの構築ではない。
「完璧な」コード生成を目指す場合、「何が完璧か」という問いに正面から向き合う必要がある。 自分でコードを書いていると、詳細に向き合う必要があるためにこの問いに正面から向き合いづらい。 「何が完璧か」という問いに正面から向き合うことで、ドメイン知識が育っていく。
完璧なコード生成を目指すと、コードの構築速度は自分の手で書くのと同じくらいの速度になる。 しかし、自分の手で書く場合、詳細に隠されてドメイン知識がうまく育たない。 AI エージェントによるコード生成の利点はここだと考えている。
ドキュメント駆動開発
- 詳細な実装計画ドキュメントを整備
- 実装計画ドキュメントに沿ってコードを生成
- 生成されたコードの内容を実装計画ドキュメントに反映
- TODO ドキュメントを更新
AI エージェントによるコード生成のために、詳細な実装計画ドキュメントが必要になる。 指示だけで完璧なコードを生成させるのは不安定だという結論だ。 たまにいいコードを生成してくれることもあるが、いい具合だったのに急によくないコードが混入して全てダメになることもよくある。
Claude Code はコンテキストが小さいので、セッションを細かく区切って開発を進める必要がある。 このために少なくとも詳細な TODO ドキュメントは必須となる。
実装計画ドキュメントを整備したら、以下の指示を回して開発を進めている。
docs/path/to/feature/TODO.md を分析してください docs/path/to/feature/*.md の該当する実装計画も詳細に確認しましょう 実装されている箇所も詳細に分析して、次の作業を特定してください docs/path/to/feature/*.md の該当する実装計画を詳細に確認しましょう docs/architecture/*.md の詳細も確認してください 実装計画に従って実装を開始してください 実装が進むたびに実装計画を確認するようにしましょう docs/path/to/feature/*.md の実装計画と実装を比較してください ドキュメント一つ一つ詳細に確認して、対応する実装と比較してください 異なる部分はありますか？ 実装に合わせて実装計画ドキュメントを更新してください docs/path/to/feature/TODO.md を更新してください cargo +nightly fmt してコミットしましょう
feature ごとの詳細設計と、設計思想を抽出した architecture ドキュメントを用意している。 開発を進めるにあたって遵守してほしい原則などをここにまとめる。
TODO ドキュメントで進捗を管理させることで、この指示を回すことで開発が完了するようにしている。
やっても意味のないこと
生成させた実装計画ドキュメントやコードについて一つ一つ手で修正するレベルのマイクロマネジメントは意味を持たない。
実装計画ドキュメントや実装コードの生成は、設計思想や要求仕様を伝えて生成させたものをそのまま使用するべきだ。 「完璧を目指す」というのは、「完璧な生成を目指す」という意味で、生成させたコードを手で調整することではない。
手で調整するのは流れる水の流れをせき止めたり、流れを変えようとしたりするのと似ている。 生成されたコードに不適切なものが含まれている場合、そのコードが生成された理由がコードベースや指示内容に存在する。 それを排除しなければ、また何度でも不適切なコードを生成する可能性がある。
気に入らないコードを生成した場合はもう一度一からやり直させることはできる。 ただ、何度も同じような設計をする場合、その原因があるはず。 それを特定して排除することで、より適切な設計を生成させることができる。
できる限り少ない回数の指示で完璧な生成を目指すことが重要だ。
まとめ
Claude Code を使用した開発の手順が固まってきたのでまとめてみた。 Claude Code 固有のワークアラウンドがいくらか含まれるが、 AI コード生成に対する向き合い方が固まってきた。
ドキュメント生成、コード生成について、全て AI 生成に任せるのが良さそう。 ユーザー側で行う必要があるのはコードの修正ではなく、コードを製品にマージするかどうかの判断だろう。
参考資料
- 特になし
