Kernel — Hiến pháp của PARA Workspace
Kernel là hệ thống quy tắc điều khiển tất cả các phiên bản PARA Workspace. Hãy hình dung nó như một bản hiến pháp — định nghĩa những luật cơ bản mà mọi workspace, agent, workflow, và công cụ CLI phải tuân theo.
🧠 Kernel là gì?
Kernel gồm ba thành phần:
| Thành phần | Mục đích | Ảnh hưởng khi thay đổi |
|---|---|---|
| Invariants | 11 quy tắc cứng KHÔNG ĐƯỢC vi phạm | Tăng MAJOR version |
| Heuristics | 9 quy ước mềm, được khuyến khích mạnh | Tăng MINOR/PATCH |
| Schemas | Hợp đồng định dạng file (tasks, catalog, decisions) | Phải cập nhật templates |
Kernel chính thức nằm trong repo tại kernel/. Khi cài vào workspace, nó tồn tại dưới dạng bản sao chỉ đọc tại Resources/ai-agents/kernel/.
[!IMPORTANT] Chỉ
/para-auditđược phép đọc toàn bộ Kernel trong hoạt động bình thường. Các workflow khác tương tác với quy tắc Kernel gián tiếp thông qua hệ thống Rule Layers.
⚖️ 11 Invariants (Bất biến)
Vi phạm bất kỳ invariant nào là hành vi không tuân thủ. Thay đổi cần RFC + tăng MAJOR version.
| # | Quy tắc | Tóm tắt |
|---|---|---|
| I1 | Cấu trúc Thư mục PARA | Mỗi workspace phải có đúng 4 thư mục gốc: Projects/, Areas/, Resources/, Archive/ |
| I2 | Mô hình Task Hybrid 3-File | Tasks quản lý qua backlog.md (chính thức), sprint-current.md (Hot Lane), done.md (chỉ thêm) |
| I3 | Đặt tên Project | Slug project phải dùng kebab-case: my-saas-app |
| I4 | Không hoạt động Project | Không có task hoạt động trong backlog = project không hoạt động |
| I5 | Areas — Không có Task Runtime | Areas/ chỉ chứa tri thức ổn định, không có công việc đang hoạt động |
| I6 | Archive là Kho Lạnh | Bất biến. Kernel và agent KHÔNG đọc Archive trong hoạt động bình thường |
| I7 | Seeds là Ý tưởng Thô | .beads/seeds.md chứa ý tưởng, không phải tasks. Bừa bộn là OK |
| I8 | Không có File Lẻ | Mọi file phải thuộc một trụ cột PARA. Không có nội dung ở gốc workspace |
| I9 | Resources Bất biến | Resources/ai-agents/ chỉ đọc. Không bao giờ ghi ngược lại Resources |
| I10 | Tách biệt Repo ↔ Workspace | Repo chứa quản trị. Workspace chứa dữ liệu người dùng. Không trộn lẫn |
| I11 | Tuân thủ Ngôn ngữ Workflow | Agent phải dùng preferences.language từ .para-workspace.yml cho mọi output |
Chi tiết Invariant Quan trọng
I2 — Mô hình Hybrid 3-File là invariant được tham chiếu nhiều nhất:
backlog.mdlà cơ quan vận hành — file duy nhất nơi tasks được tạo/sửa/xóasprint-current.mdlà Hot Lane — agent ghi task nhanh trực tiếpdone.mdlà chỉ thêm — nhận tasks hoàn thành từ/end/endlà điểm đồng bộ duy nhất — hòa giải Hot Lane + tasks chiến lược
→ Học: Kiến trúc Hybrid 3-File
📐 9 Heuristics (Quy ước)
Heuristics là quy ước mềm — được khuyến khích mạnh nhưng có thể điều chỉnh theo ngữ cảnh.
| # | Heuristic | Mục đích |
|---|---|---|
| H1 | Quy ước Đặt tên | kebab-case cho files, PascalCase cho thư mục PARA, camelCase cho code |
| H2 | Ưu tiên Tải Context | Contract → Rules → Artifacts → Beads → Areas → Resources |
| H3 | Quản lý Phiên bản | SemVer cho tất cả projects. PATCH = agent tự quyết, MINOR/MAJOR = cần phê duyệt |
| H4 | Cấu trúc Project | Layout chuẩn: project.md, sessions/, artifacts/, .beads/ |
| H5 | Vòng đời Beads | Tạo khi cần → bừa bộn khi project chạy → tốt nghiệp trước archive |
| H6 | VCS & Git Ranh giới | Git chỉ ảnh hưởng repo/. Session logs và artifacts không commit |
| H7 | Tham chiếu Xuyên Project | Ưu tiên tài nguyên dùng chung hơn là phụ thuộc xuyên project |
| H8 | Tương thích Workflow | Khai báo phạm vi kernel_compat cho mỗi workflow |
| H9 | Catalog Thư viện Quản trị | catalog.yml với id, name, version, kernel_min cho mỗi item |
H2 trong Thực tế — Ưu tiên Tải Context
1. Hợp đồng Project (project.md) ← Luôn đọc đầu tiên
2. Rules Project (.agent/rules/) ← Tải lười qua Trigger Index
3. Rules Workspace (.agent/rules/) ← Qua chỉ mục rules.md
4. Artifacts (tasks/, plans/) ← Đọc tối ưu token
5. Bộ nhớ Hoạt động (.beads/) ← Cho vấn đề lặp lại
6. Tri thức Trừu tượng (Areas/) ← SOPs ổn định
7. Tham chiếu (Resources/) ← Templates chỉ đọc→ Học: Rule Layers & Trigger Index
🔄 Quy trình Thay đổi Kernel
| Loại thay đổi | Quy trình | Ảnh hưởng version |
|---|---|---|
| Invariant | Cần RFC → review cộng đồng → merge | Tăng MAJOR |
| Heuristic | Pull request → review → merge | MINOR hoặc PATCH |
| Schema | Phải cập nhật templates + examples | Tùy phạm vi |
Mọi thay đổi phải pass test vectors trong kernel/examples/ (vectors tuân thủ hợp lệ + không hợp lệ).
Kernel trong Workspace
- Cài đặt dưới dạng bản sao chỉ đọc tại
Resources/ai-agents/kernel/ - Version theo dõi tại
Resources/ai-agents/VERSION - Cập nhật qua
./para update— cũng chạy migration scripts nếu cần
📚 Tham Khảo
- Rules: Rule Layers & Trigger Index — Cách rules được tổ chức và tải
- Kiến trúc: Hybrid 3-File — Quản lý task (I2)
- Bảo vệ: Defense-in-Depth — Chiến lược phục hồi context
- Rule: Rule governance — Áp dụng bất biến kernel
→ Học: Governance & Tiêu chuẩn Quyết định → Học: Rule Layers & Trigger Index → Học: Kiến trúc Hybrid 3-File