Lập bản đồ và kiểm tra Harness Claude Code bằng harness-map

harness-map làm gì

harness-map đọc cấu hình xung quanh Claude Code và chuyển cấu hình đó thành một sơ đồ lắp ráp trực quan duy nhất. Cấu hình xung quanh này, được gọi là harness, bao gồm các tệp chỉ dẫn như CLAUDE.md, bộ nhớ tự động, máy chủ MCP, skill, quyền, hook, quy tắc và các thiết lập liên quan.

Harness hiệu lực có thể thay đổi tùy theo thư mục nơi Claude Code khởi động và cách agent mới được khởi chạy. Một phiên chính, fork, subagent, agent Explore hoặc Plan, teammate hay lần gọi claude -p có thể nhận được những thông tin khác nhau. harness-map làm hiển thị những khác biệt này cho từng thư mục khởi đầu và phương thức khởi chạy được chọn.

Dự án sử dụng Python 3 và không yêu cầu thêm gói Python nào. Các script đọc cấu hình mà không sửa đổi, tạo tệp harness.json có cấu trúc và xây dựng báo cáo harness-map.html có thể xem trong trình duyệt.

Tính năng chính

• Phân tích theo thư mục: So sánh bao nhiêu thư mục khởi đầu tùy nhu cầu bằng cách lặp lại --cwd.
• Trực quan hóa việc bàn giao agent: Xem mỗi thành phần được kế thừa từ phiên cha, đọc lại từ tệp hay không được truyền cho agent mới.
• Phân tích tương tác giữa các quy tắc: Kiểm tra năm cách xử lý: thay thế, hợp nhất với quyền từ chối được ưu tiên, chạy tất cả quy tắc, nối không ưu tiên và chỉ chọn một quy tắc.
• Trường hợp rủi ro và cần chú ý: Xác định các tình huống như bộ nhớ tự động bị phân chia theo thư mục hoặc chức năng nhóm khiến chế độ quyền được truyền cho agent mới.
• Đánh giá mức độ hoàn thiện: Xem xét cấp độ từ 1 đến 5 trên sáu lĩnh vực của harness trong biểu đồ lục giác.
• Đầu ra chú trọng quyền riêng tư: Ghi lại siêu dữ liệu cấu trúc nhưng loại bỏ nội dung chỉ dẫn, giá trị biến môi trường, token, đối số lệnh và các chi tiết nhạy cảm khác.
• Kết xuất linh hoạt: Dán harness.json của người khác vào giao diện báo cáo để vẽ lại sơ đồ của họ.

Trước khi bắt đầu

Bạn cần Python 3, Git và quyền truy cập vào cấu hình Claude Code thuộc tài khoản người dùng thông thường của mình. Không cần cài đặt gói bằng pip.

Chạy harness-map bằng chính người dùng chạy Claude Code. Không sử dụng sudo. Việc thực thi với quyền quản trị có thể thay đổi thư mục home hiệu lực và làm lộ cấu hình của người dùng khác, vì vậy script từ chối chạy theo cách đó.

Chọn các thư mục thực tế mà bạn thường dùng để khởi động Claude Code. Quét một thư mục cha không cho thấy toàn bộ cấu hình áp dụng khi khởi động bên trong một dự án con, vì cấu hình được phân giải ngược lên từ từng thư mục khởi đầu.

Cài đặt

Clone repository và chuyển vào thư mục của nó:

git clone https://github.com/Dominic-DK/harness-map.git
cd harness-map

Bạn có thể xem dự án tại github.com/Dominic-DK/harness-map. Dự án được phân phối theo Giấy phép MIT.

Bước 1: Quét harness Claude Code của bạn

Chạy harness-map.py với một đối số --cwd cho mỗi workspace bạn muốn so sánh. Lệnh sau quét hai thư mục ví dụ và ghi kết quả vào harness.json:

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b -o harness.json

Bạn có thể lặp lại --cwd bao nhiêu lần tùy cần thiết. Nếu bỏ qua, harness-map chỉ quét thư mục hiện tại:

python3 harness-map.py -o harness.json

Lần quét ban đầu đọc các tệp cấu hình và thực hiện những kiểm tra có thể hoàn tất từ các tệp đó cùng số lượng tổng hợp của lịch sử hội thoại.

