第4章チームに情報を渡す

第3章では、AIを使う前に境界を決め、使った後に検証結果を残すことを学んだ。第4章では、その情報をチームの人に渡す。

実務の開発は、一人で黙って正解へたどり着く作業ではない。分からないことを相談し、変更の背景を説明し、レビューを受け、指摘に返答する。そのたびに、文章が仕事の進み方を左右する。

文章が苦手だと感じる人の多くは、表現力で損をしているのではない。情報の順番で損をしている。相手が次に判断できる順番で、事実、推測、依頼を分けて渡せば、文章は仕事の道具になる。

この章でできるようになること

この章のゴールは、きれいな文章を書けるようになることではない。チームの相手が、再現、確認、判断、レビュー、次の対応を始められる情報を渡せるようになることである。

この章を読み終えたら、次のことができる状態を目指す。

技術相談で、状況、期待結果、実際の結果、確認したこと、判断してほしいことを分けて書ける。
観察、推測、依頼を混ぜずに書ける。
急ぎ度、期限、影響範囲を添えて、相手が優先度を判断できるようにする。
変更説明で、背景、変更内容、今回やらないこと、確認方法、リスク、レビューしてほしい点を書ける。
レビュー返信で、理解したこと、対応方針、追加確認、見送り理由を残せる。
AIを使って文章を整えた場合でも、実際に確認していないことを確認済みとして書かない。

この章の成果物は、technical-question.md、change-description.md、review-replies.md である。どれも提出用の作文ではなく、後のPR、レビュー、デバッグ、メンター相談にそのまま使うための作業メモである。

チームに渡す文章は、相手の次の行動を決める

支援ステータス機能を進めている途中で、あなたが次のような状況になったとする。

AIにステータス名の候補を出してもらった。候補には「緊急」「注意」「順調」が含まれていた。しかし、この表現がメンターにとって分かりやすいのか、受講者に見える可能性がある場合に強すぎないか、自分だけでは判断しきれない。

このとき、ただ「ステータス名どう思いますか」と聞くと、相手は背景から確認しなければならない。一方で、次のように渡せば、相手は判断に入りやすい。

状況: 支援ステータス機能の初回MVPで、担当受講者一覧にステータスを表示しようとしています。

期待していること: メンターが支援の必要な受講者を早く見つけられることです。

迷っていること: AIが「緊急」「注意」「順調」という候補を出しましたが、表現が強すぎないか判断したいです。

確認したこと: 初回MVPでは通知や履歴は対象外です。一覧上で支援対象を見つけられるかを確認したいです。

判断してほしいこと: この3つの状態名でメンターが同じ意味に解釈できるか、よりよい表現があるかを見てほしいです。

同じ内容でも、情報の並べ方で相談の質は変わる。チームに渡す文章は、読む人の次の行動を設計するものだと考える。

誰に、何をしてほしいかを先に決める

同じ情報でも、読む相手によって必要な形は変わる。メンターに相談する文、レビュー担当者に差分を見てもらう文、後から自分が読み返すメモは、目的が違う。

書き始める前に、まず読者と次の行動を決める。

読む人	次にしてほしいこと	入れるべき情報
メンター、先輩	調査方針や設計判断を助ける	期待結果、実際の結果、確認したこと、判断してほしいこと
レビュー担当者	差分を読んでリスクを見つける	背景、変更内容、確認方法、レビューしてほしい点
依頼者、運営	範囲や見送りを確認する	目的、今回やること、今回やらないこと、残るリスク
未来の自分	判断の経緯を思い出す	採用した案、見送った案、未確認事項、次のアクション

「誰かに伝わればよい」では範囲が広すぎる。誰に、何をしてほしいのかを先に決めると、文章に入れる情報と省く情報を選びやすくなる。

観察、推測、依頼を分ける

技術相談では、観察、推測、依頼を分ける必要がある。

観察：実際に見たこと、実行したこと、起きた結果。
推測：観察から考えている原因や可能性。
依頼：相手に判断してほしいこと、確認してほしいこと。

この三つが混ざると、相談を受けた人はどこを信じてよいのか分からなくなる。たとえば「APIが壊れている気がします」とだけ書かれても、それが画面の表示なのか、Networkタブの結果なのか、サーバーログなのか、推測なのかが分からない。

支援ステータス機能で保存に失敗した場合なら、次のように分ける。

観察: 支援ステータスを変更して保存ボタンを押すと、画面には「保存に失敗しました」と表示されます。 Networkタブでは PATCH /support-status が 403 を返しています。自分のアカウントは対象受講者の担当メンターではない可能性があります。

推測: API側の認可チェックで拒否されている可能性があります。

依頼: この場合、画面では権限エラーとして表示すべきか、担当外の受講者を一覧に出さない設計にすべきか、判断を相談したいです。

