✍️ 필사 모드: 不慣れなコードベースに素早く適応する: 新しく入った人のスキル

「コードベースを理解する一番速い道は、上から読むことではない。それを動かし、1本の道を最後まで追うことだ。」

プロローグ — 私たちは繰り返し新しく入った人になる

「ramp-up(適応)」という言葉を聞くと、ジュニア開発者の初出社日を思い浮かべがちです。しかし現実は違います。キャリア全体を通して、私たちは繰り返し新しく入った人になります。

転職すれば新しい会社のコードベースの前に立ちます。チームを移れば、同じ会社なのに初めて見るサービスを担当します。誰かが退職して、5年もののペイメントシステムを引き継ぐこともあります。OSS に貢献しようと他人の repo を clone することもあります。社内で他チームのバグを直しに、1週間だけ入ることもあります。

これらすべての状況に共通点が1つあります。すでに存在する、自分が書いていない、頭の中に地図がないコードの前に立っている、ということです。

ここで重要な事実: 適応は才能ではありません。学べるスキルです。ある人は不慣れな repo で3日で最初の PR を出し、ある人は3週間経っても「まだ把握中」です。その差は頭の良し悪しではなく、方法を知っているかどうかです。

この記事はその方法についてです。チームやマネージャーの立場で「onboarding をどう設計するか」ではなく、**個人の立場で「自分はどう速く生産性を出すか」**についての実践ガイドです。両者は違います。onboarding の設計はチームの仕事ですが、適応は結局、自分がやることです。良い onboarding ドキュメントがなくても — たいていの場合ありません — 素早く適応するスキルは自分の手の中にあります。

この記事で扱う内容:

1章 · まず動かす

不慣れな repo を受け取ったとき、最初の本能はたいてい「コードを読もう」です。間違った本能です。一番レバレッジの大きい最初の一手は、ローカルで動くようにすることです。

1.1 動く環境は1週間分の読書に勝つ

コードだけ読むと、頭の中に静的な絵しかできません。しかし動く環境があれば、生きているシステムを手にできます。値を変えてみる、ログを足してみる、debugger を attach する、「これを消すとどうなる?」を実際に試せる。読むだけなら3日かかる理解が、動かせば1時間で終わることもあります。

そして環境を構築する過程そのものが学習です。build がどう回るか、どの service に依存するか、environment variable が何を on/off するか — README が教えてくれないことを手で学べます。

1.2 初日のゴールは「緑の画面」

初日のゴールを明確にしましょう。機能を理解することではなく、アプリが起動し、テストが通ることです。

git clone <repository-url>
cd project
# README の setup 手順をそのまま辿る
make setup        # または npm install / poetry install / ...
make dev          # アプリを立ち上げる
make test         # テストが回るか見る

この過程で詰まるのは普通です。詰まる地点こそが最初の発見です。欠けている environment variable、入らない依存、ドキュメントにない前提条件 — これらを記録しておきましょう。9章で扱いますが、これは後で onboarding ドキュメントを直す良い材料であり、同時に「このチームの setup がどれだけ手に馴染んでいるか」を示すシグナルです。

1.3 詰まったときの順序

4番が肝心です。CI 設定(.github/workflows/、.gitlab-ci.yml など)は、「このプロジェクトをクリーンな環境でどう build するか」の答案です。人の README は古びますが、CI は毎回実行されるので嘘をつきません。

初日に「緑の画面」を見れば、その日からすべての学習が実験になります。見られなければ、すべての学習が推測のまま残ります。

2章 · エントリーポイントを探す

環境が動いたら、次の問いは「このシステムはどこで始まるか」です。コードベースには必ず**エントリーポイント(entry point)**があります。そこを見つければ、残りはそこから枝分かれします。

2.1 エントリーポイントの種類

ほとんどの framework は、エントリーポイントがどこかが決まっています。package.json の scripts、Makefile の target、Procfile、Dockerfile の CMD — これらが「このプロジェクトが何で始まるか」を教えてくれます。

2.2 リクエストの一生

Web サービスなら、最初に描くべき絵は**リクエストの一生(request lifecycle)**です。1つの HTTP リクエストが入ってきて response が出ていくまで、どの段階を通るか。

