Incomex AI Portal
KB-1789 rev 2

Quy định viết Description — Dành cho mọi Agent

6 min read Revision 2
guidedescriptionenrichmentPROV-AIdieu3agentpermanent

QUY ĐỊNH VIẾT DESCRIPTION — DÀNH CHO MỌI AGENT

Đọc file này là đủ để viết description. Luật gốc chỉ cần xem khi có thắc mắc. Căn cứ: Đ3 §2.2 + §2.4 + §2.5 | Phụ lục Đ3 §A.3 | Đ35 §4.1.1 | HP NT14 Áp dụng: Mọi lần viết/sửa description cho entity trong hệ thống Incomex.

1. PHẠM VI

VIẾT cho thực thể kiến trúc — thành phần cố định trong thiết kế hệ thống: DOT, collection, species, module, config, domain, agent, page, workflow step, task, governance entity...

KHÔNG VIẾT cho bản ghi dữ liệu vận hành — entity tạo/đóng liên tục bởi runtime: system_issues, system_log, audit_log... (mô tả cơ bản máy sinh là đủ). Danh sách loại trừ: dot_config.h11b_exclude_species.

2. QUY TẮC — 5 ĐIỀU BẮT BUỘC

  1. 50–200 ký tự. Ngắn hơn = thiếu ngữ cảnh. Dài hơn = thừa.
  2. Ghi "Thuộc Đxx" — mọi entity phải nói thuộc luật nào quản lý.
  3. Paraphrase mô tả cơ bản — đọc description hiện tại, bao hàm nội dung, KHÔNG copy nguyên văn.
  4. Tiếng Việt có dấu. Giữ code/enum/tên DOT tiếng Anh.
  5. 1 đoạn liền. Không bullet, không heading, không markdown trong description.

3. TEMPLATE — MỖI LOẠI ENTITY 1 FORMAT CỐ ĐỊNH

DOT (dot_tools)

Format: [Chức năng] thuộc [Luật]. [Hoạt động: đọc gì → xử lý → ghi gì]. [Trigger + tần suất]. Cặp: [paired_dot]. Đọc trước: tier, domain, trigger_type, operation, paired_dot, source code nếu có. Ví dụ: Executor tổng hợp thuộc Đ22 (Tự chữa lành). Quét system_health_checks, dispatch theo executor_type, log qua fn_log_issue. Cron mỗi 3h. Cặp: dot-hc-executor-verify.

Collection (collection_registry)

Format: [Vai trò governance]. Chứa [nội dung]. Lớp [Não/Kho/Cổng]. Thuộc [Luật]. [FK chính]. Đọc trước: governance_role, species, columns, FK, database (directus=Kho, incomex_metadata=Não). Ví dụ: Bảng đăng ký collection governed. Chứa governance_role, species_code, status. Lớp Kho. Thuộc Đ36 (Collection Protocol). FK tới entity_species, meta_catalog.

Catalog (meta_catalog)

Format: Catalog entry đại diện [bảng/loại gì]. [Số entity + loài + lớp]. [Vai trò]. Thuộc [Luật]. Đọc trước: entity_type, source_model, layer, record_count. Ví dụ: Catalog entry đại diện bảng dot_tools. 288 entity loài dot_tool, lớp atom. Cung cấp metadata đếm cho registry. Thuộc Đ2 (Luật Registry).

Species (entity_species)

Format: Loài [đại diện nhóm gì]. Lớp [composition_level]. [Đặc điểm]. [Parent nếu có]. Đọc trước: species metadata, composition_level, collection mapping. Ví dụ: Loài đại diện DOT tools. Lớp atom. Mỗi entity là 1 script thực thi có trigger + paired DOT. Không có parent.

Config (dot_config)

Format: Tham số [chức năng]. Ảnh hưởng [hành vi]. Mặc định: [value]. Thuộc [Luật]. Đọc trước: key, current value, consumers (grep trong code). Ví dụ: Tham số thời gian tối đa executor chạy 1 cycle. Ảnh hưởng lockfile timeout. Mặc định: 600 giây. Thuộc Đ22 §4.3.

Page (ui_pages)

Format: Trang [chức năng]. Hiển thị [dữ liệu]. Thuộc [module/domain]. Route: [path]. Đọc trước: page name, route URL, module. Ví dụ: Trang danh sách DOT tools với bộ lọc domain/tier/status. Hiển thị từ dot_tools qua Directus API. Thuộc Governance. Route: /knowledge/registries/dot_tool.

Domain (dot_domains)

Format: Domain phạm vi [chức năng]. [Số DOT]. [DOT tiêu biểu]. Thuộc [Luật]. Đọc trước: domain rules, count DOTs, representative DOTs. Ví dụ: Domain giám sát sức khỏe hệ thống. 7 DOT. Tiêu biểu: dot-hc-executor. Thuộc Đ22.

Workflow Step (workflow_steps)

Format: Bước [thứ tự] trong [workflow]. [Chức năng]. [Input → Output]. Thuộc [Luật]. Đọc trước: parent workflow, step_type, position. Ví dụ: Bước 2 trong WF-001 phê duyệt. Kiểm tra quorum theo risk_level. Input: approval_request. Output: approved/rejected. Thuộc Đ32.

Agent (agents)

Format: Agent [loại]. [Vai trò]. [Công cụ sử dụng]. Thuộc [domain]. Đọc trước: agent metadata, tools, role. Ví dụ: Agent AI trên Claude Code CLI. Chạy prompt kỹ thuật, SSH VPS, đọc/ghi KB. Thuộc infrastructure.deploy.

Task (tasks)

Format: Công việc [mục tiêu]. [Trạng thái]. [Agent chịu trách nhiệm]. Thuộc [context]. Đọc trước: task metadata, status, assignee. Ví dụ: Deploy executor v1.5.0 lên production. Completed. Agent: Claude Code CLI. Thuộc S178 Fix 29.

Governance (taxonomy, law_jurisdiction, label, v.v.)

Format: [Quy tắc gì]. Áp dụng [đối tượng]. Thuộc [Luật]. [Enforcement nếu có]. Đọc trước: entity metadata, related law, FK. Ví dụ: Phân loại entity theo facet "Vai trò" (FAC-ROLE). Áp dụng governed qua label_rules. Thuộc Đ24. Enforcement: PG trigger tự gán label.

4. QUY TRÌNH

1. Query entity cần viết (PROV-DOT hoặc description chưa đạt chuẩn)
2. Đọc description hiện tại + metadata entity
3. Viết theo template §3 cho đúng loại entity
4. Ghi qua Directus REST API (KHÔNG raw SQL)
5. Cập nhật provenance: PROV-DOT → PROV-AI
6. Verify: đọc lại description → đúng format, đúng nội dung

5. CHECKLIST — HỎI TRƯỚC KHI GHI

  • Đọc description hiện tại chưa?
  • Bao hàm/paraphrase thông tin cơ bản?
  • Có "Thuộc Đxx"?
  • 50–200 ký tự?
  • Tiếng Việt có dấu?
  • Đúng template cho loại entity?
  • Không copy nguyên văn mô tả cũ?

Quy định viết Description v1.0 | Phụ lục Đ3 | HP NT14