システム開発の技術者は、コードと文章の両方を書きます。AIに仕事を任せるようになると、文章を書く機会はむしろ増えます。AIへの指示（プロンプト）、AIが作業を始めるたびに読む決まりごとのファイル（この記事では「作業ルール」と呼びます）、仕様書、レビューの依頼。どれも、AIが読む文章です。
その文章を、コードと同じ感覚で直していないでしょうか。問題が見つかったら、その箇所だけ直す。足りない決まりがあれば、一行足す。コードではごく普通のやり方ですが、文章では逆効果になることがあります。私たちは、このブログの記事をAIに改訂させたとき、まさにそのやり方で記事を読みにくくしてしまいました。
先に結論を書きます。コードは、直す範囲を絞り込んでよい。文章は、一か所を直したら、全体を読み直す必要がある。以下、私たちの二つの失敗を例に、その理由と、私たちが変えたことを紹介します。
コードは、直す範囲を絞り込める
コードは部品に分けて作ります。処理を関数やクラスに分け、部品同士のやり取りの約束（インターフェース）を決めておく。新しい関数を一つ足しても、どこからも呼ばなければ、ほかの関数の動きは変わりません。約束を破れば、型の検査やテストが失敗して知らせてくれることもあります。だから、直す範囲を絞り込んで考えられます。
もちろん、絞り込みを誤ることはあります。前回の記事「人にとって保守しやすいコードは、AIにとっても保守しやすいのか」で紹介した件では、二つの業務が同じ共通関数を使っていました。不具合の報告だけを渡されたAIは、一方の業務の不具合を直すために共通関数を修正し、もう一方の業務の処理まで変えてしまいました（経緯は「AIに任せた開発は、なぜ「つなぐところ」でつまずくのか」でも紹介しています）。コードで気をつけるのは、こうした「複数の場所から使われている部分」です。その部分を使っている呼び出し元を洗い出し、それぞれの業務のテストを走らせれば、確かめる範囲は絞れます。
文章は、一か所の修正が全体に効く
二つ目の失敗は、文章で起きました。私たちはこのブログの記事を、原案づくり、改訂、レビューのそれぞれにAIを使って作っています。事実を提供し、最後に判断するのは人です。レビュー役のAIには、前の回のやり取りを覚えていない状態で、毎回新しく読ませています。書いた本人ではない目で読ませるためです。
前回の記事を仕上げるとき、改訂役のAIは、レビューで出た指摘を一件ずつ、その箇所だけ直していきました。レビュー役が「その作業は誰がしているのか」「何時間かかるのか」と疑問を挙げれば、答えを書いた段落を足しました。コードで言えば、バグ報告が来るたびに、その行だけを直していく進め方です。その結果、次のことが起きました。
- 本文が膨らみ、話が本題からそれた。本文は約6,500字から約8,600字に増えました。足した段落の多くは、テストに何時間かかるかといった、社内の進め方の話です。読者が知りたい「AIとどう付き合うか」から、話がそれていきました。
- 導入が重くなった。経緯を正確にするための説明を一つずつ足した結果、本題に入る前に、前回の記事との関係、研究の紹介、その研究の断り書きが積み上がっていました。
- 直した一文が、新しい誤りを生んだ。前回の記事では、人とAIの違いを「人なら覚えている」と書いていました。「その書き方は言い過ぎ」という指摘に応えて、改訂役は「各業務が共通関数に何を期待しているかは、コードのどこにも書かれていなかった」と書き直しました。実際には、その期待は別の処理のテストの中に書かれていて、以前の記事にもそう書いていました。この一文だけを見れば筋が通っていたので、次のレビューまで誰も気づきませんでした。
レビュー役には、記事の有用性などを5段階で採点するようにも頼んでいました。その間も、点数は3から4へと上がっていきました。指摘は一つずつ片づいていくので、直している側からは、良くなっているように見えたのです。崩れに気づいたのは、担当者が記事を通して読んだときでした。「読者がこの記事を読むとして、それらは必須なのかな？」。この問いかけを受けて、指摘ごとの修正をやめ、読者が何を知りたいかを軸に、全体を書き直しました。本文は約5,700字になり、次のレビューで残ったのは小さな指摘だけでした。
なぜ、文章では範囲を絞り込めないのか
コードでは直す範囲を絞り込めるのに、文章ではなぜできないのか。私たちは、三つの違いがあると考えています。
- 一文足すと、記事全体の読まれ方が変わる。関数を一つ足しても、ほかの関数の動きは変わりません。文章では、一文足すだけで、読者がどこに注目するかが変わります。前回の記事の導入では、正確さのために足した説明が積み上がり、本題に入るまでが長くなりました。足した文は一つずつ正しくても、記事が何を言いたいのかは見えにくくなります。
- 作業ルールは、関係のない規則まで毎回読まれる。コードでは、使われない関数は、動くときに何の影響もありません。作業ルールは違います。AIは作業を始めるたびにファイルを読み込むので、「図を作るときは〜すること」という規則も、文章を直すだけの作業で毎回読まれます。規則を足すほど、そのときの作業に必要な規則が、ほかの規則に埋もれていきます。
- 間違えても、機械的には教えてもらえない。コードの間違いの一部は、型の検査やテストが見つけてくれます。文章には、型の検査のように機械的に確実に知らせてくれる仕組みがありません。先の「どこにも書かれていなかった」という一文も、次のレビューで記事を読み通したときに、初めて見つかりました。
AI開発企業のAnthropicも、作業ルールのような指示について、似た注意を促しています。AIが一度に扱える情報には限りがあり、量が増えるほど、必要な情報を正しく拾えなくなる。そのため、想定される例外を指示に洗いざらい書き並べることは勧めず、期待する振る舞いを示す、多様で典型的な例を選んで載せるよう勧めています。[1]
ただし、コードに全体の見通しが要らないわけではありません。部品ごとに直せるのは、そう作るための工夫を積み重ねてきたからです。文章には、その工夫に当たるものがありません。だから、人が意識して全体を読み直す必要があるのです。
レビューを頼む文章も、AIが読む文章だった
振り返ると、レビュー役への依頼の書き方にも原因がありました。最初の3回は、「読者が期待するのに、欠けているものはないか」と尋ねていました。そう聞かれれば、レビュー役は足りないものを探し、「これも書くべきだ」と返してきます。改訂役がそれに応えれば、記事は膨らむ一方です。
全体を書き直し、依頼にも「社内の進め方の細部は、意図して削った。誤解を招く場合を除き、足すよう求めないこと」と書き添えた4回目では、指摘は事実の書き方に関わる数か所に絞られました。
AIは、渡されたものだけを手掛かりに動きます。直す側に指摘の一覧だけを渡せば、その箇所だけを直す。レビュー側に「足りないものはないか」とだけ尋ねれば、足りないものを探す。不具合の報告だけを渡されたAIが、共通関数に最小限の修正を加えた先の件と、同じ形です。
文章をAIと直すときに、私たちが変えたこと
次の五つのうち、1と5は今回実際に効いたもの、2から4は今回の振り返りから取り入れた方針です。
- 最初に「何のための文章か」を書き出し、両方のAIに渡す。読者、目的、言いたいこと、書かないこと、長さを短く書き、直す側にもレビューする側にも渡します。直すたびに、各段落がこれに合っているかで判断する。コードでいうテストの代わりです。この記事では、次のように決めました。
- 読者：AIに仕事を任せ始めたばかりの技術者
- 目的：コードと文章で、AIに任せるときの注意点の違いを示す
- 言いたいこと：コードは直す範囲を絞り込めるが、文章は全体を読み直す
- 書かないこと：社内の進め方の細部
- 長さ：本文6,000字以内
- 指摘は、直す前に仕分ける。「直す」「直さない（理由を書く）」「人に確認する」に分けます。たとえば「何時間かかるのか」という疑問には、それが分からないと記事の言いたいことが誤解される場合だけ答え、そうでなければ足しません。
- 継ぎ足しをやめる目安を決めておく。私たちは、レビューが2回を超えた、本文が15%以上増えた、人が読んで「重い」と感じた、のどれかに当たったら、指摘ごとの修正をやめることにしました。全体を通して読み、必要なら書き直します。
- 作業ルールも、規則を足さずにまとめ直す。作業ルールのファイルに、失敗のたびに「〜のときは〜すること」を足していくと、ファイルそのものが同じように崩れます。新しい規則を足す前に、似た規則と一つにまとめられないか、効かなかった規則を消せないかを確かめます。たとえば、「図の文字は21px以上にする」「表は横にはみ出さないか確かめる」と規則が増えてきたら、「図や表は、スマートフォンの幅で読めるか確かめる」の一つにまとめる、といった具合です。
- 最後に通して読むのは人。点数は参考にとどめ、読者として読んで伝わるかを人が判断します。今回立て直せたのも、人が通して読んだからでした。
まとめ：コードは範囲を絞って直し、文章は全体を読み直す
AIにコードを直させるときは、複数の場所から使われている部分に注意し、そこを押さえて確かめる範囲を絞る。AIに文章を直させるときは、一か所を直すたびに、全体が目的を果たしているかを読み直す。プロンプトや作業ルール、仕様書を書く機会が増えた今こそ、この違いを意識しておく価値があります。
初めての作業で問題が出るのは、避けられません。私たちは、見つけた問題を振り返って、AIが次の作業で必ず読む作業ルールに書き残しています。これからは、規則を足すのではなく、まとめ直して書き残すことにしました。AIが作業をまたいで覚えていられるのは、書き残したものだけだからです。この記事も、その振り返りから生まれました。
参考資料
- Anthropic. Effective context engineering for AI agents（2025年9月29日）。AIが扱える情報の限りと、例外を書き並べるより典型的な例を選ぶ指示の書き方。
資料確認日：2026年10月17日