リクエストの一生(典型的な Web バックエンド)

  HTTP リクエスト
     │
     ▼
  [Router]  ── URL を handler に対応づける
     │
     ▼
  [Middleware]  ── 認証、logging、parsing、rate limit
     │
     ▼
  [Handler / controller]  ── リクエストごとのエントリ関数
     │
     ▼
  [Service / domain 層]  ── ビジネスロジック
     │
     ▼
  [データアクセス層]  ── DB、cache、外部 API
     │
     ▼
  [Response シリアライズ]  ── 結果を JSON などに
     │
     ▼
  HTTP response

この絵はほぼすべての Web バックエンドに当てはまります。framework ごとに名前と境界が違うだけです。この絵を手に持って「各層はこの repo のどのディレクトリにあるか?」を埋めていけば、それがコードベース地図の骨格になります。

2.3 build もエントリーポイント

runtime のエントリーポイントと同じくらい重要なのが、build のエントリーポイントです。ソースから deploy 可能な成果物までどう行くか。build 設定ファイル(vite.config、webpack.config、tsconfig、Makefile)を一度ざっと見れば、「このコードが実際にどんな形で実行されるか」が見えます。transpile されるか、bundle されるか、どの環境を target にするか。

3章 · 詳細より形を先に読む

エントリーポイントを見つけたからといって、すぐ関数の中に潜ってはいけません。まず**形(shape)**を見ます。森を見てから木へ行くのです。

3.1 ディレクトリ構造 = チームのメンタルモデル

ディレクトリ構造は単なるフォルダ整理ではありません。このチームがシステムをどう切り分けて考えているかの化石です。

src/
  routes/        ← HTTP の境界(エントリーポイント)
  services/      ← ビジネスロジック
  models/        ← データの形
  lib/           ← 共用ユーティリティ
  jobs/          ← バックグラウンド処理
  config/        ← 設定

この構造1つだけで「このチームは層で考えている」とわかります。逆に features/checkout/、features/search/ のように機能ごとに分かれていれば「機能中心で考えている」になります。ディレクトリ構造を5分見ることが、ランダムなファイルを1時間読むことに勝ちます。

3.2 依存グラフ — 何が何に寄りかかるか

次に依存を見ます。2つの層があります。

• 外部依存: package.json、requirements.txt、go.mod — どの framework とライブラリの上に立っているか。馴染みのないものがあれば印をつけます。
• 内部依存: module 同士がどう import するか。どの module が「ハブ」か(多くの場所から import される)、どの module が「葉」か(誰も import しない)。

ハブ module はシステムの心臓です。そこから読むと、一度に一番多くの文脈を得られます。

3.3 データモデルが真実を語る

最後に、そして最も重要に — データモデルを見ます。schema 定義、ORM model、migration ファイル、型定義。

コードは嘘をつけます。コメントは古びます。しかしデータモデルはシステムが実際に何を扱っているかを示します。User、Order、Subscription のような中核 entity とその関係を把握すれば、ビジネスの半分を理解したことになります。コードがやることは結局、このデータを作り、読み、変え、消すことだからです。

形を先に読めば、後で詳細を読むとき「これがどこに属するか」がすぐわかります。形なしで詳細から読むと、すべてのファイルが宙に浮きます。

4章 · 1つの本物のリクエストを最後まで追う

形を見たら、次は1つの本物のリクエストを最後まで追います。これを垂直スライス(vertical slice)テクニックと呼びます。

4.1 垂直スライスとは

コードベース全体を水平に(層ごとに)全部読もうとしないでください。代わりに、**1つの機能を選び、それがシステムの全層を貫く道を追います。**一番上(リクエストの入口)から一番下(DB)まで、そして response まで戻ります。

例: 「ユーザがログインすると何が起きるか」

