Claude Code cho onboarding codebase: các prompt giúp lập bản đồ ứng dụng của bạn

Điều bạn đang cố gắng học (và những gì có thể chờ)

Đọc file một cách ngẫu nhiên cảm thấy chậm vì hầu hết codebase không được tổ chức như một câu chuyện. Bạn mở một thư mục, thấy mười cái tên có vẻ quan trọng, bấm vào một cái, và kết thúc ở helpers, configs và các trường hợp cạnh. Sau một giờ, bạn có nhiều chi tiết nhưng vẫn không thể giải thích cách app hoạt động.

Mục tiêu tốt hơn cho Claude Code trong quá trình onboarding là xây một bản đồ tinh thần đơn giản. Bản đồ đó nên trả lời ba câu hỏi:

• Các module chính là gì?
• Những luồng người dùng chính nào được kích hoạt?
• Khu vực rủi ro nào có thể làm production hỏng hoặc gây bug?

Onboarding đủ tốt trong 1–2 ngày không phải là "Tôi có thể giải thích mọi class." Nó gần hơn với điều này:

• Bạn có thể gọi tên 5–8 module quan trọng và mỗi module quản lý gì.
• Bạn có thể theo dõi 2–3 luồng người dùng thực tế end-to-end (từ UI hoặc entry API tới database và quay lại).
• Bạn biết các rủi ro hàng đầu (thanh toán, auth, ghi dữ liệu, job nền) và chúng nằm ở đâu.
• Bạn có thể thực hiện một thay đổi nhỏ an toàn vì biết cần test gì và hỏi ai.

Một số việc có thể chờ. Refactor sâu, hiểu hoàn hảo mọi abstraction, và đọc code cũ ít ai đụng hiếm khi đem lại giá trị nhanh nhất.

Hãy nghĩ onboarding như xây một bản đồ, không phải nhớ từng con phố. Prompt của bạn nên liên tục kéo bạn về: "Tôi đang ở đâu trong hệ thống, chuyện gì xảy ra tiếp theo, và ở đây có thể hỏng gì?" Khi đã có điều đó, chi tiết sẽ dễ học dần khi cần.

Công việc chuẩn bị: lấy context mà không làm quá tải

Trước khi bắt đầu hỏi, thu thập những thứ cơ bản bạn thường cần vào ngày đầu. Claude Code hoạt động tốt nhất khi nó có thể phản ứng với file thật, config thật, và hành vi thật bạn có thể tái tạo.

Bắt đầu với truy cập và một lần chạy được. Đảm bảo bạn có thể clone repo, cài dependency và chạy app (hoặc ít nhất một phần nhỏ) ở local. Nếu thiết lập local khó, xin quyền truy cập môi trường staging và nơi lưu logs, để bạn có thể xác minh code thực sự làm gì.

Tiếp theo, tìm các tài liệu "nguồn sự thật". Bạn tìm bất cứ thứ gì đội ngũ cập nhật khi mọi thứ thay đổi: README, ghi chú kiến trúc ngắn, thư mục ADR, runbook, hoặc note triển khai. Dù lộn xộn, chúng cho tên module và luồng, làm cho Q&A chính xác hơn.

Quyết định phạm vi sớm. Nhiều repo chứa nhiều app, service, và package chia sẻ. Chọn ranh giới như "chỉ API và worker billing" hoặc "chỉ web app và luồng auth của nó." Phạm vi rõ ràng ngăn những lạc hướng vô tận.

Ghi lại giả định bạn không muốn assistant đoán. Nghe có vẻ nhỏ, nhưng nó ngăn các mô hình tư duy sai lầm làm mất giờ sau này.

Dưới đây là checklist chuẩn bị đơn giản:

• Xác nhận quyền truy cập repo, quyền cần thiết, và cách chạy tests.
• Thu thập ghi chú cài môi trường (env vars, seeds, feature flags) và nơi xem logs và metrics.
• Xác định các file "sự thật hiện tại" (README, ghi chú kiến trúc, ADRs, runbooks).
• Định nghĩa rõ phạm vi nằm trong và nằm ngoài cho lần onboarding này.
• Đặt quy tắc an toàn: không dán secrets, API keys, token, dữ liệu khách hàng riêng tư, hoặc logs production có thông tin nhạy cảm.

Nếu thiếu thứ gì, ghi nó thành một câu hỏi cho đồng nghiệp. Đừng "vượt qua" thiếu context bằng đoán mò.

Bản đồ tinh thần: những gì cần nắm khi khám phá

