Onboarding Claude Code Như Một Lập Trình Viên Mới: Bài Học Từ 17 Năm Phát Triển
Điểm chính
- Claude Code hiệu quả nhất khi bạn xem nó như một developer mới cần được onboard, không phải một công cụ biết hết mọi thứ ngay từ đầu.
context,skillsvàMCPlà ba lớp quan trọng để AI hiểu codebase lớn mà không phải học lại từ con số 0 ở mỗi phiên.- Với legacy codebase, đầu tư vào lớp context bền vững thường tạo ra năng suất lớn hơn việc chỉ cố “prompt hay hơn”.
Một codebase lớn không trở nên dễ làm việc chỉ vì bạn thêm AI vào. Nó trở nên dễ làm việc hơn khi bạn thiết kế cách để AI được onboard đúng cách.
Đó là tinh thần chính trong câu chuyện của Brendan MacLean, người đã duy trì Skyline — phần mềm phân tích protein mã nguồn mở của MacCoss Lab — suốt 17 năm. Codebase này có hơn 700.000 dòng C#, hàng trăm nghìn bài test tự động mỗi đêm, và đủ lớp lịch sử để khiến nhiều khu vực trở nên gần như “khó đụng vào”. Khi Claude Code được đưa vào đúng quy trình, nó không chỉ hỗ trợ sửa code mà còn giúp mở lại những vùng trước đây bị đóng băng vì thiếu người hiểu bối cảnh.
Cùng một vấn đề onboarding, nhưng là một kiểu developer khác
Brendan ban đầu khá hoài nghi rằng công cụ code AI có thể hiểu C# trong một môi trường phức tạp như Skyline. Những thử nghiệm đầu tiên với Claude.ai trên trình duyệt xác nhận điều anh lo ngại: mỗi lần làm việc gần như phải bắt đầu lại từ đầu. Claude có thể trả lời một vấn đề cụ thể, nhưng khi thay đổi trở nên nhỏ hơn, liên tục hơn và gắn chặt hơn với codebase, mọi thứ nhanh chóng trở nên nặng nề.
Cảm giác đó rất giống việc onboard một lập trình viên mới vào dự án lớn. Người mới không cần biết mọi thứ ngay ngày đầu, nhưng họ cần một lộ trình đủ rõ để hoàn thành một phần việc giới hạn và từ đó tích lũy hiểu biết cho vòng sau.
Brendan nhận ra mình có thể onboarding Claude theo đúng cách đó: giao cho nó một dự án nhỏ nhưng có thật, rồi dùng kết quả của lần đó để tăng context cho lần kế tiếp.
Anh tách toàn bộ lớp AI context ra một repository riêng tên pwiz-ai, tách khỏi codebase chính để nó áp dụng xuyên suốt nhiều nhánh và nhiều mốc thời gian. Ở gốc repo này là file CLAUDE.md, nơi chứa hướng dẫn môi trường và các tài liệu cần tham chiếu. Nói ngắn gọn, đây là phần “bản đồ” chứ không phải toàn bộ kiến thức chuyên môn.
Kiến thức chuyên sâu nằm trong skills — một cách để đóng gói năng lực và domain knowledge cho agent. Ví dụ, skill debug của Brendan được thiết kế để kéo Claude ra khỏi chế độ “đoán rồi thử”, buộc nó đi về phân tích nguyên nhân gốc trước khi sửa. Một số skill được kích hoạt thủ công, một số khác được gắn điều kiện rõ ràng để tự động load khi cần.
Khi lớp context này đã có, việc dạy Claude cách debug codebase giảm độ dốc rất nhiều. Claude không còn bắt đầu từ số 0; nó đã biết phần nào code đang làm gì và đang đứng ở đâu trong bức tranh tổng thể.
Giảm tech debt và tăng tốc phát triển
Một ví dụ rất thuyết phục là Files View panel trong Skyline. Đây là một dự án kéo dài cả năm, hiển thị các file liên quan đến tài liệu, có theo dõi filesystem và hỗ trợ sắp xếp bằng kéo-thả. Khi developer phụ trách rời đi, phần việc này bị bỏ dang dở.
Brendan tiếp quản nó cùng Claude Code, và chỉ hai tuần sau thì hoàn thành, với các commit cuối cùng đều có Claude đồng tác giả.
Điều này đặc biệt có ý nghĩa trong môi trường học thuật. Ở MacCoss Lab, developer thường luân chuyển: nghiên cứu sinh tốt nghiệp, postdoc chuyển đi, thực tập sinh rời dự án sau mùa hè. Trong quá khứ, nhiều phần dở dang có thể bị chôn vĩnh viễn. Với Claude Code, một phần việc bị bỏ quên có thể được kéo trở lại dòng chảy phát triển.
Một ví dụ khác là module quản lý test hằng đêm của Skyline. Ba năm trước, Brendan đã ngừng thêm tính năng cho module này sau khi người duy trì rời đi. Gần đây, sau khi có một developer LabKey tạo tài liệu setup bằng Claude Code, Brendan chỉ mất chưa đến một ngày để thêm những tính năng anh đã muốn từ lâu, rồi sửa luôn layout bằng CSS mà trước đó anh thường phải nhờ designer hỗ trợ.
Từ đó, một lớp hạ tầng mới xuất hiện.
Việc chụp lại screenshot cho hơn 2.000 ảnh tutorial của Skyline giờ đã tự động hóa hoàn toàn và gần như tái hiện được 100%. Hệ thống còn được mở rộng bằng Claude Code để có chế độ diff-only view, khuếch đại thay đổi pixel, và một MCP server viết bằng C# để Claude có thể “nhìn thấy” các diff này. Claude Code cũng tạo bản tóm tắt hằng ngày, gom test failures, exceptions và các thread hỗ trợ mở từ hạ tầng nightly test rồi gửi vào inbox của Brendan trước khi anh bắt đầu làm việc.
Claude còn viết luôn một MCP server bằng Python để thực hiện điều này, lấy dữ liệu từ ba nguồn riêng: relational data trên LabKey Server, email của team và code có release tag trên GitHub.
Kết quả là cả nhóm bắt đầu viết ít code hơn và chỉ đạo Claude Code nhiều hơn. Một developer vốn hoài nghi về agentic coding tools đã dùng nó để xây dựng và ship một extension biểu đồ mới — mobilogram pane — phục vụ trực quan hóa dữ liệu ion mobility, và chính người đó cũng ghi nhận Claude Code cho thành quả này.
Lời khuyên cho developer làm việc với legacy codebase
Sau 17 năm onboard developer vào Skyline và hơn một năm áp dụng cùng phương pháp đó cho Claude Code, Brendan rút ra vài điều khá thực tế cho những ai đang làm với legacy codebase.
Context là bạn đồng hành quan trọng nhất
to-do list và plan mà Claude tạo ra không tồn tại xuyên suốt các phiên làm việc. Cái còn lại là context, và context phải được duy trì có chủ đích.
Đây là phần nhiều developer hay bỏ qua nhất, và cũng là lý do khiến hiệu quả khi dùng AI thường chững lại ở một mức nào đó.
Brendan nhấn mạnh rằng bạn không thể mong Claude “tự học” nếu không ghi lại context cho nó. Hãy đầu tư vào việc xây và duy trì lớp context này, rồi coi nó như một artifact của dự án: có version, có cập nhật và có bảo trì.
Anh giữ AI context trong một repository riêng vì nó phát triển theo nhịp khác với code, đồng thời áp dụng cho mọi branch và mọi thời điểm lịch sử. Để chung với repo code vẫn là một lựa chọn hợp lệ; điều quan trọng là nó phải được version hóa, được giữ sống và sẵn sàng khi cần.
Hãy xây thư viện skills của riêng bạn
Skills là nơi bạn mã hóa domain knowledge để bất kỳ instance nào của Claude cũng có thể load được. Cách Brendan làm là “reference, đừng embed”: mỗi skill trỏ đến một knowledge base trung tâm thay vì sao chép nội dung vào từng chỗ, nhờ đó nhẹ hơn và dễ bảo trì hơn.
Những skill được dùng nhiều nhất gồm: một skill định hướng Claude vào Skyline và tài liệu liên quan; một skill version control mã hóa quy ước commit và pull request riêng của dự án; và một skill debug giúp Claude thoát khỏi chế độ “đoán rồi thử”, quay về phân tích nguyên nhân gốc trước khi sửa.
Dùng MCP khi dữ liệu thật là thứ quan trọng
Nếu Claude cần truy cập dữ liệu thật — test results, exception reports, support threads — thì hãy xây MCP integration cho dữ liệu đó. Đây là cách tốt hơn nhiều so với việc bắt AI suy đoán từ mô tả rời rạc.
Với open source project, lớp context còn có giá trị lớn hơn nữa. Không có ngân sách onboarding cố định, không có “trí nhớ tổ chức” nào đảm bảo sẽ còn nguyên năm sau, và cũng không có gì bảo đảm contributor hiện tại sẽ còn ở lại. Nhưng một lớp context được viết tốt thì có thể tồn tại xuyên suốt vòng đời dự án, và phục vụ mọi contributor về sau.
Repo pwiz-ai vì thế không chỉ là công cụ nội bộ. Nó là một artifact của chính dự án — thuộc về dự án, không thuộc về riêng một người nào, và tồn tại lâu hơn những người đã xây nó.
Seventeen năm onboard developer, một kết luận
Bạn sẽ không đưa một codebase 700.000 dòng cho một nhân sự mới rồi mong họ ra kết quả ngay trong ngày đầu tiên. Bạn sẽ chọn một phần việc đủ gọn, hướng dẫn họ qua nó, rồi mở rộng phạm vi khi họ hiểu dần hệ thống.
Claude cũng vậy.
Khi bạn xây context đủ tốt, tổ chức skills rõ ràng và nối Claude với dữ liệu thật qua MCP, nó có thể làm việc trên nhiều branch và nhiều mốc thời gian giống như một developer đã quen hệ thống.
Câu hỏi thường gặp
Vì sao không nên để Claude tự “học” mọi thứ từ đầu trong mỗi phiên?
Vì mỗi phiên mới dễ làm mất mạch hiểu biết. Nếu không có context bền vững, Claude sẽ phải đoán lại cấu trúc dự án, quan hệ giữa các thành phần và các quy ước ngầm của team.
Nên lưu context ở đâu?
Có thể để trong repo riêng hoặc ngay trong repo code chính. Điều quan trọng là nó phải được version hóa, dễ cập nhật và dùng lại được cho nhiều branch, nhiều thời điểm.
Khi nào nên dùng skills thay vì chỉ viết prompt?
Khi bạn có domain knowledge lặp lại nhiều lần, hoặc cần một quy trình cụ thể như debug, version control, setup môi trường hay kiểm tra dữ liệu thật. Skills giúp tái sử dụng tri thức đó ổn định hơn prompt ngắn.
MCP có thật sự cần thiết không?
Không phải lúc nào cũng cần. Nhưng nếu Claude phải làm việc với dữ liệu thật như test logs, báo lỗi, thread hỗ trợ hay hệ thống nội bộ, MCP thường đáng làm vì nó giảm rất nhiều suy đoán.
Kết luận
Điều đáng nhớ nhất từ câu chuyện này không phải là Claude Code “thông minh đến đâu”, mà là cách bạn tổ chức môi trường để nó học được bối cảnh đúng.
Với legacy codebase, chiến thắng không đến từ một prompt hay hơn một chút. Nó đến từ việc xây một lớp context sống được lâu dài, chia nhỏ tri thức thành skills có thể tái dùng, và nối AI vào dữ liệu thật khi cần.
Nói cách khác, nếu bạn onboard Claude như một lập trình viên mới, bạn sẽ nhận lại một cộng sự có thể lớn lên cùng codebase — thay vì một công cụ phải dạy lại từ đầu ở mọi phiên.
Bình luận