垂直スライス: ログインリクエスト

  POST /login                    ← routes/auth.ts で始まる
     │
     ▼
  authMiddleware を通過           ← middleware/ — これはスキップする経路だ
     │
     ▼
  loginHandler を呼ぶ             ← controllers/auth.ts
     │
     ▼
  AuthService.login()            ← services/auth.ts — 中核ロジックはここ
     │
     ├─▶ UserRepo.findByEmail()  ← db/users.ts — クエリはここ
     │
     ├─▶ password.verify()       ← lib/crypto.ts
     │
     └─▶ Session.create()        ← services/session.ts
     │
     ▼
  Set-Cookie + 200 response      ← シリアライズはどこで?

このスライス1本を追えば、routing・middleware・controller・service・repository・ユーティリティがどうつながるかを一度に体験できます。そしてこのパターンは他の機能にもほぼそのまま繰り返されます。1つを深く追うことが、10を浅くなぞることに勝ちます。

4.2 スライスを追うためのツール

• debugger の breakpoint をエントリーポイントに打ち、本物のリクエストを1回送ります。スタックを1段ずつ辿れば、呼び出し順がそのまま見えます。
• ログを追加: 各層に一時的なログを差し込んでリクエストを送ります。どの順で出るかが流れです。(終わったら消します。)
• 「定義へ移動」を連鎖的に: エントリ関数が呼ぶ関数へ、さらにその関数が呼ぶ関数へ、と jump し続けます。

4.3 良い最初のスライスを選ぶ

何でもいい機能を選ばず、シンプルだが代表性のあるものを選びましょう。ログイン、項目1つの取得、シンプルなフォーム送信 — システムの主要な層を全部通るが、edge case の少ないもの。「決済の精算」や「レポート生成」のような複雑なものは2番目、3番目に回します。

5章 · テストをドキュメントとして読む

テストは「合格/不合格」を確認するツールであるだけではありません。一番正直なドキュメントです。

5.1 テストがドキュメントである理由

• コメントは古びますが、テストは古びると赤くなります。CI が通る限り、テストは現在の挙動を正確に反映します。
• テストは「この関数をどう呼ぶか」の実使用の例です。入力の形、期待される出力、エラーケースが全部そこにあります。
• テスト名はしばしば意図を語ります。it("クーポンが期限切れなら割引を適用しない") — この1行がビジネスルールです。

5.2 テストを読む順序

1. テストファイルの一覧を見る
   → 「このシステムで何がテストする価値があるか」の地図

2. 中核 entity の単体テストを読む
   → User、Order などがどう動くよう意図されているか

3. 結合 / E2E テストを読む
   → 層同士がどう一緒に動くよう意図されているか
   → 4章の「垂直スライス」がコードで書かれていることが多い

4. テストの fixture / factory を見る
   → 有効なデータが実際にどんな形か

3番が特に良いです。よく書かれた結合テストは「この機能を使う正しい方法」をコードで示します。4章で手で追ったスライスがすでに結合テストとして書かれていれば、それは検証済みの地図です。

5.3 テストがなければ

テストが乏しい repo も多いです。その場合は2つやります。1つ目、あるテストはより貴重に読みます — 少ないほど、それが「チームが一番怖がっている部分」である確率が高いです。2つ目、7章で扱いますが、自分が最初のテストを追加することが良い最初の貢献になります。

6章 · ツールを使う

不慣れなコードベースで肉眼でファイルを漁るのは非効率です。ツールがあります。うまく使えば探索速度が1桁倍速くなります。

6.1 検索 — grep / ripgrep

文字列検索は一番基本で、一番強力です。

# 関数/シンボルが定義され使われるすべての場所
rg "createOrder"

# route がどこで登録されるか
rg "router\.(get|post|put|delete)"

# environment variable がどこで読まれるか
rg "process\.env\.|os\.environ"

# TODO/FIXME — チームが知りつつ先送りしたもの
rg "TODO|FIXME|HACK|XXX"

# 特定のエラーメッセージの出どころ
rg "User not found"

ripgrep は .gitignore を尊重し、速いです。「この文字列はどこから来るか?」という問いの90%は、rg 1行で答えが出ます。

6.2 定義へ移動 / 参照を探す / 呼び出し階層

IDE や LSP がくれる機能です。

特に**呼び出し階層(call hierarchy)**は、4章の垂直スライスを逆向きに辿るとき強力です。「この DB クエリ関数は結局どの HTTP endpoint から呼ばれるか?」を一度に見せてくれます。

