入社2週間、AIに"問い詰めて"コードベースをキャッチアップしてみた | スパイダープラス Tech Blog

こんにちは。今月スパイダープラスに入社したエンジニアの熊瀬川です。

入社して最初の仕事は、配属されたプロジェクトのコードベースのキャッチアップでした。従来であれば「ドキュメントを読んで、分からないところを先輩に質問する」のが定番ですが、いまは手元にコードベースを丸ごと読めるAIエージェント（私の場合は Claude Code）があります。

先輩の時間をなるべく奪わずに、AIにどこまで「問い詰めて」キャッチアップできるのか。この記事は、入社1ヶ月の私が実際に試してみた正直な記録です。うまくいったことだけでなく、うまくいかなかったこと、そして「やっぱり人との時間が効いた」という話も書きます。

最初にやったこと: ドキュメントを読む前に「説明させる」

リポジトリをクローンしてまずやったのは、ドキュメントを自分で読むことではなく、Claude Code にこう投げることでした。

このプロジェクトに入ったばかりの新人です。
このプロジェクトに関してドキュメントがたくさんあるので、
まずはそれを読んでこのプロジェクトに関して説明してください。
私が把握しているドキュメントはREADMEとREADMEからの参照先で
ルートリポジトリにいくつかあるのと、あとはdocs/ディレクトリです。
どのように理解・キャッチアップしていくのが良いかも提案してください

数分待つと、返ってきたのは以下のようなものでした。

プロジェクトが「何のために存在するか」の全体像（システム構成図つき）
アーキテクチャの背骨（レイヤー構成と依存方向のルール）
ドキュメントの「地図」 — どこに何が書いてあって、どれが一番重要か
ステップ式のキャッチアップ計画（まず環境を動かす → 思想を掴む → コードを縦に1本読む → 一番難しい領域に腰を据える）

自分で全ドキュメントを読んで同じ地図を作ろうとしたら、数日はかかっていたと思います。

効いたこと

1. 「ドキュメントの地図」が先に手に入る

個人的に一番大きかったのはこれです。新しいプロジェクトに入ったとき、つらいのは「どれを・どの順で・どこまで読めばいいか分からない」ことだと思います。

最初に地図と全体量が手に入ると、「今週中にここまで理解する」という目標と期日を立てられます。キャッチアップが「霧の中を歩く」から「地図を持って歩く」に変わる感覚がありました。

2. プロジェクト固有の「用語の罠」を即答してくれる

歴史のあるプロジェクトには、同じ概念が文脈によって違う名前で呼ばれている、という罠がよくあります。私のプロジェクトにもまさにそれがあり、業務用語・レガシーDB上の名前・新APIでの名前がそれぞれ違う概念がありました。

これを Claude Code に聞くと、業務としての意味と、システム上の表現の2面から説明してくれて、さらに「なぜズレているのか」の歴史的経緯まで、ドキュメントの記述を根拠に教えてくれました。

この手の知識は、先輩に聞くには細かすぎる気がして遠慮しがちで、かといって検索でも辿り着きにくい。新規参画者にとってAIが一番ありがたい領域のひとつだと感じます。

3. 「コードで裏を取って」と言える

ドキュメントに書いていない実装詳細について質問したとき、印象的だったのは「コードを見ないと正確に答えられない質問なので、実装を確認します」と言って、その場でコードを読んで証拠つきで答えてくれたことです。

また、設計ドキュメントの記述が現状のコードより古くなっている箇所を、「ドキュメントにはこう書いてあるが、実際のコードはここまで進んでいる」と教えてくれたこともありました。

人間の先輩でも記憶が古いことはあります。「いま現在のコード」を Source of Truth として答えてくれるのは、AIならではの価値だと思いました。

効かなかったこと・注意点

1. 核心のドキュメントは、直接読んだ方が分かりやすかった

意外だったのがこれです。プロジェクトで一番難しく一番重要な設計ドキュメントについて、Claude Code に説明してもらったのですが、原文を直接読んだ方が分かりやすかったのです。

なぜだろうと考えてみると、思い当たることが2つありました。

原文の1行目に書いてある「システムの大前提」が、会話の中ではすでに説明済みとして省略されていた。しかし核心部の理解には、その大前提を何度でも踏み直すことが必要だった
分かりやすくしようと気の利いた喩えを挟んでくれるのが、正確に理解したい場面では逆にノイズになった

ここから得た私なりの使い分けの指針はこうです。

構成把握・地図づくり・用語解説はAI経由。設計思想（Why）の核心は原文を直読。

そもそも、それぞれのドキュメントは結局直に読んだ方がいいと思っています。要約では何が省略されているか分からないからです。AIの説明は「読む前の地図」と「読んだ後の答え合わせ」に使うのが、私にはしっくりきました。

2. 際限なく質問できてしまい、時間が溶ける

AIは何を聞いても嫌な顔ひとつせず答えてくれます。これは罠でもあって、細部への好奇心のままに質問し続けると、気づいたら時間が溶けています。先輩相手なら「こんなに時間をもらえない」というブレーキが自然にかかりますが、AIにはそれがありません。

私がやった対策は次の3つです。

キャッチアップの目的を「全体像と、設計・仕様上ポイントとなる点の把握」に区切る
全体量を先に把握して、理解の目標と期日を決める
「質問や関心が細部に入り込みすぎていたら注意して」とAI自身にあらかじめ頼んでおく

それでも「人との時間」が効いた

ここまでAIの話を中心に書いてきましたが、振り返ってみると、理解と自信に一番つながったのは人とのやりとりでした。AI時代のオンボーディングを考えるうえで、ここは外せないと感じたので書いておきます。

上長との毎日30分の1on1

配属の翌週から、上長が毎日30分の1on1の時間を取ってくれました。業務手続きの質問からシステム面の疑問解消まで、口頭ベースでその場で解消できたのが本当にありがたかったです。

特に大きかったのは、ドキュメントを読んだだけでは誤解していたこと・腑に落ちていなかったことが、対話を通して解消できたことです。ドキュメントやAIに説明してもらうのと、人に聞いて「そういうことか」となるのとでは、納得の深さが違いました。

これは自分からお願いしたわけではなく、上長が設定してくれたものでした。もし受け入れ側にそういう習慣がない場合でも、15分でもいいので新規参画者の側からお願いする価値があると思います。

バグチケットをペアプロで対応する

キャッチアップがある程度進んだ頃、ちょうど良い粒度のバグチケットが発生し、それを割り当ててもらってペアプロで対応しました。実際の開発フローを最初から最後まで経験できたことは、コードリーディングだけでは得られない理解と自信につながりました。

印象的だったのは、開発フローが Claude Code のスキルとして整備されていても、人間の側も理解しながら進めることが前提になっていたことです。「現仕様を変えない」といった制約をその都度チェックしながら、ペアで実装方針を明確にしていく。AIに任せる部分と人間が押さえる部分の役割分担を、実際に手を動かしながら学べました。

なお、新規参画者にちょうど良いハンズオン的なチケットがあるかどうかはプロジェクトの状況次第なので、最初の入り方はチームによって違って当然だと思います。私の場合はタイミングに恵まれましたが、「実タスクを誰かと一緒にやる機会」を早めに作ってもらえるなら、それが一番効く、というのが実感です。