ここまで分かれていれば、相手はAPIの認可を見るべきか、画面のエラー表示を見るべきか、仕様を確認すべきかを判断しやすい。まだ確認していないことは、確認済みのように書かない。「サーバー側は未確認」「テストはまだ実行していない」「権限仕様はメンター確認待ち」のように書けば、相手は残りの作業を見積もりやすい。

技術相談文を書く

技術相談文は、長く書けばよいわけではない。相手が再現、確認、判断を始められるだけの情報を、短く並べる。

基本の型は次である。

何をしようとしているか。
期待結果。
実際の結果。
確認したこと。
自分の仮説。
判断してほしいこと。
期限や影響範囲。

急ぎ度や影響範囲は、遠慮して省かない。相手がすぐ見るべきか、明日でよいかを判断する材料になる。

たとえば、次のように書ける。

急ぎ度:
今日中に方針だけ決めたいです。実装は明日以降で問題ありません。

影響範囲:
メンター向け進捗一覧だけです。受講者側の画面には影響しない想定です。

止まっていること:
未提出者フィルタを画面側で続けるか、API側へ寄せるかを判断できず、次の実装に進めていません。

悪い相談文は、たいてい焦りだけが伝わる。

悪い例: 支援ステータスが保存できません。たぶんAPIがおかしいです。見てもらえますか。

この文章では、何をしたのか、何が返ったのか、どこまで確認したのか、相手に何を判断してほしいのかが分からない。

良い相談文は、相手が次に開くべき場所を想像できる。

良い例: 担当受講者一覧で支援ステータスを変更し、保存ボタンを押しました。期待結果は、ステータスが保存され、一覧上の表示が更新されることです。実際には、画面に「保存に失敗しました」と表示されました。 Networkタブでは PATCH /support-status が 403 を返しています。同じ操作を担当受講者で試すと 200 になります。担当外アクセスを拒否する認可は正しそうですが、画面のエラー文を権限エラーとして出すべきか判断したいです。

この例では、相手はAPIが完全に壊れているのではなく、認可と画面表示の判断が相談対象だと分かる。

未提出者フィルタの相談なら、次のように書ける。

状況:
メンター向け進捗一覧で、未提出者だけを表示するフィルタを実装しています。

期待結果:
submittedAt が null の受講者だけが表示されることです。

実際の結果:
フィルタを有効にしても、submittedAt が入っている提出済み受講者が一覧に残ります。

確認したこと:
- テストデータには、submittedAt が null の受講者と日時が入っている受講者が混在しています。
- 画面側のフィルタ条件は確認しましたが、API側で絞るべきかはまだ判断できていません。
- メンター以外は進捗一覧を見られない必要があります。

判断してほしいこと:
未提出者フィルタを画面側で続けてよいか、権限チェックも考えてAPI側で処理すべきかを相談したいです。

変更説明は、差分の案内である

コードを変更したあと、変更説明を書く。変更説明は、ファイル名の一覧ではない。レビューする人が、どの背景で、何を、どの順番で見ればよいかを知るための案内である。

支援ステータス機能の初回MVPなら、変更説明は次のように書ける。

背景: メンターが担当受講者一覧で支援が必要な受講者を見つけやすくするため、一覧に支援ステータスを表示します。

変更内容: 担当受講者一覧のレスポンスに supportStatus を追加しました。フロントエンドでは、支援ステータスを一覧上に表示し、状態の意味を補足テキストで示します。

今回やらないこと: ステータス更新、通知、CSV出力、更新履歴の詳細表示は初回MVPに含めません。

確認方法: 担当受講者一覧を開き、各行に支援ステータスが表示されることを確認しました。ステータスが未設定の受講者では「未設定」と表示されることを確認しました。

リスク: ステータス名の表現がメンター間で同じ意味に解釈されるかは、運用確認が必要です。

レビューしてほしい点: 初回MVPとして範囲が大きすぎないか。支援ステータスの表示文言がメンターに伝わるか。権限まわりの確認観点が不足していないか。

AIを使った場合の検証: AIにはステータス名と確認観点の候補出しを依頼しました。採用した提案はDecision Memoと照合し、通知とCSV出力は初回範囲外として見送りました。実行結果やテスト結果はAIの出力ではなく、自分で確認したものだけを書いています。

この説明があると、レビュー担当者は差分を読む前に、何を守る変更なのかを理解できる。背景を読めば第2章の価値に戻れる。今回やらないことを読めば、MVPの範囲が分かる。確認方法を読めば、レビュー時に何を再確認すべきかが分かる。レビューしてほしい点があれば、レビュアーは限られた時間をどこに使うべきか判断しやすくなる。

レビュー返信は、共同作業の記録である

レビューコメントへの返信は、反論でも謝罪文でもない。指摘をどう理解し、どう対応し、どこで確認したかを残す共同作業の記録である。

たとえば、レビューで次のように指摘されたとする。

