Giữ CLAUDE.md ngắn gọn và có thể kiểm chứng

Với người thường xuyên làm việc trong cùng kho mã, CLAUDE.md nên giữ những thông tin giúp tác vụ tiếp theo được thực hiện đúng: lệnh kiểm thử hiện tại, ranh giới module dùng chung và ràng buộc khó nhìn ra khi chỉ đọc một tệp. Tệp mất ích lợi khi trở thành biên bản của mọi cuộc trò chuyện cũ. Bài này giả định bạn đọc được script trong package.json và chạy được Python với Node đã cài, không cần phiên Claude đang hoạt động.

Tài liệu bộ nhớ Claude Code, được đọc ngày 21 tháng 9 năm 2026, phân biệt chỉ dẫn do chủ dự án viết với ghi nhớ tự động do công cụ duy trì. Tài liệu cũng mô tả tệp hướng dẫn của kho mã và quy tắc theo phạm vi. Các cơ chế ấy cung cấp ngữ cảnh; chúng không phải hệ thống kiểm soát quyền truy cập.

Đặt thông tin vào đúng nơi

Quy tắc toàn kho mã thuộc hướng dẫn dùng chung. Sở thích cá nhân về độ dài câu trả lời có thể thuộc cấu hình cấp người dùng. Giả thuyết từ một phiên gỡ lỗi chưa xong thuộc phần bàn giao tác vụ và phải mang nhãn chưa xác nhận. Trộn chúng dễ biến suy đoán tạm thời thành quy tắc kiến trúc lâu dài.

Giả sử dự án có ứng dụng desktop và lõi TypeScript dùng chung. Lõi phải chạy được trong cả ứng dụng lẫn kiểm thử Node, nên không phụ thuộc trực tiếp biến toàn cục của trình duyệt. Ràng buộc này đáng được viết ngắn gọn cùng lý do.

# Ngữ cảnh dự án

Lõi dùng chung chạy trong ứng dụng desktop và kiểm thử Node.
Không dùng biến toàn cục trình duyệt trong packages/core; truyền adapter nền tảng.

Chạy script kiểm thử của package sau khi đổi hành vi công khai.
Xem lệnh hiện tại trong package.json trước khi chép ghi chú tác vụ cũ.

Kiểu API được sinh từ schema/api.yaml.
Sửa schema rồi chạy script sinh thay vì sửa tay tệp đầu ra.

Các đường dẫn mô tả dự án giả định. Trong kho mã thật, xác nhận chúng trước khi thêm. Tệp hướng dẫn đầy đường dẫn nghe hợp lý nhưng không tồn tại tạo sự tự tin sai về nơi cần làm việc.

Mở ảnh kích thước đầy đủ ↗

Một quan sát kiểm thử thất bại có thể quan trọng mà chưa cần trở thành quy tắc cho mọi tác vụ sau. Giá trị của nó gắn với commit, môi trường và phép kiểm tra cụ thể.

Gắn lệnh với nguồn đang định nghĩa nó

Lệnh có thể lỗi thời khi script được đổi tên hoặc package được tổ chức lại. Bản sao trong ghi nhớ có thể tồn tại rất lâu sau khi kho mã chuyển sang công cụ kiểm thử khác. Ghi rõ thư mục chạy và tệp cấu hình đang định nghĩa lệnh.

Hướng dẫn thực hành Claude Code khuyên giữ chỉ dẫn ngắn, hữu ích và có cách xác minh. Hãy thử hướng dẫn trên một tác vụ thật: người đọc có tìm được lệnh hiện tại, hiểu ranh giới module dùng chung và giải thích kết quả thành công chứng minh điều gì không?

Lệnh trả mã thành công vẫn có thể không chạy kiểm tra cần thiết do bộ lọc không còn khớp. Khi bảo trì hướng dẫn, cần đọc nội dung kết quả. Tệp nên dẫn tới phép kiểm tra có ý nghĩa chứ không chỉ tới một lệnh trả về số không.

Kiểm tra lệnh có thực thi đúng phần kiểm thử không

