AIと本気で協業するために、試行錯誤から学んだ3つの設計パターン

AIと本気で協業するために、試行錯誤から学んだ3つの設計パターン

Claude Codeを何日にもわたって動かし続けた経験がある。
開発環境のリファクタリングに没頭していると、気づいたら深夜になっていた。そのまま朝を迎え、昼を過ぎ、夕方になっても作業は終わらない。途中で何度か「そのバグ、さっき直した内容と矛盾してない?」と感じる瞬間があった。驚くほど鋭かったAIが、急に不慣れなアシスタントのような挙動を見せ始める。
「AIなんだから疲れないだろう」と思い込んでいたが、長時間動かし続けると、あからさまに回答の精度が落ちていく境界線があった。セッションを重ねた結果、AIとの協業で本当に大切な3つのことが見えてきた。

AIの記憶は有限リソースだと理解する

コンテキストが飽和していくプロセス

長時間のセッションを振り返ると、後半は情報がうまく整理できていない様子が伺えた。

• セッション序盤: 鋭い提案が続く。細かい約束事もきちんと守られる
• 中盤を過ぎたあたり:「この変数は使わない」といった、会話の中での細かい約束事を忘れ始める
• 後半: エラーに対して、以前試してダメだった案を何度も繰り返し提案してくる
• 末期:「一度ファイルを読み直しましょう」と提案してくるが、読み直しても結局同じ間違いを繰り返すようになる

これはAIが疲れているのではなく、膨大な会話履歴によって、肝心の「今やるべきこと」が記憶（コンテキスト）の奥底に埋もれてしまっている状態だ。

「詳しく説明」が逆効果になる罠

今回反省したのは、「分かってくれないから、もっと詳しく説明しよう」と指示を積み重ねたことが、逆にトドメを刺してしまった点だ。
背景を事細かに説明すればするほど、AIが一度に保持できる情報の許容量を圧迫する。その結果、解決のヒントが押し出され、さらに回答が不安定になる。良かれと思って、AIをさらに混乱させていただけだった。
「もっと詳しく」ではなく「もっと短く」。これが長時間セッションで学んだ最初の教訓だ。

実践している3時間ルール

AIのコンテキストには限りがある、と割り切ってから、以下のルールで運用している。

1. 3時間を目安にスレッドを切り替える — 会話がスムーズなうちに、あえて一度スレッドを終了する。これが最も効果的だった。調子が良いからと続けてしまうと、気づいた時にはもう手遅れになっている。
2. 重要なことは外部ファイルに置いておく — current_context.md というファイルを作って、そこに「現在のフェーズ」や「共通ルール」を書いておく。新しいスレッドを始めても、そのファイルを読ませれば、重要な記憶を引き継げる。
3. 2回同じミスが続いたら一回止める — 修正をミスして、その後のフォローも外れたら、そのセッションは情報の整理が追いついていないサインだ。一度深追いするのをやめる。

この「3時間ルール」を守るようになってから、AIとの協業によるストレスは劇的に減った。

AIのための情報アーキテクチャを設計する

README.mdはAI向けではない

Claude CodeやChatGPTを使い分けていると、作業が進むにつれて「あれ、この設定はさっき伝えたはずなんだけどな……」という小さなズレが重なってくることがある。
README.mdは人間向けに書かれたものであり、AIにとっては情報が多すぎたり、逆に詳細な規約が足りなかったりする。

人間向けドキュメント:

• プロジェクトの背景、モチベーション
• 技術選定の理由、将来の展望
• コントリビューターへの感謝

AI向けドキュメント:

• インデントはスペース2つ
• テストコマンドは npm test
• コミットメッセージは日本語

AIに求められているのは「綺麗に整えられたマニュアル」ではなく、「今すぐ実行できる指示」だ。

.llms/ フォルダという解決策

そこで、リポジトリの中に .llms/ というフォルダを作って、そこに「AIに見せるための指示書」をまとめている。

AGENTS.md: 絶対に外してほしくない共通ルール

# 共通ルール

- インデントはスペース2つ
- テストコマンド: `npm test`
- コミットメッセージは日本語
- PRは `gh pr-ja` を使用（`gh pr create` は禁止）

current_context.md: 今どこにいて、次に何をすべきか

# 現在の状況

- フェーズ: 認証機能のリファクタリング
- 次のタスク: セッション管理のテスト追加
- 注意: `auth.ts` は別のAIが編集中のため触らない

AIに「綺麗に整えられたマニュアル」を読ませるよりも、こうした「箇条書きのカンペ」を渡すほうが、回答の精度が安定する。

GitHub Issueを進捗ログとして使う

AIのセッションが終わると、その中での詳細な思考プロセスはリセットされる。次に別のAI（あるいは新しく立ち上げたAI）が作業を再開する時、前任者がどこまで進め、どんなエラーに直面したかを把握するのは意外と大変だ。
作業の節目で必ずGitHub Issueに進捗をコメントするようにしている。

## 進捗報告 (2025-12-23 15:00)

- ✅ 認証ミドルウェアのリファクタリング完了
- ✅ 既存テストは全てパス
- ❌ セッション永続化の実装を試みたが、Redis接続の型エラーで断念
  - 理由: `ioredis` のバージョンが古く、型定義が不完全
  - 代替案: 一旦インメモリストアで実装、Redisは次フェーズで検討

