AI・生成AI

AI が扱いやすいリポジトリにする — 生成精度を上げる整備

· by IT.Skill

同じ指示を出しても、リポジトリの状態によって生成されるコードの質が変わります。
実際に効果があった整備を、効果の大きい順に並べます。

1. 規約をファイルに書く（効果：最大）

プロジェクトのルールを1つのファイルにまとめ、常に参照させます。

# このプロジェクトの規約

## 技術構成
- Django 5 / PostgreSQL / HTMX（SPAにはしない）

## 必ず守ること
- ビューでは `owned_xxx(user)` を使い、他人のデータを取得しない
- 例外は握りつぶさず、logger に記録して呼び出し元へ伝える
- 金額は int（円単位）。Decimal や float は使わない
- 日時は必ず timezone-aware
- テストは「権限・金額・状態遷移」を優先して書く

## 命名
- モデル: 単数形（Order）
- テンプレート: `<app>/<機能>.html`

毎回同じ指示を書かなくて済むだけでなく、
新しく参加した人にとってのドキュメントにもなります。

2. 共通処理を1か所に集める

同じ処理が散らばっていると、生成時にどれを使えばよいか判断できず、
新しい関数が作られてしまいます。

apps/core/utils.py      … 共通処理はここだけ
apps/core/permissions.py … 認可のヘルパーはここだけ

「共通処理は core/utils.py にある」と規約に書いておけば、既存を使ってくれます。

3. 型を付ける

型情報があると、生成されるコードの精度が上がります。

def calculate_total(items: list[OrderItem], tax_rate: Decimal) -> int:
    ...

引数と戻り値の型が分かると、呼び出し側のコードが正確になります。

4. テストを揃える

既存のテストがあると、同じ書き方で新しいテストが生成されます。
テストの書き方の見本を、リポジトリ内に持っておく意味があります。

5. ディレクトリ構造を意味で分ける

apps/
  orders/      … 注文
  billing/     … 請求
  inventory/   … 在庫

技術的な分類（models, views をトップに置く）ではなく、
業務の単位で分けるほうが、関連ファイルを見つけやすくなります。

6. 大きすぎるファイルを分割する

数千行の views.py は、全体を読ませることができません。
機能単位に分けると、必要な部分だけを正確に扱えます。

views/
  order.py
  billing.py
  report.py

7. 死んだコードを消す

使われていない関数やコメントアウトされたコードが残っていると、
それを参考に生成されることがあります。

# 未使用の検出
ruff check --select F401 .    # 未使用のimport
vulture .                      # 未使用の関数・変数

効果の測り方

整備の効果は、手直しの量で測れます。

整備前: 生成されたコードの3〜4割を修正
整備後: 1割程度

規約ファイルを置いた効果が最も大きく、次に共通処理の集約でした。

副次的な効果

これらの整備は、AI のためだけのものではありません。

  • 新しく参加した人の立ち上がりが速くなる
  • 引き継ぎ資料の作成が楽になる
  • 自分が半年後に読むときにも助かる

もともとやるべきだった整備が、実行する動機を得た形です。

まとめ

効果の大きい順に、

  1. 規約をファイルに書く
  2. 共通処理を1か所に集める
  3. 型を付ける
  4. テストの見本を置く
  5. 業務単位でディレクトリを分ける
  6. 大きすぎるファイルを分割する
  7. 死んだコードを消す

どれも本来やるべき整備であり、AI の有無にかかわらず価値があります。

関連記事