Thay đổi khoảng thời gian lịch sử hội thoại

Khoảng thời gian tổng hợp mặc định là 30 ngày. Sử dụng --days khi cần một khoảng quan sát khác. Ví dụ, lệnh này sử dụng 90 ngày:

python3 harness-map.py --cwd ~/work/a --days 90 -o harness.json

Phân tích hội thoại chỉ đếm sự kiện. Kết quả không chứa văn bản hội thoại, nội dung lệnh hoặc nội dung tệp.

Bước 2: In kế hoạch kiểm tra agent

Một số kiểm tra yêu cầu agent thực hiện các thử nghiệm có kiểm soát thay vì chỉ kiểm tra cấu hình tĩnh. In quy trình và quy tắc an toàn do dự án cung cấp bằng lệnh:

python3 harness-map.py --probe-plan

Đọc đầu ra này trước khi yêu cầu agent thực hiện kiểm tra. Làm theo hướng dẫn được tạo ra thay vì tự nghĩ ra các lệnh kiểm tra. Các kiểm tra có thể bao gồm đọc cấu hình, đếm các sự kiện lịch sử liên quan và kiểm thử hành vi bên trong một thư mục tạm thời.

Bước 3: Thực hiện hoặc bỏ qua các lần kiểm tra

Yêu cầu agent thực hiện kế hoạch kiểm tra đã in và lưu các quan sát vào probes.json. Mỗi lần kiểm tra ghi lại những gì đã chạy và những gì đã quan sát được làm bằng chứng hỗ trợ.

Bước này là tùy chọn. Nếu không thực hiện một lần kiểm tra, mục tương ứng sẽ hiển thị là chưa kiểm tra và bị loại khỏi phép tính cấp độ. Tránh tự ghi nhận hành vi thành công khi chưa thực sự quan sát được, đặc biệt với các kiểm tra cấp độ 5.

Bước 4: Hợp nhất kết quả kiểm tra

Chạy lại quá trình quét với cùng các thư mục khởi đầu và thêm --probes probes.json:

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b --probes probes.json -o harness.json

Sử dụng cùng một tập hợp --cwd giúp phép tính cuối cùng khớp với các workspace được bao phủ trong lần quét đầu tiên.

Bước 5: Xây dựng và mở báo cáo

Tạo báo cáo HTML từ tệp JSON đã hoàn tất:

python3 build.py harness.json

Trên macOS, mở bằng:

open harness-map.html

Trên Linux, dùng:

xdg-open harness-map.html

Trên Windows, dùng:

start harness-map.html

Đọc sơ đồ harness

Trong báo cáo, chuyển đổi giữa các thư mục bắt đầu và phương thức khởi chạy để xem harness thực tế cho từng tình huống. Với mỗi thành phần, báo cáo phân biệt ba trạng thái phân phối:

• Agent mới nhận trực tiếp thành phần đó từ phiên làm việc cha.
• Agent mới đọc lại thành phần đó từ một tệp.
• Thành phần không được truyền cho agent mới.

So sánh này giúp giải thích vì sao hai agent sử dụng cùng một kho lưu trữ có thể hoạt động khác nhau. Ví dụ: agent phụ có thể không nhận được mọi thứ mà phiên làm việc chính có, trong khi các cài đặt gắn với một thư mục bắt đầu cụ thể có thể không áp dụng ở nơi khác.

Hiểu các quy tắc chồng lấn

Báo cáo cũng cho thấy cách xử lý các quy tắc chồng lấn. Tùy loại cấu hình, một giá trị ở phía sau có thể thay thế giá trị khác, các quy tắc có thể được hợp nhất với quyền từ chối được ưu tiên, mọi hành động phù hợp có thể được thực thi, văn bản có thể được nối lại mà không theo thứ tự ưu tiên, hoặc chỉ một tùy chọn được chọn.

Hãy xem xét các tương tác này khi một chỉ thị, quyền hoặc hook dường như không có hiệu lực. Vấn đề có thể nằm ở cách kết hợp quy tắc thay vì do thiếu tệp.

Hiểu đánh giá mức độ trưởng thành

harness-map chấm điểm sáu lĩnh vực từ cấp độ 1 đến cấp độ 5:

