← パースペクティブに戻る
/Intellicon FDE Team

AI が書くコード変更の説明は、人が選んだ要点を先に、詳細はその後に

問題、解決策、検証が一度に詰め込まれていると、読み手は下まで読まなければ変更の目的がわかりません。文書を渡す担当者が冒頭に載せる要点を選び、その後に詳しい説明を残す。使いやすさを確認したら、構成のルールをスキルにまとめましょう。

AIEgentWrX人機協作
AI が書くコード変更の説明は、人が選んだ要点を先に、詳細はその後に

同僚から、AI Agent がまとめたコード変更の説明が届きました。問題の背景、変更方法、検証手順は詳しく書かれているのに、自分が何を確認すべきかは、下まで探さなければわかりません。チームでもこうした文書を読みにくいと感じているなら、すぐに AI に全文を短くするよう求めるのは待ちましょう。内容を精査する人には詳細が必要ですが、自分の業務にどのような影響があるかだけを知りたい人には、冒頭で自分に関係する情報が伝わる必要があります。

Intellicon Solutions が勧めるのは、文書を渡す担当者が、読み手にとって最も重要な要点を選んで冒頭に置く方法です。なぜ読む必要があるのか、読んだ後に何をすべきかを同僚に伝え、その後に詳しい説明を残します。チームでこの書き方が実際に役立つと確認できたら、文書作成の共通ルールにしましょう。長文ができあがるたびに、削ったり書き直したりする必要がなくなります。

説明は十分なのに、なぜ読む気になれないのか?

Simon Willison は最近の記事で、同じような悩みを取り上げています。彼はプルリクエスト(pull request、PR)を使ってコードの変更を整理し、判断の経緯を記録して、完成した成果をマージしています。しかし、AI Agent が問題、解決策、検証を正確かつ十分に記述していても、最後まで読む気にはなれないといいます。そこで、自分で要点を選んで冒頭に置き、詳しい説明はクリックして展開できるブロックに収めています。冒頭には AI が書いた文章をそのまま使うこともありますが、どの内容が読み手の時間を割くに値するかは、まず本人が判断します。

これは彼個人の編集上の工夫であり、元の記事には読了時間やチームの成果を比較したデータはありません。企業が参考にできるのは、情報をどの順番で伝えるかという考え方です。文書を送る前に、受け手がその文書を何に使うのかを明確にし、どの情報を先に示すかを決めましょう。冒頭から作業の経緯をすべて説明する必要はありません。

たとえば、購買の相見積もりを比較する文書で考えてみましょう。上司に特定の取引先を採用するかどうか判断してもらうための文書なら、冒頭には、どの取引先を推奨するのか、まだ確認が必要な条件は何かを明記します。見積もりの明細、比較方法、やり取りの記録は後に続ければよいでしょう。ただし、納期が未確認で、それが上司の判断に影響するなら、要約を短くするために最後へ回してはいけません。これは文書の構成を説明するための例であり、実際の顧客事例ではありません。まずはチームの既存の文書で構成を変えてみて、読み手が後半まで読まなくても、自分が何を判断すべきかわかるかを確かめてください。

冒頭で文書の目的、業務への影響、読み手に求める対応を明確にする

まずは、コード変更の説明など、チームが日常的に作成・共有する文書を一種類選び、共通の形式を決めることを勧めます。単に AI に「もっと簡潔に」と指示するよりも、冒頭で答えるべき問いを明示したほうが、文書を渡す担当者もそれに沿って内容を確認できます。

  • どの問題を解決するのか:利用者がこれまで何に困っていて、今回の変更によって何ができるようになるのかを明確にします。変更したコードを列挙するだけでは不十分です。
  • どの利用者に影響するのか:誰の操作方法が変わるのかを説明します。まだ対応できていないケースがあれば、それも併記し、すべての問題が解決したと読み手に誤解させないようにします。
  • 読み手は次に何をすべきか:確認、テスト、承認が必要な事項を明記します。情報共有だけが目的なら、その旨をはっきり伝え、同僚に推測させないようにします。

