Dùng AI đọc hiểu một kho mã lớn

Bài này dựa trên tài liệu Claude Code (quy trình thường gặp, best practices, quản lý chi phí), đọc ngày 11/11/2026. Ví dụ câu hỏi dịch từ các câu mẫu trong tài liệu; cách làm áp dụng được với mọi trợ lý AI đọc được kho mã.

AI giúp gì khi đọc một kho mã lạ?

Tài liệu Claude Code nhận xét rằng agent bắt đầu mọi việc bằng việc đọc code, và các mô hình hiện nay đọc code rất tốt: chúng tìm ra cấu trúc thư mục, quy ước, công cụ test và cách các thành phần được xây, thường nhanh hơn bạn giải thích. Với người mới vào một dự án hay sinh viên phải đọc mã nguồn mở, đây là trợ giúp lớn: thay vì mở từng tệp mò mẫm, bạn hỏi và được dẫn tới đúng chỗ.

Nhưng có hai giới hạn cần nhớ. Thứ nhất, lời tóm tắt có thể sai: AI có thể nhầm vai trò một tệp, đoán tên hàm không tồn tại, hoặc bỏ qua một đường đi hiếm. Thứ hai, thứ AI không đọc được thì nó không biết: quyết định của nhóm trong một buổi họp, quy trình triển khai chỉ có trong đầu một người. Vì vậy cách làm đúng là dùng AI để tìm nhanh, rồi tự kiểm chỗ quan trọng.

Bước 1: hỏi tổng quan, rộng trước hẹp sau

Mở công cụ AI ở thư mục gốc của dự án, rồi bắt đầu bằng câu hỏi rộng. Các câu mẫu trong tài liệu Claude Code, dịch sang tiếng Việt:

• "Cho tôi tổng quan về kho mã này."
• "Giải thích các mẫu kiến trúc chính được dùng ở đây."
• "Các mô hình dữ liệu chính là gì?"
• "Việc xác thực người dùng được xử lý thế nào?"

Ba mẹo từ tài liệu: bắt đầu bằng câu hỏi rộng rồi thu hẹp vào từng phần; hỏi về quy ước và mẫu viết code của dự án; và nhờ lập một bảng thuật ngữ riêng của dự án. Bảng thuật ngữ đặc biệt hữu ích với dự án nghiệp vụ, nơi tên biến như don_hang, phieu_xuat, ton_kho mang ý nghĩa riêng.

Một câu hỏi nên thêm ngay từ đầu: "Liệt kê điểm vào của chương trình và lệnh để chạy test." Biết chương trình bắt đầu từ đâu và chạy test thế nào là hai thứ bạn cần để tự kiểm mọi điều AI nói sau đó.

Bước 2: tìm đúng chỗ và lần theo một luồng

Khi đã có bức tranh chung, đi vào một tính năng cụ thể. Các câu mẫu trong tài liệu:

• "Tìm các tệp xử lý xác thực người dùng."
• "Các tệp xác thực này phối hợp với nhau thế nào?"
• "Lần theo quá trình đăng nhập từ giao diện tới cơ sở dữ liệu."

Câu cuối là kỹ thuật mạnh nhất: chọn một luồng người dùng thật (đăng nhập, đặt hàng, nộp bài) và đi theo nó qua các lớp. Hiểu được một luồng trọn vẹn giúp bạn đoán đúng các luồng còn lại, vì dự án thường lặp lại cùng một khuôn.

Mẹo từ tài liệu cho bước này: nói cụ thể thứ bạn tìm; dùng đúng từ ngữ nghiệp vụ của dự án; và với ngôn ngữ có kiểu, cài plugin hiểu code để AI có chức năng "đi tới định nghĩa" và "tìm nơi dùng" chính xác. Tài liệu chi phí còn cho biết plugin loại này giúp giảm việc đọc tệp thừa: một lần "đi tới định nghĩa" thay cho một lần tìm chữ rồi đọc nhiều tệp ứng viên.

Đưa thẳng tệp vào câu hỏi bằng @

Khi đã biết tệp cần hỏi, nhắc nó bằng @ thay vì để AI tự tìm. Theo tài liệu Claude Code:

• Giải thích logic trong @src/utils/auth.js đưa nội dung tệp vào cuộc trò chuyện, nếu tệp vừa giới hạn đọc (mặc định 25.000 token); tệp văn bản lớn hơn 256 KB không được đưa vào.
• Cấu trúc của @src/components là gì? nhắc một thư mục cho AI thấy danh sách tệp, không phải nội dung.
• Nhắc một tệp bằng @ còn đưa vào các tệp CLAUDE.md ở thư mục của tệp đó và các thư mục cha.

Bước 3: kiểm lời tóm tắt của AI

Đây là bước nhiều người bỏ qua. Một lời tóm tắt nghe hợp lý chưa chắc đúng. Ba cách kiểm nhanh:

1. Đòi dẫn chứng. Thêm vào câu hỏi: "dẫn tệp và số dòng cho mỗi khẳng định". Rồi mở vài chỗ ra xem. Nếu AI dẫn một tệp không có, bạn biết ngay phần đó không đáng tin.
2. Hỏi chỗ AI chưa chắc. "Phần nào trong lời giải thích của bạn là suy đoán chứ không đọc thấy trong code?" Câu hỏi này thường làm lộ các giả định.
3. Đối chiếu với dữ liệu do máy tạo. Ví dụ một bản đồ ai nhập ai, test, hoặc chạy chương trình với một đầu vào và xem kết quả.

Đoạn Python dưới đây làm cách thứ ba: dùng mô-đun ast có sẵn của Python để đọc (không chạy) mọi tệp .py trong kho, rồi in điểm vào, quan hệ nhập giữa các mô-đun, mô-đun được nhập nhiều nhất và mô-đun không ai nhập. Ví dụ chạy trên một kho bán hàng nhỏ được tạo trong thư mục tạm.

"""Vẽ bản đồ một kho mã Python bằng thư viện ast có sẵn: điểm vào, ai nhập ai, hàm và lớp theo tệp.

Dùng để đối chiếu lời tóm tắt kho mã do AI viết với dữ liệu do máy đếm, hoặc đưa cho AI làm điểm bắt đầu.
Chỉ đọc tệp, không chạy mã của kho.
"""
import ast
import os
import tempfile
from collections import Counter


def ten_mo_dun(goc, duong_dan):
    rel = os.path.relpath(duong_dan, goc)[:-3].replace(os.sep, ".")
    return rel[:-9] if rel.endswith(".__init__") else rel


def ve_ban_do(goc):
    mo_dun = {}
    for thu_muc, con, tep_ds in os.walk(goc):
        con[:] = sorted(c for c in con if not c.startswith((".", "__pycache__", "venv")))
        for tep in sorted(tep_ds):
            if tep.endswith(".py"):
                p = os.path.join(thu_muc, tep)
                with open(p, encoding="utf-8") as f:
                    nguon = f.read()
                mo_dun[ten_mo_dun(goc, p)] = (nguon, ast.parse(nguon))
    ban_do = {}
    for ten, (nguon, cay) in mo_dun.items():
        nhap = set()
        for nut in ast.walk(cay):
            if isinstance(nut, ast.Import):
                nhap |= {a.name for a in nut.names}
            elif isinstance(nut, ast.ImportFrom) and nut.module:
                nhap.add(nut.module)
        ban_do[ten] = {
            "dong": len(nguon.splitlines()),
            "nhap_noi_bo": sorted(n for n in nhap if n in mo_dun),
            "ham": [n.name for n in cay.body if isinstance(n, (ast.FunctionDef, ast.ClassDef))],
            "diem_vao": "__main__" in nguon,
        }
    return ban_do


def in_ban_do(ban_do):
    tong = sum(m["dong"] for m in ban_do.values())
    print(f"{len(ban_do)} tệp Python, {tong} dòng")
    print("Điểm vào:", ", ".join(t for t, m in ban_do.items() if m["diem_vao"]) or "(không thấy)")
    for ten, m in ban_do.items():
        if m["nhap_noi_bo"]:
            print(f"  {ten} -> {', '.join(m['nhap_noi_bo'])}")
    dem = Counter(n for m in ban_do.values() for n in m["nhap_noi_bo"])
    if dem:
        ten, so = dem.most_common(1)[0]
        print(f"Được nhập nhiều nhất: {ten} ({so} nơi)")
    khong_ai_nhap = [t for t, m in ban_do.items() if m["dong"] and not m["diem_vao"] and dem[t] == 0]
    print("Không nơi nào nhập (có thể là mã thừa):", ", ".join(khong_ai_nhap) or "(không có)")


def tao_kho_mau(goc):
    tep = {
        "app.py": "from dich_vu.dat_hang import dat_hang\n\nif __name__ == '__main__':\n    print(dat_hang('SP01', 2))\n",
        "dich_vu/__init__.py": "",
        "dich_vu/dat_hang.py": "from dich_vu.thanh_toan import thu_tien\nfrom kho.ton_kho import con_hang\n\n"
                               "def dat_hang(ma, so_luong):\n    if not con_hang(ma, so_luong):\n        return 'hết hàng'\n"
                               "    return thu_tien(ma, so_luong)\n",
        "dich_vu/thanh_toan.py": "from kho.ton_kho import gia\n\ndef thu_tien(ma, so_luong):\n    return gia(ma) * so_luong\n",
        "kho/__init__.py": "",
        "kho/ton_kho.py": "TON = {'SP01': 5}\nGIA = {'SP01': 30000}\n\ndef con_hang(ma, n):\n    return TON.get(ma, 0) >= n\n\n"
                          "def gia(ma):\n    return GIA[ma]\n",
        "kho/bao_cao_cu.py": "def xuat_excel():\n    pass\n",
    }
    for ten, nd in tep.items():
        p = os.path.join(goc, *ten.split("/"))
        os.makedirs(os.path.dirname(p), exist_ok=True)
        with open(p, "w", encoding="utf-8") as f:
            f.write(nd)