Thí nghiệm độc lập sau tạo kho mã tạm, chạy lệnh rồi tự xóa thư mục. Tệp schema chỉ là dấu mốc đường dẫn, không phải định nghĩa API đã được xác nhận hợp lệ. Lõi dùng chung có một hàm xử lý nhãn chuỗi và một kiểm thử mang tên. Dấu vết được ghi bên trong thân kiểm thử để phân biệt chạy thân ấy với chỉ kết thúc tiến trình thành công.

import json
import subprocess
from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as directory:
    root = Path(directory)
    (root / 'packages/core').mkdir(parents=True)
    (root / 'schema').mkdir()
    (root / 'schema/api.yaml').write_text('openapi: 3.1.1\n')
    scripts = {
        'test:core': 'node --test core.test.mjs',
        'test:empty': 'node --test --test-name-pattern=absent core.test.mjs'
    }
    (root / 'package.json').write_text(json.dumps({'scripts': scripts}))
    core = root / 'packages/core/label.mjs'
    core.write_text('export const label = name => name.trim();\n')
    (root / 'core.test.mjs').write_text(
        'import test from "node:test";\n'
        'import assert from "node:assert/strict";\n'
        'import {writeFileSync} from "node:fs";\n'
        'import {label} from "./packages/core/label.mjs";\n'
        'test("core label", () => { writeFileSync("ran.txt", "yes"); '
        'assert.equal(label(" Ada "), "Ada"); });\n'
    )
    print('old script exists:', 'test' in scripts)
    print('current script exists:', 'test:core' in scripts)
    print('schema path exists:', (root / 'schema/api.yaml').is_file())

    def inspect(script):
        (root / 'ran.txt').unlink(missing_ok=True)
        result = subprocess.run(
            ['npm', 'run', '--silent', script], cwd=root,
            text=True, capture_output=True, check=False
        )
        print(script, 'exit:', result.returncode,
              'body ran:', (root / 'ran.txt').is_file())
        for line in result.stdout.splitlines():
            if line.startswith(('# tests ', '# pass ', '# fail ', '# skipped ')):
                print(line)
        return result

    inspect('test:core')
    inspect('test:empty')
    core.write_text('export const label = name => window.document.title;\n')
    inspect('test:core')
    inspect('test:empty')

Ba dòng đầu cho biết script cũ test không tồn tại, script hiện tại test:core có tồn tại và đường dẫn schema có tệp. Đó là thông tin có thể tìm thấy trong kho mã. Chúng chưa chứng minh lệnh kiểm tra hành vi hữu ích hoặc schema hợp lệ. Các lần chạy tiếp theo bổ sung bằng chứng hành vi còn thiếu.

Lần chạy tại máy dùng Python 3.12.3 và Node 22.23.2. Kiểm thử lõi thông thường thoát với mã không và tạo dấu vết. Lệnh có bộ lọc cũng thoát với mã không nhưng không tạo dấu vết. Sau khi cố ý thay hàm lõi bằng phụ thuộc vào biến toàn cục của trình duyệt, kiểm thử thường thoát với mã một; dấu vết vẫn được ghi trước khi assertion thất bại. Lệnh có bộ lọc tiếp tục báo thành công mà không có dấu vết.

Như vậy, một lệnh được ghi nhớ có thể che đúng loại hồi quy mà ghi chú kiến trúc muốn ngăn. Trong phiên Node này, phần tổng hợp của lệnh có bộ lọc còn báo một mục qua: mục đại diện cho tệp kiểm thử thành công dù thân kiểm thử được đặt tên đã bị loại. Chỉ yêu cầu số lượng mục qua lớn hơn không vẫn bỏ sót trường hợp này. Cần xem kiểm thử nào đã chạy và nối assertion của nó với hành vi thay đổi. Dấu vết tệp là dụng cụ minh họa, không phải đề nghị thêm ghi tệp vào mọi kiểm thử thật.

Mở ảnh kích thước đầy đủ ↗

Thí nghiệm chỉ xác nhận hành vi Node của đường gọi lõi đã được thực thi. Nó chưa phân tích tĩnh toàn bộ import, chứng minh cả package không dùng API trình duyệt, kiểm tra trình sinh schema hoặc đo việc Claude tải hướng dẫn. Tiến trình con chỉ chạy hai script cố định được tạo ngay phía trên. Đừng biến mã này thành công cụ thực thi tùy ý chỉ dẫn lấy từ ghi chú không đáng tin.