Bản đồ tinh thần là một tập ghi chú nhỏ trả lời: các phần chính của app là gì, chúng giao tiếp với nhau ra sao, và điều gì có thể sai. Làm tốt, onboarding ít còn là lướt file và nhiều hơn là xây một bức tranh bạn có thể tái dùng.

Bắt đầu bằng việc định nghĩa đầu ra mong muốn. Bạn muốn một danh sách module mang tính thực tế, không hoàn hảo. Với mỗi module, ghi nó làm gì, ai sở hữu (team hoặc người nếu biết), và phụ thuộc chính của nó (module khác, service, database, API ngoài). Ghi luôn các entry point chính: route UI, endpoint API, job nền, và tác vụ theo lịch.

Tiếp theo, chọn vài hành trình người dùng quan trọng. Ba đến năm là đủ. Chọn luồng chạm đến tiền, quyền, hoặc thay đổi dữ liệu. Ví dụ: signup và xác thực email, tạo gói trả tiền hoặc mua hàng, một hành động admin thay đổi quyền truy cập người dùng, và một luồng dùng hàng ngày quan trọng mà phần lớn người dùng dựa vào.

Quyết định cách bạn gắn nhãn rủi ro trước khi bắt đầu thu thập ghi chú. Giữ các danh mục đơn giản để bạn có thể quét sau này. Một tập hữu ích là: security, data integrity, uptime, và cost. Khi gắn nhãn một thứ là rủi ro, thêm một câu giải thích lý do, cộng với điều gì sẽ chứng minh nó an toàn (một test, một log, một kiểm tra quyền).

Dùng một định dạng nhất quán để bạn có thể biến ghi chú thành doc onboarding mà không viết lại mọi thứ:

• Modules: mục đích, entry points, phụ thuộc, owner
• Key flows: trigger, các bước, dữ liệu ghi, điểm thất bại
• Data: bảng hoặc collection bị ảnh hưởng, trường quan trọng, ràng buộc
• Risks: danh mục, tác động xấu nhất, cách giám sát, cách rollback
• Open questions: những gì bạn vẫn chưa biết, hỏi ai

Ví dụ: nếu Checkout gọi Billing và ghi payments và invoices, dán nhãn là data integrity và cost. Rồi ghi nơi retry xảy ra và điều gì ngăn chặn charge đôi.

Các prompt Q&A theo bước để khám phá codebase

Khi vào một repo mới, bạn cần định hướng nhanh, không hiểu hoàn hảo. Những prompt dưới đây giúp bạn xây bản đồ tinh thần theo các bước nhỏ, an toàn.

Bắt đầu bằng việc đưa assistant cây thư mục repo (hoặc một phần dán) và yêu cầu một tour. Giữ mỗi vòng tập trung, rồi kết thúc bằng một câu hỏi bảo bạn đọc gì tiếp theo.

1) Repo tour
"Here is the top-level folder list: <paste>. Explain what each folder likely contains and which ones matter for core product behavior."

2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."

3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."

4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."

5) Flow trace
"Trace this flow end-to-end: <flow>. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."

6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."

Một ví dụ cụ thể: nếu bạn đang map "user signs up and creates their first project," yêu cầu API route handler, validation, DB write, và bất kỳ job async nào gửi email hoặc provision tài nguyên. Rồi chạy lại flow trace cho "user deletes project" để phát hiện khoảng trống cleanup.

Để câu trả lời dễ hành động, yêu cầu các artefact cụ thể, không chỉ tóm tắt:

• Đường dẫn file và tên hàm
• Giả định và những điều chưa biết được gọi rõ
• Phụ thuộc được diễn đạt như "Nếu tôi thay X, điều gì sẽ hỏng?"
• Một nhiệm vụ đọc nhỏ bạn có thể làm tiếp trong 10 phút

Cách lưu câu trả lời để chúng còn hữu dụng

Chiến thắng lớn nhất trong onboarding là biến các Q&A rời rạc thành ghi chú người khác có thể tái sử dụng. Nếu ghi chú chỉ có ý nghĩa với bạn, bạn sẽ lặp lại công việc sau này.

Một cấu trúc đơn giản tốt hơn những trang dài. Sau mỗi buổi khám phá, lưu câu trả lời vào năm artefact nhỏ (một file hoặc doc là được): một bảng module, một glossary, các luồng chính, các điều chưa biết, và một sổ đăng ký rủi ro.

Đây là template gọn bạn có thể dán vào ghi chú và điền dần:

Module table
- Module:
  Owns:
  Touches:
  Entry points:

Glossary
- Term:
  Meaning:
  Code name(s):

Key flow (name)
1.
2.
3.

Unknowns
- Question:
  Best person to ask:
  Where to look next:

