コードベースとドメイン知識を渡す

環境構築が終わり、最初のタスクも渡した。それでも新人が動けない時があります。

原因はたいてい、これです。

コードは読めるが、何のためのコードか分からない

言語もフレームワークも分かる。それでも 「この status が 3 になるのはどういう時か」は、コードを読んでも出てきません。 それは業務の知識であって、あなたの頭の中にしかないからです。

この章は、あなたの頭の中にあるものを、どう渡すかを扱います。

渡すものは3種類ある

多くのチームは1番目だけを渡して、2番目と3番目を 「やっていれば分かる」で済ませています。そこが立ち上がりの遅れの正体です。

コードベースの地図を渡す

30分のコードツアー

新人が入って最初の3日以内に、画面共有で一緒にコードを歩いてください。 資料は要りません。エディタとブラウザだけで構いません。

1. ユーザーが画面で操作する（実際にブラウザで見せる）
2. どのリクエストが飛ぶか（DevTools の Network を見せる）
3. どこで受けるか（ハンドラのコードを開く）
4. どこで業務ロジックが動くか
5. どのテーブルが更新されるか（実際にレコードを見せる）
6. ログとダッシュボードにどう現れるか

1つの機能を、端から端まで通すのが要点です。 浅くても構いません。全体像の骨格が入れば、 以降の細かい知識をそこにぶら下げられるようになります。

悪い: 構造 → 機能
良い: 実際の動き → その裏側 → 構造

図を1枚、正本として用意する

完璧な設計書は要りません。1枚のシステム構成図があるだけで違います。

[ブラウザ] ──→ [BFF] ──→ [注文サービス] ──→ [Spanner]
                  │              │
                  │              └──→ [在庫サービス]
                  └──→ [認証基盤]

そこに、次の情報を添えます。

□ 各サービスのリポジトリ URL
□ 各サービスの担当チーム / 聞くべき人
□ どのサービスが「触ってよい」もので、どれが「触ってはいけない」ものか
□ 本番の管理画面・ダッシュボード・ログの場所

「なぜこうなっているか」を先に言う

コードベースには必ず、説明が要る不自然な部分があります。

・移行途中で、新旧2つの実装が並存している
・特定の顧客のためだけの分岐がある
・一見無駄なリトライが、外部サービスの仕様のために必要
・命名規則が途中から変わっている

これを先に伝えないと、新人は3つの誤解をします。

1. 「このコードを書いた人は下手なのだろう」（信頼が下がる）
2. 「自分が直してあげよう」（消してはいけないものを消す）
3. 「自分の理解が足りないのだろう」（質問できなくなる）

「ここは移行途中で汚いです。触らないでください。
 PROJ-1234 で今年中に消す予定です」

この一言で、上の3つが全部防げます。

ドメイン知識を渡す

ここが本題です。最も価値があり、最も渡されていないものです。

用語集をチームで持つ

新人に「用語集を作れ」と言う前に、チームの正本を1つ作ってください。

「よくある例外」を教える

正常系はコードを読めば分かります。渡すべきは例外のほうです。

□ 月末だけ発生する処理
□ 特定の取引先だけの特別扱い
□ 手作業でカバーしている部分（Excel での突合、電話確認）
□ 過去に大きな障害を起こした箇所
□ 「ここを変えるときは必ず◯◯さんに確認」というポイント

特に「今も手でやっていること」は必ず伝えてください。 新人が善意で自動化した結果、業務が止まることがあります。

ドメインエキスパートに会わせる

エンジニアだけで完結させないでください。 業務側の人と、早い段階で話す機会を作ります。

□ 業務担当者との30分の顔合わせ（何をしている部署か、何に困っているか）
□ 実際の業務画面を見せてもらう
□ 問い合わせ対応の内容を1日分見る   ← ユーザーの現実が最も濃い

問い合わせ内容を読むのは、費用対効果が非常に高いです。 「ユーザーが何で困っているか」が、抽象的な仕様書より速く伝わります。

教える機会を仕組みにする

一度に全部は渡せません。継続的に渡る仕組みにします。

渡せているかを確認する

教えたつもりでも、伝わっているとは限りません。確認の方法があります。

説明させる

「今の機能、私が知らない人だと思って説明してみて」

説明できないことは、理解していません。 これは試験ではなく、どこが伝わっていないかを知るための道具です。

図を描かせる

「注文が確定するまでに、どのサービスを通るか描いてみて」

紙でもホワイトボードでも構いません。 抜けているところが、そのまま次に教えるべきことです。

質問の質を見る

質問しやすさを仕組みで作るでも触れましたが、質問の内容は理解度の指標になります。

「これはどう動きますか」          → まだ全体像が無い
「これは◯◯という理解で合ってますか」 → 仮説が立てられている
「なぜ◯◯ではなく△△なんですか」    → 設計の意図を問えている（十分育っている）

属人化した知識を、渡せる形にする

新人の受け入れは、チームの知識の棚卸しをする機会でもあります。

□ 説明のたびに口頭で補っている内容 → ドキュメントに書く
□ 1人しか知らない手順            → 手順書にして2人目に試させる
□ 「なぜこうなっているか」の説明   → ADR や README に残す

この章のまとめ

• 渡すものは技術・コードベース・ドメインの3種類。 自習できるのは1つ目だけで、残り2つは意図的に渡さないと渡らない
• 入って3日以内に、機能を1本、端から端まで通すコードツアーをする。 ディレクトリ構成の説明から始めない
• 雑でよいので構成図を1枚用意し、新人に更新させる
• 「なぜこうなっているか」を先に言う。 言わないと、新人は「下手な人が書いた」か「自分の理解不足」と誤解する
• 用語集をチームの正本として持つ。作ると定義の食い違いが表面化するが、それは成果
• 渡すべきは正常系ではなく例外。特に今も手作業でカバーしている部分
• 設計レビューへの同席、障害対応の見学、問い合わせ当番を仕組みにする
• 伝わったかは説明させる・図を描かせる・質問の質を見るで確認する
• 出てきた質問は、そのまま次の新人のためのドキュメントにする

□ ログがどこに出ているか分からない
□ sudo を付けていいのか判断できない
□ サービスが起動しない時に systemctl を知らない
□ ディスクが一杯、と言われても何を見ればいいか分からない

参考資料