6.3 git を考古学に

git history は**「このコードがなぜこうなったか」の記録**です。コードを読むのは現在を見ること、git を読むのは過去を見ることです。

# この行を最後に変えた commit とそのメッセージ
git blame path/to/file.ts

# このファイルの変更履歴
git log --oneline -- path/to/file.ts

# このファイルがなぜこうなったか、commit メッセージとともに
git log -p -- path/to/file.ts

# 特定の文字列が追加/削除された commit を探す
git log -S "featureFlag" --oneline

# この関数の変更履歴だけ
git log -L :functionName:path/to/file.ts

git blame で奇妙なコードの commit を見つけ、その commit メッセージや紐づいた PR/issue を読めば、「なぜこう書いたか」が出てきます。奇妙に見えるコードの半分は消えた文脈のせいです — 過去のバグ修正、外部 API の制約、急ぎの hotfix。git はその文脈を蘇らせてくれます。

コードは「何を」、git history は「なぜ」、テストは「どう使うべきか」を語ります。3つを一緒に読みましょう。

7章 · 小さな変更を早めにする

読むだけでは適応は終わりません。どこかの時点で自分で変更を加えてみる必要があります。それもできるだけ早く。

7.1 なぜ小さな変更が重要か

小さな変更1つを最後まで押し通せば、開発ループ全体が回るかを証明できます。コード修正 → ローカル確認 → テスト → commit → PR → review → CI → merge。このループが詰まりなく回るのを1度経験すれば、その次の本物の作業ははるかに怖くなくなります。

そして小さな変更は速くフィードバックをもらえます。reviewer が「うちのチームはこうしません」と言ってくれる機会を早めに作るのです。大きな機能を2週間作ってからそれを聞くより、typo 修正で聞くほうが100倍ましです。

7.2 良い最初の変更の候補

good first issue やそれに準ずるラベルがあれば、それから。なければ、1章で setup 中に見つけた問題(古い README の1行など)が完璧な最初の PR になります。

7.3 最初の PR で気にすること

• 小さく: reviewer が5分で全部読めるように。
• チームの規約に従う: 既存の commit メッセージ、既存の PR 説明、既存のコードスタイルを先に見て真似ます。
• 「なぜ」を書く: PR 説明に、何をなぜ変えたか1段落。
• CI を自分で確認: merge を待たず、CI が緑か自分が先に見ます。

最初の週に merge された小さな PR 1つは、読むだけの最初の週よりはるかに遠くへ連れて行ってくれます。

8章 · メンタルマップを描いて書き留める

ここまで集めたもの — エントリーポイント、形、スライス、テスト、git から掘った文脈 — を頭の中だけに置くと漏れます。外に出して書き留める必要があります。

8.1 自分だけのノート

大層である必要はありません。Markdown ファイル1つ、または wiki ページ1つで十分です。書くこと:

自分の適応ノート — <サービス名>

## 一行サマリ
このサービスは ___ をする。

## エントリーポイント
- runtime: src/main.ts
- build: vite.config.ts
- 主な route: src/routes/

## 中核データモデル
- User ─< Order ─< OrderItem
- Subscription (User と 1:1)

## 追ってみたスライス
- ログイン: routes/auth -> services/auth -> db/users
- (次: 注文作成)

## まだ知らないこと / 質問
- [ ] cache の無効化はどこで起きるか?
- [ ] `LEGACY_MODE` フラグは何のためか?
- [ ] なぜ決済は別 service に分かれているか?

## 混乱したこと(後の自分へ)
- `utils/` と `lib/` の違い: 合意されたルールなし、ただの歴史的経緯

8.2 ダイアグラム1つ

文章より絵が速いときがあります。大層な UML ではなく、箱と矢印のレベルで十分です。