Trong Effective context engineering for AI agents, công bố ngày 29 tháng 9 năm 2025, nhóm Anthropic đề nghị chọn ngữ cảnh có ích và giữ tham chiếu để lấy chi tiết khi cần. Áp dụng ở đây, chỉ dẫn ngắn có thể nêu lệnh hiện tại cùng mục đích; báo cáo được liên kết giữ đầu ra chính xác. Bài viết cung cấp lý do chọn ngữ cảnh. Thí nghiệm này không đo khả năng nhớ của mô hình và không khẳng định CLAUDE.md ngắn hơn sẽ bảo đảm tuân thủ.

Gắn nhãn trung thực cho điều đã ghi nhớ

Câu “kiểm thử xuất dữ liệu lỗi vì múi giờ” có thể chỉ bắt đầu từ giả thuyết. Trước khi giữ như sự thật, cần đọc lỗi và xác nhận nguyên nhân. Nếu không, tác vụ sau sẽ kế thừa một chẩn đoán tự tin chưa từng được chứng minh.

Bàn giao hữu ích phân biệt quan sát, diễn giải và phép kiểm tra tiếp theo. Ví dụ: kiểm thử thất bại với ngày gần nửa đêm tại một commit xác định; chuyển đổi múi giờ là giả thuyết; bước tiếp là so sánh giá trị tuần tự hóa trước và sau adapter. Cách ghi ấy cho phép tiếp tục điều tra mà không coi phỏng đoán là thẩm quyền.

Lưu dữ liệu nhạy cảm theo quy định của kho mã. Ghi nhớ hiếm khi cần token truy cập, tin nhắn khách hàng hoặc toàn bộ nhật ký production. Ưu tiên dấu hiệu lỗi đã che dữ liệu và tham chiếu có kiểm soát đến bằng chứng gốc. Ngữ cảnh lâu dài không nên trở thành kho bí mật ngoài ý muốn.

Giải quyết mâu thuẫn tại nguồn

Nếu CLAUDE.md yêu cầu một trình quản lý package còn lockfile và tài liệu thiết lập hiện tại chỉ tới công cụ khác, điều tra trước khi cài đặt rộng. Đó là vấn đề bảo trì hướng dẫn. Nếu chính kho mã không giải quyết được, cần xác định nguồn có thẩm quyền với người phụ trách rồi cập nhật bằng chứng tương ứng.

Hướng dẫn chung cũng cần được hiểu trong ngữ cảnh tác vụ. Quy tắc tránh sửa tệp sinh tự động vẫn có thể cho phép chạy script để sinh lại chúng. Phân biệt sửa tay đầu ra với tạo đầu ra từ nguồn đã được chỉ định.

Không cần thêm một đoạn mới cho mọi ngoại lệ. Khi nhiều quy tắc mâu thuẫn, viết lại phần liên quan theo hợp đồng hiện tại. Chồng các bổ sung lên câu cũ dễ để lại danh sách chỉ dẫn không thể đồng thời thực hiện.

Bảo trì bộ nhớ như tài liệu của dự án

Sau thay đổi kiến trúc đáng kể, kiểm tra tên ranh giới và lệnh còn đúng không. Bỏ chi tiết tác vụ đã xong nếu nó không còn hướng dẫn công việc tương lai. Khi lý do thiết kế dài, liên kết tài liệu giải thích thay vì chép toàn bộ vào tệp chỉ dẫn.

Trong lần rà soát đầu, chọn ba mục: một lệnh, một đường dẫn và một ràng buộc kiến trúc. Đối chiếu từng mục với checkout; ghi lại phần chưa rõ thay vì điền bằng trí nhớ. Bài tập nhỏ này cho thấy hướng dẫn đang mô tả dự án hiện có hay dự án mà ai đó nhớ lại.

Kết quả cũng phải có ích cho người mới trong nhóm. Nếu chỉ agent đã viết mới hiểu một câu, bổ sung ngữ cảnh hoặc bỏ câu ấy. Chỉ dẫn lâu dài đáng giữ khi giúp người đọc tiếp theo đưa ra quyết định đúng dựa trên bằng chứng có thể kiểm tra.