Harness Engineering (Phần 7): Toolchain quan trọng hơn model, deploy Claude Code trong codebase hàng triệu dòng

TL;DR

Anthropic vừa công bố hướng dẫn chi tiết cho việc triển khai Claude Code trong large codebase: monorepo hàng triệu dòng, legacy system qua nhiều thập kỷ, và tổ chức với hàng nghìn developer. Insight cốt lõi: "The harness matters as much as the model" - toolchain xây xung quanh model ảnh hưởng đến kết quả nhiều hơn chính model đó.

Tại sao RAG-based tools thất bại ở quy mô lớn

Hầu hết AI coding tools hiện nay dùng RAG (Retrieval-Augmented Generation): embed toàn bộ codebase thành vector, query khi cần. Ở quy mô nhỏ, cách này hoạt động tốt. Ở quy mô lớn, nó vỡ theo một cách cụ thể: embedding pipeline không theo kịp tốc độ commit của team active.

Khi developer query index, họ có thể nhận về function đã bị rename hai tuần trước, hoặc module bị xóa sprint trước - mà không có dấu hiệu nào cho thấy thông tin đó đã lỗi thời. Claude Code giải quyết điều này bằng agentic search: đọc trực tiếp live filesystem, traverse cấu trúc thư mục, dùng grep và trace reference qua codebase. Không cần index trung tâm, không có stale data.

Đánh đổi duy nhất: Claude cần đủ starting context để biết bắt đầu tìm kiếm từ đâu. Đây là lý do CLAUDE.md và skills tồn tại.

Harness 7 thành phần - yếu tố quyết định thực sự

Toolchain của Claude Code được xây từ 7 extension point, mỗi loại có vai trò khác nhau:

• CLAUDE.md files: Context đọc tự động mỗi session. Root file cho toàn dự án, subdirectory files cho local convention. Giữ ngắn khoảng 200 dòng mỗi file - CLAUDE.md quá dài khiến Claude bỏ qua rule quan trọng.
• Hooks: Script chạy tự động tại các điểm xác định (PreToolUse, PostToolUse). Khác với CLAUDE.md chỉ là advisory, hooks là deterministic - đảm bảo linting, formatting, security check chạy mỗi lần, không ngoại lệ. Exit code 2 block operation, exit code 0 cho tiếp tục.
• Skills: Domain knowledge theo yêu cầu qua progressive disclosure. Chỉ load khi task cần, không làm bloat mỗi session. Có thể scope theo path cụ thể trong monorepo - payment service skill chỉ activate khi làm việc trong thư mục đó.
• Plugins: Đóng gói skills + hooks + MCP config thành package cài được. Engineer mới cài plugin ngày 1 là có context và capability như người dùng lâu năm - phân phối qua managed marketplace trong tổ chức.
• LSP integration: Cho Claude symbol-level precision: follow function call đến definition, trace reference xuyên file, phân biệt function cùng tên ở các ngôn ngữ khác nhau. Đặc biệt quan trọng với C, C++ trong large codebase đa ngôn ngữ.
• MCP servers: Kết nối Claude với internal tools, data source, API không trực tiếp access được - ticketing system, analytics platform, internal docs. Một retail tổ chức lớn đã build skill kết nối analytics platform nội bộ và phân phối qua plugin.
• Subagents: Instance riêng biệt với context window độc lập. Dùng để tách exploration khỏi editing, giữ main context window sạch cho implementation. Dùng Haiku cho explore subagents (5x rẻ hơn Sonnet), Sonnet cho implement.

Ba giai đoạn triển khai trong tổ chức

Anthropic quan sát thấy pattern triển khai thành công chia thành 3 phase rõ ràng:

1. Phase 01 - Quiet investment: Trước khi broad access. Infrastructure owner lắp từng mảnh: CLAUDE.md, hooks, skills, LSP. Không vội roll out - làm đúng trước.
2. Phase 02 - The rollout lands: Ngày ra mắt. Infrastructure sẵn sàng, wave đầu developer thấy productive ngay lập tức nhờ setup có sẵn.
3. Phase 03 - Adoption spreads: Sau rollout. Word-of-mouth lan từ team này sang team khác. Population trên harness tăng dần.

Một vai trò mới đang nổi lên trong các tổ chức: "agent manager" - hybrid PM/engineer, chịu trách nhiệm config, plugins, CLAUDE.md conventions và governance cho toàn tổ chức. Đây không phải DevOps truyền thống - đây là người hiểu cả business context lẫn toolchain.

Chi phí thực tế và model tiering

Với pricing tháng 4/2026, dùng đúng model cho đúng task tiết kiệm 40-50% so với dùng Sonnet đồng đều:

• File search, exploration → Haiku (~$0.03/task, 5× rẻ hơn Sonnet)
• Bug fix, implementation → Sonnet (~$0.75/task)
• Architecture review, hard problems → Opus 4.7 (~$2.00/task, SWE-bench Verified 87.6%)

Full-day session dùng mixed models: ~$2.00 so với $3.75 nếu dùng toàn Sonnet. Pattern tối ưu nhất: Haiku cho explore subagents, Sonnet cho implementation, Opus 4.7 cho quyết định architecture.

Checklist 6 bước trước khi rollout

Anthropic tổng hợp 6 việc cần làm trước khi broad rollout:

1. Structure CLAUDE.md files - Root cho org-wide context, subdirectory cho team-specific rules. ~200 dòng mỗi file. Dùng /init để generate starter file dựa trên codebase hiện tại.
2. Wire up hooks cho non-negotiables - Formatting, test commands, security check cần chạy mỗi lần không ngoại lệ - hook đảm bảo điều đó, CLAUDE.md instructions không đảm bảo.
3. Install skills và plugins cho domain expertise - Domain knowledge không thuộc về CLAUDE.md - cho vào skills, chỉ load khi cần.
4. Make codebase navigable - .ignore files cho generated code, LSP servers cho symbol navigation, codebase maps. Ít noise = kết quả tốt hơn.
5. Schedule regular config reviews - Mỗi 3-6 tháng hoặc khi model mới ra. Workaround cho model cũ có thể trở thành overhead không cần thiết với model mới hơn.
6. Assign ownership - Tối thiểu 1 người sở hữu CLAUDE.md hierarchy và giữ nó cập nhật. Không có owner = config thối dần theo thời gian.

Kết

Insight quan trọng nhất từ Anthropic: đừng chỉ nhìn vào benchmark model. Những team đầu tư vào toolchain - từ CLAUDE.md đúng cách đến LSP integration - đều thấy kết quả tốt hơn đáng kể so với team chỉ nâng cấp model mà bỏ qua harness. Model quan trọng, nhưng ecosystem xây xung quanh nó mới là yếu tố quyết định.

Thứ tự đầu tư được khuyến nghị: bắt đầu từ CLAUDE.md, thêm hooks, đưa vào skills, cuối cùng mới mở rộng sang plugins và MCP servers. Mỗi layer xây trên layer trước - không nên bỏ qua bước nào.

via Anthropic Blog · Claude Code Docs