Risk register
- Risk:
  Location:
  Why it matters:
  How to verify:

Giữ key flows ngắn có chủ đích. Ví dụ: 1) user signs in, 2) backend creates a session, 3) client loads the dashboard, 4) API fetches data, 5) UI renders and handles errors. Nếu bạn không thể nhét một flow vào năm bước, tách nó (login vs dashboard load).

Khi dùng Claude Code, thêm một dòng vào mỗi câu trả lời: "How would I test this?" Dòng đó biến ghi chú thụ động thành checklist bạn có thể chạy sau, nhất là khi unknowns và risks bắt đầu chồng chéo.

Nếu bạn xây trên một nền tảng vibe-coding như Koder.ai, kiểu ghi chép này cũng giúp bạn thấy chỗ các thay đổi sinh ra bởi generation có thể gây side-effect. Những module có nhiều touchpoint thường là nam châm thay đổi.

Tìm vùng rủi ro nhanh (không đọc mọi file)

Rủi ro trong codebase hiếm khi ngẫu nhiên. Nó tập trung nơi app quyết định ai bạn là, thay đổi dữ liệu, nói chuyện với hệ thống khác, hoặc chạy công việc nền. Bạn có thể tìm hầu hết bằng câu hỏi nhắm mục tiêu và vài tìm kiếm có trọng điểm.

Bắt đầu với identity. Hỏi nơi authentication xảy ra (login, session, token) và nơi quyết định authorization nằm (kiểm tra role, feature flag, rule ownership). Một cái bẫy phổ biến là checks rải rác ở UI, handler API và query DB mà không có một nguồn sự thật duy nhất.

Tiếp theo, map các đường ghi. Tìm endpoint hoặc hàm tạo, cập nhật, xóa bản ghi, cộng các migration thay đổi dữ liệu theo thời gian. Bao gồm job nền nữa. Nhiều bug bí ẩn tới từ worker async ghi giá trị bất ngờ lâu sau khi request kết thúc.

Những prompt giúp bộc lộ rủi ro nhanh:

• "List every place that enforces permissions for [resource X]. Which one is the final gate?"
• "Show the full path for writing [table/entity X]: API handler -> service -> DB call. Where are validations?"
• "What external integrations exist (payments, email, webhooks, third-party APIs)? Where are retries and timeouts set?"
• "Where can work run twice (queues, goroutines, cron)? What makes it idempotent?"
• "What can break silently, and how would we notice (logs, metrics, alerts, dashboards)?"

Rồi kiểm tra cấu hình và cách xử lý secrets. Tìm env var, file config runtime, và fallback mặc định. Defaults hữu ích, nhưng nguy hiểm khi che lấp misconfiguration (ví dụ dùng key dev ở production vì một giá trị bị thiếu).

Một ví dụ nhanh: trong backend Go với PostgreSQL, bạn có thể tìm một job "send email" retry khi thất bại. Nếu nó retry mà không có idempotency key, người dùng có thể nhận email trùng. Nếu failures chỉ log warning và không có alert, nó sẽ hỏng trong im lặng. Đó là vùng rủi ro cao cần ghi lại và test sớm.

Ví dụ walkthrough: map một luồng người dùng thực tế

Dùng một luồng thực tế để xây thread end-to-end đầu tiên trong hệ thống. Login là khởi đầu tốt vì nó chạm routing, validation, session/token, và đọc DB.

Kịch bản: một React web app gọi một API Go, và API đọc/ghi PostgreSQL. Mục tiêu của bạn không phải hiểu mọi file. Mà là trả lời: "Khi user click Login, code nào chạy tiếp theo, dữ liệu nào di chuyển, và có gì có thể hỏng?" Đây là cách onboarding giữ cụ thể.

Map luồng từ browser tới database

Bắt đầu ở UI và bước tới trước, từng hop một. Hỏi tên file cụ thể, hàm, và shape request/response.

• "Find the React route or page for the login screen. What component renders it, and what action fires on submit?"
• "Where is the API client call made (fetch/axios/etc.)? What exact URL path, method, headers, and body does it send?"
• "On the Go side, where is the handler for that path registered? Show the router setup and the handler function."
• "Inside the handler, where does input validation happen (frontend, backend, both)? What rules exist, and where do errors get formatted?"
• "What database query runs for login? Point to the repository/SQL file, list touched tables/columns, and note any transactions or locks."

Sau mỗi câu trả lời, viết một dòng ngắn vào bản đồ tinh thần: "UI component -> API endpoint -> handler -> service -> DB query -> response." Bao gồm tên, không chỉ "một hàm nào đó."

Xác nhận bằng một lần chạy nhanh

