AIエージェントを個人開発で使ってわかった5つの注意点

このブログサイトの構築でClaude Codeを数週間使い倒した。AIエージェントを実際のプロジェクトに使ってみて「これは知っておくべきだった」と思った注意点を5つ共有する。

AIエージェントとは

ここで言うAIエージェントは「自律的にファイルを読み書きし、コマンドを実行してタスクをこなすAI」のこと。Claude Codeがその代表例。指示を出せば計画を立て、ファイルを編集し、実行し、エラーを修正する、という一連の作業を自分でやってくれる。

注意点1: コンテキストが詰まると品質が落ちる

AIエージェントには「コンテキストウィンドウ」という制限がある。セッションが長くなるほど、過去の情報を参照しながら作業するのが難しくなり、回答の精度が落ちてくる。

体験した症状：

対処法は「定期的にコンテキストをリセット」すること。セッションが1〜2時間を超えたあたりで新しいセッションを始め、重要な情報だけを引き継ぐようにした。

# 新しいセッションへの引き継ぎテンプレート

## プロジェクト概要
[プロジェクトの目的と現在の状態]

## 完了した作業
- [完了タスク1]
- [完了タスク2]

## 今からやること
[次のタスク]

## 重要な制約・決定事項
- [重要な技術的決定]
- [使っているライブラリのバージョン等]

注意点2: 確認なしにファイルを変更する

Claude Codeは「修正して」と言うと確認なしにファイルを書き換える。これは便利だが、意図しない変更が入ることもある。

やらかした例：「パフォーマンスを改善して」と言ったら、改善どころか動いていたコードが壊れた状態で返ってきた。

対処法：

# 作業前に必ずコミット
git add .
git commit -m "chore: AIエージェント作業前のセーフポイント"

# 作業中も定期的にコミット
git add .
git commit -m "feat: 途中経過 - ログイン機能実装中"

Git管理をしっかりやっておけば、壊れてもすぐに戻せる。「作業前コミット」を習慣化するだけで心理的な安全が大きく上がった。

注意点3: 「動く」と「正しい」は別

AIエージェントが生成したコードは動くことが多い。でも「動く」と「正しい」は別の話だ。

体験した問題：

# AIが生成したコード（動くが問題あり）
def get_posts(category_id):
    posts = []
    categories = wp.get("wp/v2/categories")  # カテゴリ一覧を毎回取得（N+1クエリ）
    for cat in categories:
        if cat["id"] == category_id:
            posts = wp.get(f"wp/v2/posts?categories={category_id}")
    return posts

「カテゴリ一覧を毎回取得する」という非効率な実装になっていた。動くからテストは通るが、パフォーマンスが悪い。

生成されたコードは必ずレビューする。特に：

注意点4: 指示があいまいだと解釈がブレる

「改善して」「きれいにして」という漠然とした指示だと、AIが勝手に判断して意図と違う変更をすることがある。

あいまいな指示の例:

このコードをリファクタリングして。

具体的な指示の例:

このコードのリファクタリングをしてほしい。
変更範囲は以下の点のみに限定して：
1. 関数名を動詞_名詞の形式に統一（例: get_posts, create_article）
2. 1関数が50行を超えている場合は分割
コードのロジック自体は変更しないこと。

「何をして」「何をしないか」を明確にすることで、意図しない変更を防げる。

注意点5: 自信満々に間違える

AIエージェントの厄介な特徴は「間違えるとき自信満々に間違える」ことだ。

体験した例：WordPressのREST APIのエンドポイントについて「/wp/v2/settings でサイトタイトルを更新できます」と言われて信じて実装したら、実際にはそのエンドポイントは別の権限が必要だった。

自信のある回答でも、重要な部分は公式ドキュメントで確認する習慣が必要。特に：

「本当にそのエンドポイントは存在しますか？公式ドキュメントのURLを教えてください」と確認を求めるのも有効。存在しないURLを返してくることもあるので最終的には自分で確認する。

まとめ

AIエージェントを個人開発で使ってわかった5つの注意点：

1. コンテキストが詰まると品質が落ちる → 定期的にセッションをリセットし、重要情報だけ引き継ぐ

2. 確認なしにファイルを変更する → 作業前に必ずgitコミットしてセーフポイントを作る

3. 「動く」と「正しい」は別 → 生成コードは必ずレビューする（特にN+1問題、セキュリティ）

4. 指示があいまいだと解釈がブレる → 「何をして」「何をしないか」を明確に指示する

5. 自信満々に間違える → 重要な仕様は公式ドキュメントで確認する

AIエージェントは強力なツールだが、盲目的に信頼するのは危険だ。「人間がレビューしながらAIに作業させる」というスタンスが、今のところ最もうまく機能している。