1. Thiết kế chỉ thị
2. Bộ nhớ và vị trí
3. Phạm vi công cụ
4. Chặn phòng ngừa
5. Xác minh sau hành động và khả năng quan sát
6. Thiết kế ủy quyền

Tập lệnh có thể tự động tính đến cấp độ 4 khi dữ liệu hiện có hỗ trợ. Kết quả ghi lại những điều kiện đã đạt và nơi quá trình đánh giá dừng lại. Các định nghĩa chấm điểm được lưu trong SCORECARD bên trong harness-map.py.

Cấp độ 5 yêu cầu bằng chứng từ một lần kiểm tra thực tế đã được quan sát. Ví dụ, chặn phòng ngừa chỉ đạt cấp độ 5 khi có bản ghi cho thấy một lệnh cấm thực sự đã ngăn một lệnh được thực thi. Chỉ có lệnh cấm trong cấu hình là chưa đủ.

Đánh giá cũng có thể hạ điểm khi cấu hình tồn tại nhưng dường như không được sử dụng, chẳng hạn như một công cụ không được dùng trong khoảng thời gian lịch sử đã chọn hoặc các phiên làm việc chạy ở chế độ quyền khác với chế độ được cấu hình.

Khi quét nhiều thư mục bắt đầu, cấp độ hiển thị là trung vị của điểm cấp thư mục. Với số lượng thư mục chẵn, giá trị ở giữa thấp hơn được sử dụng. Báo cáo cũng hiển thị phạm vi từ tối thiểu đến tối đa.

Cấp độ cao hơn không tự động tốt hơn. harness-map ước tính cấp độ mỗi lĩnh vực cần dựa trên các mẫu sử dụng, bao gồm việc bạn làm việc một mình hay không, tần suất khởi chạy agent cấp dưới và tần suất chạy các lệnh khó hoàn tác. Công cụ làm nổi bật những lĩnh vực thấp hơn nhu cầu ước tính thay vì cảnh báo về mọi điểm dưới cấp độ 5.

Quyền riêng tư và xem xét đầu ra

Trình quét đọc các tệp nhưng không thay đổi cấu hình. Công cụ cố ý giới hạn những gì được sao chép vào đầu ra:

• Đối với CLAUDE.md và các tệp quy tắc, công cụ ghi lại đường dẫn, số dòng và thời điểm chúng được đọc, nhưng không ghi lại nội dung.
• Đối với các cài đặt, công cụ ghi lại chế độ quyền, số lượng quy tắc và tên biến môi trường, nhưng không ghi lại giá trị biến môi trường hoặc nội dung quy tắc.
• Đối với hook, công cụ ghi lại sự kiện, nguồn và tên tệp thực thi, nhưng loại bỏ đối số lệnh và đường dẫn.
• Đối với máy chủ MCP, công cụ ghi lại tên và nguồn, nhưng loại bỏ lệnh, đối số, tiêu đề và token.
• Đối với đường dẫn, công cụ thay thế tiền tố thư mục chính thực tế bằng ~.

Các tệp không thể đọc được sẽ được đưa vào danh sách unreadable. Theo dự án, Claude Code cũng không thể đọc những tệp đó với cùng quyền của người dùng.

Đầu ra vẫn chứa tên thư mục và danh sách plugin đã cài đặt. Hãy mở và kiểm tra cả harness.json lẫn harness-map.html trước khi chia sẻ.

Tệp .gitignore của kho lưu trữ được cấu hình để loại harness.json và harness-map.html khỏi hệ thống kiểm soát phiên bản, nhưng bạn vẫn nên kiểm tra các tệp đã đưa vào staging trước khi commit.

Ủy quyền quy trình cho một coding agent

Bạn có thể yêu cầu Claude Code hoặc một coding agent khác làm theo các chỉ dẫn của kho lưu trữ. Hãy thay các thư mục ví dụ bằng những thư mục bắt đầu bạn thường sử dụng. Một yêu cầu phù hợp là:

Đọc README tại https://github.com/Dominic-DK/harness-map và làm theo các bước thực thi trực tiếp.
Các thư mục bắt đầu tôi thường sử dụng là ~/work/a và ~/work/b.
Thực hiện các bước kiểm tra agent ở bước 3 theo đúng các quy tắc an toàn đã tài liệu hóa và ghi lại kết quả.
Khi hoàn tất, mở harness-map.html trong trình duyệt và tóm tắt kết quả trong khoảng năm câu rõ ràng.

