hướng dẫn

Hướng dẫn áp dụng

Bản dịch có sự hỗ trợ của AI agent. Nếu có khác biệt, trang tiếng Anh là bản có hiệu lực. Nếu bạn thấy vấn đề nào trong văn bản, rất mong bạn mở một issue hoặc gửi một pull request.

Áp dụng Leji biến phần khung ban đầu của kho mã nguồn thành một lớp ngữ cảnh dùng được. Bạn sẽ ánh xạ tài liệu hiện có, nối các điểm vào, thêm các phép kiểm và chọn nơi đặt lớp ngữ cảnh. Nhờ đó, ai cũng có một điểm bắt đầu duy nhất và đáng tin cậy.

01Dựng khung

leji adopt tái sử dụng docs/, doc/, hoặc documentation/ mà không di chuyển công việc của bạn. Nó ghi ra:

• Một tệp leji.json với name lấy từ tên thư mục, rootPath đã đặt, và owners lấy từ một danh tính git có sẵn.
• Một boot profile, các index danh mục, một brief onboarding, và một bản ghi quyết định đầu tiên hoàn chỉnh với status: accepted.
• Một con trỏ AGENTS.md khi chưa có tệp nào như vậy.

leji adopt --dry-run       # xem trước mọi lần ghi; chưa ghi gì
leji adopt                 # kho mã nguồn hiện có: dựng khung quanh nội dung đang có
leji init                  # kho mã nguồn mới: dựng leji.json, boot profile, mầm danh mục và quyết định đầu tiên
leji adopt --wire-adapters # hoàn tất áp dụng trên điểm vào của nhà cung cấp (CLAUDE.md, AGENTS.md)

Hoặc, thực hiện tất cả trong một bước mà không cần cài gì: npm create leji đọc thư mục rồi chạy leji adopt ngay tại đó, hoặc chạy leji init trên một kho mã nguồn chưa có gì để áp dụng. Lệnh này thay thế bước hiện tại chứ không phải chạy trước bước đó; sau khi dùng, hãy chuyển sang mục kế tiếp.

Hãy ánh xạ những đường dẫn đang dùng thay vì đổi tên chúng. docs/engineering/START-HERE.md vẫn tuân thủ với vai trò một boot profile; còn các lớp mới thì nên dùng mặc định chữ thường nối gạch nối.

02Biến nó thành của bạn

Trước hết, hãy phân loại những tài liệu hiện có. Mỗi tệp index tạo sẵn chọn nguyên thư mục danh mục của nó, nên bất cứ thứ gì đã nằm sẵn trong đó đều được quản trị ngay khi bản dựng khung xuất hiện; những gì bạn viết ở nơi khác thì vẫn nằm ngoài lớp ngữ cảnh cho tới khi có người liệt kê chúng vào. Hãy đưa brief onboarding cho agent của bạn rồi phê duyệt cách ánh xạ mà nó đề xuất, hoặc tự tay sửa các tệp index.

Không cần di chuyển bất kỳ tệp nào. Mỗi danh mục ánh xạ tới các tệp index đã được biên tập, và mỗi mục trong đó chọn hoặc một tệp đơn lẻ hoặc nguyên một thư mục, nên một cây docs/ sẵn có có thể ở nguyên đúng chỗ của nó (danh mục nội dung).

Hãy đưa cả lịch sử quyết định vào lớp ngữ cảnh. Thư mục ADR hiện có có thể dùng nguyên trạng khi các bản ghi mang đủ phần frontmatter mà schema bản ghi quyết định đòi hỏi; bản dựng khung thì đã viết sẵn <rootPath>/decisions/0001-adopt-leji.md làm bản ghi đầu tiên.

Tiếp theo, hãy nối phần khám phá. Việc áp dụng lên một tệp CLAUDE.md, GEMINI.md, .cursor/rules, hay AGENTS.md sẵn có sẽ để nguyên tệp đó theo đúng thiết kế, nghĩa là lần áp dụng ấy vẫn còn là một bản nháp: điểm vào cũ chưa chuyển hướng, leji validate báo vendor-adapter-redirect, và leji conformance xác minh ra none so với mức core mà bạn đã tuyên bố.

leji adopt --wire-adapters chuyển phần nội dung đó vào lớp ngữ cảnh và thay điểm vào bằng dòng: Read ./<bootProfilePath> first. It is the canonical context entrypoint for this repository. Sau đó phép kiểm sẽ qua được ở mức core.

AGENTS.md là adapter dùng chung được, nhiều host đọc được nó một cách tự nhiên. init và adopt tạo ra một tệp chỉ chứa con trỏ khi chưa có tệp nào; --no-agents thì bỏ qua nó. Các điểm vào chỉ dành cho một nhà cung cấp thì không bao giờ được tạo ra.

Nếu muốn áp dụng thủ công, hãy chép templates/leji.json và templates/boot-profile.md, tạo các index, rồi dùng templates/decision-record.md. Hãy bỏ hết mọi nội dung mẫu mà leji validate nêu tên trước khi tuyên bố mức core; và bỏ đi những mục agents hay những danh mục không cần tới.

03Đưa vào sử dụng

Lớp ngữ cảnh chỉ phát huy giá trị khi agent đọc nó trước tác vụ, không phải sau đó. leji start mở coding agent của bạn ngay từ gốc kho mã nguồn, nên nó khởi đầu bằng boot profile thay vì bằng thứ nó tự suy ra.