「この機能の実装は完了した」だけでなく、「この手法を試したが、ライブラリの制約で断念した」という記録が重要だ。これを外部記録として残しておくことで、次のAIが「同じ失敗」を繰り返すのを防げる。
AIに「完了報告」を書かせてからセッションを閉じる。これだけで、AIとの共同作業がぐっとスムーズになる。

ハマりポイント: 情報の「整理しすぎ」に注意

最初は意気込んで、フォルダを細かく分けて管理しようとした。

.llms/
├── rules/
│   ├── coding-style.md
│   ├── git-workflow.md
│   └── testing.md
├── history/
│   ├── 2025-12/
│   │   ├── 12-01-auth-refactor.md
│   │   └── 12-15-redis-migration.md
└── context/
    └── current.md

これが逆に失敗だった。
AIはファイルを開くたびに計算リソース（トークン）を使う。階層が深くなると、目的の情報にたどり着くまでのステップが増え、かえって指示の取りこぼしが増えてしまった。
結局、.llms/ の直下に重要な情報を数ファイルに集約して置いておくのが、最も読み取り効率が良いという結論に達した。

.llms/
├── AGENTS.md         # 共通ルール（3KB以内）
└── current_context.md  # 現在地（1KB以内）

「整理したい」という気持ちをぐっと抑えて、シンプルに保つ。これがAI向け設計の鉄則だ。

AIが書いた文章を人間らしくする

AIとの協業は、コードだけではない。ドキュメント、Issue、PRの説明、技術記事。AIに下書きを書いてもらうことが増えてきた。
ただ、AIに下書きを書いてもらうと、一見整っているようで、どこか「誰が書いても同じ」ような無機質な文章になりがちだ。

「GitHub Actionsの最適化は、開発効率を高めるために非常に重要です」

確かにその通りなのだが、これだけを読まされても、書き手の顔が見えてこない。

AI文章の典型的な問題

AIは放っておくと、「背景」「メリット」「デメリット」「まとめ」という、非常に丁寧な構成を作ってくれる。ただ、これがあまりに綺麗すぎると、かえって情報の芯がどこにあるか分かりにくくなることがある。
まず、AIが出してきた「まとめ」の段落を見直す。結論が「AIを積極的に活用していきましょう」といった一般的な内容に留まっているなら、それを消して、「自分が実際に使ってどう感じたか」という本音を書き足すようにしている。
それと、文章のあちこちに太字を入れたがる傾向もある。

「重要なのは、セキュリティと利便性を両立させることです」

こういった全体に太字が散らばる文章では、どこが一番大事なのかがかえって伝わらない。最後に見直しをする時、AIがつけた太字を一度すべて外して、本当に自分が大切だと思っている箇所にだけ付け直すようにしている。

調整のポイント

接続詞を少し崩すだけでも、文章の風通しは良くなる。

「したがって」→「要するに」
「また、」→「それと、」
「しかしながら」→「正直なところ、」

AIは基本的に、最初から正解を提示する。でも、技術記事を読んでいる人が本当に助けられるのは、その正解にたどり着くまでの「ハマりどころ」だったりする。

「ポート番号を8080と8000で間違えて、30分悩んだ」
「単純なスペルミスなのに、ライブラリのバグだと疑ってしまった」

こういう、AIなら決してしないような「人間のマヌケな失敗」をあえて書くことで、記事に人間味と説得力が生まれる。
具体的な数値を入れるのも効果的だ。「大幅に改善されました」ではなく「210MBから28MBまで削減できた（87%減）」のように書くと、読者は自分のケースに置き換えて考えやすくなる。
AIは「大量の情報を整理する」のは得意だが、「誰かに自分の体験を伝える」という意思は持っていない。AIが集めてくれた情報の骨組みに対して、自分だけの経験や失敗という「肉」をつけていく。このひと手間こそが、今の時代の「書く」という作業なのだと感じている。

試行錯誤から見えてきた3つのこと

セッションを重ねて分かったのは、AIの性能限界というよりは、こちらの「情報の渡し方」の重要性だった。

記憶管理: コンテキストは有限リソース

• 3時間でスレッド切り替え
• 重要情報は外部ファイル化（current_context.md）
• 2回同じミスなら一旦停止

情報設計: AI向けのドキュメント設計

• README.mdとは別に .llms/ フォルダを用意
• 箇条書きカンペ方式（AGENTS.md）
• GitHub Issueで進捗ログ管理
• 過度な階層化は逆効果

出力調整: 人間の体温を乗せる

• 決まり文句を削除
• 太字を一度全削除して付け直し
• 接続詞を崩す
• 失敗談を追加
• 具体的な数値を入れる

AIを「すべてをオートで把握してくれる魔法の杖」だと考えると、期待とのギャップに疲れてしまうかもしれない。「非常に有能だが、短期的な記憶で動いているパートナー」だと捉えて、こちらがこまめにメモを残してあげることが大切だ。
AIに無限の記憶力を期待しすぎない。定期的にスレッドを掃除して、共通認識はファイルとして外に出してあげる。この「情報の交通整理」をこちらが意識するだけで、AIとの協業はずっと実用的で、快適なものになる。

この記事で書いた『AIとの協業設計』を、技術同人誌を1冊書き上げる実際の工程(企画から入稿まで)に通した記録を書籍にまとめました。

書籍『自分にしか書けないことをAIに書かせる【増補版】』(A5・70p・PDF ¥1,000)

• BOOTH: https://nomura-san.booth.pm/items/8589855