メンタルマップ(不慣れなコードベース、1週目)

   ┌──────────┐     ┌──────────┐     ┌──────────┐
   │  routes/ │────▶│ services/│────▶│   db/    │
   │ (入口)   │     │ (ロジック)│     │ (永続化) │
   └──────────┘     └────┬─────┘     └──────────┘
                         │
                         ▼
                   ┌──────────┐     ┌──────────┐
                   │  jobs/   │     │ external │
                   │ (非同期) │────▶│   APIs   │
                   └──────────┘     └──────────┘

   ?  = まだ入っていない場所: jobs/ の内部、external の retry ロジック

この絵を描く行為そのものが学習です。描いていると「あれ、ここに矢印が描けない = ここをまだ知らない」が浮かび上がります。知らない場所に疑問符を打っておけば、それが次に読む場所のリストになります。

8.3 質問リストを生かしておく

「まだ知らないこと」リストは適応の中核ツールです。浮かぶたびに書き、答えを見つけたら消します。このリストが縮む速度が、適応の速度です。そしてこのリストは9章 — 人に聞くとき — の材料になります。

頭の中の地図は霧のように散ります。書き留めた地図は残り、次に入る人に引き継ぐこともできます。

9章 · 何を、誰に聞くか

適応は一人でやるものではありません。どこかの時点で人に聞く必要があります。しかし何を、誰に、どう聞くかが結果を分けます。

9.1 聞く前に: チャット履歴を先に読む

質問する前に、5分だけ投資しましょう。チームチャット(Slack など)、issue tracker、PR コメントを検索します。あなたの質問は新しいものではない確率が高いです。誰かがすでに聞き、誰かがすでに答えています。

• エラーメッセージ → チャットでそのまま検索
• 「なぜ X か」 → 関連 PR/issue で検索
• アーキテクチャの質問 → docs/、wiki、設計ドキュメントで検索

これを先にやれば、人のところへ行くとき「検索したけど見つからなくて」と言えます。その一言が信頼を作ります。

9.2 良い質問 vs 悪い質問

良い質問の共通点: **自分がどこまでやったかを示す。**これは相手の時間を節約すると同時に、答えをより正確にします。相手が「ああ、そこまで見たならこれだけ知ればいい」と精密に答えられるからです。

9.3 誰に聞くか

• setup / 環境の問題 → 最近合流した人。同じ苦労をついさっきしたので、記憶が新鮮です。
• 「なぜこうなったか」 → git blame が指す人、またはその領域の古い貢献者。
• アーキテクチャ / 全体像 → チームリードかシニア。ただし整理された質問をまとめて一度に。
• 詰まった作業 → mentor や buddy が指定されていればその人。なければ code reviewer。

同じ人に同じ種類の質問を繰り返さないでください。質問をまとめて、束ねて、整理された形で持っていくのが、相手の時間を尊重する方法です。

9.4 もらった答えを流さない

誰かが答えをくれたら、それを8章のノートに書きます。同じことを2度聞かないため、そして次に入る人に引き継ぐためです。さらに良いのは、その答えを README や wiki に PR で入れることです — 7章の「良い最初の変更」がもう1つできたわけです。

質問は弱点ではありません。準備のない質問が弱点です。5分検索し、どこまでやったか示し、もらった答えを記録すれば — 質問は一番速い学習ツールになります。

10章 · AI agent と一緒に適応する

2026年の適応には、もう1つツールが加わりました。AI コーディング agent です。うまく使えば強力で、誤って信じれば危険です。

10.1 agent が得意なこと

不慣れなコードベースで、AI agent は速いガイドツアーをくれます。

特に「説明して」と「追って」は agent の強みです。人が1時間かける探索を数分に縮めてくれます。

10.2 しかし — ツアーを盲信しない

問題は、agent の説明がもっともらしいが間違っている可能性があることです。agent は見たことのない部分を、一番もっともらしい default で埋めます — つまりハルシネーションします。そしてハルシネーションは、本物の説明と同じくらい自信ありげに聞こえます。

なので原則は1つです: agent のツアーは仮説として受け取り、コードで検証する。

agent と一緒に適応するループ

  1. agent に聞く
     「決済の流れを説明して」
        │
        ▼
  2. 答えを仮説として受け取る(事実として受け取らない)
        │
        ▼
  3. コードで検証する
     - agent が言ったファイルを自分で開く
     - agent が言った関数を rg で探す
     - 疑わしければ debugger / ログで確認
        │
        ▼
  4. 合っていればノートに書く / 間違っていれば再度聞く