詳しい解決策、検証手順、制約は後半に残し、精査が必要な人が読み進められるようにします。何を冒頭に置くかは、読み手の判断に影響するかどうかで決めます。制約が生じる詳しい理由は後で説明できますが、その制約が実施への同意を左右するなら、冒頭で知らせるべきです。同様に、上司の承認が必要な文書なら、要約にも承認待ちであることを明記し、AI Agent の提案を実施が決定した事項のように書いてはいけません。

見せ方は、チームが使っているツールに合わせられます。元の記事では、GitHub の Issue コメントや PR の説明に <details><summary> タグを使うことで、読み手が必要に応じて全文を展開できると紹介されています。他のコラボレーションシステムを使っている場合は、まず対応しているかを確認し、非対応なら要約と詳細説明に分ければ十分です。送信前には冒頭だけを読み、受け手がこの文書と自分の関係、そして次に必要な対応を理解できるかを確認してください。

試して役立った書き方をスキルにし、冒頭の要点は引き続き人が決める

同僚に試し読みをしてもらい、使いやすい形式だと確認できたら、対象となる文書の種類、要約で答えるべき問い、詳細情報の構成方法をスキル(AI Skill)にまとめましょう。以後、AI Agent が同じ方法とルールに沿って文書を作成できるようになります。形式だけでなく、適切な例も添えて、どの情報を冒頭に残す必要があり、なぜ省略できないのかを説明します。空欄だけを AI に渡し、何を記入すべきかを推測させることは避けましょう。

EgentWrX では、利用者が自分でスキルを作成することも、AI に下書きを生成してもらうこともできます。AI Agent は適切な場面でこれらのスキルを使用でき、利用者が会話の中で指定することも可能です。同僚が作成したスキルを全社で利用するには、管理画面での審査・承認が必要です。ここで整えるのは文書作成のルールであり、個々の文書で何を要点とするかは、その業務に詳しく、文書を渡す責任を持つ人が引き続き判断すべきです。

文書を送る前に、担当者がまず要約と後半の詳細説明に食い違いがないかを確認し、重要な影響、未確認の条件、取得すべき承認が抜けていないかを点検することを勧めます。要約を一字一句書き直す必要はなく、AI の下書きから適切な部分を選んで、そのまま使ってもかまいません。ただし、選んだ人は、なぜその情報を受け手に最初に見てもらう必要があるのかを説明できることが大切です。

次に作る文書で、さっそく試してみましょう。実際の受け手に冒頭だけを読んでもらい、何のための文書なのか、次に何をすべきなのかを、自分の言葉で説明してもらいます。重要な制約に気づいていなければ、まず要約に明確に書かれているかを確認し、スキルのルールや例を調整してください。文字数の上限を下げるだけでは、同僚が読み終えても何をすべきかわからない状態は解消しません。

よくある質問

AI が書いた業務説明が長すぎる場合、詳細をすべて削除すべきですか?

いいえ。まず冒頭の要点と詳細説明を分け、そのうえで本当に重複している内容を削ることを勧めます。解決策、検証手順、制約が同僚の精査に必要な情報であれば、残すべきです。ただし、承認の可否に影響する条件は要約に明記し、文章を短くするために後回しにしてはいけません。

冒頭の要約に、AI が書いた文章をそのまま使えますか?

はい。ただし、文書を渡す担当者が、内容が正確で、受け手の必要としている情報に合っているかを先に確認してください。人が選ぶからといって、すべての言葉を書き直す必要はありません。要約と詳細説明の整合性を確認し、未確認の事項を決定済みと書いたり、必要な承認を記載し忘れたりしないようにしましょう。

社内のコラボレーションシステムに折りたたみ機能がなくても、この書き方を使えますか?

はい。要約と詳細説明を明確に分ければ十分で、折りたたみ機能のためにシステムを変える必要はありません。まず文書の目的、業務への影響、次に必要な対応を受け手に伝え、その後に精査のための詳細を示します。展開できるブロックを使いたい場合は、文書の共有に使うツールが対応しているかを確認し、受け手にどう表示されるかをプレビューしてください。

参考資料

30 分で、AI に先に任せられる業務を一緒に洗い出します

社員一人ひとりに AI の分身を持たせませんか。

コンサルタントより速やかにご連絡いたします。

ISO/IEC 27001:2022 情報セキュリティ認証