Khi đã có đường đi, xác minh bằng một test nhỏ. Bạn kiểm tra đường code bạn map có thực sự được app dùng.

Quan sát request network trong dev tools (path, status code, response body). Thêm hoặc bật logs server quanh handler và DB call (nếu có request ID). Query PostgreSQL để kiểm tra thay đổi mong đợi (với login có thể là last_login_at, sessions, hoặc audit rows). Ép một thất bại (mật khẩu sai, thiếu field) và ghi nơi thông báo lỗi được tạo và hiển thị. Ghi lại response mong đợi cho success và failure (status code và trường quan trọng) để dev tiếp theo có thể sanity-check nhanh.

Luồng đơn này thường lộ ranh giới ownership: UI tin vào gì, API bắt buộc gì, và lỗi biến mất hoặc bị xử lý hai lần ở đâu.

Biến bản đồ tinh thần thành tài liệu onboarding ngắn

Khi đã có bản đồ tinh thần kha khá, đóng băng nó thành note 1–2 trang. Mục tiêu không phải hoàn chỉnh. Mà là giúp dev tiếp theo trả lời: app này là gì, tôi nên nhìn đâu trước, và thứ gì dễ hỏng nhất?

Nếu dùng Claude Code, coi doc là đầu ra của Q&A: rõ ràng, cụ thể, và dễ quét.

Cấu trúc 1–2 trang đơn giản

Giữ doc dự đoán được để người ta tìm nhanh. Một cấu trúc tốt là:

• Purpose: app làm gì, ai dùng, và "done" nghĩa là gì
• Architecture summary: dịch vụ chính, data store, và cách request di chuyển qua hệ thống
• How to run: prerequisites, lệnh để khởi động, và lệnh để chạy tests
• Where things live: thư mục quan trọng, và 5–10 file là entry points
• Key flows và risks: trace ngắn các hành trình quan trọng, và những gì cần validate sau thay đổi

Làm cho nó có thể hành động, không học thuật

Cho phần "Where things live" các con trỏ như "Auth bắt đầu ở X, logic session ở Y, route UI ở Z." Tránh dump cây thư mục đầy đủ. Chỉ chọn thứ người sẽ đụng.

Với "Key flows," viết 4–7 bước mỗi flow: trigger, controller/handler, module chính, gọi DB, và hiệu ứng ra ngoài (email gửi, state cập nhật, job queued). Thêm tên file ở mỗi bước.

Với "Risky areas," nêu failure mode và kiểm tra an toàn nhanh nhất (một test cụ thể, smoke run, hoặc log để theo dõi).

Kết thúc bằng một danh sách nhiệm vụ ban đầu để ai đó có thể đóng góp an toàn:

• Cập nhật một chỉnh sửa giao diện nhỏ hoặc rule validation trong một màn hình cô lập
• Thêm unit test nhỏ quanh helper phức tạp bạn nhận ra
• Sửa bug rủi ro thấp có repro rõ và kết quả mong đợi
• Thêm guardrail: tin nhắn lỗi tốt hơn, kiểm tra input, hoặc timeout
• Hỏi ai sở hữu deploy production và ai ping cho các câu hỏi domain

Sai lầm phổ biến và cách tránh

Cách nhanh nhất để lãng phí assistant là hỏi "một giải thích đầy đủ về toàn repo." Bạn nhận một tóm tắt dài nghe tự tin nhưng mơ hồ. Thay vào đó, chọn một lát nhỏ quan trọng (một module + một luồng người dùng), rồi mở rộng dần.

Sai lầm thứ hai là không nêu rõ luồng quan trọng. Nếu bạn không nói "checkout," "login," hay "admin edit," câu trả lời dễ trôi vào kiến trúc chung chung. Bắt đầu mỗi phiên với một mục tiêu cụ thể: "Giúp tôi hiểu luồng signup end-to-end, gồm validation, trạng thái lỗi, và nơi dữ liệu lưu."

Bẫy khác là để assistant đoán mò. Khi điều gì đó không rõ, bắt nó gắn nhãn sự không chắc chắn. Yêu cầu tách rõ bằng chứng từ code và suy luận.

Giữ các unknowns hiển thị (để bạn giải quyết)

Dùng quy tắc đơn giản trong ghi chú: mỗi khẳng định phải được gắn là một trong:

• Confirmed in code
• Confirmed by running the app
• Assumption (needs check)
• Unknown (missing context)

Ghi chú cũng hỏng khi thu thập không có cấu trúc. Một đống snippet chat khó biến thành bản đồ tinh thần. Giữ template nhất quán: modules liên quan, entry point, hàm và file chính, dữ liệu chạm tới, side effects, đường lỗi, và test cần chạy.