Hãy duy trì sự giám sát của con người trong giai đoạn thăm dò. Agent phải tuân theo chính xác kế hoạch an toàn do --probe-plan tạo ra.

Mẹo nâng cao

Quét mọi điểm vào có ý nghĩa

Đừng cho rằng quét thư mục gốc của kho lưu trữ sẽ bao phủ các dự án lồng nhau. Hãy thêm từng thư mục mà bạn thực sự dùng để khởi chạy Claude Code dưới dạng một --cwd riêng. Điều này tạo ra sự so sánh hữu ích hơn về các chỉ thị được kế thừa, ranh giới bộ nhớ và tính khả dụng của công cụ.

Chọn khoảng thời gian quan sát phù hợp với công việc

Khoảng thời gian mặc định 30 ngày phù hợp với hoạt động gần đây, nhưng các công cụ ít được sử dụng có thể cần khoảng thời gian dài hơn. Hãy sử dụng --days một cách có chủ đích vì bằng chứng về việc không sử dụng có thể ảnh hưởng đến điểm trưởng thành.

Tách cấu hình khỏi hành vi đã được xác minh

Hãy xem các phát hiện dựa trên tệp là bằng chứng về cấu hình dự kiến, không phải bằng chứng rằng một cơ chế kiểm soát hoạt động khi chạy. Sử dụng các bước kiểm tra tùy chọn khi cần xác nhận rằng hook, hạn chế hoặc hành vi khác thực sự có hiệu lực.

So sánh báo cáo mà không để lộ cấu hình thô

Nếu ai đó gửi cho bạn một harness.json đã được xem xét, hãy dùng vùng dán của báo cáo để dựng lại tệp đó. Mặc dù các giá trị nhạy cảm đã được lược bỏ, cả hai bên vẫn nên kiểm tra JSON trước vì tên dự án, tên thư mục và tên plugin vẫn còn hiện diện.

Sử dụng phương án dự phòng khi không có Python

Nếu không có Python 3, hãy sao chép nội dung của PROMPT.md vào một agent. Agent có thể đọc trực tiếp cấu hình, tạo JSON theo cùng định dạng và dựng giao diện. README cảnh báo rằng phương pháp này có khả năng bỏ sót mục hoặc đếm sai nhiều hơn so với script.

Giới hạn đã biết

• Các quy tắc chuyển giao được cố định trong SPAWN_RULES của harness-map.py; chúng không được suy ra bằng cách quan sát các phiên trực tiếp của bạn.
• README cho biết các quy tắc này tuân theo tài liệu Claude Code 2.1.287 được kiểm tra vào ngày 2 tháng 10 năm 2026. Hành vi có thể khác trong các phiên bản sau này.
• Các nguồn được trích dẫn là tài liệu chính thức về sub-agent, nhóm agent và bộ nhớ.
• Dự án ghi nhận một điểm khác biệt: tài liệu cho biết sub-agent không đọc bộ nhớ tự động, trong khi môi trường của tác giả được cho là đã truyền danh sách bộ nhớ cho một sub-agent. Báo cáo đánh dấu đây là sự khác biệt giữa tài liệu và quan sát thực tế.
• Các cài đặt chỉ dành cho dòng lệnh như --agents và --permission-mode không được lưu trong tệp, vì vậy scanner không thể phát hiện chúng.
• Đối với các plugin đã cài đặt, scanner đọc phiên bản mới nhất được tìm thấy trong thư mục cài đặt plugin.

Kết luận

harness-map cung cấp một cách thực tế để hiểu cấu hình mà Claude Code thực sự nhận được trên các dự án và chế độ khởi chạy agent. Hãy bắt đầu bằng cách quét mọi thư mục làm việc quan trọng, tùy chọn chạy các bước kiểm tra được tài liệu hóa, dựng lại dữ liệu cùng bằng chứng của chúng và tạo báo cáo HTML. Sử dụng phần trực quan hóa và đánh giá mức độ hoàn thiện để tìm ra khoảng trống cấu hình, nhưng hãy xem xét các tệp được tạo trước khi chia sẻ và coi các quy tắc chuyển giao được tài liệu hóa là phụ thuộc vào phiên bản.