def chay_thu():
    with tempfile.TemporaryDirectory() as goc:
        tao_kho_mau(goc)
        ban_do = ve_ban_do(goc)
    in_ban_do(ban_do)
    return ban_do


if __name__ == "__main__":
    chay_thu()

Kết quả:

7 tệp Python, 25 dòng
Điểm vào: app
  app -> dich_vu.dat_hang
  dich_vu.dat_hang -> dich_vu.thanh_toan, kho.ton_kho
  dich_vu.thanh_toan -> kho.ton_kho
Được nhập nhiều nhất: kho.ton_kho (2 nơi)
Không nơi nào nhập (có thể là mã thừa): kho.bao_cao_cu

Bản đồ này cho bạn ba điều để hỏi lại AI: luồng chính đi từ app qua dat_hang tới thanh_toan và ton_kho; ton_kho là mô-đun trung tâm (sửa nó ảnh hưởng nhiều chỗ nhất); và bao_cao_cu không ai dùng. Nếu lời tóm tắt của AI nói bao_cao_cu là "phần xuất báo cáo chính của hệ thống", bạn có bằng chứng để hỏi lại. Lưu ý giới hạn: bản đồ chỉ thấy lệnh import viết thẳng trong code, không thấy các mô-đun được nạp động theo tên hay qua cấu hình.

Kho mã lớn: giữ ngữ cảnh gọn

Với kho hàng nghìn tệp, việc đọc lan man làm đầy ngữ cảnh và tốn token. Bốn thói quen theo tài liệu:

• Giao việc khảo sát cho subagent. Câu mẫu trong tài liệu: "Dùng một subagent để tìm hiểu hệ thống xác thực xử lý việc làm mới token như thế nào." Subagent đọc tệp trong ngữ cảnh riêng và chỉ trả về bản tóm tắt. Xem subagent là gì.
• Dùng chế độ lập kế hoạch khi chỉ muốn hiểu, để AI chỉ đọc mà không sửa gì.
• Hỏi cụ thể. Tài liệu chi phí ví dụ: yêu cầu mơ hồ như "cải thiện kho mã này" khiến AI quét rộng; yêu cầu cụ thể giúp nó đọc ít tệp.
• Bắt đầu lại giữa các chủ đề. Khi chuyển từ tìm hiểu phần thanh toán sang phần báo cáo, /clear để ngữ cảnh không chở theo hàng chục tệp cũ.

Ghi lại những gì đã hiểu

Hiểu biết bạn vừa có (đã kiểm) đáng được ghi lại để lần sau, cho cả bạn và AI. Hai chỗ:

• Tài liệu cho người: một tệp ARCHITECTURE.md hay mục trong README mô tả luồng chính, mô-đun trung tâm, điểm vào. Có thể nhờ AI soạn bản nháp, nhưng chỉ giữ những gì bạn đã kiểm.
• Tệp hướng dẫn cho AI: chỉ ghi những gì AI không tự đọc được từ code, như quyết định của nhóm, lệnh cần môi trường đặc biệt, phần không được đụng. Tài liệu best practices khuyên không cần mô tả kiến trúc và cấu trúc thư mục trong CLAUDE.md vì AI tự đọc được. Xem viết hướng dẫn dự án cho AI.

Dùng AI để học đọc code, không chỉ để được giải thích

Với sinh viên, đọc code là kỹ năng cần luyện, và AI có thể giúp luyện thay vì làm hộ. Một vòng luyện tập hiệu quả:

1. Tự đọc một hàm và đoán nó làm gì, đoán kết quả với một đầu vào cụ thể.
2. Chạy thử để kiểm đoán của bạn.
3. Chỉ khi đoán sai mới hỏi AI giải thích, và hỏi "vì sao tôi đoán sai" thay vì "hàm này làm gì".

Cách này giữ cho bạn là người hiểu code, còn AI là người gợi ý khi bạn bí. Bài kiểm chứng việc AI làm có thêm cách đối chiếu kết quả bằng chạy thử.

Câu hỏi thường gặp

Học tiếp

• Muốn giao việc khảo sát cho một agent chạy trong ngữ cảnh riêng, đọc subagent là gì.
• Muốn ghi lại những gì AI cần biết về dự án, đọc viết hướng dẫn dự án cho AI.
• Muốn kiểm các kết luận của AI một cách có hệ thống, đọc kiểm chứng việc AI làm.

Nếu bạn muốn rèn nền tảng lập trình để đọc hiểu code tốt hơn, tham khảo khóa học AI của Big-O Coding.

Nguồn tham khảo

• Tài liệu Claude Code: Common workflows
• Tài liệu Claude Code: Best practices
• Tài liệu Claude Code: Manage costs effectively
• Python docs: ast — Abstract Syntax Trees