10.3 検証可能な質問をする

agent に聞くとき、検証しやすい形で聞くのが良いです。

• 悪い: 「このシステムは安全?」(検証不可能、ハルシネーションのリスク大)
• 良い: 「createOrder を呼ぶすべての場所を、ファイルパスとともに列挙して」(rg で直接照合できる)
• 良い: 「このファイルで外部ネットワーク呼び出しをする行を指して」(その行を自分で開いて確認)

具体的で、位置を含み、照合可能な質問 — これが agent を安全に使う方法です。9章で人に良い質問をする原則とまったく同じです。

10.4 agent は人を置き換えない

agent はコードについての質問に強いです。しかしコードに書かれていない文脈 — 「なぜこの決定をしたか」のような — は知りません。消えた会議、組織の制約、未来の計画 — それは依然として人に聞く必要があります。agent は9章を置き換えるのではなく、9章へ持っていく質問をより鋭く研いでくれます。コードで答えられることは agent に、人だけが答えられることは人に。

agent は優れたツアーガイドです。しかしツアーガイドの言葉を書き取るだけの観光客は、道を覚えません。聞き、検証し、自分で歩きましょう。

エピローグ — 適応は繰り返されるスキルだ

不慣れなコードベースの前に立つことは、キャリアで一度起きる出来事ではありません。転職するとき、チームを移るとき、サービスを引き継ぐとき、OSS に貢献するとき — 繰り返し起きます。

だから適応は一度身につければ一生使うスキルです。そしてそのスキルの核心はシンプルです。上から全部読もうとしないこと。まず動かし、エントリーポイントを探し、形を見て、1本の道を最後まで追い、小さな変更でループを証明し、地図を書き留め、良い質問をし、AI はガイドとして使うが検証すること。素早く適応する人はより賢いのではなく、この順序を知っている人です。

素早い適応のチェックリスト

1. 動かした — ローカルでアプリが起動し、テストが通る
2. エントリーポイントを知っている — runtime・build のエントリーポイントがどこか知っている
3. 形を見た — ディレクトリ構造、依存、データモデルをざっと見た
4. スライスを追った — 本物のリクエスト1つを端から端まで追跡した
5. テストを読んだ — 中核の挙動をテストで確認した
6. ツールを使う — rg、定義へ移動、呼び出し階層、git blame が手に馴染んでいる
7. 小さな変更をした — 最初の PR が merge された(または review 中)
8. 地図を書いた — 自分だけのノートとダイアグラム、質問リストがある
9. うまく聞いた — 検索を先に、どこまでやったか示し、答えを記録した
10. AI を検証しながら使う — agent のツアーを仮説として受け取り、コードで確認する

避けるべきアンチパターン

• 読むだけ — 動かさずコードだけ読むと、学習が推測にとどまる
• 上から全部読む — 形なしでファイルをランダムに読むと、宙に浮く
• 水平に読む — 層を別々に読まず、1つのスライスを垂直に
• 一人で長く詰まる — タイムボックスを決め、超えたら整理された質問で聞く
• 準備なしに聞く — 検索もせず、どこまでやったかもなしに聞かない
• 変更を先送り — 「十分理解したら」を待たず、小さな変更を早めに
• AI ツアーを盲信 — agent のもっともらしい説明を事実として受け取らない
• 地図を頭の中だけに — 書き留めなければ散り、次の人に引き継げない

次回予告

次回は **「レガシーコードと共に生きる — 怖いコードを安全に変える方法」**です。今回が「不慣れなコードをどう理解するか」だったなら、次回は「理解したそのコードが怖くてテストもないとき、どう手を入れるか」です。characterization test、seam(継ぎ目)の見つけ方、小さな単位の安全な refactor、そしてレガシーに向き合う心構えを扱います。

どんな専門家も、かつてはそのコードベースの新しく入った人でした。差は適応にかかった時間であり、その時間は方法で縮みます。この記事の順序を一度体に染み込ませれば、次の不慣れな repo はより不慣れでなくなります。