「ステータスが未設定の場合、空欄だと読み手がデータ欠損なのか未設定なのか分からないので、表示を分けた方がよさそうです。」

弱い返信は、次のようなものだ。

「修正しました。」

これでは、何をどう直したのか、確認したのかが分からない。

良い返信は、次のように書く。

「未設定の場合は空欄ではなく『未設定』と表示するように変更しました。担当受講者一覧で、ステータスあり、未設定の両方を確認しています。スクリーンショットもPR本文に追加しました。」

この返信なら、指摘の理解、対応内容、確認方法が分かる。レビューは、指摘を受けて終わりではない。対応の結果をチームに戻して、変更の意味を共有するところまでが仕事である。

レビューコメントは、修正、質問、見送りに分けて返すと整理しやすい。

修正する場合:

理解しました。未提出者フィルタは権限チェックとも関係するため、画面側ではなくAPI側で処理する方針にします。
API側で submittedAt が null の受講者だけを返すように変更し、担当メンター以外から見えないことも確認します。
テストには、提出済み、未提出、担当外受講者のケースを追加します。

質問する場合:

困っていることの表示範囲がリスクになる点を理解しました。
実装を進める前に、メンターだけに表示してよい情報の範囲を運営に確認します。
確認が取れるまでは、困っていることの本文表示は入れず、提出状況と最終ログ日時だけで進めます。

見送る場合:

CSV出力が便利という点は理解しました。
ただ、第2章のDecision Memoでは、初回は詰まっている受講者に早く気づける一覧に絞る方針にしています。
CSVは誰が何に使うかがまだ不明なため、初回では見送り、一覧利用後に週次報告で必要かを再検討します。

見送る返信でも、相手の提案を否定する必要はない。判断の根拠、再検討条件、次に見るタイミングを書けば、議論を閉じずに前へ進められる。

AI時代でも、相手は人である

第3章で作ったAI利用計画やAI利用ログも、最終的には人に読まれる。 AIが出した候補を採用したのか、見送ったのか、どう確認したのかを、人が理解できる形にする必要がある。

AIにうまく依頼できる人ほど、チームへの相談もうまくなる。どちらも、目的、文脈、制約、期待する出力を整理して渡す作業だからである。

ただし、AIと人には違いもある。人には、チームの状況、過去の判断、運用上の事情、暗黙の制約がある。だから人への相談では、判断してほしいことを明確にし、相手が持っている文脈を引き出せるように書く。

AIで文章を整えた場合も、事実確認は人が行う。 AIが「テストを実行しました」「ログを確認しました」のように書いても、実際に自分が実行していないなら消す。 AIに作らせた文章は、語調より先に、事実、未確認事項、検証結果、秘密情報の有無を確認する。

チーム共有で起きやすい誤解

長いログを貼れば、相談として十分だと思う。
推測を事実のように書く。
変更内容だけを書き、変更の背景を書かない。
レビューしてほしい点を書かず、相手に全部を同じ重さで見てもらおうとする。
レビュー返信を「修正しました」だけで終える。
見送る判断を書くと失礼だと思い、理由や再検討条件を書かない。
期限、影響範囲、判断してほしいことを書かない。
AIが整えた文章に、実行していないテストや確認していないログが混ざっている。

相談文と変更説明で確認すること

technical-question.md、change-description.md、review-replies.md を作り、チームに渡せる文章へ変換する。

technical-question.mdでは、状況、期待結果、実際の結果、確認したこと、仮説、判断してほしいことを書く。急ぎ度、期限、影響範囲がある場合は、補足に入れる。 change-description.mdでは、背景、変更内容、今回やらないこと、確認方法、リスク、レビューしてほしい点、AIを使った場合の検証を書く。 review-replies.mdでは、指摘の理解、対応内容、確認方法、質問事項、未対応の場合の理由と再検討条件を書く。

文章を整えることだけを目標にしない。相手が次に何を見ればよいか、何を判断すればよいかが分かる文章にする。

チームに情報を渡す章で持ち帰ること

第4章で身につけるべきことは、チームに渡す情報を、相手の次の行動に合わせて並べることである。観察、推測、依頼を分ける。変更の背景、範囲、確認方法を説明する。レビュー返信では、修正する、質問する、見送るを分け、対応内容と確認結果を残す。 AIを使って文章を作った場合も、事実と検証結果は自分で確認する。

この力は、第5章以降で何度も使う。手元の環境で何が起きたのかを相談するとき、GitHubでPull Requestを出すとき、デバッグ結果を共有するとき、すべてこの章の延長にある。

手元で動かす作業場の章へ

次章では、相談やレビューの前提になる、手元で動かす作業場を整える。自分の環境で何を実行し、何が起き、どのログを見たのかを説明できることが、チームへの相談の質を上げる。

第4章 チームに情報を渡す