1. なぜ「小さなコード」なのか
生成AIにプログラムを書かせるとき、いつも困ることがありました。一度に長いコードを出力されると、どこが重要なのかわからなくなるんです。
特に学習用のコードでは、エラーハンドリング（エラーが起きたときの処理）や複雑な機能まで含まれていると、本質が見えにくくなります。
そこで考えました。「AIに渡す開発方針を、最初に決めておけばいいんじゃないか」と。
1.1. YAML形式で方針を整理する
プロンプトの形式には、YAML（ヤムル）という書き方を選びました。YAMLは設定ファイルでよく使われる形式で、階層構造が見やすいのが特徴です。
コードの方針を箇条書きでバラバラに書くより、構造的に整理できると思ったんです。
最終的にこんな形になりました。
# 開発方針
コーディング方針:
可読性:
- 変数名・関数名は役割が明確にわかる名前
- 1関数は1つの責任のみ
- マジックナンバーは設定ファイルで管理
- 難しい書き方より、わかりやすい書き方優先
- デザインパターンは避ける（シンプルな実装を優先）
コードサイズ:
- 1関数: 20行以内
- 1クラス: 100行以内
- 1ファイル: 200行以内
- 機能追加時は関数の肥大化を防ぐ（分割・リファクタリング）
構造:
- 早期リターンでネストを浅く（2階層まで）
- 条件判定は関数化
- 重複コードは関数化（過度な抽象化は避ける）
- 機能ごとにファイル分割（細かすぎない）
- 1ファイルの依存は5つ以内
- 循環依存を避ける
簡潔性:
- エラーハンドリングは最小限
- コメント不要（コードで説明する）
- 型ヒントを活用（対応言語のみ）
開発プロセス:
- 段階的に実装（一度に全部作らない）
出力形式:
- 変更部分のみコードブロックで提示
- ファイル名・関数名（またはクラス名）を明示
- 変更理由を1行で記載
# 案件情報（毎回変わる）
言語:
目的: Code language: PHP (php)上の部分は共通の開発方針で、下の「案件情報」だけをプロジェクトごとに書き換えて使います。
1.2. 使い方
新しいプロジェクトを始めるとき、このYAMLをAIに渡してから具体的な機能要求を伝えます。
すると、最初に決めた方針に沿って、小さく読みやすいコードを生成してくれるはずです。
2. 重視したポイント
2.1. コメント不要で理解できるコード
コメントがなくても読めるコードが理想だと考えています。そのためには、変数名や関数名で何をしているかが明確にわかることが大切です。
例えば、calc()よりcalculateTotalPrice()の方が、何を計算しているのかすぐわかりますよね。
2.2. サイズの制限
関数は20行以内、クラスは100行以内、ファイルは200行以内という目安を設けました。
これくらいのサイズなら、画面にすべて収まって把握しやすいんです。機能を追加するときも、関数が大きくなりすぎないよう分割を意識できます。
2.3. ネストを浅く保つ
if文の中にif文が何重にもあると、読みにくくなります。
そこで「早期リターン」という書き方を推奨しました。条件に合わない場合は早めに処理を終了させて、ネストを2階層までに抑えるんです。
# ネストが深い例
def process(data):
if data is not None:
if len(data) > 0:
if data[0] == 'valid':
# 処理
# 早期リターンの例
def process(data):
if data is None:
return
if len(data) == 0:
return
if data[0] != 'valid':
return
# 処理Code language: PHP (php)条件判定自体も関数化すると、さらに読みやすくなります。
2.4. 依存関係を少なく
1つのファイルが他のファイルに依存する数を5つ以内にしました。
ファイル同士が複雑に絡み合うと、修正したときの影響範囲がわからなくなるからです。特に循環依存（AがBに依存し、BがAに依存する状態）は避けたいところです。
2.5. デザインパターンは使わない
シングルトンやファクトリーといったデザインパターンは、確かに便利です。でも学習用には複雑すぎると感じました。
シンプルな実装の方が、何をしているのか追いやすいんです。
2.6. 段階的な実装
「一度に全部作らない」というのも重要なポイントです。
生成AIは頼めば何でも一気に作ってくれますが、段階的に進めた方が理解しやすいし、途中で方向修正もできます。
2.7. 出力形式の工夫
AIには「変更部分のみをコードブロックで示す」ように指示しました。
ファイル全体を毎回出力されると、どこが変わったのか探すのが大変です。「このファイルのこの関数を修正した」と明示してもらえば、変更箇所がすぐわかります。
変更理由も1行で書いてもらうことで、なぜその修正が必要だったのか振り返れるようにしました。
2.8. 設定ファイルの活用
マジックナンバー（コード中に直接書かれた数値）は、設定ファイルで管理することにしました。
例えば「最大件数100件」という制限があるとき、コードの中に直接100と書くのではなく、設定ファイルにmax_items: 100と書いておくんです。
こうすると、後で変更したいときに1箇所修正するだけで済みます。設定ファイルの形式（JSONやYAMLなど）は、使う言語に応じてAIに任せることにしました。
2.9. やってみてわかったこと
エラーハンドリングを最小限にするのは、学習用だからこそできることです。実際のプロダクトなら、もっと丁寧なエラー処理が必要になります。
でも学習段階では、「まず動く最小限のコード」を理解することが大事だと思うんです。必要になったら、ログ出力のコードを追加すればいいわけですから。
3. まとめ
生成AIは便利ですが、何も指示しないと長くて複雑なコードを出力しがちです。
最初に方針を明確にしておくことで、理解しやすい小さなコードを生成してもらえます。特に学習用なら、シンプルさを優先した方が本質が見えやすくなると感じました。