引き継いだ大規模または未知の codebase を理解するために AI assistant をどう使いますか？

Question

Accepted Answer

AI は未知の code での **orientation** に優れています。ただし、system がたぶんどう動くかという generic な説明をさせるのではなく、**実際の file に grounded** させる必要があります。実 path を示し、説明する前に読むよう求めます。

## 広いところから具体へ進める strategy

- **high-level map と entry point を聞く** — 「request はどこから始まるか？主要 module は何でどう関係するか？」深掘り前に全体像を得ます。
- **1 つの feature を end-to-end に trace する** — 実 feature（例: user login）を選び、route から controller/service、database まで追わせます。abstract overview より trace が有効です。
- **module を 1 つずつ summarize する** — repo 全体ではなく「`src/billing/` は何を担当するか」。
- **不慣れな code を説明させる** — 複雑な function を貼り、何をなぜしているか line by line で聞きます。
- **dependency overview を作らせる** — 何が何を import し、どの module が central で、coupling がどこにあるか。

## grounded に保つ

```text
❌ UNGROUNDED: "How does authentication usually work in a Node app?"
   → generic textbook answer。THIS codebase と合わない可能性が高い

✅ GROUNDED: "Read src/auth/login.js and src/middleware/session.js.
             Trace what happens when POST /login is called, step by step,
             citing the functions involved."
   → AI は実際の file を読む必要がある → 説明が YOUR system に対応する
```

grounded version は AI に actual files を根拠にさせます。そのため、もっともらしい一般論を信じるのではなく、各 step を real files と照合できます。

## なぜ重要なのか

大きな codebase の引き継ぎは、主に **reading and mapping problem** です。ここで AI は加速します。module を summarize し、flow を trace し、cryptic function を数秒で説明できます。cold reading の数日を guided exploration に変えられます。risk は、ungrounded prompt が actual code に合わない confident generic answer を生むことです。すべての質問を**実 file path** に anchor し、trace を source と照合することで、AI の speed を hallucination なしに使えます。より速く正確な mental model を作れ、source と照合しているので信頼できます。