Đừng coi outputs là sự thật tuyệt đối

Ngay cả với Claude Code, coi output là bản nháp. Xác minh các luồng chính trong app đang chạy, đặc biệt các phần có thể làm production hỏng: auth, payments, permissions, job nền, và migrations.

Một ví dụ thực tế: nếu assistant nói "password reset gửi email qua X," xác nhận bằng cách kích hoạt reset trong môi dev và kiểm tra logs hoặc email sandbox. Kiểm chứng này ngăn bạn onboard vào một câu chuyện không đúng.

Checklist nhanh trước khi nói "Tôi đã onboard"

Bạn không cần thuộc lòng repo. Bạn cần đủ tự tin để làm thay đổi an toàn, debug issue thật, và giải thích hệ thống cho người kế tiếp.

Trước khi gọi là onboarded, chắc rằng bạn có thể trả lời những điều này mà không đoán:

• Bạn có thể giải thích năm khu vực quan trọng nhất của code và mỗi khu vực làm gì (ví dụ: UI, layer API, job nền, truy cập dữ liệu, tích hợp)?
• Bạn có thể đi qua hai luồng người dùng giá trị cao end-to-end, và chỉ ra file hoặc hàm bắt đầu mỗi luồng?
• Bạn có thể chỉ ra nơi authentication được thực thi, và nơi role hoặc permission được định nghĩa và kiểm tra?
• Bạn có thể nêu các ghi DB rủi ro nhất (tiền, permission, xóa, chuyển trạng thái) và mô tả cách test từng thay đổi an toàn?
• Bạn có thể trao cho dev mới một note onboarding ngắn họ đọc trong dưới 10 phút và biết bắt đầu từ đâu?

Nếu thiếu một mục, làm một pass nhỏ tập trung thay vì tìm kiếm rộng. Chọn một luồng, theo nó đến ranh giới DB, rồi dừng và viết những gì bạn học. Khi có điều không rõ, ghi nó thành một câu hỏi, không phải một đoạn văn. "Role X được tạo ở đâu?" hữu dụng hơn "auth rối."

Một bài test cuối: tưởng tượng bạn được hỏi thêm một feature nhỏ sau feature flag. Nếu bạn có thể nêu tên file sẽ chạm, test sẽ chạy, và các failure mode cần theo dõi, thì bạn đã đủ onboard để đóng góp có trách nhiệm.

Bước tiếp theo: giữ bản đồ cập nhật và làm handoff dễ hơn

Bản đồ tinh thần chỉ hữu dụng khi nó phản ánh thực tế. Đối xử nó như artefact sống, không phải nhiệm vụ một lần. Cách dễ nhất để giữ nó chính xác là update ngay sau thay đổi ảnh hưởng hành vi.

Quy trình nhẹ đánh bại rewrite lớn. Kết nối cập nhật với công việc bạn đang làm:

• Sau mỗi feature: cập nhật danh sách module và các luồng chính nó chạm tới
• Sau mỗi incident: thêm trigger, impact, và chính xác chỗ fix
• Sau mỗi refactor rủi ro: ghi gì đã thay đổi và gì vẫn tương thích
• Trước release: kiểm tra lại 3 vùng rủi ro hàng đầu và các path test
• Một lần mỗi tháng: xóa ghi chép cũ và xác nhận owner cho module chính

Giữ doc onboarding gần code và version nó với cùng kỷ luật như codebase. Diff nhỏ được đọc. Rewrite lớn hiếm khi được đọc.

Khi deploy rủi ro, ghi lại điều gì giúp người tiếp theo recover nhanh: gì thay đổi, theo dõi gì, và cách rollback. Nếu nền tảng bạn hỗ trợ snapshot và rollback, thêm tên snapshot, lý do, và điều gì là "good" sau fix.

Nếu bạn build với Koder.ai (koder.ai), planning mode có thể giúp bạn phác thảo map module và note onboarding nhất quán từ Q&A, và export source code cho reviewer cách rõ ràng để xác minh kết quả.

Cuối cùng, định nghĩa checklist handoff cho dev tiếp theo mà không phải đoán:

• Cần đọc gì trước (2–3 file hoặc doc) và vì sao
• Chạy gì local (lệnh, env vars, seed data)
• Xác minh gì (một happy path và một failure case)
• Những điểm nhọn (module rủi ro, test flaky, config khó)
• Hỏi ai về gì (owner cho luồng chính)

Làm tốt, Claude Code cho onboarding codebase trở thành thói quen: mỗi thay đổi để lại một bản đồ rõ hơn cho người kế tiếp.