leji start                                  # phát hiện host rồi mở trong lớp ngữ cảnh
leji start --agent codex                    # ghim host thay vì phát hiện
leji start --agent claude-code -- --chrome  # chuyển tiếp cờ tới host đó

leji detect liệt kê các host; leji start --help giải thích cách chuyển tiếp cờ. Các script thì dùng bootProfilePath. Một liên kết agents, kể cả default, chỉ ghi nhận các profile chứ không bao giờ nạp chúng; chỉ có chỉ dẫn trong boot profile mới làm việc đó.

04Giữ lớp ngữ cảnh trung thực

Một lớp ngữ cảnh trung thực mô tả đúng trạng thái hiện tại của kho mã nguồn. Các phép kiểm này báo lỗi khi có tham chiếu hỏng và khi index không còn khớp với nguồn của nó. Markdown chưa được lập index và nội dung mẫu còn sót lại sẽ được báo cáo chứ không khiến phép kiểm thất bại, để bạn thấy sự trôi lệch trước khi agent làm theo hướng dẫn lỗi thời.

leji validate --content tìm ra nội dung mẫu và nội dung sơ sài. leji status tìm ra những gì chưa lập index, tham chiếu treo, hay đã lỗi thời. leji conformance báo cáo tiến độ.

Ở mức indexed, leji index sinh ra context-index.json; còn leji index --check thì báo lỗi khi nó đã lỗi thời. leji changelog check kiểm changelog dành cho máy.

Nếu chưa có quy ước CI nào, leji ci sinh ra một workflow; leji ci --hooks cài các cổng chặn đó vào hook pre-commit. leji ci --help giải thích cách phân giải CLI.

Trong một pipeline đã ổn định, hãy chạy leji validate và leji index --check trong các job bắt buộc và trong hook. Hãy khai CLI dưới dạng dev dependency để nó luôn có mặt sau một lần cài mới: leji init/leji adopt nhận ra trình quản lý gói mà kho mã nguồn này đang dùng và, khi bạn đồng ý rõ ràng, chạy lệnh thêm gói của chính nó (với pip và Go trước 1.24 thì nó in ra dòng cần thêm).

Ở mức governed, hãy thêm các thay đổi đã qua xem xét, các agent profile hợp lệ, các phép kiểm độ tươi, và CI bắt buộc.

Hiển thị mức tuân thủ

leji badge ghi ra leji-badge.svg ở gốc kho mã nguồn và in ra dòng để bạn dán vào README:

leji badge                        # ghi leji-badge.svg rồi in đoạn mã
leji badge --out docs/badge.svg   # ghi ở nơi khác; đoạn mã dùng đường dẫn này

[![Leji 1.0 · governed · self-attested](leji-badge.svg)](https://leji.org/agent-ready/)

Huy hiệu mang tính tự khai và phản ánh đúng lần chạy hiện tại: nó nêu mức mà leji conformance đã xác minh, mức đó không bao giờ cao hơn những gì leji.json tuyên bố và đôi khi thấp hơn. Một tuyên bố mà lần chạy offline không xác nhận được thì sẽ được nêu tên trên stdout chứ không được đưa lên huy hiệu.

Hãy chạy nó trên một cây đã commit. Một changelog không có mốc nền đã commit thì không kiểm được quy tắc chỉ được thêm vào, nên lần chạy dừng lại ở mức core bất kể leji.json tuyên bố mức nào; còn những phần thêm vào bên trên một changelog đã commit thì được đối chiếu với HEAD và qua được mà không cần commit riêng. Một lần chạy không xác minh được mức nào thì không ghi ra huy hiệu nào cả.

Đường dẫn ảnh trong đoạn mã đó là tương đối so với gốc kho mã nguồn. Một tệp README nằm trong thư mục con thì cần chỉnh lại đường dẫn để với tới được tệp ảnh từ chỗ đó.

05Nơi đặt lớp ngữ cảnh

Một kho mã nguồn giữ một lớp ngữ cảnh ngay bên cạnh phần công việc của nó.

Khi nhiều kho mã nguồn cùng dùng một lớp, hãy đặt lớp đó trong một submodule chỉ chứa tài liệu. Tạo một kho mã nguồn riêng, mount tại context/ trong từng kho mã nguồn sử dụng, rồi ghim riêng cho mỗi kho mã nguồn. Hãy cập nhật pin bằng script dưới dạng thay đổi có thể xem xét. Phần build và runtime không được phụ thuộc vào lớp này.

Hãy trỏ agent tới context/docs/boot-profile.md; những tệp của nhà cung cấp còn giữ lại thì chuyển hướng về đó. Xem ví dụ nhiều kho mã nguồn và bản đặc tả về phân phối.

Federation dành cho những nhóm mà mỗi nhóm đã sở hữu một lớp. Hướng dẫn của nó bao gồm phần khai báo, nạp về, trạng thái, định tuyến, và các phép kiểm mức federated.

06Các trường hợp tuỳ chọn

```leji-index record
- path: docs/operations/
```

```leji-index intent
- path: docs/operations/escalation-policy.md
```

leji viewer serve      # xem trước trên localhost tại http://127.0.0.1:5354/
leji viewer build      # xuất thư mục tĩnh độc lập để host nội bộ

Tiếp theo: tài liệu tra cứu manifest cho từng trường, hoặc bản đặc tả cho những quy tắc đằng sau chúng.